diff options
Diffstat (limited to 'lib/tsocket')
| -rw-r--r-- | lib/tsocket/tsocket_guide.txt | 78 |
1 files changed, 37 insertions, 41 deletions
diff --git a/lib/tsocket/tsocket_guide.txt b/lib/tsocket/tsocket_guide.txt index dfe2dd44e1..f937385a82 100644 --- a/lib/tsocket/tsocket_guide.txt +++ b/lib/tsocket/tsocket_guide.txt @@ -23,20 +23,20 @@ for all abstracted methods that need to be async. The tsocket_address abstraction =============================== -The tsocket_address represents an socket endpoint genericly. -As it's like an abstract class it has no specific constructor. -The specific constructors are descripted later sections. +A tsocket_address represents a generic socket endpoint. +It behaves like an abstract class, therefore it has no direct constructor. +Constructors are described in later sections of this document. -There's a function get the string representation of the -endpoint for debugging. Callers should not try to parse -the string! The should use additional methods of the specific -tsocket_address implemention to get more details. +A function get the string representation of an endpoint for debugging is +available but callers SHOULD NOT try to parse this string. To get more +details callers should use getter methods of the specific tsocket_address +implemention. char *tsocket_address_string(const struct tsocket_address *addr, TALLOC_CTX *mem_ctx); -There's a function to create a copy of the tsocket_address. -This is useful when before doing modifications to a socket +A function to create a copy of the tsocket_address is also avilable. +This is useful before doing modifications to a socket via additional methods of the specific tsocket_address implementation. struct tsocket_address *tsocket_address_copy(const struct tsocket_address *addr, @@ -47,14 +47,13 @@ The tdgram_context abstraction The tdgram_context is like an abstract class for datagram based sockets. The interface provides async 'tevent_req' based -functions on top functionality is similar to the -recvfrom(2)/sendto(2)/close(2) syscalls. +functions similar to recvfrom(2)/sendto(2)/close(2) syscalls. The tdgram_recvfrom_send() method can be called to ask for the -next available datagram on the abstracted tdgram_context. +next available datagram from the abstracted tdgram_context. It returns a 'tevent_req' handle, where the caller can register a callback with tevent_req_set_callback(). The callback is triggered -when a datagram is available or an error happened. +when a datagram is available or an error occurs. The callback is then supposed to get the result by calling tdgram_recvfrom_recv() on the 'tevent_req'. It returns -1 @@ -122,20 +121,18 @@ of the tdgram_context on a fatal error. The tstream_context abstraction =============================== -The tstream_context is like an abstract class for stream +A tstream_context is like an abstract class for stream based sockets. The interface provides async 'tevent_req' based -functions on top functionality is similar to the -readv(2)/writev(2)/close(2) syscalls. +functions similar to the readv(2)/writev(2)/close(2) syscalls. -The tstream_pending_bytes() function is able to report -how much bytes of the incoming stream have arrived -but not consumed yet. It returns -1 and sets 'errno' on failure. -Otherwise it returns the number of uncomsumed bytes -(it can return 0!). +The tstream_pending_bytes() function is able to report how many bytes of +the incoming stream have been received but have not been consumed yet. +It returns -1 and sets 'errno' on failure. +Otherwise it returns the number of uncomsumed bytes (it can return 0!). ssize_t tstream_pending_bytes(struct tstream_context *stream); -The tstream_readv_send() method can be called to read for a +The tstream_readv_send() method can be called to read a specific amount of bytes from the stream into the buffers of the given iovec vector. The caller has to preallocate the buffers in the iovec vector. The caller might need to use @@ -143,13 +140,12 @@ tstream_pending_bytes() if the protocol doesn't have a fixed pdu header containing the pdu size. tstream_readv_send() returns a 'tevent_req' handle, where the caller can register a callback with tevent_req_set_callback(). The callback is triggered when all iovec buffers are completely -filled with bytes from the socket or an error happened. +filled with bytes from the socket or an error occurs. The callback is then supposed to get the result by calling tstream_readv_recv() on the 'tevent_req'. It returns -1 and sets '*perrno' to the actual 'errno' on failure. -Otherwise it returns the length of the datagram -(0 is never returned!). +Otherwise it returns the length of the datagram (0 is never returned!). The caller can only have one outstanding tstream_readv_send() at a time otherwise the caller will get *perrno = EBUSY. @@ -165,7 +161,7 @@ at a time otherwise the caller will get *perrno = EBUSY. The tstream_writev_send() method can be called to write buffers in the given iovec vector into the stream socket. -It's invalid to pass an empty vector. +It is invalid to pass an empty vector. tstream_writev_send() returns a 'tevent_req' handle, where the caller can register a callback with tevent_req_set_callback(). The callback is triggered when the specific implementation (thinks it) @@ -189,7 +185,7 @@ at a time otherwise the caller will get '*perrno = EBUSY'. int tstream_writev_recv(struct tevent_req *req, int *perrno); -The tstream_disconnect_send() method should be used to normally +The tstream_disconnect_send() method should normally be used to shutdown/close the abstracted socket. The caller should make sure there're no outstanding tstream_readv_send() @@ -208,21 +204,21 @@ of the tstream_context on a fatal error. PDU receive helper functions ============================ -In order to make the live easier for callers which want to implement +In order to simplify the job, for callers that want to implement a function to receive a full PDU with a single async function pair, -there're some helper functions. +some helper functions are provided. The caller can use the tstream_readv_pdu_send() function to ask for the next available PDU on the abstracted tstream_context. The caller needs to provide a "next_vector" function and a private state for this function. The tstream_readv_pdu engine will ask -the next_vector function for the next iovec vetor to be filled. +the next_vector function for the next iovec vector to be used. There's a tstream_readv_send/recv pair for each vector returned by the next_vector function. If the next_vector function detects it received a full pdu, it returns an empty vector. The the callback of the tevent_req (returned by tstream_readv_pdu_send()) is triggered. Note: the buffer allocation is completely up to the next_vector function -and it's private state. +and its private state. See the 'dcerpc_read_ncacn_packet_send/recv' functions in Samba as an example. @@ -244,14 +240,14 @@ example. Async 'tevent_queue' based helper functions =========================================== -There're some cases where the caller wants doesn't care about the -order of doing IO on the abstracted sockets. +In some cases the caller doesn't care about the IO ordering on the +abstracted socket. (Remember at the low level there's always only one IO in a specific direction allowed, only one tdgram_sendto_send() at a time). -There're some helpers using 'tevent_queue' to make it easier -for callers. The functions just get a 'queue' argument -and serialize the operations. +Some helpers that use 'tevent_queue' are avilable to simplify handling +multiple IO requests. The functions just get a 'queue' argument and +internally serialize all operations. struct tevent_req *tdgram_sendto_queue_send(TALLOC_CTX *mem_ctx, struct tevent_context *ev, @@ -295,7 +291,7 @@ With "ip" is autodetects "ipv4" or "ipv6" based on the ip address string based on the selected family (dns names are not allowed!). But it's valid to pass NULL, which gets mapped to "0.0.0.0" or "::". -It return -1 and set errno on error. Otherwise it returns 0. +It returns -1 and sets errno on error. Otherwise it returns 0. int tsocket_address_inet_from_strings(TALLOC_CTX *mem_ctx, const char *family, @@ -342,7 +338,7 @@ On success it returns 0. To get the path of an 'unix' tsocket_address you can use the tsocket_address_unix_path() function. It will return NULL and set errno to EINVAL if the tsocket_address -doesn't represent an unix domain endpoint path. +doesn't represent a unix domain endpoint path. char *tsocket_address_unix_path(const struct tsocket_address *addr, TALLOC_CTX *mem_ctx); @@ -371,7 +367,7 @@ and it returns 0 on success. TALLOC_CTX *mem_ctx, struct tdgram_context **dgram); -You can use tstream_inet_tcp_connect_send to async +You can use tstream_inet_tcp_connect_send to asynchronously connect to a remote ipv4 or ipv6 TCP endpoint and create a tstream_context for the stream based communication. "local_address" has to be an 'inet' tsocket_address and it has to represent the local @@ -397,7 +393,7 @@ in '*stream'. TALLOC_CTX *mem_ctx, struct tstream_context **stream); -You can use tstream_unix_connect_send to async +You can use tstream_unix_connect_send to asynchronously connect to a unix domain endpoint and create a tstream_context for the stream based communication. "local_address" has to be an 'unix' tsocket_address and @@ -438,7 +434,7 @@ In some situations it's needed to create a tsocket_address from a given 'struct sockaddr'. You can use tsocket_address_bsd_from_sockaddr() for that. This should only be used if really needed, because of already existing fixed APIs. Only AF_INET, AF_INET6 and AF_UNIX -sockets are allowed. The function returns -1 and set errno on error. +sockets are allowed. The function returns -1 and sets errno on error. Otherwise it returns 0. int tsocket_address_bsd_from_sockaddr(TALLOC_CTX *mem_ctx, |