Merge branch 'master' of git://git.samba.org/samba
[ira/wip.git] / lib / tsocket / tsocket.h
1 /*
2    Unix SMB/CIFS implementation.
3
4    Copyright (C) Stefan Metzmacher 2009
5
6      ** NOTE! The following LGPL license applies to the tsocket
7      ** library. This does NOT imply that all of Samba is released
8      ** under the LGPL
9
10    This library is free software; you can redistribute it and/or
11    modify it under the terms of the GNU Lesser General Public
12    License as published by the Free Software Foundation; either
13    version 3 of the License, or (at your option) any later version.
14
15    This library is distributed in the hope that it will be useful,
16    but WITHOUT ANY WARRANTY; without even the implied warranty of
17    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
18    Lesser General Public License for more details.
19
20    You should have received a copy of the GNU Lesser General Public
21    License along with this library; if not, see <http://www.gnu.org/licenses/>.
22 */
23
24 #ifndef _TSOCKET_H
25 #define _TSOCKET_H
26
27 #include <talloc.h>
28 #include <tevent.h>
29
30 struct tsocket_address;
31 struct tdgram_context;
32 struct tstream_context;
33 struct iovec;
34
35 /**
36  * @mainpage
37  *
38  * The tsocket abstraction is an API ...
39  */
40
41 /**
42  * @defgroup tsocket The tsocket API
43  *
44  * The tsocket abstraction is splitted into two different kinds of
45  * communitation interfaces.
46  *
47  * There's the "tstream_context" interface with abstracts the communication
48  * through a bidirectional byte stream between two endpoints.
49  *
50  * And there's the "tdgram_context" interface with abstracts datagram based
51  * communication between any number of endpoints.
52  *
53  * Both interfaces share the "tsocket_address" abstraction for endpoint
54  * addresses.
55  *
56  * The whole library is based on the talloc(3) and 'tevent' libraries and
57  * provides "tevent_req" based "foo_send()"/"foo_recv()" functions pairs for
58  * all abstracted methods that need to be async.
59  *
60  * @section vsock Virtual Sockets
61  *
62  * The abstracted layout of tdgram_context and tstream_context allow
63  * implementations arround virtual sockets for encrypted tunnels (like TLS,
64  * SASL or GSSAPI) or named pipes over smb.
65  *
66  * @section npa Named Pipe Auth (NPA) Sockets
67  *
68  * Samba has an implementation to abstract named pipes over smb (within the
69  * server side). See libcli/named_pipe_auth/npa_tstream.[ch] for the core code.
70  * The current callers are located in source4/ntvfs/ipc/vfs_ipc.c and
71  * source4/rpc_server/service_rpc.c for the users.
72  */
73
74 /**
75  * @defgroup tsocket_address The tsocket_address abstraction
76  * @ingroup tsocket
77  *
78  * The tsocket_address represents an socket endpoint genericly.
79  * As it's like an abstract class it has no specific constructor.
80  * The specific constructors are descripted in later sections.
81  *
82  * @{
83  */
84
85 /**
86  * @brief Get a string representaion of the endpoint.
87  *
88  * This function creates a string representation of the endpoint for debugging.
89  * The output will look as followed:
90  *      prefix:address:port
91  *
92  * e.g.
93  *      ipv4:192.168.1.1:143
94  *
95  * Callers should not try to parse the string! The should use additional methods
96  * of the specific tsocket_address implemention to get more details.
97  *
98  * @param[in]  addr     The address to convert.
99  *
100  * @param[in]  mem_ctx  The talloc memory context to allocate the memory.
101  *
102  * @return              The address as a string representation, NULL on error.
103  *
104  * @see tsocket_address_inet_addr_string()
105  * @see tsocket_address_inet_port()
106  */
107 char *tsocket_address_string(const struct tsocket_address *addr,
108                              TALLOC_CTX *mem_ctx);
109
110 #ifdef DOXYGEN
111 /**
112  * @brief This creates a copy of a tsocket_address.
113  *
114  * This is useful when before doing modifications to a socket via additional
115  * methods of the specific tsocket_address implementation.
116  *
117  * @param[in]  addr     The address to create the copy from.
118  *
119  * @param[in]  mem_ctx  The talloc memory context to use.
120  *
121  * @return              A newly allocated copy of addr (tsocket_address *), NULL
122  *                      on error.
123  */
124 struct tsocket_address *tsocket_address_copy(const struct tsocket_address *addr,
125                 TALLOC_CTX *mem_ctx);
126 #else
127 struct tsocket_address *_tsocket_address_copy(const struct tsocket_address *addr,
128                                               TALLOC_CTX *mem_ctx,
129                                               const char *location);
130
131 #define tsocket_address_copy(addr, mem_ctx) \
132         _tsocket_address_copy(addr, mem_ctx, __location__)
133 #endif
134
135 /**
136  * @}
137  */
138
139 /**
140  * @defgroup tdgram_context The tdgram_context abstraction
141  * @ingroup tsocket
142  *
143  * The tdgram_context is like an abstract class for datagram based sockets. The
144  * interface provides async 'tevent_req' based functions on top functionality
145  * is similar to the recvfrom(2)/sendto(2)/close(2) syscalls.
146  *
147  * @note You can always use talloc_free(tdgram) to cleanup the resources
148  * of the tdgram_context on a fatal error.
149  * @{
150  */
151
152 /**
153  * @brief Ask for next available datagram on the abstracted tdgram_context.
154  *
155  * It returns a 'tevent_req' handle, where the caller can register
156  * a callback with tevent_req_set_callback(). The callback is triggered
157  * when a datagram is available or an error happened.
158  *
159  * @param[in]  mem_ctx  The talloc memory context to use.
160  *
161  * @param[in]  ev       The tevent_context to run on.
162  *
163  * @param[in]  dgram    The dgram context to work on.
164  *
165  * @return              Returns a 'tevent_req' handle, where the caller can
166  *                      register a callback with tevent_req_set_callback().
167  *                      NULL on fatal error.
168  *
169  * @see tdgram_inet_udp_socket()
170  * @see tdgram_unix_socket()
171  */
172 struct tevent_req *tdgram_recvfrom_send(TALLOC_CTX *mem_ctx,
173                                         struct tevent_context *ev,
174                                         struct tdgram_context *dgram);
175
176 /**
177  * @brief Receive the next available datagram on the abstracted tdgram_context.
178  *
179  * This function should be called by the callback when a datagram is available
180  * or an error happened.
181  *
182  * The caller can only have one outstanding tdgram_recvfrom_send() at a time
183  * otherwise the caller will get '*perrno = EBUSY'.
184  *
185  * @param[in]  req      The tevent request from tdgram_recvfrom_send().
186  *
187  * @param[out] perrno   The error number, set if an error occured.
188  *
189  * @param[in]  mem_ctx  The memory context to use.
190  *
191  * @param[out] buf      This will hold the buffer of the datagram.
192  *
193  * @param[out] src      The abstracted tsocket_address of the sender of the
194  *                      received datagram.
195  *
196  * @return              The length of the datagram (0 is never returned!),
197  *                      -1 on error with perrno set to the actual errno.
198  *
199  * @see tdgram_recvfrom_send()
200  */
201 ssize_t tdgram_recvfrom_recv(struct tevent_req *req,
202                              int *perrno,
203                              TALLOC_CTX *mem_ctx,
204                              uint8_t **buf,
205                              struct tsocket_address **src);
206
207 /**
208  * @brief Send a datagram to a destination endpoint.
209  *
210  * The function can be called to send a datagram (specified by a buf/len) to a
211  * destination endpoint (specified by dst). It's not allowed for len to be 0.
212  *
213  * It returns a 'tevent_req' handle, where the caller can register a callback
214  * with tevent_req_set_callback(). The callback is triggered when the specific
215  * implementation (assumes it) has delivered the datagram to the "wire".
216  *
217  * The callback is then supposed to get the result by calling
218  * tdgram_sendto_recv() on the 'tevent_req'.
219  *
220  * @param[in]  mem_ctx  The talloc memory context to use.
221  *
222  * @param[in]  ev       The tevent_context to run on.
223  *
224  * @param[in]  dgram    The dgram context to work on.
225  *
226  * @param[in]  buf      The buffer to send.
227  *
228  * @param[in]  len      The length of the buffer to send. It has to be bigger
229  *                      than 0.
230  *
231  * @param[in]  dst      The destination to send the datagram to in form of a
232  *                      tsocket_address.
233  *
234  * @return              Returns a 'tevent_req' handle, where the caller can
235  *                      register a callback with tevent_req_set_callback().
236  *                      NULL on fatal error.
237  *
238  * @see tdgram_inet_udp_socket()
239  * @see tdgram_unix_socket()
240  * @see tdgram_sendto_recv()
241  */
242 struct tevent_req *tdgram_sendto_send(TALLOC_CTX *mem_ctx,
243                                       struct tevent_context *ev,
244                                       struct tdgram_context *dgram,
245                                       const uint8_t *buf, size_t len,
246                                       const struct tsocket_address *dst);
247
248 /**
249  * @brief Receive the result of the sent datagram.
250  *
251  * The caller can only have one outstanding tdgram_sendto_send() at a time
252  * otherwise the caller will get '*perrno = EBUSY'.
253  *
254  * @param[in]  req      The tevent request from tdgram_sendto_send().
255  *
256  * @param[out] perrno   The error number, set if an error occured.
257  *
258  * @return              The length of the datagram (0 is never returned!), -1 on
259  *                      error with perrno set to the actual errno.
260  *
261  * @see tdgram_sendto_send()
262  */
263 ssize_t tdgram_sendto_recv(struct tevent_req *req,
264                            int *perrno);
265
266 /**
267  * @brief Shutdown/close an abstracted socket.
268  *
269  * It returns a 'tevent_req' handle, where the caller can register a callback
270  * with tevent_req_set_callback(). The callback is triggered when the specific
271  * implementation (assumes it) has delivered the datagram to the "wire".
272  *
273  * The callback is then supposed to get the result by calling
274  * tdgram_sendto_recv() on the 'tevent_req'.
275  *
276  * @param[in]  mem_ctx  The talloc memory context to use.
277  *
278  * @param[in]  ev       The tevent_context to run on.
279  *
280  * @param[in]  dgram    The dgram context diconnect from.
281  *
282  * @return              Returns a 'tevent_req' handle, where the caller can
283  *                      register a callback with tevent_req_set_callback().
284  *                      NULL on fatal error.
285  *
286  * @see tdgram_disconnect_recv()
287  */
288 struct tevent_req *tdgram_disconnect_send(TALLOC_CTX *mem_ctx,
289                                           struct tevent_context *ev,
290                                           struct tdgram_context *dgram);
291
292 /**
293  * @brief Receive the result from a tdgram_disconnect_send() request.
294  *
295  * The caller should make sure there're no outstanding tdgram_recvfrom_send()
296  * and tdgram_sendto_send() calls otherwise the caller will get
297  * '*perrno = EBUSY'.
298  *
299  * @param[in]  req      The tevent request from tdgram_disconnect_send().
300  *
301  * @param[out] perrno   The error number, set if an error occured.
302  *
303  * @return              The length of the datagram (0 is never returned!), -1 on
304  *                      error with perrno set to the actual errno.
305  *
306  * @see tdgram_disconnect_send()
307  */
308 int tdgram_disconnect_recv(struct tevent_req *req,
309                            int *perrno);
310
311 /**
312  * @}
313  */
314
315 /**
316  * @defgroup tstream_context The tstream_context abstraction
317  * @ingroup tsocket
318  *
319  * The tstream_context is like an abstract class for stream based sockets. The
320  * interface provides async 'tevent_req' based functions on top functionality
321  * is similar to the readv(2)/writev(2)/close(2) syscalls.
322  *
323  * @note You can always use talloc_free(tstream) to cleanup the resources
324  * of the tstream_context on a fatal error.
325  *
326  * @{
327  */
328
329 /**
330  * @brief Report the number of bytes received but not consumed yet.
331  *
332  * The tstream_pending_bytes() function reports how much bytes of the incoming
333  * stream have been received but not consumed yet.
334  *
335  * @param[in]  stream   The tstream_context to check for pending bytes.
336  *
337  * @return              The number of bytes received, -1 on error with errno
338  *                      set.
339  */
340 ssize_t tstream_pending_bytes(struct tstream_context *stream);
341
342 /**
343  * @brief Read a specific amount of bytes from a stream socket.
344  *
345  * The function can be called to read for a specific amount of bytes from the
346  * stream into given buffers. The caller has to preallocate the buffers.
347  *
348  * The caller might need to use tstream_pending_bytes() if the protocol doesn't
349  * have a fixed pdu header containing the pdu size.
350  *
351  * @param[in]  mem_ctx  The talloc memory context to use.
352  *
353  * @param[in]  ev       The tevent_context to run on.
354  *
355  * @param[in]  stream   The tstream context to work on.
356  *
357  * @param[out] vector   A preallocated iovec to store the data to read.
358  *
359  * @param[in]  count    The number of buffers in the vector allocated.
360  *
361  * @return              A 'tevent_req' handle, where the caller can register
362  *                      a callback with tevent_req_set_callback(). NULL on
363  *                      fatal error.
364  *
365  * @see tstream_unix_connect_send()
366  * @see tstream_inet_tcp_connect_send()
367  */
368 struct tevent_req *tstream_readv_send(TALLOC_CTX *mem_ctx,
369                                       struct tevent_context *ev,
370                                       struct tstream_context *stream,
371                                       struct iovec *vector,
372                                       size_t count);
373
374 /**
375  * @brief Get the result of a tstream_readv_send().
376  *
377  * The caller can only have one outstanding tstream_readv_send()
378  * at a time otherwise the caller will get *perrno = EBUSY.
379  *
380  * @param[in]  req      The tevent request from tstream_readv_send().
381  *
382  * @param[out] perrno   The error number, set if an error occured.
383  *
384  * @return              The length of the stream (0 is never returned!), -1 on
385  *                      error with perrno set to the actual errno.
386  */
387 int tstream_readv_recv(struct tevent_req *req,
388                        int *perrno);
389
390 /**
391  * @brief Write buffers from a vector into a stream socket.
392  *
393  * The function can be called to write buffers from a given vector
394  * to a stream socket.
395  *
396  * You have to ensure that the vector is not empty.
397  *
398  * @param[in]  mem_ctx  The talloc memory context to use.
399  *
400  * @param[in]  ev       The tevent_context to run on.
401  *
402  * @param[in]  stream   The tstream context to work on.
403  *
404  * @param[in]  vector   The iovec vector with data to write on a stream socket.
405  *
406  * @param[in]  count    The number of buffers in the vector to write.
407  *
408  * @return              A 'tevent_req' handle, where the caller can register
409  *                      a callback with tevent_req_set_callback(). NULL on
410  *                      fatal error.
411  */
412 struct tevent_req *tstream_writev_send(TALLOC_CTX *mem_ctx,
413                                        struct tevent_context *ev,
414                                        struct tstream_context *stream,
415                                        const struct iovec *vector,
416                                        size_t count);
417
418 /**
419  * @brief Get the result of a tstream_writev_send().
420  *
421  * The caller can only have one outstanding tstream_writev_send()
422  * at a time otherwise the caller will get *perrno = EBUSY.
423  *
424  * @param[in]  req      The tevent request from tstream_writev_send().
425  *
426  * @param[out] perrno   The error number, set if an error occured.
427  *
428  * @return              The length of the stream (0 is never returned!), -1 on
429  *                      error with perrno set to the actual errno.
430  */
431 int tstream_writev_recv(struct tevent_req *req,
432                         int *perrno);
433
434 /**
435  * @brief Shutdown/close an abstracted socket.
436  *
437  * It returns a 'tevent_req' handle, where the caller can register a callback
438  * with tevent_req_set_callback(). The callback is triggered when the specific
439  * implementation (assumes it) has delivered the stream to the "wire".
440  *
441  * The callback is then supposed to get the result by calling
442  * tdgram_sendto_recv() on the 'tevent_req'.
443  *
444  * @param[in]  mem_ctx  The talloc memory context to use.
445  *
446  * @param[in]  ev       The tevent_context to run on.
447  *
448  * @param[in]  stream   The tstream context to work on.
449  *
450  * @return              A 'tevent_req' handle, where the caller can register
451  *                      a callback with tevent_req_set_callback(). NULL on
452  *                      fatal error.
453  */
454 struct tevent_req *tstream_disconnect_send(TALLOC_CTX *mem_ctx,
455                                            struct tevent_context *ev,
456                                            struct tstream_context *stream);
457
458 /**
459  * @brief Get the result of a tstream_disconnect_send().
460  *
461  * The caller can only have one outstanding tstream_writev_send()
462  * at a time otherwise the caller will get *perrno = EBUSY.
463  *
464  * @param[in]  req      The tevent request from tstream_disconnect_send().
465  *
466  * @param[out] perrno   The error number, set if an error occured.
467  *
468  * @return              The length of the stream (0 is never returned!), -1 on
469  *                      error with perrno set to the actual errno.
470  */
471 int tstream_disconnect_recv(struct tevent_req *req,
472                             int *perrno);
473
474 /**
475  * @}
476  */
477
478
479 /**
480  * @defgroup tsocket_bsd  tsocket_bsd - inet, inet6 and unix
481  * @ingroup tsocket
482  *
483  * The main tsocket library comes with implentations for BSD style ipv4, ipv6
484  * and unix sockets.
485  *
486  * @{
487  */
488
489 #if DOXYGEN
490 /**
491  * @brief Create a tsocket_address for ipv4 and ipv6 endpoint addresses.
492  *
493  * @param[in]  mem_ctx  The talloc memory context to use.
494  *
495  * @param[in]  fam      The family can be can be "ipv4", "ipv6" or "ip". With
496  *                      "ip" is autodetects "ipv4" or "ipv6" based on the
497  *                      addr.
498  *
499  * @param[in]  addr     A valid ip address string based on the selected family
500  *                      (dns names are not allowed!). It's valid to pass NULL,
501  *                      which gets mapped to "0.0.0.0" or "::".
502  *
503  * @param[in]  port     A valid port number.
504  *
505  * @param[out] _addr    A tsocket_address pointer to store the information.
506  *
507  * @return              0 on success, -1 on error with errno set.
508  */
509 int tsocket_address_inet_from_strings(TALLOC_CTX *mem_ctx,
510                                       const char *fam,
511                                       const char *addr,
512                                       uint16_t port,
513                                       struct tsocket_address **_addr);
514 #else
515 int _tsocket_address_inet_from_strings(TALLOC_CTX *mem_ctx,
516                                        const char *fam,
517                                        const char *addr,
518                                        uint16_t port,
519                                        struct tsocket_address **_addr,
520                                        const char *location);
521
522 #define tsocket_address_inet_from_strings(mem_ctx, fam, addr, port, _addr) \
523         _tsocket_address_inet_from_strings(mem_ctx, fam, addr, port, _addr, \
524                                            __location__)
525 #endif
526
527 /**
528  * @brief Get the address of an 'inet' tsocket_address as a string.
529  *
530  * @param[in]  addr     The address to convert to a string.
531  *
532  * @param[in]  mem_ctx  The talloc memory context to use.
533  *
534  * @return              A newly allocated string of the address, NULL on error
535  *                      with errno set.
536  */
537 char *tsocket_address_inet_addr_string(const struct tsocket_address *addr,
538                                        TALLOC_CTX *mem_ctx);
539
540 /**
541  * @brief Get the port number as an integer from an 'inet' tsocket_address.
542  *
543  * @param[in]  addr     The tsocket address to use.
544  *
545  * @return              The port number, 0 on error with errno set.
546  */
547 uint16_t tsocket_address_inet_port(const struct tsocket_address *addr);
548
549 /**
550  * @brief Set the port number of an existing 'inet' tsocket_address.
551  *
552  * @param[in]  addr     The existing tsocket_address to use.
553  *
554  * @param[in]  port     The valid port number to set.
555  *
556  * @return              0 on success, -1 on error with errno set.
557  */
558 int tsocket_address_inet_set_port(struct tsocket_address *addr,
559                                   uint16_t port);
560
561 #ifdef DOXYGEN
562 /**
563  * @brief Create a tsocket_address for a unix domain endpoint addresses.
564  *
565  * @param[in]  mem_ctx  The talloc memory context to use.
566  *
567  * @param[in]  path     The filesystem path, NULL will map "".
568  *
569  * @param[in]  _addr    The tsocket_address pointer to store the information.
570  *
571  * @return              0 on success, -1 on error with errno set.
572  */
573 int tsocket_address_unix_from_path(TALLOC_CTX *mem_ctx,
574                                    const char *path,
575                                    struct tsocket_address **_addr);
576 #else
577 int _tsocket_address_unix_from_path(TALLOC_CTX *mem_ctx,
578                                     const char *path,
579                                     struct tsocket_address **_addr,
580                                     const char *location);
581
582 #define tsocket_address_unix_from_path(mem_ctx, path, _addr) \
583         _tsocket_address_unix_from_path(mem_ctx, path, _addr, \
584                                         __location__)
585 #endif
586
587 /**
588  * @brief Get the address of an 'unix' tsocket_address.
589  *
590  * @param[in]  addr     A valid 'unix' tsocket_address.
591  *
592  * @param[in]  mem_ctx  The talloc memory context to use.
593  *
594  * @return              The path of the unix domain socket, NULL on error or if
595  *                      the tsocket_address doesn't represent an unix domain
596  *                      endpoint path.
597  */
598 char *tsocket_address_unix_path(const struct tsocket_address *addr,
599                                 TALLOC_CTX *mem_ctx);
600
601 #ifdef DOXYGEN
602 /**
603  * @brief Create a tdgram_context for a ipv4 or ipv6 UDP communication.
604  *
605  * @param[in]  local    An 'inet' tsocket_address for the local endpoint.
606  *
607  * @param[in]  remote   An 'inet' tsocket_address for the remote endpoint or
608  *                      NULL (??? to create a listener?).
609  *
610  * @param[in]  mem_ctx  The talloc memory context to use.
611  *
612  * @param[in]  dgram    The tdgram_context pointer to setup the udp
613  *                      communication. The function will allocate the memory.
614  *
615  * @return              0 on success, -1 on error with errno set.
616  */
617 int tdgram_inet_udp_socket(const struct tsocket_address *local,
618                             const struct tsocket_address *remote,
619                             TALLOC_CTX *mem_ctx,
620                             struct tdgram_context **dgram);
621 #else
622 int _tdgram_inet_udp_socket(const struct tsocket_address *local,
623                             const struct tsocket_address *remote,
624                             TALLOC_CTX *mem_ctx,
625                             struct tdgram_context **dgram,
626                             const char *location);
627 #define tdgram_inet_udp_socket(local, remote, mem_ctx, dgram) \
628         _tdgram_inet_udp_socket(local, remote, mem_ctx, dgram, __location__)
629 #endif
630
631 #ifdef DOXYGEN
632 /**
633  * @brief Create a tdgram_context for unix domain datagram communication.
634  *
635  * @param[in]  local    An 'unix' tsocket_address for the local endpoint.
636  *
637  * @param[in]  remote   An 'unix' tsocket_address for the remote endpoint or
638  *                      NULL (??? to create a listener?).
639  *
640  * @param[in]  mem_ctx  The talloc memory context to use.
641  *
642  * @param[in]  dgram    The tdgram_context pointer to setup the udp
643  *                      communication. The function will allocate the memory.
644  *
645  * @return              0 on success, -1 on error with errno set.
646  */
647 int tdgram_unix_socket(const struct tsocket_address *local,
648                         const struct tsocket_address *remote,
649                         TALLOC_CTX *mem_ctx,
650                         struct tdgram_context **dgram);
651 #else
652 int _tdgram_unix_socket(const struct tsocket_address *local,
653                         const struct tsocket_address *remote,
654                         TALLOC_CTX *mem_ctx,
655                         struct tdgram_context **dgram,
656                         const char *location);
657
658 #define tdgram_unix_socket(local, remote, mem_ctx, dgram) \
659         _tdgram_unix_socket(local, remote, mem_ctx, dgram, __location__)
660 #endif
661
662 /**
663  * @brief Connect async to a TCP endpoint and create a tstream_context for the
664  * stream based communication.
665  *
666  * Use this function to connenct asynchronously to a remote ipv4 or ipv6 TCP
667  * endpoint and create a tstream_context for the stream based communication.
668  *
669  * @param[in]  mem_ctx  The talloc memory context to use.
670  *
671  * @param[in]  ev       The tevent_context to run on.
672  *
673  * @param[in]  local    An 'inet' tsocket_address for the local endpoint.
674  *
675  * @param[in]  remote   An 'inet' tsocket_address for the remote endpoint.
676  *
677  * @return              A 'tevent_req' handle, where the caller can register a
678  *                      callback with tevent_req_set_callback(). NULL on a fatal
679  *                      error.
680  *
681  * @see tstream_inet_tcp_connect_recv()
682  */
683 struct tevent_req *tstream_inet_tcp_connect_send(TALLOC_CTX *mem_ctx,
684                                         struct tevent_context *ev,
685                                         const struct tsocket_address *local,
686                                         const struct tsocket_address *remote);
687
688 #ifdef DOXYGEN
689 /**
690  * @brief Receive the result from a tstream_inet_tcp_connect_send().
691  *
692  * @param[in]  req      The tevent request from tstream_inet_tcp_connect_send().
693  *
694  * @param[out] perrno   The error number, set if an error occured.
695  *
696  * @param[in]  mem_ctx  The talloc memory context to use.
697  *
698  * @param[in]  stream   A tstream_context pointer to setup the tcp communication
699  *                      on. This function will allocate the memory.
700  *
701  * @return              0 on success, -1 on error with perrno set.
702  */
703 int tstream_inet_tcp_connect_recv(struct tevent_req *req,
704                                   int *perrno,
705                                   TALLOC_CTX *mem_ctx,
706                                   struct tstream_context **stream);
707 #else
708 int _tstream_inet_tcp_connect_recv(struct tevent_req *req,
709                                    int *perrno,
710                                    TALLOC_CTX *mem_ctx,
711                                    struct tstream_context **stream,
712                                    const char *location);
713 #define tstream_inet_tcp_connect_recv(req, perrno, mem_ctx, stream) \
714         _tstream_inet_tcp_connect_recv(req, perrno, mem_ctx, stream, \
715                                        __location__)
716 #endif
717
718 /**
719  * @brief Connect async to a unix domain endpoint and create a tstream_context
720  * for the stream based communication.
721  *
722  * Use this function to connenct asynchronously to a unix domainendpoint and
723  * create a tstream_context for the stream based communication.
724  *
725  * The callback is triggered when a socket is connected and ready for IO or an
726  * error happened.
727  *
728  * @param[in]  mem_ctx  The talloc memory context to use.
729  *
730  * @param[in]  ev       The tevent_context to run on.
731  *
732  * @param[in]  local    An 'unix' tsocket_address for the local endpoint.
733  *
734  * @param[in]  remote   An 'unix' tsocket_address for the remote endpoint.
735  *
736  * @return              A 'tevent_req' handle, where the caller can register a
737  *                      callback with tevent_req_set_callback(). NULL on a falal
738  *                      error.
739  *
740  * @see tstream_unix_connect_recv()
741  */
742 struct tevent_req * tstream_unix_connect_send(TALLOC_CTX *mem_ctx,
743                                         struct tevent_context *ev,
744                                         const struct tsocket_address *local,
745                                         const struct tsocket_address *remote);
746
747 #ifdef DOXYGEN
748 /**
749  * @brief Receive the result from a tstream_unix_connect_send().
750  *
751  * @param[in]  req      The tevent request from tstream_inet_tcp_connect_send().
752  *
753  * @param[out] perrno   The error number, set if an error occured.
754  *
755  * @param[in]  mem_ctx  The talloc memory context to use.
756  *
757  * @param[in]  stream   The tstream context to work on.
758  *
759  * @return              0 on success, -1 on error with perrno set.
760  */
761 int tstream_unix_connect_recv(struct tevent_req *req,
762                               int *perrno,
763                               TALLOC_CTX *mem_ctx,
764                               struct tstream_context **stream);
765 #else
766 int _tstream_unix_connect_recv(struct tevent_req *req,
767                                int *perrno,
768                                TALLOC_CTX *mem_ctx,
769                                struct tstream_context **stream,
770                                const char *location);
771 #define tstream_unix_connect_recv(req, perrno, mem_ctx, stream) \
772         _tstream_unix_connect_recv(req, perrno, mem_ctx, stream, \
773                                           __location__)
774 #endif
775
776 #ifdef DOXYGEN
777 /**
778  * @brief Create two connected 'unix' tsocket_contexts for stream based
779  *        communication.
780  *
781  * @param[in]  mem_ctx1 The talloc memory context to use for stream1.
782  *
783  * @param[in]  stream1  The first stream to connect.
784  *
785  * @param[in]  mem_ctx2 The talloc memory context to use for stream2.
786  *
787  * @param[in]  stream2  The second stream to connect.
788  *
789  * @return              0 on success, -1 on error with errno set.
790  */
791 int tstream_unix_socketpair(TALLOC_CTX *mem_ctx1,
792                             struct tstream_context **stream1,
793                             TALLOC_CTX *mem_ctx2,
794                             struct tstream_context **stream2);
795 #else
796 int _tstream_unix_socketpair(TALLOC_CTX *mem_ctx1,
797                              struct tstream_context **_stream1,
798                              TALLOC_CTX *mem_ctx2,
799                              struct tstream_context **_stream2,
800                              const char *location);
801
802 #define tstream_unix_socketpair(mem_ctx1, stream1, mem_ctx2, stream2) \
803         _tstream_unix_socketpair(mem_ctx1, stream1, mem_ctx2, stream2, \
804                                  __location__)
805 #endif
806
807 struct sockaddr;
808
809 #ifdef DOXYGEN
810 /**
811  * @brief Convert a tsocket address to a bsd socket address.
812  *
813  * @param[in]  mem_ctx  The talloc memory context to use.
814  *
815  * @param[in]  sa       The sockaddr structure to convert.
816  *
817  * @param[in]  sa_socklen   The lenth of the sockaddr sturucte.
818  *
819  * @param[out] addr     The tsocket pointer to allocate and fill.
820  *
821  * @return              0 on success, -1 on error with errno set.
822  */
823 int tsocket_address_bsd_from_sockaddr(TALLOC_CTX *mem_ctx,
824                                       struct sockaddr *sa,
825                                       size_t sa_socklen,
826                                       struct tsocket_address **addr);
827 #else
828 int _tsocket_address_bsd_from_sockaddr(TALLOC_CTX *mem_ctx,
829                                        struct sockaddr *sa,
830                                        size_t sa_socklen,
831                                        struct tsocket_address **_addr,
832                                        const char *location);
833
834 #define tsocket_address_bsd_from_sockaddr(mem_ctx, sa, sa_socklen, _addr) \
835         _tsocket_address_bsd_from_sockaddr(mem_ctx, sa, sa_socklen, _addr, \
836                                            __location__)
837 #endif
838
839 /**
840  * @brief Fill a bsd sockaddr structure.
841  *
842  * @param[in]  addr     The tsocket address structure to use.
843  *
844  * @param[in]  sa       The bsd sockaddr structure to fill out.
845  *
846  * @param[in]  sa_socklen   The length of the  bsd sockaddr structure to fill out.
847  *
848  * @return              The actual size of the sockaddr structure, -1 on error
849  *                      with errno set. The size could differ from sa_socklen.
850  *
851  * @code
852  *   ssize_t socklen;
853  *   struct sockaddr_storage ss;
854  *
855  *   socklen = tsocket_address_bsd_sockaddr(taddr,
856  *                    (struct sockaddr *) &ss,
857  *                    sizeof(struct sockaddr_storage));
858  *   if (socklen < 0) {
859  *     return -1;
860  *   }
861  * @endcode
862  */
863 ssize_t tsocket_address_bsd_sockaddr(const struct tsocket_address *addr,
864                                      struct sockaddr *sa,
865                                      size_t sa_socklen);
866
867 #ifdef DOXYGEN
868 /**
869  * @brief Wrap an existing file descriptors into the tstream abstraction.
870  *
871  * You can use this function to wrap an existing file descriptors into the
872  * tstream abstraction.
873  *
874  * @param[in]  mem_ctx      The talloc memory context to use.
875  *
876  * @param[in]  fd           The non blocking fd to use!
877  *
878  * @param[in]  stream       The filed tstream_context you allocated before.
879  *
880  * @return              0 on success, -1 on error with errno set.
881  *
882  * @warning You should read the tsocket_bsd.c code and unterstand it in order
883  * use this function.
884  */
885 int tstream_bsd_existing_socket(TALLOC_CTX *mem_ctx,
886                                 int fd,
887                                 struct tstream_context **stream);
888 #else
889 int _tstream_bsd_existing_socket(TALLOC_CTX *mem_ctx,
890                                  int fd,
891                                  struct tstream_context **_stream,
892                                  const char *location);
893 #define tstream_bsd_existing_socket(mem_ctx, fd, stream) \
894         _tstream_bsd_existing_socket(mem_ctx, fd, stream, \
895                                      __location__)
896 #endif
897
898 /**
899  * @}
900  */
901
902 /**
903  * @defgroup tsocket_helper Queue and PDU helpers
904  * @ingroup tsocket
905  *
906  * In order to make the live easier for callers which want to implement a
907  * function to receive a full PDU with a single async function pair, there're
908  * some helper functions.
909  *
910  * There're some cases where the caller wants doesn't care about the order of
911  * doing IO on the abstracted sockets.
912  *
913  * @{
914  */
915
916 /**
917  * @brief Queue a dgram blob for sending through the socket.
918  *
919  * This function queues a blob for sending to destination through an existing
920  * dgram socket. The async callback is triggered when the whole blob is
921  * delivered to the underlying system socket.
922  *
923  * The caller needs to make sure that all non-scalar input parameters hang
924  * arround for the whole lifetime of the request.
925  *
926  * @param[in]  mem_ctx  The memory context for the result.
927  *
928  * @param[in]  ev       The event context the operation should work on.
929  *
930  * @param[in]  dgram    The tdgram_context to send the message buffer.
931  *
932  * @param[in]  queue    The existing dgram queue.
933  *
934  * @param[in]  buf      The message buffer to send.
935  *
936  * @param[in]  len      The message length.
937  *
938  * @param[in]  dst      The destination socket address.
939  *
940  * @return              The async request handle. NULL on fatal error.
941  *
942  * @see tdgram_sendto_queue_recv()
943  */
944 struct tevent_req *tdgram_sendto_queue_send(TALLOC_CTX *mem_ctx,
945                                             struct tevent_context *ev,
946                                             struct tdgram_context *dgram,
947                                             struct tevent_queue *queue,
948                                             const uint8_t *buf,
949                                             size_t len,
950                                             struct tsocket_address *dst);
951
952 /**
953  * @brief Receive the result of the sent dgram blob.
954  *
955  * @param[in]  req      The tevent request from tdgram_sendto_queue_send().
956  *
957  * @param[out] perrno   The error set to the actual errno.
958  *
959  * @return              The length of the datagram (0 is never returned!), -1 on
960  *                      error with perrno set to the actual errno.
961  */
962 ssize_t tdgram_sendto_queue_recv(struct tevent_req *req, int *perrno);
963
964 typedef int (*tstream_readv_pdu_next_vector_t)(struct tstream_context *stream,
965                                                void *private_data,
966                                                TALLOC_CTX *mem_ctx,
967                                                struct iovec **vector,
968                                                size_t *count);
969
970 struct tevent_req *tstream_readv_pdu_send(TALLOC_CTX *mem_ctx,
971                                 struct tevent_context *ev,
972                                 struct tstream_context *stream,
973                                 tstream_readv_pdu_next_vector_t next_vector_fn,
974                                 void *next_vector_private);
975 int tstream_readv_pdu_recv(struct tevent_req *req, int *perrno);
976
977 /**
978  * @brief Queue a dgram blob for sending through the socket.
979  *
980  * This function queues a blob for sending to destination through an existing
981  * dgram socket. The async callback is triggered when the whole blob is
982  * delivered to the underlying system socket.
983  *
984  * The caller needs to make sure that all non-scalar input parameters hang
985  * arround for the whole lifetime of the request.
986  *
987  * @param[in]  mem_ctx  The memory context for the result
988  *
989  * @param[in]  ev       The tevent_context to run on
990  *
991  * @param[in]  stream   The stream to send data through
992  *
993  * @param[in]  queue    The existing send queue
994  *
995  * @param[in]  next_vector_fn  The next vector function
996  *
997  * @param[in]  next_vector_private  The private_data of the next vector function
998  *
999  * @return              The async request handle. NULL on fatal error.
1000  *
1001  * @see tstream_readv_pdu_queue_recv()
1002  */
1003 struct tevent_req *tstream_readv_pdu_queue_send(TALLOC_CTX *mem_ctx,
1004                                 struct tevent_context *ev,
1005                                 struct tstream_context *stream,
1006                                 struct tevent_queue *queue,
1007                                 tstream_readv_pdu_next_vector_t next_vector_fn,
1008                                 void *next_vector_private);
1009
1010 /**
1011  * @brief Receive the result of the sent dgram blob.
1012  *
1013  * @param[in]  req      The tevent request from tstream_readv_pdu_queue_send().
1014  *
1015  * @param[out] perrno   The error set to the actual errno.
1016  *
1017  * @return              The length of the datagram (0 is never returned!), -1 on
1018  *                      error with perrno set to the actual errno.
1019  */
1020 int tstream_readv_pdu_queue_recv(struct tevent_req *req, int *perrno);
1021
1022 /**
1023  * @brief Queue a dgram blob for sending through the socket
1024  *
1025  * This function queues a blob for sending to destination through an existing
1026  * dgram socket. The async callback is triggered when the whole blob is
1027  * delivered to the underlying system socket.
1028  *
1029  * The caller needs to make sure that all non-scalar input parameters hang
1030  * arround for the whole lifetime of the request.
1031  *
1032  * @param[in]  mem_ctx  The memory context for the result.
1033  *
1034  * @param[in]  ev       The tevent_context to run on.
1035  *
1036  * @param[in]  stream   The stream to send data through.
1037  *
1038  * @param[in]  queue    The existing send queue.
1039  *
1040  * @param[in]  vector   The iovec vector so write.
1041  *
1042  * @param[in]  count    The size of the vector.
1043  *
1044  * @return              The async request handle. NULL on fatal error.
1045  */
1046 struct tevent_req *tstream_writev_queue_send(TALLOC_CTX *mem_ctx,
1047                                              struct tevent_context *ev,
1048                                              struct tstream_context *stream,
1049                                              struct tevent_queue *queue,
1050                                              const struct iovec *vector,
1051                                              size_t count);
1052
1053 /**
1054  * @brief Receive the result of the sent dgram blob.
1055  *
1056  * @param[in]  req      The tevent request from tstream_writev_queue_send().
1057  *
1058  * @param[out] perrno   The error set to the actual errno.
1059  *
1060  * @return              The length of the datagram (0 is never returned!), -1 on
1061  *                      error with perrno set to the actual errno.
1062  */
1063 int tstream_writev_queue_recv(struct tevent_req *req, int *perrno);
1064
1065 /**
1066  * @}
1067  */
1068
1069 #endif /* _TSOCKET_H */
1070