22 * |
22 * |
23 * Once you have an opened transport, sending and receiving data is simple - just call transport_read()/transport_write(). |
23 * Once you have an opened transport, sending and receiving data is simple - just call transport_read()/transport_write(). |
24 * These implement unbuffered I/O, so they may do partial reads/writes. In terms of the system read/write calls, the |
24 * These implement unbuffered I/O, so they may do partial reads/writes. In terms of the system read/write calls, the |
25 * main difference is in the error return codes. On EOF, instead of returning zero, they return ERR_EOF (or |
25 * main difference is in the error return codes. On EOF, instead of returning zero, they return ERR_EOF (or |
26 * ERR_WRITE_EOF for transport_write, for whoever knows what that means...). This means that when the underlying |
26 * ERR_WRITE_EOF for transport_write, for whoever knows what that means...). This means that when the underlying |
27 * transport is unable to fufill the request due to lack of data/buffer space, these can return zero to signifiy s |
27 * transport is unable to fufill the request due to lack of data/buffer space, these can return zero to signifiy |
28 * something simliar to EAGAIN. |
28 * something simliar to EAGAIN. |
29 * |
29 * |
30 * The transport API also implements non-blocking/event-based operation (usually on top of libevent), although at a |
30 * The transport API also implements non-blocking/event-based operation (usually on top of libevent), although at a |
31 * slightly different level than the normal select/poll API. Instead of the user asking the transport to notify for |
31 * slightly different level than the normal select/poll API. Instead of the user asking the transport to notify for |
32 * read/write after transport_read/transport_write return zero, the transport will take care of this itself. |
32 * read/write after transport_read/transport_write return zero, the transport will take care of this itself. |
38 * |
38 * |
39 * For reads, the transport maintains a persistent read event, and will always call on_read when data is available on |
39 * For reads, the transport maintains a persistent read event, and will always call on_read when data is available on |
40 * the socket (i.e. normal select() semantics). If masked out using transport_events(), there should be no event |
40 * the socket (i.e. normal select() semantics). If masked out using transport_events(), there should be no event |
41 * activity on the transport (i.e. the fd read event is removed). |
41 * activity on the transport (i.e. the fd read event is removed). |
42 * |
42 * |
43 * For writes, the transport maintains a write event that is disabled by default. If on_write returns zero, it will |
43 * For writes, the transport maintains a write event that is disabled by default. If transport_write() returns zero, it will |
44 * become enabled *once*, and consequently trigger transport_callbacks::on_write *once*, after which you must call |
44 * become enabled *once*, and consequently trigger transport_callbacks::on_write *once*, after which you must call |
45 * transport_write() to possibly enable it again. If masked out using transport_events(), transport_write() will not |
45 * transport_write() to possibly enable it again. If masked out using transport_events(), transport_write() will not |
46 * enable the write event, and any pending write event is cancelled. If masked back in using transport_events(), the |
46 * enable the write event, and any pending write event is cancelled. If masked back in using transport_events(), the |
47 * write event will *not* be registered, so if you have pending data, do a transport_write() after enabling |
47 * write event will *not* be registered, so if you have pending data, do a transport_write() after enabling |
48 * TRANSPORT_WRITE. |
48 * TRANSPORT_WRITE. |
129 /** |
129 /** |
130 * Write a series of bytes from the given \a buf (containing \a len bytes) to the transport. If succesfull, this |
130 * Write a series of bytes from the given \a buf (containing \a len bytes) to the transport. If succesfull, this |
131 * returns the number of bytes written (which may be less than \a len). If the transport is nonblocking, and the |
131 * returns the number of bytes written (which may be less than \a len). If the transport is nonblocking, and the |
132 * operation would have blocked, no data will be written, and zero is returned. |
132 * operation would have blocked, no data will be written, and zero is returned. |
133 * |
133 * |
134 * XXX: behaviour of transport_callbacks::on_write? |
|
135 * |
|
136 * On errors, this returns the negative error code, along with extended info via \a err. |
134 * On errors, this returns the negative error code, along with extended info via \a err. |
137 * |
135 * |
138 * @param transport the transport state |
136 * @param transport the transport state |
139 * @param buf the buffer to write the bytes from |
137 * @param buf the buffer to write the bytes from |
140 * @param len number of bytes to write |
138 * @param len number of bytes to write |