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 <tevent.h>
  28
  29 struct tsocket_address;
  30 struct tdgram_context;
  31 struct tstream_context;
  32 struct iovec;
  33
  34 /**
  35  * @mainpage
  36  *
  37  * The tsocket abstraction is an API ...
  38  */
  39
  40 /**
  41  * @defgroup tsocket The tsocket API
  42  *
  43  * The tsocket abstraction is split into two different kinds of
  44  * communication interfaces.
  45  *
  46  * There's the "tstream_context" interface with abstracts the communication
  47  * through a bidirectional byte stream between two endpoints.
  48  *
  49  * And there's the "tdgram_context" interface with abstracts datagram based
  50  * communication between any number of endpoints.
  51  *
  52  * Both interfaces share the "tsocket_address" abstraction for endpoint
  53  * addresses.
  54  *
  55  * The whole library is based on the talloc(3) and 'tevent' libraries and
  56  * provides "tevent_req" based "foo_send()"/"foo_recv()" functions pairs for
  57  * all abstracted methods that need to be async.
  58  *
  59  * @section vsock Virtual Sockets
  60  *
  61  * The abstracted layout of tdgram_context and tstream_context allow
  62  * implementations around virtual sockets for encrypted tunnels (like TLS,
  63  * SASL or GSSAPI) or named pipes over smb.
  64  *
  65  * @section npa Named Pipe Auth (NPA) Sockets
  66  *
  67  * Samba has an implementation to abstract named pipes over smb (within the
  68  * server side). See libcli/named_pipe_auth/npa_tstream.[ch] for the core code.
  69  * The current callers are located in source4/ntvfs/ipc/vfs_ipc.c and
  70  * source4/rpc_server/service_rpc.c for the users.
  71  */
  72
  73 /**
  74  * @defgroup tsocket_address The tsocket_address abstraction
  75  * @ingroup tsocket
  76  *
  77  * The tsocket_address represents an socket endpoint genericly.
  78  * As it's like an abstract class it has no specific constructor.
  79  * The specific constructors are descripted in later sections.
  80  *
  81  * @{
  82  */
  83
  84 /**
  85  * @brief Get a string representation of the endpoint.
  86  *
  87  * This function creates a string representation of the endpoint for debugging.
  88  * The output will look as followed:
  89  *      prefix:address:port
  90  *
  91  * e.g.
  92  *      ipv4:192.168.1.1:143
  93  *
  94  * Callers should not try to parse the string! The should use additional methods
  95  * of the specific tsocket_address implemention to get more details.
  96  *
  97  * @param[in]  addr     The address to convert.
  98  *
  99  * @param[in]  mem_ctx  The talloc memory context to allocate the memory.
 100  *
 101  * @return              The address as a string representation, NULL on error.
 102  *
 103  * @see tsocket_address_is_inet()
 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 occurred.
 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 occurred.
 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 occurred.
 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 occurred.
 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 occurred.
 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 occurred.
 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 /**
 490  * @brief Find out if the tsocket_address represents an ipv4 or ipv6 endpoint.
 491  *
 492  * @param[in]  addr     The tsocket_address pointer
 493  *
 494  * @param[in]  fam      The family can be can be "ipv4", "ipv6" or "ip". With
 495  *                      "ip" is autodetects "ipv4" or "ipv6" based on the
 496  *                      addr.
 497  *
 498  * @return              true if addr represents an address of the given family,
 499  *                      otherwise false.
 500  */
 501 bool tsocket_address_is_inet(const struct tsocket_address *addr, const char *fam);
 502
 503 #ifdef DOXYGEN
 504 /**
 505  * @brief Create a tsocket_address for ipv4 and ipv6 endpoint addresses.
 506  *
 507  * @param[in]  mem_ctx  The talloc memory context to use.
 508  *
 509  * @param[in]  fam      The family can be can be "ipv4", "ipv6" or "ip". With
 510  *                      "ip" is autodetects "ipv4" or "ipv6" based on the
 511  *                      addr.
 512  *
 513  * @param[in]  addr     A valid ip address string based on the selected family
 514  *                      (dns names are not allowed!). It's valid to pass NULL,
 515  *                      which gets mapped to "0.0.0.0" or "::".
 516  *
 517  * @param[in]  port     A valid port number.
 518  *
 519  * @param[out] _addr    A tsocket_address pointer to store the information.
 520  *
 521  * @return              0 on success, -1 on error with errno set.
 522  */
 523 int tsocket_address_inet_from_strings(TALLOC_CTX *mem_ctx,
 524                                       const char *fam,
 525                                       const char *addr,
 526                                       uint16_t port,
 527                                       struct tsocket_address **_addr);
 528 #else
 529 int _tsocket_address_inet_from_strings(TALLOC_CTX *mem_ctx,
 530                                        const char *fam,
 531                                        const char *addr,
 532                                        uint16_t port,
 533                                        struct tsocket_address **_addr,
 534                                        const char *location);
 535
 536 #define tsocket_address_inet_from_strings(mem_ctx, fam, addr, port, _addr) \
 537         _tsocket_address_inet_from_strings(mem_ctx, fam, addr, port, _addr, \
 538                                            __location__)
 539 #endif
 540
 541 /**
 542  * @brief Get the address of an 'inet' tsocket_address as a string.
 543  *
 544  * @param[in]  addr     The address to convert to a string.
 545  *
 546  * @param[in]  mem_ctx  The talloc memory context to use.
 547  *
 548  * @return              A newly allocated string of the address, NULL on error
 549  *                      with errno set.
 550  *
 551  * @see tsocket_address_is_inet()
 552  */
 553 char *tsocket_address_inet_addr_string(const struct tsocket_address *addr,
 554                                        TALLOC_CTX *mem_ctx);
 555
 556 /**
 557  * @brief Get the port number as an integer from an 'inet' tsocket_address.
 558  *
 559  * @param[in]  addr     The tsocket address to use.
 560  *
 561  * @return              The port number, 0 on error with errno set.
 562  */
 563 uint16_t tsocket_address_inet_port(const struct tsocket_address *addr);
 564
 565 /**
 566  * @brief Set the port number of an existing 'inet' tsocket_address.
 567  *
 568  * @param[in]  addr     The existing tsocket_address to use.
 569  *
 570  * @param[in]  port     The valid port number to set.
 571  *
 572  * @return              0 on success, -1 on error with errno set.
 573  */
 574 int tsocket_address_inet_set_port(struct tsocket_address *addr,
 575                                   uint16_t port);
 576
 577 /**
 578  * @brief Find out if the tsocket_address represents an unix domain endpoint.
 579  *
 580  * @param[in]  addr     The tsocket_address pointer
 581  *
 582  * @return              true if addr represents an unix domain endpoint,
 583  *                      otherwise false.
 584  */
 585 bool tsocket_address_is_unix(const struct tsocket_address *addr);
 586
 587 #ifdef DOXYGEN
 588 /**
 589  * @brief Create a tsocket_address for a unix domain endpoint addresses.
 590  *
 591  * @param[in]  mem_ctx  The talloc memory context to use.
 592  *
 593  * @param[in]  path     The filesystem path, NULL will map "".
 594  *
 595  * @param[in]  _addr    The tsocket_address pointer to store the information.
 596  *
 597  * @return              0 on success, -1 on error with errno set.
 598  *
 599  * @see tsocket_address_is_unix()
 600  */
 601 int tsocket_address_unix_from_path(TALLOC_CTX *mem_ctx,
 602                                    const char *path,
 603                                    struct tsocket_address **_addr);
 604 #else
 605 int _tsocket_address_unix_from_path(TALLOC_CTX *mem_ctx,
 606                                     const char *path,
 607                                     struct tsocket_address **_addr,
 608                                     const char *location);
 609
 610 #define tsocket_address_unix_from_path(mem_ctx, path, _addr) \
 611         _tsocket_address_unix_from_path(mem_ctx, path, _addr, \
 612                                         __location__)
 613 #endif
 614
 615 /**
 616  * @brief Get the address of an 'unix' tsocket_address.
 617  *
 618  * @param[in]  addr     A valid 'unix' tsocket_address.
 619  *
 620  * @param[in]  mem_ctx  The talloc memory context to use.
 621  *
 622  * @return              The path of the unix domain socket, NULL on error or if
 623  *                      the tsocket_address doesn't represent an unix domain
 624  *                      endpoint path.
 625  */
 626 char *tsocket_address_unix_path(const struct tsocket_address *addr,
 627                                 TALLOC_CTX *mem_ctx);
 628
 629 #ifdef DOXYGEN
 630 /**
 631  * @brief Wrap an existing file descriptors into the tdgram abstraction.
 632  *
 633  * You can use this function to wrap an existing file descriptors into the
 634  * tdgram abstraction. After that you're not able to use this file descriptor
 635  * for anything else. The file descriptor will be closed when the stream gets
 636  * freed. If you still want to use the fd you have have to create a duplicate.
 637  *
 638  * @param[in]  mem_ctx  The talloc memory context to use.
 639  *
 640  * @param[in]  fd       The non blocking fd to use!
 641  *
 642  * @param[out] dgram    A pointer to store an allocated tdgram_context.
 643  *
 644  * @return              0 on success, -1 on error.
 645  *
 646  * Example:
 647  * @code
 648  *   fd2 = dup(fd);
 649  *   rc = tdgram_bsd_existing_socket(mem_ctx, fd2, &tdgram);
 650  *   if (rc < 0) {
 651  *     return;
 652  *   }
 653  * @endcode
 654  *
 655  * @warning This is an internal function. You should read the code to fully
 656  *          understand it if you plan to use it.
 657  */
 658 int tdgram_bsd_existing_socket(TALLOC_CTX *mem_ctx,
 659                                int fd,
 660                                struct tdgram_context **dgram);
 661 #else
 662 int _tdgram_bsd_existing_socket(TALLOC_CTX *mem_ctx,
 663                                 int fd,
 664                                 struct tdgram_context **_dgram,
 665                                 const char *location);
 666 #define tdgram_bsd_existing_socket(mem_ctx, fd, dgram) \
 667         _tdgram_bsd_existing_socket(mem_ctx, fd, dgram, \
 668                                     __location__)
 669 #endif
 670
 671 /**
 672  * @brief Request a syscall optimization for tdgram_recvfrom_send()
 673  *
 674  * This function is only used to reduce the amount of syscalls and
 675  * optimize performance. You should only use this if you know
 676  * what you're doing.
 677  *
 678  * The optimization is off by default.
 679  *
 680  * @param[in]  dgram    The tdgram_context of a bsd socket, if this
 681  *                      not a bsd socket the function does nothing.
 682  *
 683  * @param[in]  on       The boolean value to turn the optimization on and off.
 684  *
 685  * @return              The old boolean value.
 686  *
 687  * @see tdgram_recvfrom_send()
 688  */
 689 bool tdgram_bsd_optimize_recvfrom(struct tdgram_context *dgram,
 690                                   bool on);
 691
 692 #ifdef DOXYGEN
 693 /**
 694  * @brief Create a tdgram_context for a ipv4 or ipv6 UDP communication.
 695  *
 696  * @param[in]  local    An 'inet' tsocket_address for the local endpoint.
 697  *
 698  * @param[in]  remote   An 'inet' tsocket_address for the remote endpoint or
 699  *                      NULL (??? to create a listener?).
 700  *
 701  * @param[in]  mem_ctx  The talloc memory context to use.
 702  *
 703  * @param[in]  dgram    The tdgram_context pointer to setup the udp
 704  *                      communication. The function will allocate the memory.
 705  *
 706  * @return              0 on success, -1 on error with errno set.
 707  *
 708  * @see tdgram_inet_udp_broadcast_socket()
 709  */
 710 int tdgram_inet_udp_socket(const struct tsocket_address *local,
 711                             const struct tsocket_address *remote,
 712                             TALLOC_CTX *mem_ctx,
 713                             struct tdgram_context **dgram);
 714 #else
 715 int _tdgram_inet_udp_socket(const struct tsocket_address *local,
 716                             const struct tsocket_address *remote,
 717                             TALLOC_CTX *mem_ctx,
 718                             struct tdgram_context **dgram,
 719                             const char *location);
 720 #define tdgram_inet_udp_socket(local, remote, mem_ctx, dgram) \
 721         _tdgram_inet_udp_socket(local, remote, mem_ctx, dgram, __location__)
 722 #endif
 723
 724 #ifdef DOXYGEN
 725 /**
 726  * @brief Create a tdgram_context for a ipv4 UDP broadcast (and unicast) communication.
 727  *
 728  * @param[in]  local    An 'inet' (ipv4 only) tsocket_address for the local endpoint.
 729  *
 730  * @param[in]  mem_ctx  The talloc memory context to use.
 731  *
 732  * @param[in]  dgram    The tdgram_context pointer to setup the udp
 733  *                      communication. The function will allocate the memory.
 734  *
 735  * @return              0 on success, -1 on error with errno set.
 736  *
 737  * @see tdgram_inet_udp_socket()
 738  */
 739 int tdgram_inet_udp_broadcast_socket(const struct tsocket_address *local,
 740                                      TALLOC_CTX *mem_ctx,
 741                                      struct tdgram_context **dgram);
 742 #else
 743 int _tdgram_inet_udp_broadcast_socket(const struct tsocket_address *local,
 744                                       TALLOC_CTX *mem_ctx,
 745                                       struct tdgram_context **dgram,
 746                                       const char *location);
 747 #define tdgram_inet_udp_broadcast_socket(local, mem_ctx, dgram) \
 748         _tdgram_inet_udp_broadcast_socket(local, mem_ctx, dgram, __location__)
 749 #endif
 750
 751 #ifdef DOXYGEN
 752 /**
 753  * @brief Create a tdgram_context for unix domain datagram communication.
 754  *
 755  * @param[in]  local    An 'unix' tsocket_address for the local endpoint.
 756  *
 757  * @param[in]  remote   An 'unix' tsocket_address for the remote endpoint or
 758  *                      NULL (??? to create a listener?).
 759  *
 760  * @param[in]  mem_ctx  The talloc memory context to use.
 761  *
 762  * @param[in]  dgram    The tdgram_context pointer to setup the udp
 763  *                      communication. The function will allocate the memory.
 764  *
 765  * @return              0 on success, -1 on error with errno set.
 766  */
 767 int tdgram_unix_socket(const struct tsocket_address *local,
 768                         const struct tsocket_address *remote,
 769                         TALLOC_CTX *mem_ctx,
 770                         struct tdgram_context **dgram);
 771 #else
 772 int _tdgram_unix_socket(const struct tsocket_address *local,
 773                         const struct tsocket_address *remote,
 774                         TALLOC_CTX *mem_ctx,
 775                         struct tdgram_context **dgram,
 776                         const char *location);
 777
 778 #define tdgram_unix_socket(local, remote, mem_ctx, dgram) \
 779         _tdgram_unix_socket(local, remote, mem_ctx, dgram, __location__)
 780 #endif
 781
 782 /**
 783  * @brief Request a syscall optimization for tstream_readv_send()
 784  *
 785  * This function is only used to reduce the amount of syscalls and
 786  * optimize performance. You should only use this if you know
 787  * what you're doing.
 788  *
 789  * The optimization is off by default.
 790  *
 791  * @param[in]  stream   The tstream_context of a bsd socket, if this
 792  *                      not a bsd socket the function does nothing.
 793  *
 794  * @param[in]  on       The boolean value to turn the optimization on and off.
 795  *
 796  * @return              The old boolean value.
 797  *
 798  * @see tstream_readv_send()
 799  */
 800 bool tstream_bsd_optimize_readv(struct tstream_context *stream,
 801                                 bool on);
 802
 803 /**
 804  * @brief Connect async to a TCP endpoint and create a tstream_context for the
 805  * stream based communication.
 806  *
 807  * Use this function to connect asynchronously to a remote ipv4 or ipv6 TCP
 808  * endpoint and create a tstream_context for the stream based communication.
 809  *
 810  * @param[in]  mem_ctx  The talloc memory context to use.
 811  *
 812  * @param[in]  ev       The tevent_context to run on.
 813  *
 814  * @param[in]  local    An 'inet' tsocket_address for the local endpoint.
 815  *
 816  * @param[in]  remote   An 'inet' tsocket_address for the remote endpoint.
 817  *
 818  * @return              A 'tevent_req' handle, where the caller can register a
 819  *                      callback with tevent_req_set_callback(). NULL on a fatal
 820  *                      error.
 821  *
 822  * @see tstream_inet_tcp_connect_recv()
 823  */
 824 struct tevent_req *tstream_inet_tcp_connect_send(TALLOC_CTX *mem_ctx,
 825                                         struct tevent_context *ev,
 826                                         const struct tsocket_address *local,
 827                                         const struct tsocket_address *remote);
 828
 829 #ifdef DOXYGEN
 830 /**
 831  * @brief Receive the result from a tstream_inet_tcp_connect_send().
 832  *
 833  * @param[in]  req      The tevent request from tstream_inet_tcp_connect_send().
 834  *
 835  * @param[out] perrno   The error number, set if an error occurred.
 836  *
 837  * @param[in]  mem_ctx  The talloc memory context to use.
 838  *
 839  * @param[out] stream   A tstream_context pointer to setup the tcp communication
 840  *                      on. This function will allocate the memory.
 841  *
 842  * @param[out] local    The real 'inet' tsocket_address of the local endpoint.
 843  *                      This parameter is optional and can be NULL.
 844  *
 845  * @return              0 on success, -1 on error with perrno set.
 846  */
 847 int tstream_inet_tcp_connect_recv(struct tevent_req *req,
 848                                   int *perrno,
 849                                   TALLOC_CTX *mem_ctx,
 850                                   struct tstream_context **stream,
 851                                   struct tsocket_address **local)
 852 #else
 853 int _tstream_inet_tcp_connect_recv(struct tevent_req *req,
 854                                    int *perrno,
 855                                    TALLOC_CTX *mem_ctx,
 856                                    struct tstream_context **stream,
 857                                    struct tsocket_address **local,
 858                                    const char *location);
 859 #define tstream_inet_tcp_connect_recv(req, perrno, mem_ctx, stream, local) \
 860         _tstream_inet_tcp_connect_recv(req, perrno, mem_ctx, stream, local, \
 861                                        __location__)
 862 #endif
 863
 864 /**
 865  * @brief Connect async to a unix domain endpoint and create a tstream_context
 866  * for the stream based communication.
 867  *
 868  * Use this function to connenct asynchronously to a unix domainendpoint and
 869  * create a tstream_context for the stream based communication.
 870  *
 871  * The callback is triggered when a socket is connected and ready for IO or an
 872  * error happened.
 873  *
 874  * @param[in]  mem_ctx  The talloc memory context to use.
 875  *
 876  * @param[in]  ev       The tevent_context to run on.
 877  *
 878  * @param[in]  local    An 'unix' tsocket_address for the local endpoint.
 879  *
 880  * @param[in]  remote   An 'unix' tsocket_address for the remote endpoint.
 881  *
 882  * @return              A 'tevent_req' handle, where the caller can register a
 883  *                      callback with tevent_req_set_callback(). NULL on a falal
 884  *                      error.
 885  *
 886  * @see tstream_unix_connect_recv()
 887  */
 888 struct tevent_req * tstream_unix_connect_send(TALLOC_CTX *mem_ctx,
 889                                         struct tevent_context *ev,
 890                                         const struct tsocket_address *local,
 891                                         const struct tsocket_address *remote);
 892
 893 #ifdef DOXYGEN
 894 /**
 895  * @brief Receive the result from a tstream_unix_connect_send().
 896  *
 897  * @param[in]  req      The tevent request from tstream_inet_tcp_connect_send().
 898  *
 899  * @param[out] perrno   The error number, set if an error occurred.
 900  *
 901  * @param[in]  mem_ctx  The talloc memory context to use.
 902  *
 903  * @param[in]  stream   The tstream context to work on.
 904  *
 905  * @return              0 on success, -1 on error with perrno set.
 906  */
 907 int tstream_unix_connect_recv(struct tevent_req *req,
 908                               int *perrno,
 909                               TALLOC_CTX *mem_ctx,
 910                               struct tstream_context **stream);
 911 #else
 912 int _tstream_unix_connect_recv(struct tevent_req *req,
 913                                int *perrno,
 914                                TALLOC_CTX *mem_ctx,
 915                                struct tstream_context **stream,
 916                                const char *location);
 917 #define tstream_unix_connect_recv(req, perrno, mem_ctx, stream) \
 918         _tstream_unix_connect_recv(req, perrno, mem_ctx, stream, \
 919                                           __location__)
 920 #endif
 921
 922 #ifdef DOXYGEN
 923 /**
 924  * @brief Create two connected 'unix' tsocket_contexts for stream based
 925  *        communication.
 926  *
 927  * @param[in]  mem_ctx1 The talloc memory context to use for stream1.
 928  *
 929  * @param[in]  stream1  The first stream to connect.
 930  *
 931  * @param[in]  mem_ctx2 The talloc memory context to use for stream2.
 932  *
 933  * @param[in]  stream2  The second stream to connect.
 934  *
 935  * @return              0 on success, -1 on error with errno set.
 936  */
 937 int tstream_unix_socketpair(TALLOC_CTX *mem_ctx1,
 938                             struct tstream_context **stream1,
 939                             TALLOC_CTX *mem_ctx2,
 940                             struct tstream_context **stream2);
 941 #else
 942 int _tstream_unix_socketpair(TALLOC_CTX *mem_ctx1,
 943                              struct tstream_context **_stream1,
 944                              TALLOC_CTX *mem_ctx2,
 945                              struct tstream_context **_stream2,
 946                              const char *location);
 947
 948 #define tstream_unix_socketpair(mem_ctx1, stream1, mem_ctx2, stream2) \
 949         _tstream_unix_socketpair(mem_ctx1, stream1, mem_ctx2, stream2, \
 950                                  __location__)
 951 #endif
 952
 953 struct sockaddr;
 954
 955 #ifdef DOXYGEN
 956 /**
 957  * @brief Convert a tsocket address to a bsd socket address.
 958  *
 959  * @param[in]  mem_ctx  The talloc memory context to use.
 960  *
 961  * @param[in]  sa       The sockaddr structure to convert.
 962  *
 963  * @param[in]  sa_socklen   The length of the sockaddr structure.
 964  *
 965  * @param[out] addr     The tsocket pointer to allocate and fill.
 966  *
 967  * @return              0 on success, -1 on error with errno set.
 968  */
 969 int tsocket_address_bsd_from_sockaddr(TALLOC_CTX *mem_ctx,
 970                                       const struct sockaddr *sa,
 971                                       size_t sa_socklen,
 972                                       struct tsocket_address **addr);
 973 #else
 974 int _tsocket_address_bsd_from_sockaddr(TALLOC_CTX *mem_ctx,
 975                                        const struct sockaddr *sa,
 976                                        size_t sa_socklen,
 977                                        struct tsocket_address **_addr,
 978                                        const char *location);
 979
 980 #define tsocket_address_bsd_from_sockaddr(mem_ctx, sa, sa_socklen, _addr) \
 981         _tsocket_address_bsd_from_sockaddr(mem_ctx, sa, sa_socklen, _addr, \
 982                                            __location__)
 983 #endif
 984
 985 /**
 986  * @brief Fill a bsd sockaddr structure.
 987  *
 988  * @param[in]  addr     The tsocket address structure to use.
 989  *
 990  * @param[in]  sa       The bsd sockaddr structure to fill out.
 991  *
 992  * @param[in]  sa_socklen   The length of the  bsd sockaddr structure to fill out.
 993  *
 994  * @return              The actual size of the sockaddr structure, -1 on error
 995  *                      with errno set. The size could differ from sa_socklen.
 996  *
 997  * @code
 998  *   ssize_t socklen;
 999  *   struct sockaddr_storage ss;
1000  *
1001  *   socklen = tsocket_address_bsd_sockaddr(taddr,
1002  *                    (struct sockaddr *) &ss,
1003  *                    sizeof(struct sockaddr_storage));
1004  *   if (socklen < 0) {
1005  *     return -1;
1006  *   }
1007  * @endcode
1008  */
1009 ssize_t tsocket_address_bsd_sockaddr(const struct tsocket_address *addr,
1010                                      struct sockaddr *sa,
1011                                      size_t sa_socklen);
1012
1013 #ifdef DOXYGEN
1014 /**
1015  * @brief Wrap an existing file descriptors into the tstream abstraction.
1016  *
1017  * You can use this function to wrap an existing file descriptors into the
1018  * tstream abstraction. After that you're not able to use this file descriptor
1019  * for anything else. The file descriptor will be closed when the stream gets
1020  * freed. If you still want to use the fd you have have to create a duplicate.
1021  *
1022  * @param[in]  mem_ctx  The talloc memory context to use.
1023  *
1024  * @param[in]  fd       The non blocking fd to use!
1025  *
1026  * @param[out] stream   A pointer to store an allocated tstream_context.
1027  *
1028  * @return              0 on success, -1 on error.
1029  *
1030  * Example:
1031  * @code
1032  *   fd2 = dup(fd);
1033  *   rc = tstream_bsd_existing_socket(mem_ctx, fd2, &tstream);
1034  *   if (rc < 0) {
1035  *     stream_terminate_connection(conn, "named_pipe_accept: out of memory");
1036  *     return;
1037  *   }
1038  * @endcode
1039  *
1040  * @warning This is an internal function. You should read the code to fully
1041  *          understand it if you plan to use it.
1042  */
1043 int tstream_bsd_existing_socket(TALLOC_CTX *mem_ctx,
1044                                 int fd,
1045                                 struct tstream_context **stream);
1046 #else
1047 int _tstream_bsd_existing_socket(TALLOC_CTX *mem_ctx,
1048                                  int fd,
1049                                  struct tstream_context **_stream,
1050                                  const char *location);
1051 #define tstream_bsd_existing_socket(mem_ctx, fd, stream) \
1052         _tstream_bsd_existing_socket(mem_ctx, fd, stream, \
1053                                      __location__)
1054 #endif
1055
1056 /**
1057  * @}
1058  */
1059
1060 /**
1061  * @defgroup tsocket_helper Queue and PDU helpers
1062  * @ingroup tsocket
1063  *
1064  * In order to make the live easier for callers which want to implement a
1065  * function to receive a full PDU with a single async function pair, there're
1066  * some helper functions.
1067  *
1068  * There're some cases where the caller wants doesn't care about the order of
1069  * doing IO on the abstracted sockets.
1070  *
1071  * @{
1072  */
1073
1074 /**
1075  * @brief Queue a dgram blob for sending through the socket.
1076  *
1077  * This function queues a blob for sending to destination through an existing
1078  * dgram socket. The async callback is triggered when the whole blob is
1079  * delivered to the underlying system socket.
1080  *
1081  * The caller needs to make sure that all non-scalar input parameters hang
1082  * around for the whole lifetime of the request.
1083  *
1084  * @param[in]  mem_ctx  The memory context for the result.
1085  *
1086  * @param[in]  ev       The event context the operation should work on.
1087  *
1088  * @param[in]  dgram    The tdgram_context to send the message buffer.
1089  *
1090  * @param[in]  queue    The existing dgram queue.
1091  *
1092  * @param[in]  buf      The message buffer to send.
1093  *
1094  * @param[in]  len      The message length.
1095  *
1096  * @param[in]  dst      The destination socket address.
1097  *
1098  * @return              The async request handle. NULL on fatal error.
1099  *
1100  * @see tdgram_sendto_queue_recv()
1101  */
1102 struct tevent_req *tdgram_sendto_queue_send(TALLOC_CTX *mem_ctx,
1103                                             struct tevent_context *ev,
1104                                             struct tdgram_context *dgram,
1105                                             struct tevent_queue *queue,
1106                                             const uint8_t *buf,
1107                                             size_t len,
1108                                             struct tsocket_address *dst);
1109
1110 /**
1111  * @brief Receive the result of the sent dgram blob.
1112  *
1113  * @param[in]  req      The tevent request from tdgram_sendto_queue_send().
1114  *
1115  * @param[out] perrno   The error set to the actual errno.
1116  *
1117  * @return              The length of the datagram (0 is never returned!), -1 on
1118  *                      error with perrno set to the actual errno.
1119  */
1120 ssize_t tdgram_sendto_queue_recv(struct tevent_req *req, int *perrno);
1121
1122 typedef int (*tstream_readv_pdu_next_vector_t)(struct tstream_context *stream,
1123                                                void *private_data,
1124                                                TALLOC_CTX *mem_ctx,
1125                                                struct iovec **vector,
1126                                                size_t *count);
1127
1128 struct tevent_req *tstream_readv_pdu_send(TALLOC_CTX *mem_ctx,
1129                                 struct tevent_context *ev,
1130                                 struct tstream_context *stream,
1131                                 tstream_readv_pdu_next_vector_t next_vector_fn,
1132                                 void *next_vector_private);
1133 int tstream_readv_pdu_recv(struct tevent_req *req, int *perrno);
1134
1135 /**
1136  * @brief Queue a read request for a PDU on the socket.
1137  *
1138  * This function queues a read request for a PDU on a stream socket. The async
1139  * callback is triggered when a full PDU has been read from the socket.
1140  *
1141  * The caller needs to make sure that all non-scalar input parameters hang
1142  * around for the whole lifetime of the request.
1143  *
1144  * @param[in]  mem_ctx  The memory context for the result
1145  *
1146  * @param[in]  ev       The tevent_context to run on
1147  *
1148  * @param[in]  stream   The stream to send data through
1149  *
1150  * @param[in]  queue    The existing send queue
1151  *
1152  * @param[in]  next_vector_fn  The next vector function
1153  *
1154  * @param[in]  next_vector_private  The private_data of the next vector function
1155  *
1156  * @return              The async request handle. NULL on fatal error.
1157  *
1158  * @see tstream_readv_pdu_queue_recv()
1159  */
1160 struct tevent_req *tstream_readv_pdu_queue_send(TALLOC_CTX *mem_ctx,
1161                                 struct tevent_context *ev,
1162                                 struct tstream_context *stream,
1163                                 struct tevent_queue *queue,
1164                                 tstream_readv_pdu_next_vector_t next_vector_fn,
1165                                 void *next_vector_private);
1166
1167 /**
1168  * @brief Receive the PDU blob read from the stream.
1169  *
1170  * @param[in]  req      The tevent request from tstream_readv_pdu_queue_send().
1171  *
1172  * @param[out] perrno   The error set to the actual errno.
1173  *
1174  * @return              The number of bytes read on success, -1 on error with
1175  *                      perrno set to the actual errno.
1176  */
1177 int tstream_readv_pdu_queue_recv(struct tevent_req *req, int *perrno);
1178
1179 /**
1180  * @brief Queue an iovector for sending through the socket
1181  *
1182  * This function queues an iovector for sending to destination through an
1183  * existing stream socket. The async callback is triggered when the whole
1184  * vectror has been delivered to the underlying system socket.
1185  *
1186  * The caller needs to make sure that all non-scalar input parameters hang
1187  * around for the whole lifetime of the request.
1188  *
1189  * @param[in]  mem_ctx  The memory context for the result.
1190  *
1191  * @param[in]  ev       The tevent_context to run on.
1192  *
1193  * @param[in]  stream   The stream to send data through.
1194  *
1195  * @param[in]  queue    The existing send queue.
1196  *
1197  * @param[in]  vector   The iovec vector so write.
1198  *
1199  * @param[in]  count    The size of the vector.
1200  *
1201  * @return              The async request handle. NULL on fatal error.
1202  */
1203 struct tevent_req *tstream_writev_queue_send(TALLOC_CTX *mem_ctx,
1204                                              struct tevent_context *ev,
1205                                              struct tstream_context *stream,
1206                                              struct tevent_queue *queue,
1207                                              const struct iovec *vector,
1208                                              size_t count);
1209
1210 /**
1211  * @brief Receive the result of the sent iovector.
1212  *
1213  * @param[in]  req      The tevent request from tstream_writev_queue_send().
1214  *
1215  * @param[out] perrno   The error set to the actual errno.
1216  *
1217  * @return              The length of the iovector (0 is never returned!), -1 on
1218  *                      error with perrno set to the actual errno.
1219  */
1220 int tstream_writev_queue_recv(struct tevent_req *req, int *perrno);
1221
1222 /**
1223  * @}
1224  */
1225
1226 #endif /* _TSOCKET_H */
1227