lib/tsocket/tsocket.h

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