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