lib/tsocket/tsocket.h

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