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 30struct tsocket_address; 31struct tdgram_context; 32struct tstream_context; 33struct 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 */ 107char *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 */ 124struct tsocket_address *tsocket_address_copy(const struct tsocket_address *addr, 125 TALLOC_CTX *mem_ctx); 126#else 127struct 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 */ 172struct 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 */ 201ssize_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 */ 242struct 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 */ 263ssize_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 */ 288struct 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 */ 308int 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 */ 340ssize_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 */ 368struct 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 */ 387int 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 */ 412struct 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 */ 431int 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 */ 454struct 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 */ 471int 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 */ 509int 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 515int _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 */ 537char *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 */ 547uint16_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 */ 558int 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 */ 573int tsocket_address_unix_from_path(TALLOC_CTX *mem_ctx, 574 const char *path, 575 struct tsocket_address **_addr); 576#else 577int _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 */ 598char *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 */ 617int 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 622int _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 */ 647int 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 652int _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 */ 683struct 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 */ 703int tstream_inet_tcp_connect_recv(struct tevent_req *req, 704 int *perrno, 705 TALLOC_CTX *mem_ctx, 706 struct tstream_context **stream); 707#else 708int _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 */ 742struct 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 */ 761int tstream_unix_connect_recv(struct tevent_req *req, 762 int *perrno, 763 TALLOC_CTX *mem_ctx, 764 struct tstream_context **stream); 765#else 766int _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 */ 791int tstream_unix_socketpair(TALLOC_CTX *mem_ctx1, 792 struct tstream_context **stream1, 793 TALLOC_CTX *mem_ctx2, 794 struct tstream_context **stream2); 795#else 796int _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 807struct 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 */ 823int 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 828int _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 */ 863ssize_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. After that you're not able to use this file descriptor 873 * for anything else. The file descriptor will be closed when the stream gets 874 * freed. If you still want to use the fd you have have to create a duplicate. 875 * 876 * @param[in] mem_ctx The talloc memory context to use. 877 * 878 * @param[in] fd The non blocking fd to use! 879 * 880 * @param[in] stream The filed tstream_context you allocated before. 881 * 882 * @return 0 on success, -1 on error with errno set. 883 * 884 * @warning You should read the tsocket_bsd.c code and unterstand it in order 885 * use this function. 886 */ 887int tstream_bsd_existing_socket(TALLOC_CTX *mem_ctx, 888 int fd, 889 struct tstream_context **stream); 890#else 891int _tstream_bsd_existing_socket(TALLOC_CTX *mem_ctx, 892 int fd, 893 struct tstream_context **_stream, 894 const char *location); 895#define tstream_bsd_existing_socket(mem_ctx, fd, stream) \ 896 _tstream_bsd_existing_socket(mem_ctx, fd, stream, \ 897 __location__) 898#endif 899 900/** 901 * @} 902 */ 903 904/** 905 * @defgroup tsocket_helper Queue and PDU helpers 906 * @ingroup tsocket 907 * 908 * In order to make the live easier for callers which want to implement a 909 * function to receive a full PDU with a single async function pair, there're 910 * some helper functions. 911 * 912 * There're some cases where the caller wants doesn't care about the order of 913 * doing IO on the abstracted sockets. 914 * 915 * @{ 916 */ 917 918/** 919 * @brief Queue a dgram blob for sending through the socket. 920 * 921 * This function queues a blob for sending to destination through an existing 922 * dgram socket. The async callback is triggered when the whole blob is 923 * delivered to the underlying system socket. 924 * 925 * The caller needs to make sure that all non-scalar input parameters hang 926 * around for the whole lifetime of the request. 927 * 928 * @param[in] mem_ctx The memory context for the result. 929 * 930 * @param[in] ev The event context the operation should work on. 931 * 932 * @param[in] dgram The tdgram_context to send the message buffer. 933 * 934 * @param[in] queue The existing dgram queue. 935 * 936 * @param[in] buf The message buffer to send. 937 * 938 * @param[in] len The message length. 939 * 940 * @param[in] dst The destination socket address. 941 * 942 * @return The async request handle. NULL on fatal error. 943 * 944 * @see tdgram_sendto_queue_recv() 945 */ 946struct tevent_req *tdgram_sendto_queue_send(TALLOC_CTX *mem_ctx, 947 struct tevent_context *ev, 948 struct tdgram_context *dgram, 949 struct tevent_queue *queue, 950 const uint8_t *buf, 951 size_t len, 952 struct tsocket_address *dst); 953 954/** 955 * @brief Receive the result of the sent dgram blob. 956 * 957 * @param[in] req The tevent request from tdgram_sendto_queue_send(). 958 * 959 * @param[out] perrno The error set to the actual errno. 960 * 961 * @return The length of the datagram (0 is never returned!), -1 on 962 * error with perrno set to the actual errno. 963 */ 964ssize_t tdgram_sendto_queue_recv(struct tevent_req *req, int *perrno); 965 966typedef int (*tstream_readv_pdu_next_vector_t)(struct tstream_context *stream, 967 void *private_data, 968 TALLOC_CTX *mem_ctx, 969 struct iovec **vector, 970 size_t *count); 971 972struct tevent_req *tstream_readv_pdu_send(TALLOC_CTX *mem_ctx, 973 struct tevent_context *ev, 974 struct tstream_context *stream, 975 tstream_readv_pdu_next_vector_t next_vector_fn, 976 void *next_vector_private); 977int tstream_readv_pdu_recv(struct tevent_req *req, int *perrno); 978 979/** 980 * @brief Queue a read request for a PDU on the socket. 981 * 982 * This function queues a read request for a PDU on a stream socket. The async 983 * callback is triggered when a full PDU has been read from the socket. 984 * 985 * The caller needs to make sure that all non-scalar input parameters hang 986 * around for the whole lifetime of the request. 987 * 988 * @param[in] mem_ctx The memory context for the result 989 * 990 * @param[in] ev The tevent_context to run on 991 * 992 * @param[in] stream The stream to send data through 993 * 994 * @param[in] queue The existing send queue 995 * 996 * @param[in] next_vector_fn The next vector function 997 * 998 * @param[in] next_vector_private The private_data of the next vector function 999 * 1000 * @return The async request handle. NULL on fatal error. 1001 * 1002 * @see tstream_readv_pdu_queue_recv() 1003 */ 1004struct tevent_req *tstream_readv_pdu_queue_send(TALLOC_CTX *mem_ctx, 1005 struct tevent_context *ev, 1006 struct tstream_context *stream, 1007 struct tevent_queue *queue, 1008 tstream_readv_pdu_next_vector_t next_vector_fn, 1009 void *next_vector_private); 1010 1011/** 1012 * @brief Receive the PDU blob read from the stream. 1013 * 1014 * @param[in] req The tevent request from tstream_readv_pdu_queue_send(). 1015 * 1016 * @param[out] perrno The error set to the actual errno. 1017 * 1018 * @return The number of bytes read on success, -1 on error with 1019 * perrno set to the actual errno. 1020 */ 1021int tstream_readv_pdu_queue_recv(struct tevent_req *req, int *perrno); 1022 1023/** 1024 * @brief Queue an iovector for sending through the socket 1025 * 1026 * This function queues an iovector for sending to destination through an 1027 * existing stream socket. The async callback is triggered when the whole 1028 * vectror has been delivered to the underlying system socket. 1029 * 1030 * The caller needs to make sure that all non-scalar input parameters hang 1031 * around for the whole lifetime of the request. 1032 * 1033 * @param[in] mem_ctx The memory context for the result. 1034 * 1035 * @param[in] ev The tevent_context to run on. 1036 * 1037 * @param[in] stream The stream to send data through. 1038 * 1039 * @param[in] queue The existing send queue. 1040 * 1041 * @param[in] vector The iovec vector so write. 1042 * 1043 * @param[in] count The size of the vector. 1044 * 1045 * @return The async request handle. NULL on fatal error. 1046 */ 1047struct tevent_req *tstream_writev_queue_send(TALLOC_CTX *mem_ctx, 1048 struct tevent_context *ev, 1049 struct tstream_context *stream, 1050 struct tevent_queue *queue, 1051 const struct iovec *vector, 1052 size_t count); 1053 1054/** 1055 * @brief Receive the result of the sent iovector. 1056 * 1057 * @param[in] req The tevent request from tstream_writev_queue_send(). 1058 * 1059 * @param[out] perrno The error set to the actual errno. 1060 * 1061 * @return The length of the iovector (0 is never returned!), -1 on 1062 * error with perrno set to the actual errno. 1063 */ 1064int tstream_writev_queue_recv(struct tevent_req *req, int *perrno); 1065 1066/** 1067 * @} 1068 */ 1069 1070#endif /* _TSOCKET_H */ 1071 1072