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 samba_sockaddr;
  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 split into two different kinds of
  45  * communication 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 around 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 generically.
  79  * As it's like an abstract class it has no specific constructor.
  80  * The specific constructors are described in later sections.
  81  *
  82  * @{
  83  */
  84
  85 /**
  86  * @brief Get a string representation 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 implementation 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_is_inet()
 105  * @see tsocket_address_inet_addr_string()
 106  * @see tsocket_address_inet_port()
 107  */
 108 char *tsocket_address_string(const struct tsocket_address *addr,
 109                              TALLOC_CTX *mem_ctx);
 110
 111 #ifdef DOXYGEN
 112 /**
 113  * @brief This creates a copy of a tsocket_address.
 114  *
 115  * This is useful when before doing modifications to a socket via additional
 116  * methods of the specific tsocket_address implementation.
 117  *
 118  * @param[in]  addr     The address to create the copy from.
 119  *
 120  * @param[in]  mem_ctx  The talloc memory context to use.
 121  *
 122  * @return              A newly allocated copy of addr (tsocket_address *), NULL
 123  *                      on error.
 124  */
 125 struct tsocket_address *tsocket_address_copy(const struct tsocket_address *addr,
 126                 TALLOC_CTX *mem_ctx);
 127 #else
 128 struct tsocket_address *_tsocket_address_copy(const struct tsocket_address *addr,
 129                                               TALLOC_CTX *mem_ctx,
 130                                               const char *location);
 131
 132 #define tsocket_address_copy(addr, mem_ctx) \
 133         _tsocket_address_copy(addr, mem_ctx, __location__)
 134 #endif
 135
 136 /**
 137  * @}
 138  */
 139
 140 /**
 141  * @defgroup tdgram_context The tdgram_context abstraction
 142  * @ingroup tsocket
 143  *
 144  * The tdgram_context is like an abstract class for datagram based sockets. The
 145  * interface provides async 'tevent_req' based functions on top functionality
 146  * is similar to the recvfrom(2)/sendto(2)/close(2) syscalls.
 147  *
 148  * @note You can always use talloc_free(tdgram) to cleanup the resources
 149  * of the tdgram_context on a fatal error.
 150  * @{
 151  */
 152
 153 /**
 154  * @brief Ask for next available datagram on the abstracted tdgram_context.
 155  *
 156  * It returns a 'tevent_req' handle, where the caller can register
 157  * a callback with tevent_req_set_callback(). The callback is triggered
 158  * when a datagram is available or an error happened.
 159  *
 160  * @param[in]  mem_ctx  The talloc memory context to use.
 161  *
 162  * @param[in]  ev       The tevent_context to run on.
 163  *
 164  * @param[in]  dgram    The dgram context to work on.
 165  *
 166  * @return              Returns a 'tevent_req' handle, where the caller can
 167  *                      register a callback with tevent_req_set_callback().
 168  *                      NULL on fatal error.
 169  *
 170  * @see tdgram_inet_udp_socket()
 171  * @see tdgram_unix_socket()
 172  */
 173 struct tevent_req *tdgram_recvfrom_send(TALLOC_CTX *mem_ctx,
 174                                         struct tevent_context *ev,
 175                                         struct tdgram_context *dgram);
 176
 177 /**
 178  * @brief Receive the next available datagram on the abstracted tdgram_context.
 179  *
 180  * This function should be called by the callback when a datagram is available
 181  * or an error happened.
 182  *
 183  * The caller can only have one outstanding tdgram_recvfrom_send() at a time
 184  * otherwise the caller will get '*perrno = EBUSY'.
 185  *
 186  * @param[in]  req      The tevent request from tdgram_recvfrom_send().
 187  *
 188  * @param[out] perrno   The error number, set if an error occurred.
 189  *
 190  * @param[in]  mem_ctx  The memory context to use.
 191  *
 192  * @param[out] buf      This will hold the buffer of the datagram.
 193  *
 194  * @param[out] src      The abstracted tsocket_address of the sender of the
 195  *                      received datagram.
 196  *
 197  * @return              The length of the datagram (0 is never returned!),
 198  *                      -1 on error with perrno set to the actual errno.
 199  *
 200  * @see tdgram_recvfrom_send()
 201  */
 202 ssize_t tdgram_recvfrom_recv(struct tevent_req *req,
 203                              int *perrno,
 204                              TALLOC_CTX *mem_ctx,
 205                              uint8_t **buf,
 206                              struct tsocket_address **src);
 207
 208 /**
 209  * @brief Send a datagram to a destination endpoint.
 210  *
 211  * The function can be called to send a datagram (specified by a buf/len) to a
 212  * destination endpoint (specified by dst). It's not allowed for len to be 0.
 213  *
 214  * It returns a 'tevent_req' handle, where the caller can register a callback
 215  * with tevent_req_set_callback(). The callback is triggered when the specific
 216  * implementation (assumes it) has delivered the datagram to the "wire".
 217  *
 218  * The callback is then supposed to get the result by calling
 219  * tdgram_sendto_recv() on the 'tevent_req'.
 220  *
 221  * @param[in]  mem_ctx  The talloc memory context to use.
 222  *
 223  * @param[in]  ev       The tevent_context to run on.
 224  *
 225  * @param[in]  dgram    The dgram context to work on.
 226  *
 227  * @param[in]  buf      The buffer to send.
 228  *
 229  * @param[in]  len      The length of the buffer to send. It has to be bigger
 230  *                      than 0.
 231  *
 232  * @param[in]  dst      The destination to send the datagram to in form of a
 233  *                      tsocket_address.
 234  *
 235  * @return              Returns a 'tevent_req' handle, where the caller can
 236  *                      register a callback with tevent_req_set_callback().
 237  *                      NULL on fatal error.
 238  *
 239  * @see tdgram_inet_udp_socket()
 240  * @see tdgram_unix_socket()
 241  * @see tdgram_sendto_recv()
 242  */
 243 struct tevent_req *tdgram_sendto_send(TALLOC_CTX *mem_ctx,
 244                                       struct tevent_context *ev,
 245                                       struct tdgram_context *dgram,
 246                                       const uint8_t *buf, size_t len,
 247                                       const struct tsocket_address *dst);
 248
 249 /**
 250  * @brief Receive the result of the sent datagram.
 251  *
 252  * The caller can only have one outstanding tdgram_sendto_send() at a time
 253  * otherwise the caller will get '*perrno = EBUSY'.
 254  *
 255  * @param[in]  req      The tevent request from tdgram_sendto_send().
 256  *
 257  * @param[out] perrno   The error number, set if an error occurred.
 258  *
 259  * @return              The length of the datagram (0 is never returned!), -1 on
 260  *                      error with perrno set to the actual errno.
 261  *
 262  * @see tdgram_sendto_send()
 263  */
 264 ssize_t tdgram_sendto_recv(struct tevent_req *req,
 265                            int *perrno);
 266
 267 /**
 268  * @brief Shutdown/close an abstracted socket.
 269  *
 270  * It returns a 'tevent_req' handle, where the caller can register a callback
 271  * with tevent_req_set_callback(). The callback is triggered when the specific
 272  * implementation (assumes it) has delivered the datagram to the "wire".
 273  *
 274  * The callback is then supposed to get the result by calling
 275  * tdgram_sendto_recv() on the 'tevent_req'.
 276  *
 277  * @param[in]  mem_ctx  The talloc memory context to use.
 278  *
 279  * @param[in]  ev       The tevent_context to run on.
 280  *
 281  * @param[in]  dgram    The dgram context to disconnect from.
 282  *
 283  * @return              Returns a 'tevent_req' handle, where the caller can
 284  *                      register a callback with tevent_req_set_callback().
 285  *                      NULL on fatal error.
 286  *
 287  * @see tdgram_disconnect_recv()
 288  */
 289 struct tevent_req *tdgram_disconnect_send(TALLOC_CTX *mem_ctx,
 290                                           struct tevent_context *ev,
 291                                           struct tdgram_context *dgram);
 292
 293 /**
 294  * @brief Receive the result from a tdgram_disconnect_send() request.
 295  *
 296  * The caller should make sure there're no outstanding tdgram_recvfrom_send()
 297  * and tdgram_sendto_send() calls otherwise the caller will get
 298  * '*perrno = EBUSY'.
 299  *
 300  * @param[in]  req      The tevent request from tdgram_disconnect_send().
 301  *
 302  * @param[out] perrno   The error number, set if an error occurred.
 303  *
 304  * @return              The length of the datagram (0 is never returned!), -1 on
 305  *                      error with perrno set to the actual errno.
 306  *
 307  * @see tdgram_disconnect_send()
 308  */
 309 int tdgram_disconnect_recv(struct tevent_req *req,
 310                            int *perrno);
 311
 312 /**
 313  * @}
 314  */
 315
 316 /**
 317  * @defgroup tstream_context The tstream_context abstraction
 318  * @ingroup tsocket
 319  *
 320  * The tstream_context is like an abstract class for stream based sockets. The
 321  * interface provides async 'tevent_req' based functions on top functionality
 322  * is similar to the readv(2)/writev(2)/close(2) syscalls.
 323  *
 324  * @note You can always use talloc_free(tstream) to cleanup the resources
 325  * of the tstream_context on a fatal error.
 326  *
 327  * @{
 328  */
 329
 330 /**
 331  * @brief Report the number of bytes received but not consumed yet.
 332  *
 333  * The tstream_pending_bytes() function reports how much bytes of the incoming
 334  * stream have been received but not consumed yet.
 335  *
 336  * @param[in]  stream   The tstream_context to check for pending bytes.
 337  *
 338  * @return              The number of bytes received, -1 on error with errno
 339  *                      set.
 340  */
 341 ssize_t tstream_pending_bytes(struct tstream_context *stream);
 342
 343 /**
 344  * @brief Read a specific amount of bytes from a stream socket.
 345  *
 346  * The function can be called to read for a specific amount of bytes from the
 347  * stream into given buffers. The caller has to preallocate the buffers.
 348  *
 349  * The caller might need to use tstream_pending_bytes() if the protocol doesn't
 350  * have a fixed pdu header containing the pdu size.
 351  *
 352  * @param[in]  mem_ctx  The talloc memory context to use.
 353  *
 354  * @param[in]  ev       The tevent_context to run on.
 355  *
 356  * @param[in]  stream   The tstream context to work on.
 357  *
 358  * @param[out] vector   A preallocated iovec to store the data to read.
 359  *
 360  * @param[in]  count    The number of buffers in the vector allocated.
 361  *
 362  * @return              A 'tevent_req' handle, where the caller can register
 363  *                      a callback with tevent_req_set_callback(). NULL on
 364  *                      fatal error.
 365  *
 366  * @see tstream_unix_connect_send()
 367  * @see tstream_inet_tcp_connect_send()
 368  */
 369 struct tevent_req *tstream_readv_send(TALLOC_CTX *mem_ctx,
 370                                       struct tevent_context *ev,
 371                                       struct tstream_context *stream,
 372                                       struct iovec *vector,
 373                                       size_t count);
 374
 375 /**
 376  * @brief Get the result of a tstream_readv_send().
 377  *
 378  * The caller can only have one outstanding tstream_readv_send()
 379  * at a time otherwise the caller will get *perrno = EBUSY.
 380  *
 381  * @param[in]  req      The tevent request from tstream_readv_send().
 382  *
 383  * @param[out] perrno   The error number, set if an error occurred.
 384  *
 385  * @return              The length of the stream (0 is never returned!), -1 on
 386  *                      error with perrno set to the actual errno.
 387  */
 388 int tstream_readv_recv(struct tevent_req *req,
 389                        int *perrno);
 390
 391 /**
 392  * @brief Write buffers from a vector into a stream socket.
 393  *
 394  * The function can be called to write buffers from a given vector
 395  * to a stream socket.
 396  *
 397  * You have to ensure that the vector is not empty.
 398  *
 399  * @param[in]  mem_ctx  The talloc memory context to use.
 400  *
 401  * @param[in]  ev       The tevent_context to run on.
 402  *
 403  * @param[in]  stream   The tstream context to work on.
 404  *
 405  * @param[in]  vector   The iovec vector with data to write on a stream socket.
 406  *
 407  * @param[in]  count    The number of buffers in the vector to write.
 408  *
 409  * @return              A 'tevent_req' handle, where the caller can register
 410  *                      a callback with tevent_req_set_callback(). NULL on
 411  *                      fatal error.
 412  */
 413 struct tevent_req *tstream_writev_send(TALLOC_CTX *mem_ctx,
 414                                        struct tevent_context *ev,
 415                                        struct tstream_context *stream,
 416                                        const struct iovec *vector,
 417                                        size_t count);
 418
 419 /**
 420  * @brief Get the result of a tstream_writev_send().
 421  *
 422  * The caller can only have one outstanding tstream_writev_send()
 423  * at a time otherwise the caller will get *perrno = EBUSY.
 424  *
 425  * @param[in]  req      The tevent request from tstream_writev_send().
 426  *
 427  * @param[out] perrno   The error number, set if an error occurred.
 428  *
 429  * @return              The length of the stream (0 is never returned!), -1 on
 430  *                      error with perrno set to the actual errno.
 431  */
 432 int tstream_writev_recv(struct tevent_req *req,
 433                         int *perrno);
 434
 435 /**
 436  * @brief Shutdown/close an abstracted socket.
 437  *
 438  * It returns a 'tevent_req' handle, where the caller can register a callback
 439  * with tevent_req_set_callback(). The callback is triggered when the specific
 440  * implementation (assumes it) has delivered the stream to the "wire".
 441  *
 442  * The callback is then supposed to get the result by calling
 443  * tdgram_sendto_recv() on the 'tevent_req'.
 444  *
 445  * @param[in]  mem_ctx  The talloc memory context to use.
 446  *
 447  * @param[in]  ev       The tevent_context to run on.
 448  *
 449  * @param[in]  stream   The tstream context to work on.
 450  *
 451  * @return              A 'tevent_req' handle, where the caller can register
 452  *                      a callback with tevent_req_set_callback(). NULL on
 453  *                      fatal error.
 454  */
 455 struct tevent_req *tstream_disconnect_send(TALLOC_CTX *mem_ctx,
 456                                            struct tevent_context *ev,
 457                                            struct tstream_context *stream);
 458
 459 /**
 460  * @brief Get the result of a tstream_disconnect_send().
 461  *
 462  * The caller can only have one outstanding tstream_writev_send()
 463  * at a time otherwise the caller will get *perrno = EBUSY.
 464  *
 465  * @param[in]  req      The tevent request from tstream_disconnect_send().
 466  *
 467  * @param[out] perrno   The error number, set if an error occurred.
 468  *
 469  * @return              The length of the stream (0 is never returned!), -1 on
 470  *                      error with perrno set to the actual errno.
 471  */
 472 int tstream_disconnect_recv(struct tevent_req *req,
 473                             int *perrno);
 474
 475 /**
 476  * @}
 477  */
 478
 479
 480 /**
 481  * @defgroup tsocket_bsd  tsocket_bsd - inet, inet6 and unix
 482  * @ingroup tsocket
 483  *
 484  * The main tsocket library comes with implementations for BSD style ipv4, ipv6
 485  * and unix sockets.
 486  *
 487  * @{
 488  */
 489
 490 /**
 491  * @brief Find out if the tsocket_address represents an ipv4 or ipv6 endpoint.
 492  *
 493  * @param[in]  addr     The tsocket_address pointer
 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  * @return              true if addr represents an address of the given family,
 500  *                      otherwise false.
 501  */
 502 bool tsocket_address_is_inet(const struct tsocket_address *addr, const char *fam);
 503
 504 #ifdef DOXYGEN
 505 /**
 506  * @brief Create a tsocket_address for ipv4 and ipv6 endpoint addresses.
 507  *
 508  * @param[in]  mem_ctx  The talloc memory context to use.
 509  *
 510  * @param[in]  fam      The family can be can be "ipv4", "ipv6" or "ip". With
 511  *                      "ip" is autodetects "ipv4" or "ipv6" based on the
 512  *                      addr.
 513  *
 514  * @param[in]  addr     A valid ip address string based on the selected family
 515  *                      (dns names are not allowed!). It's valid to pass NULL,
 516  *                      which gets mapped to "0.0.0.0" or "::".
 517  *
 518  * @param[in]  port     A valid port number.
 519  *
 520  * @param[out] _addr    A tsocket_address pointer to store the information.
 521  *
 522  * @return              0 on success, -1 on error with errno set.
 523  */
 524 int tsocket_address_inet_from_strings(TALLOC_CTX *mem_ctx,
 525                                       const char *fam,
 526                                       const char *addr,
 527                                       uint16_t port,
 528                                       struct tsocket_address **_addr);
 529 #else
 530 int _tsocket_address_inet_from_strings(TALLOC_CTX *mem_ctx,
 531                                        const char *fam,
 532                                        const char *addr,
 533                                        uint16_t port,
 534                                        struct tsocket_address **_addr,
 535                                        const char *location);
 536
 537 #define tsocket_address_inet_from_strings(mem_ctx, fam, addr, port, _addr) \
 538         _tsocket_address_inet_from_strings(mem_ctx, fam, addr, port, _addr, \
 539                                            __location__)
 540 #endif
 541
 542 #ifdef DOXYGEN
 543 /**
 544  * @brief Create a tsocket_address for ipv4 and ipv6 endpoint addresses.
 545  *
 546  * @param[in]  mem_ctx  The talloc memory context to use.
 547  *
 548  * @param[in]  fam      The family can be can be "ipv4", "ipv6" or "ip". With
 549  *                      "ip" it autodetects "ipv4" or "ipv6" based on the
 550  *                      addr.
 551  *
 552  * @param[in]  host_port_addr   A valid ip address string based on the
 553  *                      selected family (dns names are not allowed!). A port
 554  *                      number may follow separated by a colon. IPv6 may be
 555  *                      surrounded in square brackets, and these are required
 556  *                      if appending a port number. It's valid to pass NULL,
 557  *                      which gets mapped to "0.0.0.0" or "::".
 558  *
 559  * @param[in]  default_port  A valid port number for the default port if none
 560  *                      given.
 561  *
 562  * @param[out] _addr    A tsocket_address pointer to store the information.
 563  *
 564  * @return              0 on success, -1 on error with errno set.
 565  */
 566 int tsocket_address_inet_from_hostport_strings(TALLOC_CTX *mem_ctx,
 567                                                const char *fam,
 568                                                const char *host_port_addr,
 569                                                uint16_t default_port,
 570                                                struct tsocket_address **_addr);
 571 #else
 572 int _tsocket_address_inet_from_hostport_strings(TALLOC_CTX *mem_ctx,
 573                                                 const char *fam,
 574                                                 const char *host_port_addr,
 575                                                 uint16_t default_port,
 576                                                 struct tsocket_address **_addr,
 577                                                 const char *location);
 578
 579 #define tsocket_address_inet_from_hostport_strings(                            \
 580     mem_ctx, fam, host_port_addr, default_port, _addr)                         \
 581         _tsocket_address_inet_from_hostport_strings(                           \
 582             mem_ctx, fam, host_port_addr, default_port, _addr, __location__)
 583 #endif
 584
 585 /**
 586  * @brief Get the address of an 'inet' tsocket_address as a string.
 587  *
 588  * @param[in]  addr     The address to convert to a string.
 589  *
 590  * @param[in]  mem_ctx  The talloc memory context to use.
 591  *
 592  * @return              A newly allocated string of the address, NULL on error
 593  *                      with errno set.
 594  *
 595  * @see tsocket_address_is_inet()
 596  */
 597 char *tsocket_address_inet_addr_string(const struct tsocket_address *addr,
 598                                        TALLOC_CTX *mem_ctx);
 599
 600 /**
 601  * @brief Get the port number as an integer from an 'inet' tsocket_address.
 602  *
 603  * @param[in]  addr     The tsocket address to use.
 604  *
 605  * @return              The port number, 0 on error with errno set.
 606  */
 607 uint16_t tsocket_address_inet_port(const struct tsocket_address *addr);
 608
 609 /**
 610  * @brief Set the port number of an existing 'inet' tsocket_address.
 611  *
 612  * @param[in]  addr     The existing tsocket_address to use.
 613  *
 614  * @param[in]  port     The valid port number to set.
 615  *
 616  * @return              0 on success, -1 on error with errno set.
 617  */
 618 int tsocket_address_inet_set_port(struct tsocket_address *addr,
 619                                   uint16_t port);
 620
 621 /**
 622  * @brief Find out if the tsocket_address represents an unix domain endpoint.
 623  *
 624  * @param[in]  addr     The tsocket_address pointer
 625  *
 626  * @return              true if addr represents an unix domain endpoint,
 627  *                      otherwise false.
 628  */
 629 bool tsocket_address_is_unix(const struct tsocket_address *addr);
 630
 631 #ifdef DOXYGEN
 632 /**
 633  * @brief Create a tsocket_address for a unix domain endpoint addresses.
 634  *
 635  * @param[in]  mem_ctx  The talloc memory context to use.
 636  *
 637  * @param[in]  path     The filesystem path, NULL will map "".
 638  *
 639  * @param[in]  _addr    The tsocket_address pointer to store the information.
 640  *
 641  * @return              0 on success, -1 on error with errno set.
 642  *
 643  * @see tsocket_address_is_unix()
 644  */
 645 int tsocket_address_unix_from_path(TALLOC_CTX *mem_ctx,
 646                                    const char *path,
 647                                    struct tsocket_address **_addr);
 648 #else
 649 int _tsocket_address_unix_from_path(TALLOC_CTX *mem_ctx,
 650                                     const char *path,
 651                                     struct tsocket_address **_addr,
 652                                     const char *location);
 653
 654 #define tsocket_address_unix_from_path(mem_ctx, path, _addr) \
 655         _tsocket_address_unix_from_path(mem_ctx, path, _addr, \
 656                                         __location__)
 657 #endif
 658
 659 /**
 660  * @brief Get the address of an 'unix' tsocket_address.
 661  *
 662  * @param[in]  addr     A valid 'unix' tsocket_address.
 663  *
 664  * @param[in]  mem_ctx  The talloc memory context to use.
 665  *
 666  * @return              The path of the unix domain socket, NULL on error or if
 667  *                      the tsocket_address doesn't represent an unix domain
 668  *                      endpoint path.
 669  */
 670 char *tsocket_address_unix_path(const struct tsocket_address *addr,
 671                                 TALLOC_CTX *mem_ctx);
 672
 673 #ifdef DOXYGEN
 674 /**
 675  * @brief Wrap an existing file descriptors into the tdgram abstraction.
 676  *
 677  * You can use this function to wrap an existing file descriptors into the
 678  * tdgram abstraction. After that you're not able to use this file descriptor
 679  * for anything else. The file descriptor will be closed when the stream gets
 680  * freed. If you still want to use the fd you have to create a duplicate.
 681  *
 682  * @param[in]  mem_ctx  The talloc memory context to use.
 683  *
 684  * @param[in]  fd       The non blocking fd to use!
 685  *
 686  * @param[out] dgram    A pointer to store an allocated tdgram_context.
 687  *
 688  * @return              0 on success, -1 on error.
 689  *
 690  * Example:
 691  * @code
 692  *   fd2 = dup(fd);
 693  *   rc = tdgram_bsd_existing_socket(mem_ctx, fd2, &tdgram);
 694  *   if (rc < 0) {
 695  *     return;
 696  *   }
 697  * @endcode
 698  *
 699  * @warning This is an internal function. You should read the code to fully
 700  *          understand it if you plan to use it.
 701  */
 702 int tdgram_bsd_existing_socket(TALLOC_CTX *mem_ctx,
 703                                int fd,
 704                                struct tdgram_context **dgram);
 705 #else
 706 int _tdgram_bsd_existing_socket(TALLOC_CTX *mem_ctx,
 707                                 int fd,
 708                                 struct tdgram_context **_dgram,
 709                                 const char *location);
 710 #define tdgram_bsd_existing_socket(mem_ctx, fd, dgram) \
 711         _tdgram_bsd_existing_socket(mem_ctx, fd, dgram, \
 712                                     __location__)
 713 #endif
 714
 715 /**
 716  * @brief Request a syscall optimization for tdgram_recvfrom_send()
 717  *
 718  * This function is only used to reduce the amount of syscalls and
 719  * optimize performance. You should only use this if you know
 720  * what you're doing.
 721  *
 722  * The optimization is off by default.
 723  *
 724  * @param[in]  dgram    The tdgram_context of a bsd socket, if this
 725  *                      not a bsd socket the function does nothing.
 726  *
 727  * @param[in]  on       The boolean value to turn the optimization on and off.
 728  *
 729  * @return              The old boolean value.
 730  *
 731  * @see tdgram_recvfrom_send()
 732  */
 733 bool tdgram_bsd_optimize_recvfrom(struct tdgram_context *dgram,
 734                                   bool on);
 735
 736 #ifdef DOXYGEN
 737 /**
 738  * @brief Create a tdgram_context for a ipv4 or ipv6 UDP communication.
 739  *
 740  * @param[in]  local    An 'inet' tsocket_address for the local endpoint.
 741  *
 742  * @param[in]  remote   An 'inet' tsocket_address for the remote endpoint or
 743  *                      NULL (??? to create a listener?).
 744  *
 745  * @param[in]  mem_ctx  The talloc memory context to use.
 746  *
 747  * @param[in]  dgram    The tdgram_context pointer to setup the udp
 748  *                      communication. The function will allocate the memory.
 749  *
 750  * @return              0 on success, -1 on error with errno set.
 751  *
 752  * @see tdgram_inet_udp_broadcast_socket()
 753  */
 754 int tdgram_inet_udp_socket(const struct tsocket_address *local,
 755                             const struct tsocket_address *remote,
 756                             TALLOC_CTX *mem_ctx,
 757                             struct tdgram_context **dgram);
 758 #else
 759 int _tdgram_inet_udp_socket(const struct tsocket_address *local,
 760                             const struct tsocket_address *remote,
 761                             TALLOC_CTX *mem_ctx,
 762                             struct tdgram_context **dgram,
 763                             const char *location);
 764 #define tdgram_inet_udp_socket(local, remote, mem_ctx, dgram) \
 765         _tdgram_inet_udp_socket(local, remote, mem_ctx, dgram, __location__)
 766 #endif
 767
 768 #ifdef DOXYGEN
 769 /**
 770  * @brief Create a tdgram_context for a ipv4 UDP broadcast (and unicast) communication.
 771  *
 772  * @param[in]  local    An 'inet' (ipv4 only) tsocket_address for the local endpoint.
 773  *
 774  * @param[in]  mem_ctx  The talloc memory context to use.
 775  *
 776  * @param[in]  dgram    The tdgram_context pointer to setup the udp
 777  *                      communication. The function will allocate the memory.
 778  *
 779  * @return              0 on success, -1 on error with errno set.
 780  *
 781  * @see tdgram_inet_udp_socket()
 782  */
 783 int tdgram_inet_udp_broadcast_socket(const struct tsocket_address *local,
 784                                      TALLOC_CTX *mem_ctx,
 785                                      struct tdgram_context **dgram);
 786 #else
 787 int _tdgram_inet_udp_broadcast_socket(const struct tsocket_address *local,
 788                                       TALLOC_CTX *mem_ctx,
 789                                       struct tdgram_context **dgram,
 790                                       const char *location);
 791 #define tdgram_inet_udp_broadcast_socket(local, mem_ctx, dgram) \
 792         _tdgram_inet_udp_broadcast_socket(local, mem_ctx, dgram, __location__)
 793 #endif
 794
 795 #ifdef DOXYGEN
 796 /**
 797  * @brief Create a tdgram_context for unix domain datagram communication.
 798  *
 799  * @param[in]  local    An 'unix' tsocket_address for the local endpoint.
 800  *
 801  * @param[in]  remote   An 'unix' tsocket_address for the remote endpoint or
 802  *                      NULL (??? to create a listener?).
 803  *
 804  * @param[in]  mem_ctx  The talloc memory context to use.
 805  *
 806  * @param[in]  dgram    The tdgram_context pointer to setup the udp
 807  *                      communication. The function will allocate the memory.
 808  *
 809  * @return              0 on success, -1 on error with errno set.
 810  */
 811 int tdgram_unix_socket(const struct tsocket_address *local,
 812                         const struct tsocket_address *remote,
 813                         TALLOC_CTX *mem_ctx,
 814                         struct tdgram_context **dgram);
 815 #else
 816 int _tdgram_unix_socket(const struct tsocket_address *local,
 817                         const struct tsocket_address *remote,
 818                         TALLOC_CTX *mem_ctx,
 819                         struct tdgram_context **dgram,
 820                         const char *location);
 821
 822 #define tdgram_unix_socket(local, remote, mem_ctx, dgram) \
 823         _tdgram_unix_socket(local, remote, mem_ctx, dgram, __location__)
 824 #endif
 825
 826 /**
 827  * @brief Request a syscall optimization for tstream_readv_send()
 828  *
 829  * This function is only used to reduce the amount of syscalls and
 830  * optimize performance. You should only use this if you know
 831  * what you're doing.
 832  *
 833  * The optimization is off by default.
 834  *
 835  * @param[in]  stream   The tstream_context of a bsd socket, if this
 836  *                      not a bsd socket the function does nothing.
 837  *
 838  * @param[in]  on       The boolean value to turn the optimization on and off.
 839  *
 840  * @return              The old boolean value.
 841  *
 842  * @see tstream_readv_send()
 843  */
 844 bool tstream_bsd_optimize_readv(struct tstream_context *stream,
 845                                 bool on);
 846
 847 /**
 848  * @brief Request that tstream_readv_send() fails within pending data
 849  *
 850  * By default we allow pending data to be drained from the
 851  * recv queue, before we report EPIPE when reaching EOF.
 852  *
 853  * For server applications it's typically useful to
 854  * fail early in order to avoid useless work,
 855  * as the response can't be transferred to the client anyway.
 856  *
 857  * @param[in]  stream   The tstream_context of a bsd socket, if this
 858  *                      not a bsd socket the function does nothing.
 859  *
 860  * @param[in]  on       The boolean value to turn the early fail on and off.
 861  *
 862  * @return              The old boolean value.
 863  *
 864  * @see tstream_readv_send()
 865  */
 866 bool tstream_bsd_fail_readv_first_error(struct tstream_context *stream,
 867                                         bool on);
 868
 869 /**
 870  * @brief Connect async to a TCP endpoint and create a tstream_context for the
 871  * stream based communication.
 872  *
 873  * Use this function to connect asynchronously to a remote ipv4 or ipv6 TCP
 874  * endpoint and create a tstream_context for the stream based communication.
 875  *
 876  * @param[in]  mem_ctx  The talloc memory context to use.
 877  *
 878  * @param[in]  ev       The tevent_context to run on.
 879  *
 880  * @param[in]  local    An 'inet' tsocket_address for the local endpoint.
 881  *
 882  * @param[in]  remote   An 'inet' tsocket_address for the remote endpoint.
 883  *
 884  * @return              A 'tevent_req' handle, where the caller can register a
 885  *                      callback with tevent_req_set_callback(). NULL on a fatal
 886  *                      error.
 887  *
 888  * @see tstream_inet_tcp_connect_recv()
 889  */
 890 struct tevent_req *tstream_inet_tcp_connect_send(TALLOC_CTX *mem_ctx,
 891                                         struct tevent_context *ev,
 892                                         const struct tsocket_address *local,
 893                                         const struct tsocket_address *remote);
 894
 895 #ifdef DOXYGEN
 896 /**
 897  * @brief Receive the result from a tstream_inet_tcp_connect_send().
 898  *
 899  * @param[in]  req      The tevent request from tstream_inet_tcp_connect_send().
 900  *
 901  * @param[out] perrno   The error number, set if an error occurred.
 902  *
 903  * @param[in]  mem_ctx  The talloc memory context to use.
 904  *
 905  * @param[out] stream   A tstream_context pointer to setup the tcp communication
 906  *                      on. This function will allocate the memory.
 907  *
 908  * @param[out] local    The real 'inet' tsocket_address of the local endpoint.
 909  *                      This parameter is optional and can be NULL.
 910  *
 911  * @return              0 on success, -1 on error with perrno set.
 912  */
 913 int tstream_inet_tcp_connect_recv(struct tevent_req *req,
 914                                   int *perrno,
 915                                   TALLOC_CTX *mem_ctx,
 916                                   struct tstream_context **stream,
 917                                   struct tsocket_address **local)
 918 #else
 919 int _tstream_inet_tcp_connect_recv(struct tevent_req *req,
 920                                    int *perrno,
 921                                    TALLOC_CTX *mem_ctx,
 922                                    struct tstream_context **stream,
 923                                    struct tsocket_address **local,
 924                                    const char *location);
 925 #define tstream_inet_tcp_connect_recv(req, perrno, mem_ctx, stream, local) \
 926         _tstream_inet_tcp_connect_recv(req, perrno, mem_ctx, stream, local, \
 927                                        __location__)
 928 #endif
 929
 930 /**
 931  * @brief Connect async to a unix domain endpoint and create a tstream_context
 932  * for the stream based communication.
 933  *
 934  * Use this function to connect asynchronously to a unix domainendpoint and
 935  * create a tstream_context for the stream based communication.
 936  *
 937  * The callback is triggered when a socket is connected and ready for IO or an
 938  * error happened.
 939  *
 940  * @param[in]  mem_ctx  The talloc memory context to use.
 941  *
 942  * @param[in]  ev       The tevent_context to run on.
 943  *
 944  * @param[in]  local    An 'unix' tsocket_address for the local endpoint.
 945  *
 946  * @param[in]  remote   An 'unix' tsocket_address for the remote endpoint.
 947  *
 948  * @return              A 'tevent_req' handle, where the caller can register a
 949  *                      callback with tevent_req_set_callback(). NULL on a falal
 950  *                      error.
 951  *
 952  * @see tstream_unix_connect_recv()
 953  */
 954 struct tevent_req * tstream_unix_connect_send(TALLOC_CTX *mem_ctx,
 955                                         struct tevent_context *ev,
 956                                         const struct tsocket_address *local,
 957                                         const struct tsocket_address *remote);
 958
 959 #ifdef DOXYGEN
 960 /**
 961  * @brief Receive the result from a tstream_unix_connect_send().
 962  *
 963  * @param[in]  req      The tevent request from tstream_inet_tcp_connect_send().
 964  *
 965  * @param[out] perrno   The error number, set if an error occurred.
 966  *
 967  * @param[in]  mem_ctx  The talloc memory context to use.
 968  *
 969  * @param[in]  stream   The tstream context to work on.
 970  *
 971  * @return              0 on success, -1 on error with perrno set.
 972  */
 973 int tstream_unix_connect_recv(struct tevent_req *req,
 974                               int *perrno,
 975                               TALLOC_CTX *mem_ctx,
 976                               struct tstream_context **stream);
 977 #else
 978 int _tstream_unix_connect_recv(struct tevent_req *req,
 979                                int *perrno,
 980                                TALLOC_CTX *mem_ctx,
 981                                struct tstream_context **stream,
 982                                const char *location);
 983 #define tstream_unix_connect_recv(req, perrno, mem_ctx, stream) \
 984         _tstream_unix_connect_recv(req, perrno, mem_ctx, stream, \
 985                                           __location__)
 986 #endif
 987
 988 #ifdef DOXYGEN
 989 /**
 990  * @brief Create two connected 'unix' tsocket_contexts for stream based
 991  *        communication.
 992  *
 993  * @param[in]  mem_ctx1 The talloc memory context to use for stream1.
 994  *
 995  * @param[in]  stream1  The first stream to connect.
 996  *
 997  * @param[in]  mem_ctx2 The talloc memory context to use for stream2.
 998  *
 999  * @param[in]  stream2  The second stream to connect.
1000  *
1001  * @return              0 on success, -1 on error with errno set.
1002  */
1003 int tstream_unix_socketpair(TALLOC_CTX *mem_ctx1,
1004                             struct tstream_context **stream1,
1005                             TALLOC_CTX *mem_ctx2,
1006                             struct tstream_context **stream2);
1007 #else
1008 int _tstream_unix_socketpair(TALLOC_CTX *mem_ctx1,
1009                              struct tstream_context **_stream1,
1010                              TALLOC_CTX *mem_ctx2,
1011                              struct tstream_context **_stream2,
1012                              const char *location);
1013
1014 #define tstream_unix_socketpair(mem_ctx1, stream1, mem_ctx2, stream2) \
1015         _tstream_unix_socketpair(mem_ctx1, stream1, mem_ctx2, stream2, \
1016                                  __location__)
1017 #endif
1018
1019 struct sockaddr;
1020
1021 #ifdef DOXYGEN
1022 /**
1023  * @brief Convert a tsocket address to a bsd socket address.
1024  *
1025  * @param[in]  mem_ctx  The talloc memory context to use.
1026  *
1027  * @param[in]  sa       The sockaddr structure to convert.
1028  *
1029  * @param[in]  sa_socklen   The length of the sockaddr structure.
1030  *
1031  * @param[out] addr     The tsocket pointer to allocate and fill.
1032  *
1033  * @return              0 on success, -1 on error with errno set.
1034  */
1035 int tsocket_address_bsd_from_sockaddr(TALLOC_CTX *mem_ctx,
1036                                       const struct sockaddr *sa,
1037                                       size_t sa_socklen,
1038                                       struct tsocket_address **addr);
1039 #else
1040 int _tsocket_address_bsd_from_sockaddr(TALLOC_CTX *mem_ctx,
1041                                        const struct sockaddr *sa,
1042                                        size_t sa_socklen,
1043                                        struct tsocket_address **_addr,
1044                                        const char *location);
1045
1046 #define tsocket_address_bsd_from_sockaddr(mem_ctx, sa, sa_socklen, _addr) \
1047         _tsocket_address_bsd_from_sockaddr(mem_ctx, sa, sa_socklen, _addr, \
1048                                            __location__)
1049 #endif
1050
1051 #ifdef DOXYGEN
1052 /**
1053  * @brief Convert a samba address to a tsocket address.
1054  *
1055  * @param[in]  mem_ctx  The talloc memory context to use.
1056  *
1057  * @param[in]  s_addr   The samba address structure to convert.
1058  *
1059  * @param[out] t_addr   The tsocket pointer to allocate and fill.
1060  *
1061  * @return              0 on success, -1 on error with errno set.
1062  */
1063 int tsocket_address_bsd_from_samba_sockaddr(TALLOC_CTX *mem_ctx,
1064                                         const struct samba_sockaddr *xs_addr,
1065                                         struct tsocket_address **t_addr);
1066 #else
1067 int _tsocket_address_bsd_from_samba_sockaddr(TALLOC_CTX *mem_ctx,
1068                                          const struct samba_sockaddr *xs_addr,
1069                                          struct tsocket_address **t_addr,
1070                                          const char *location);
1071
1072 #define tsocket_address_bsd_from_samba_sockaddr(mem_ctx, xs_addr, t_addr) \
1073         _tsocket_address_bsd_from_samba_sockaddr(mem_ctx, xs_addr, t_addr, \
1074                                                  __location__)
1075 #endif
1076
1077 /**
1078  * @brief Fill a bsd sockaddr structure.
1079  *
1080  * @param[in]  addr     The tsocket address structure to use.
1081  *
1082  * @param[in]  sa       The bsd sockaddr structure to fill out.
1083  *
1084  * @param[in]  sa_socklen   The length of the  bsd sockaddr structure to fill out.
1085  *
1086  * @return              The actual size of the sockaddr structure, -1 on error
1087  *                      with errno set. The size could differ from sa_socklen.
1088  *
1089  * @code
1090  *   ssize_t socklen;
1091  *   struct sockaddr_storage ss;
1092  *
1093  *   socklen = tsocket_address_bsd_sockaddr(taddr,
1094  *                    (struct sockaddr *) &ss,
1095  *                    sizeof(struct sockaddr_storage));
1096  *   if (socklen < 0) {
1097  *     return -1;
1098  *   }
1099  * @endcode
1100  */
1101 ssize_t tsocket_address_bsd_sockaddr(const struct tsocket_address *addr,
1102                                      struct sockaddr *sa,
1103                                      size_t sa_socklen);
1104
1105 #ifdef DOXYGEN
1106 /**
1107  * @brief Wrap an existing file descriptors into the tstream abstraction.
1108  *
1109  * You can use this function to wrap an existing file descriptors into the
1110  * tstream abstraction. After that you're not able to use this file descriptor
1111  * for anything else. The file descriptor will be closed when the stream gets
1112  * freed. If you still want to use the fd you have to create a duplicate.
1113  *
1114  * @param[in]  mem_ctx  The talloc memory context to use.
1115  *
1116  * @param[in]  fd       The non blocking fd to use!
1117  *
1118  * @param[out] stream   A pointer to store an allocated tstream_context.
1119  *
1120  * @return              0 on success, -1 on error.
1121  *
1122  * Example:
1123  * @code
1124  *   fd2 = dup(fd);
1125  *   rc = tstream_bsd_existing_socket(mem_ctx, fd2, &tstream);
1126  *   if (rc < 0) {
1127  *     stream_terminate_connection(conn, "named_pipe_accept: out of memory");
1128  *     return;
1129  *   }
1130  * @endcode
1131  *
1132  * @warning This is an internal function. You should read the code to fully
1133  *          understand it if you plan to use it.
1134  */
1135 int tstream_bsd_existing_socket(TALLOC_CTX *mem_ctx,
1136                                 int fd,
1137                                 struct tstream_context **stream);
1138 #else
1139 int _tstream_bsd_existing_socket(TALLOC_CTX *mem_ctx,
1140                                  int fd,
1141                                  struct tstream_context **_stream,
1142                                  const char *location);
1143 #define tstream_bsd_existing_socket(mem_ctx, fd, stream) \
1144         _tstream_bsd_existing_socket(mem_ctx, fd, stream, \
1145                                      __location__)
1146 #endif
1147
1148 /**
1149  * @}
1150  */
1151
1152 /**
1153  * @defgroup tsocket_helper Queue and PDU helpers
1154  * @ingroup tsocket
1155  *
1156  * In order to make the live easier for callers which want to implement a
1157  * function to receive a full PDU with a single async function pair, there're
1158  * some helper functions.
1159  *
1160  * There're some cases where the caller wants doesn't care about the order of
1161  * doing IO on the abstracted sockets.
1162  *
1163  * @{
1164  */
1165
1166 /**
1167  * @brief Queue a dgram blob for sending through the socket.
1168  *
1169  * This function queues a blob for sending to destination through an existing
1170  * dgram socket. The async callback is triggered when the whole blob is
1171  * delivered to the underlying system socket.
1172  *
1173  * The caller needs to make sure that all non-scalar input parameters hang
1174  * around for the whole lifetime of the request.
1175  *
1176  * @param[in]  mem_ctx  The memory context for the result.
1177  *
1178  * @param[in]  ev       The event context the operation should work on.
1179  *
1180  * @param[in]  dgram    The tdgram_context to send the message buffer.
1181  *
1182  * @param[in]  queue    The existing dgram queue.
1183  *
1184  * @param[in]  buf      The message buffer to send.
1185  *
1186  * @param[in]  len      The message length.
1187  *
1188  * @param[in]  dst      The destination socket address.
1189  *
1190  * @return              The async request handle. NULL on fatal error.
1191  *
1192  * @see tdgram_sendto_queue_recv()
1193  */
1194 struct tevent_req *tdgram_sendto_queue_send(TALLOC_CTX *mem_ctx,
1195                                             struct tevent_context *ev,
1196                                             struct tdgram_context *dgram,
1197                                             struct tevent_queue *queue,
1198                                             const uint8_t *buf,
1199                                             size_t len,
1200                                             struct tsocket_address *dst);
1201
1202 /**
1203  * @brief Receive the result of the sent dgram blob.
1204  *
1205  * @param[in]  req      The tevent request from tdgram_sendto_queue_send().
1206  *
1207  * @param[out] perrno   The error set to the actual errno.
1208  *
1209  * @return              The length of the datagram (0 is never returned!), -1 on
1210  *                      error with perrno set to the actual errno.
1211  */
1212 ssize_t tdgram_sendto_queue_recv(struct tevent_req *req, int *perrno);
1213
1214 typedef int (*tstream_readv_pdu_next_vector_t)(struct tstream_context *stream,
1215                                                void *private_data,
1216                                                TALLOC_CTX *mem_ctx,
1217                                                struct iovec **vector,
1218                                                size_t *count);
1219
1220 struct tevent_req *tstream_readv_pdu_send(TALLOC_CTX *mem_ctx,
1221                                 struct tevent_context *ev,
1222                                 struct tstream_context *stream,
1223                                 tstream_readv_pdu_next_vector_t next_vector_fn,
1224                                 void *next_vector_private);
1225 int tstream_readv_pdu_recv(struct tevent_req *req, int *perrno);
1226
1227 /**
1228  * @brief Queue a read request for a PDU on the socket.
1229  *
1230  * This function queues a read request for a PDU on a stream socket. The async
1231  * callback is triggered when a full PDU has been read from the socket.
1232  *
1233  * The caller needs to make sure that all non-scalar input parameters hang
1234  * around for the whole lifetime of the request.
1235  *
1236  * @param[in]  mem_ctx  The memory context for the result
1237  *
1238  * @param[in]  ev       The tevent_context to run on
1239  *
1240  * @param[in]  stream   The stream to send data through
1241  *
1242  * @param[in]  queue    The existing send queue
1243  *
1244  * @param[in]  next_vector_fn  The next vector function
1245  *
1246  * @param[in]  next_vector_private  The private_data of the next vector function
1247  *
1248  * @return              The async request handle. NULL on fatal error.
1249  *
1250  * @see tstream_readv_pdu_queue_recv()
1251  */
1252 struct tevent_req *tstream_readv_pdu_queue_send(TALLOC_CTX *mem_ctx,
1253                                 struct tevent_context *ev,
1254                                 struct tstream_context *stream,
1255                                 struct tevent_queue *queue,
1256                                 tstream_readv_pdu_next_vector_t next_vector_fn,
1257                                 void *next_vector_private);
1258
1259 /**
1260  * @brief Receive the PDU blob read from the stream.
1261  *
1262  * @param[in]  req      The tevent request from tstream_readv_pdu_queue_send().
1263  *
1264  * @param[out] perrno   The error set to the actual errno.
1265  *
1266  * @return              The number of bytes read on success, -1 on error with
1267  *                      perrno set to the actual errno.
1268  */
1269 int tstream_readv_pdu_queue_recv(struct tevent_req *req, int *perrno);
1270
1271 /**
1272  * @brief Queue an iovector for sending through the socket
1273  *
1274  * This function queues an iovector for sending to destination through an
1275  * existing stream socket. The async callback is triggered when the whole
1276  * vector has been delivered to the underlying system socket.
1277  *
1278  * The caller needs to make sure that all non-scalar input parameters hang
1279  * around for the whole lifetime of the request.
1280  *
1281  * @param[in]  mem_ctx  The memory context for the result.
1282  *
1283  * @param[in]  ev       The tevent_context to run on.
1284  *
1285  * @param[in]  stream   The stream to send data through.
1286  *
1287  * @param[in]  queue    The existing send queue.
1288  *
1289  * @param[in]  vector   The iovec vector so write.
1290  *
1291  * @param[in]  count    The size of the vector.
1292  *
1293  * @return              The async request handle. NULL on fatal error.
1294  */
1295 struct tevent_req *tstream_writev_queue_send(TALLOC_CTX *mem_ctx,
1296                                              struct tevent_context *ev,
1297                                              struct tstream_context *stream,
1298                                              struct tevent_queue *queue,
1299                                              const struct iovec *vector,
1300                                              size_t count);
1301
1302 /**
1303  * @brief Receive the result of the sent iovector.
1304  *
1305  * @param[in]  req      The tevent request from tstream_writev_queue_send().
1306  *
1307  * @param[out] perrno   The error set to the actual errno.
1308  *
1309  * @return              The length of the iovector (0 is never returned!), -1 on
1310  *                      error with perrno set to the actual errno.
1311  */
1312 int tstream_writev_queue_recv(struct tevent_req *req, int *perrno);
1313
1314 /**
1315  * @}
1316  */
1317
1318 #endif /* _TSOCKET_H */
1319