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