1 /* Licensed to the Apache Software Foundation (ASF) under one or more 2 * contributor license agreements. See the NOTICE file distributed with 3 * this work for additional information regarding copyright ownership. 4 * The ASF licenses this file to You under the Apache License, Version 2.0 5 * (the "License"); you may not use this file except in compliance with 6 * the License. You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 #ifndef APR_NETWORK_IO_H 18 #define APR_NETWORK_IO_H 19 /** 20 * @file apr_network_io.h 21 * @brief APR Network library 22 */ 23 24 #include "apr.h" 25 #include "apr_pools.h" 26 #include "apr_file_io.h" 27 #include "apr_errno.h" 28 #include "apr_inherit.h" 29 30 #if APR_HAVE_NETINET_IN_H 31 #include <netinet/in.h> 32 #endif 33 34 #ifdef __cplusplus 35 extern "C" { 36 #endif /* __cplusplus */ 37 38 /** 39 * @defgroup apr_network_io Network Routines 40 * @ingroup APR 41 * @{ 42 */ 43 44 #ifndef APR_MAX_SECS_TO_LINGER 45 /** Maximum seconds to linger */ 46 #define APR_MAX_SECS_TO_LINGER 30 47 #endif 48 49 #ifndef APRMAXHOSTLEN 50 /** Maximum hostname length */ 51 #define APRMAXHOSTLEN 256 52 #endif 53 54 #ifndef APR_ANYADDR 55 /** Default 'any' address */ 56 #define APR_ANYADDR "0.0.0.0" 57 #endif 58 59 /** 60 * @defgroup apr_sockopt Socket option definitions 61 * @{ 62 */ 63 #define APR_SO_LINGER 1 /**< Linger */ 64 #define APR_SO_KEEPALIVE 2 /**< Keepalive */ 65 #define APR_SO_DEBUG 4 /**< Debug */ 66 #define APR_SO_NONBLOCK 8 /**< Non-blocking IO */ 67 #define APR_SO_REUSEADDR 16 /**< Reuse addresses */ 68 #define APR_SO_SNDBUF 64 /**< Send buffer */ 69 #define APR_SO_RCVBUF 128 /**< Receive buffer */ 70 #define APR_SO_DISCONNECTED 256 /**< Disconnected */ 71 #define APR_TCP_NODELAY 512 /**< For SCTP sockets, this is mapped 72 * to STCP_NODELAY internally. 73 */ 74 #define APR_TCP_NOPUSH 1024 /**< No push */ 75 #define APR_RESET_NODELAY 2048 /**< This flag is ONLY set internally 76 * when we set APR_TCP_NOPUSH with 77 * APR_TCP_NODELAY set to tell us that 78 * APR_TCP_NODELAY should be turned on 79 * again when NOPUSH is turned off 80 */ 81 #define APR_INCOMPLETE_READ 4096 /**< Set on non-blocking sockets 82 * (timeout != 0) on which the 83 * previous read() did not fill a buffer 84 * completely. the next apr_socket_recv() 85 * will first call select()/poll() rather than 86 * going straight into read(). (Can also 87 * be set by an application to force a 88 * select()/poll() call before the next 89 * read, in cases where the app expects 90 * that an immediate read would fail.) 91 */ 92 #define APR_INCOMPLETE_WRITE 8192 /**< like APR_INCOMPLETE_READ, but for write 93 * @see APR_INCOMPLETE_READ 94 */ 95 #define APR_IPV6_V6ONLY 16384 /**< Don't accept IPv4 connections on an 96 * IPv6 listening socket. 97 */ 98 #define APR_TCP_DEFER_ACCEPT 32768 /**< Delay accepting of new connections 99 * until data is available. 100 * @see apr_socket_accept_filter 101 */ 102 #define APR_SO_BROADCAST 65536 /**< Allow broadcast 103 */ 104 105 /** @} */ 106 107 /** Define what type of socket shutdown should occur. */ 108 typedef enum { 109 APR_SHUTDOWN_READ, /**< no longer allow read request */ 110 APR_SHUTDOWN_WRITE, /**< no longer allow write requests */ 111 APR_SHUTDOWN_READWRITE /**< no longer allow read or write requests */ 112 } apr_shutdown_how_e; 113 114 #define APR_IPV4_ADDR_OK 0x01 /**< @see apr_sockaddr_info_get() */ 115 #define APR_IPV6_ADDR_OK 0x02 /**< @see apr_sockaddr_info_get() */ 116 117 #if (!APR_HAVE_IN_ADDR) 118 /** 119 * We need to make sure we always have an in_addr type, so APR will just 120 * define it ourselves, if the platform doesn't provide it. 121 */ 122 struct in_addr { 123 apr_uint32_t s_addr; /**< storage to hold the IP# */ 124 }; 125 #endif 126 127 /** @def APR_INADDR_NONE 128 * Not all platforms have a real INADDR_NONE. This macro replaces 129 * INADDR_NONE on all platforms. 130 */ 131 #ifdef INADDR_NONE 132 #define APR_INADDR_NONE INADDR_NONE 133 #else 134 #define APR_INADDR_NONE ((unsigned int) 0xffffffff) 135 #endif 136 137 /** 138 * @def APR_INET 139 * Not all platforms have these defined, so we'll define them here 140 * The default values come from FreeBSD 4.1.1 141 */ 142 #define APR_INET AF_INET 143 /** @def APR_UNSPEC 144 * Let the system decide which address family to use 145 */ 146 #ifdef AF_UNSPEC 147 #define APR_UNSPEC AF_UNSPEC 148 #else 149 #define APR_UNSPEC 0 150 #endif 151 #if APR_HAVE_IPV6 152 /** @def APR_INET6 153 * IPv6 Address Family. Not all platforms may have this defined. 154 */ 155 156 #define APR_INET6 AF_INET6 157 #endif 158 159 /** 160 * @defgroup IP_Proto IP Protocol Definitions for use when creating sockets 161 * @{ 162 */ 163 #define APR_PROTO_TCP 6 /**< TCP */ 164 #define APR_PROTO_UDP 17 /**< UDP */ 165 #define APR_PROTO_SCTP 132 /**< SCTP */ 166 /** @} */ 167 168 /** 169 * Enum used to denote either the local and remote endpoint of a 170 * connection. 171 */ 172 typedef enum { 173 APR_LOCAL, /**< Socket information for local end of connection */ 174 APR_REMOTE /**< Socket information for remote end of connection */ 175 } apr_interface_e; 176 177 /** 178 * The specific declaration of inet_addr's ... some platforms fall back 179 * inet_network (this is not good, but necessary) 180 */ 181 182 #if APR_HAVE_INET_ADDR 183 #define apr_inet_addr inet_addr 184 #elif APR_HAVE_INET_NETWORK /* only DGUX, as far as I know */ 185 /** 186 * @warning 187 * not generally safe... inet_network() and inet_addr() perform 188 * different functions */ 189 #define apr_inet_addr inet_network 190 #endif 191 192 /** A structure to represent sockets */ 193 typedef struct apr_socket_t apr_socket_t; 194 /** 195 * A structure to encapsulate headers and trailers for apr_socket_sendfile 196 */ 197 typedef struct apr_hdtr_t apr_hdtr_t; 198 /** A structure to represent in_addr */ 199 typedef struct in_addr apr_in_addr_t; 200 /** A structure to represent an IP subnet */ 201 typedef struct apr_ipsubnet_t apr_ipsubnet_t; 202 203 /** @remark use apr_uint16_t just in case some system has a short that isn't 16 bits... */ 204 typedef apr_uint16_t apr_port_t; 205 206 /** @remark It's defined here as I think it should all be platform safe... 207 * @see apr_sockaddr_t 208 */ 209 typedef struct apr_sockaddr_t apr_sockaddr_t; 210 /** 211 * APRs socket address type, used to ensure protocol independence 212 */ 213 struct apr_sockaddr_t { 214 /** The pool to use... */ 215 apr_pool_t *pool; 216 /** The hostname */ 217 char *hostname; 218 /** Either a string of the port number or the service name for the port */ 219 char *servname; 220 /** The numeric port */ 221 apr_port_t port; 222 /** The family */ 223 apr_int32_t family; 224 /** How big is the sockaddr we're using? */ 225 apr_socklen_t salen; 226 /** How big is the ip address structure we're using? */ 227 int ipaddr_len; 228 /** How big should the address buffer be? 16 for v4 or 46 for v6 229 * used in inet_ntop... */ 230 int addr_str_len; 231 /** This points to the IP address structure within the appropriate 232 * sockaddr structure. */ 233 void *ipaddr_ptr; 234 /** If multiple addresses were found by apr_sockaddr_info_get(), this 235 * points to a representation of the next address. */ 236 apr_sockaddr_t *next; 237 /** Union of either IPv4 or IPv6 sockaddr. */ 238 union { 239 /** IPv4 sockaddr structure */ 240 struct sockaddr_in sin; 241 #if APR_HAVE_IPV6 242 /** IPv6 sockaddr structure */ 243 struct sockaddr_in6 sin6; 244 #endif 245 #if APR_HAVE_SA_STORAGE 246 /** Placeholder to ensure that the size of this union is not 247 * dependent on whether APR_HAVE_IPV6 is defined. */ 248 struct sockaddr_storage sas; 249 #endif 250 } sa; 251 }; 252 253 #if APR_HAS_SENDFILE 254 /** 255 * Support reusing the socket on platforms which support it (from disconnect, 256 * specifically Win32. 257 * @remark Optional flag passed into apr_socket_sendfile() 258 */ 259 #define APR_SENDFILE_DISCONNECT_SOCKET 1 260 #endif 261 262 /** A structure to encapsulate headers and trailers for apr_socket_sendfile */ 263 struct apr_hdtr_t { 264 /** An iovec to store the headers sent before the file. */ 265 struct iovec* headers; 266 /** number of headers in the iovec */ 267 int numheaders; 268 /** An iovec to store the trailers sent after the file. */ 269 struct iovec* trailers; 270 /** number of trailers in the iovec */ 271 int numtrailers; 272 }; 273 274 /* function definitions */ 275 276 /** 277 * Create a socket. 278 * @param new_sock The new socket that has been set up. 279 * @param family The address family of the socket (e.g., APR_INET). 280 * @param type The type of the socket (e.g., SOCK_STREAM). 281 * @param protocol The protocol of the socket (e.g., APR_PROTO_TCP). 282 * @param cont The pool for the apr_socket_t and associated storage. 283 * @note The pool will be used by various functions that operate on the 284 * socket. The caller must ensure that it is not used by other threads 285 * at the same time. 286 */ 287 APR_DECLARE(apr_status_t) apr_socket_create(apr_socket_t **new_sock, 288 int family, int type, 289 int protocol, 290 apr_pool_t *cont); 291 292 /** 293 * Shutdown either reading, writing, or both sides of a socket. 294 * @param thesocket The socket to close 295 * @param how How to shutdown the socket. One of: 296 * <PRE> 297 * APR_SHUTDOWN_READ no longer allow read requests 298 * APR_SHUTDOWN_WRITE no longer allow write requests 299 * APR_SHUTDOWN_READWRITE no longer allow read or write requests 300 * </PRE> 301 * @see apr_shutdown_how_e 302 * @remark This does not actually close the socket descriptor, it just 303 * controls which calls are still valid on the socket. 304 */ 305 APR_DECLARE(apr_status_t) apr_socket_shutdown(apr_socket_t *thesocket, 306 apr_shutdown_how_e how); 307 308 /** 309 * Close a socket. 310 * @param thesocket The socket to close 311 */ 312 APR_DECLARE(apr_status_t) apr_socket_close(apr_socket_t *thesocket); 313 314 /** 315 * Bind the socket to its associated port 316 * @param sock The socket to bind 317 * @param sa The socket address to bind to 318 * @remark This may be where we will find out if there is any other process 319 * using the selected port. 320 */ 321 APR_DECLARE(apr_status_t) apr_socket_bind(apr_socket_t *sock, 322 apr_sockaddr_t *sa); 323 324 /** 325 * Listen to a bound socket for connections. 326 * @param sock The socket to listen on 327 * @param backlog The number of outstanding connections allowed in the sockets 328 * listen queue. If this value is less than zero, the listen 329 * queue size is set to zero. 330 */ 331 APR_DECLARE(apr_status_t) apr_socket_listen(apr_socket_t *sock, 332 apr_int32_t backlog); 333 334 /** 335 * Accept a new connection request 336 * @param new_sock A copy of the socket that is connected to the socket that 337 * made the connection request. This is the socket which should 338 * be used for all future communication. 339 * @param sock The socket we are listening on. 340 * @param connection_pool The pool for the new socket. 341 * @note The pool will be used by various functions that operate on the 342 * socket. The caller must ensure that it is not used by other threads 343 * at the same time. 344 */ 345 APR_DECLARE(apr_status_t) apr_socket_accept(apr_socket_t **new_sock, 346 apr_socket_t *sock, 347 apr_pool_t *connection_pool); 348 349 /** 350 * Issue a connection request to a socket either on the same machine 351 * or a different one. 352 * @param sock The socket we wish to use for our side of the connection 353 * @param sa The address of the machine we wish to connect to. 354 */ 355 APR_DECLARE(apr_status_t) apr_socket_connect(apr_socket_t *sock, 356 apr_sockaddr_t *sa); 357 358 /** 359 * Determine whether the receive part of the socket has been closed by 360 * the peer (such that a subsequent call to apr_socket_read would 361 * return APR_EOF), if the socket's receive buffer is empty. This 362 * function does not block waiting for I/O. 363 * 364 * @param sock The socket to check 365 * @param atreadeof If APR_SUCCESS is returned, *atreadeof is set to 366 * non-zero if a subsequent read would return APR_EOF 367 * @return an error is returned if it was not possible to determine the 368 * status, in which case *atreadeof is not changed. 369 */ 370 APR_DECLARE(apr_status_t) apr_socket_atreadeof(apr_socket_t *sock, 371 int *atreadeof); 372 373 /** 374 * Create apr_sockaddr_t from hostname, address family, and port. 375 * @param sa The new apr_sockaddr_t. 376 * @param hostname The hostname or numeric address string to resolve/parse, or 377 * NULL to build an address that corresponds to 0.0.0.0 or :: 378 * @param family The address family to use, or APR_UNSPEC if the system should 379 * decide. 380 * @param port The port number. 381 * @param flags Special processing flags: 382 * <PRE> 383 * APR_IPV4_ADDR_OK first query for IPv4 addresses; only look 384 * for IPv6 addresses if the first query failed; 385 * only valid if family is APR_UNSPEC and hostname 386 * isn't NULL; mutually exclusive with 387 * APR_IPV6_ADDR_OK 388 * APR_IPV6_ADDR_OK first query for IPv6 addresses; only look 389 * for IPv4 addresses if the first query failed; 390 * only valid if family is APR_UNSPEC and hostname 391 * isn't NULL and APR_HAVE_IPV6; mutually exclusive 392 * with APR_IPV4_ADDR_OK 393 * </PRE> 394 * @param p The pool for the apr_sockaddr_t and associated storage. 395 */ 396 APR_DECLARE(apr_status_t) apr_sockaddr_info_get(apr_sockaddr_t **sa, 397 const char *hostname, 398 apr_int32_t family, 399 apr_port_t port, 400 apr_int32_t flags, 401 apr_pool_t *p); 402 403 /** 404 * Look up the host name from an apr_sockaddr_t. 405 * @param hostname The hostname. 406 * @param sa The apr_sockaddr_t. 407 * @param flags Special processing flags. 408 * @remark Results can vary significantly between platforms 409 * when processing wildcard socket addresses. 410 */ 411 APR_DECLARE(apr_status_t) apr_getnameinfo(char **hostname, 412 apr_sockaddr_t *sa, 413 apr_int32_t flags); 414 415 /** 416 * Parse hostname/IP address with scope id and port. 417 * 418 * Any of the following strings are accepted: 419 * 8080 (just the port number) 420 * www.apache.org (just the hostname) 421 * www.apache.org:8080 (hostname and port number) 422 * [fe80::1]:80 (IPv6 numeric address string only) 423 * [fe80::1%eth0] (IPv6 numeric address string and scope id) 424 * 425 * Invalid strings: 426 * (empty string) 427 * [abc] (not valid IPv6 numeric address string) 428 * abc:65536 (invalid port number) 429 * 430 * @param addr The new buffer containing just the hostname. On output, *addr 431 * will be NULL if no hostname/IP address was specfied. 432 * @param scope_id The new buffer containing just the scope id. On output, 433 * *scope_id will be NULL if no scope id was specified. 434 * @param port The port number. On output, *port will be 0 if no port was 435 * specified. 436 * ### FIXME: 0 is a legal port (per RFC 1700). this should 437 * ### return something besides zero if the port is missing. 438 * @param str The input string to be parsed. 439 * @param p The pool from which *addr and *scope_id are allocated. 440 * @remark If scope id shouldn't be allowed, check for scope_id != NULL in 441 * addition to checking the return code. If addr/hostname should be 442 * required, check for addr == NULL in addition to checking the 443 * return code. 444 */ 445 APR_DECLARE(apr_status_t) apr_parse_addr_port(char **addr, 446 char **scope_id, 447 apr_port_t *port, 448 const char *str, 449 apr_pool_t *p); 450 451 /** 452 * Get name of the current machine 453 * @param buf A buffer to store the hostname in. 454 * @param len The maximum length of the hostname that can be stored in the 455 * buffer provided. The suggested length is APRMAXHOSTLEN + 1. 456 * @param cont The pool to use. 457 * @remark If the buffer was not large enough, an error will be returned. 458 */ 459 APR_DECLARE(apr_status_t) apr_gethostname(char *buf, int len, apr_pool_t *cont); 460 461 /** 462 * Return the data associated with the current socket 463 * @param data The user data associated with the socket. 464 * @param key The key to associate with the user data. 465 * @param sock The currently open socket. 466 */ 467 APR_DECLARE(apr_status_t) apr_socket_data_get(void **data, const char *key, 468 apr_socket_t *sock); 469 470 /** 471 * Set the data associated with the current socket. 472 * @param sock The currently open socket. 473 * @param data The user data to associate with the socket. 474 * @param key The key to associate with the data. 475 * @param cleanup The cleanup to call when the socket is destroyed. 476 */ 477 APR_DECLARE(apr_status_t) apr_socket_data_set(apr_socket_t *sock, void *data, 478 const char *key, 479 apr_status_t (*cleanup)(void*)); 480 481 /** 482 * Send data over a network. 483 * @param sock The socket to send the data over. 484 * @param buf The buffer which contains the data to be sent. 485 * @param len On entry, the number of bytes to send; on exit, the number 486 * of bytes sent. 487 * @remark 488 * <PRE> 489 * This functions acts like a blocking write by default. To change 490 * this behavior, use apr_socket_timeout_set() or the APR_SO_NONBLOCK 491 * socket option. 492 * 493 * It is possible for both bytes to be sent and an error to be returned. 494 * 495 * APR_EINTR is never returned. 496 * </PRE> 497 */ 498 APR_DECLARE(apr_status_t) apr_socket_send(apr_socket_t *sock, const char *buf, 499 apr_size_t *len); 500 501 /** 502 * Send multiple buffers over a network. 503 * @param sock The socket to send the data over. 504 * @param vec The array of iovec structs containing the data to send 505 * @param nvec The number of iovec structs in the array 506 * @param len Receives the number of bytes actually written 507 * @remark 508 * <PRE> 509 * This functions acts like a blocking write by default. To change 510 * this behavior, use apr_socket_timeout_set() or the APR_SO_NONBLOCK 511 * socket option. 512 * The number of bytes actually sent is stored in argument 4. 513 * 514 * It is possible for both bytes to be sent and an error to be returned. 515 * 516 * APR_EINTR is never returned. 517 * </PRE> 518 */ 519 APR_DECLARE(apr_status_t) apr_socket_sendv(apr_socket_t *sock, 520 const struct iovec *vec, 521 apr_int32_t nvec, apr_size_t *len); 522 523 /** 524 * @param sock The socket to send from 525 * @param where The apr_sockaddr_t describing where to send the data 526 * @param flags The flags to use 527 * @param buf The data to send 528 * @param len The length of the data to send 529 */ 530 APR_DECLARE(apr_status_t) apr_socket_sendto(apr_socket_t *sock, 531 apr_sockaddr_t *where, 532 apr_int32_t flags, const char *buf, 533 apr_size_t *len); 534 535 /** 536 * Read data from a socket. On success, the address of the peer from 537 * which the data was sent is copied into the @a from parameter, and the 538 * @a len parameter is updated to give the number of bytes written to 539 * @a buf. 540 * 541 * @param from Updated with the address from which the data was received 542 * @param sock The socket to use 543 * @param flags The flags to use 544 * @param buf The buffer to use 545 * @param len The length of the available buffer 546 */ 547 548 APR_DECLARE(apr_status_t) apr_socket_recvfrom(apr_sockaddr_t *from, 549 apr_socket_t *sock, 550 apr_int32_t flags, char *buf, 551 apr_size_t *len); 552 553 #if APR_HAS_SENDFILE || defined(DOXYGEN) 554 555 /** 556 * Send a file from an open file descriptor to a socket, along with 557 * optional headers and trailers 558 * @param sock The socket to which we're writing 559 * @param file The open file from which to read 560 * @param hdtr A structure containing the headers and trailers to send 561 * @param offset Offset into the file where we should begin writing 562 * @param len (input) - Number of bytes to send from the file 563 * (output) - Number of bytes actually sent, 564 * including headers, file, and trailers 565 * @param flags APR flags that are mapped to OS specific flags 566 * @remark This functions acts like a blocking write by default. To change 567 * this behavior, use apr_socket_timeout_set() or the 568 * APR_SO_NONBLOCK socket option. 569 * The number of bytes actually sent is stored in the len parameter. 570 * The offset parameter is passed by reference for no reason; its 571 * value will never be modified by the apr_socket_sendfile() function. 572 */ 573 APR_DECLARE(apr_status_t) apr_socket_sendfile(apr_socket_t *sock, 574 apr_file_t *file, 575 apr_hdtr_t *hdtr, 576 apr_off_t *offset, 577 apr_size_t *len, 578 apr_int32_t flags); 579 580 #endif /* APR_HAS_SENDFILE */ 581 582 /** 583 * Read data from a network. 584 * @param sock The socket to read the data from. 585 * @param buf The buffer to store the data in. 586 * @param len On entry, the number of bytes to receive; on exit, the number 587 * of bytes received. 588 * @remark 589 * <PRE> 590 * This functions acts like a blocking read by default. To change 591 * this behavior, use apr_socket_timeout_set() or the APR_SO_NONBLOCK 592 * socket option. 593 * The number of bytes actually received is stored in argument 3. 594 * 595 * It is possible for both bytes to be received and an APR_EOF or 596 * other error to be returned. 597 * 598 * APR_EINTR is never returned. 599 * </PRE> 600 */ 601 APR_DECLARE(apr_status_t) apr_socket_recv(apr_socket_t *sock, 602 char *buf, apr_size_t *len); 603 604 /** 605 * Setup socket options for the specified socket 606 * @param sock The socket to set up. 607 * @param opt The option we would like to configure. One of: 608 * <PRE> 609 * APR_SO_DEBUG -- turn on debugging information 610 * APR_SO_KEEPALIVE -- keep connections active 611 * APR_SO_LINGER -- lingers on close if data is present 612 * APR_SO_NONBLOCK -- Turns blocking on/off for socket 613 * When this option is enabled, use 614 * the APR_STATUS_IS_EAGAIN() macro to 615 * see if a send or receive function 616 * could not transfer data without 617 * blocking. 618 * APR_SO_REUSEADDR -- The rules used in validating addresses 619 * supplied to bind should allow reuse 620 * of local addresses. 621 * APR_SO_SNDBUF -- Set the SendBufferSize 622 * APR_SO_RCVBUF -- Set the ReceiveBufferSize 623 * </PRE> 624 * @param on Value for the option. 625 */ 626 APR_DECLARE(apr_status_t) apr_socket_opt_set(apr_socket_t *sock, 627 apr_int32_t opt, apr_int32_t on); 628 629 /** 630 * Setup socket timeout for the specified socket 631 * @param sock The socket to set up. 632 * @param t Value for the timeout. 633 * <PRE> 634 * t > 0 -- read and write calls return APR_TIMEUP if specified time 635 * elapsess with no data read or written 636 * t == 0 -- read and write calls never block 637 * t < 0 -- read and write calls block 638 * </PRE> 639 */ 640 APR_DECLARE(apr_status_t) apr_socket_timeout_set(apr_socket_t *sock, 641 apr_interval_time_t t); 642 643 /** 644 * Query socket options for the specified socket 645 * @param sock The socket to query 646 * @param opt The option we would like to query. One of: 647 * <PRE> 648 * APR_SO_DEBUG -- turn on debugging information 649 * APR_SO_KEEPALIVE -- keep connections active 650 * APR_SO_LINGER -- lingers on close if data is present 651 * APR_SO_NONBLOCK -- Turns blocking on/off for socket 652 * APR_SO_REUSEADDR -- The rules used in validating addresses 653 * supplied to bind should allow reuse 654 * of local addresses. 655 * APR_SO_SNDBUF -- Set the SendBufferSize 656 * APR_SO_RCVBUF -- Set the ReceiveBufferSize 657 * APR_SO_DISCONNECTED -- Query the disconnected state of the socket. 658 * (Currently only used on Windows) 659 * </PRE> 660 * @param on Socket option returned on the call. 661 */ 662 APR_DECLARE(apr_status_t) apr_socket_opt_get(apr_socket_t *sock, 663 apr_int32_t opt, apr_int32_t *on); 664 665 /** 666 * Query socket timeout for the specified socket 667 * @param sock The socket to query 668 * @param t Socket timeout returned from the query. 669 */ 670 APR_DECLARE(apr_status_t) apr_socket_timeout_get(apr_socket_t *sock, 671 apr_interval_time_t *t); 672 673 /** 674 * Query the specified socket if at the OOB/Urgent data mark 675 * @param sock The socket to query 676 * @param atmark Is set to true if socket is at the OOB/urgent mark, 677 * otherwise is set to false. 678 */ 679 APR_DECLARE(apr_status_t) apr_socket_atmark(apr_socket_t *sock, 680 int *atmark); 681 682 /** 683 * Return an address associated with a socket; either the address to 684 * which the socket is bound locally or the address of the peer 685 * to which the socket is connected. 686 * @param sa The returned apr_sockaddr_t. 687 * @param which Whether to retrieve the local or remote address 688 * @param sock The socket to use 689 */ 690 APR_DECLARE(apr_status_t) apr_socket_addr_get(apr_sockaddr_t **sa, 691 apr_interface_e which, 692 apr_socket_t *sock); 693 694 /** 695 * Return the IP address (in numeric address string format) in 696 * an APR socket address. APR will allocate storage for the IP address 697 * string from the pool of the apr_sockaddr_t. 698 * @param addr The IP address. 699 * @param sockaddr The socket address to reference. 700 */ 701 APR_DECLARE(apr_status_t) apr_sockaddr_ip_get(char **addr, 702 apr_sockaddr_t *sockaddr); 703 704 /** 705 * Write the IP address (in numeric address string format) of the APR 706 * socket address @a sockaddr into the buffer @a buf (of size @a buflen). 707 * @param sockaddr The socket address to reference. 708 */ 709 APR_DECLARE(apr_status_t) apr_sockaddr_ip_getbuf(char *buf, apr_size_t buflen, 710 apr_sockaddr_t *sockaddr); 711 712 /** 713 * See if the IP addresses in two APR socket addresses are 714 * equivalent. Appropriate logic is present for comparing 715 * IPv4-mapped IPv6 addresses with IPv4 addresses. 716 * 717 * @param addr1 One of the APR socket addresses. 718 * @param addr2 The other APR socket address. 719 * @remark The return value will be non-zero if the addresses 720 * are equivalent. 721 */ 722 APR_DECLARE(int) apr_sockaddr_equal(const apr_sockaddr_t *addr1, 723 const apr_sockaddr_t *addr2); 724 725 /** 726 * See if the IP address in an APR socket address refers to the wildcard 727 * address for the protocol family (e.g., INADDR_ANY for IPv4). 728 * 729 * @param addr The APR socket address to examine. 730 * @remark The return value will be non-zero if the address is 731 * initialized and is the wildcard address. 732 */ 733 APR_DECLARE(int) apr_sockaddr_is_wildcard(const apr_sockaddr_t *addr); 734 735 /** 736 * Return the type of the socket. 737 * @param sock The socket to query. 738 * @param type The returned type (e.g., SOCK_STREAM). 739 */ 740 APR_DECLARE(apr_status_t) apr_socket_type_get(apr_socket_t *sock, 741 int *type); 742 743 /** 744 * Given an apr_sockaddr_t and a service name, set the port for the service 745 * @param sockaddr The apr_sockaddr_t that will have its port set 746 * @param servname The name of the service you wish to use 747 */ 748 APR_DECLARE(apr_status_t) apr_getservbyname(apr_sockaddr_t *sockaddr, 749 const char *servname); 750 /** 751 * Build an ip-subnet representation from an IP address and optional netmask or 752 * number-of-bits. 753 * @param ipsub The new ip-subnet representation 754 * @param ipstr The input IP address string 755 * @param mask_or_numbits The input netmask or number-of-bits string, or NULL 756 * @param p The pool to allocate from 757 */ 758 APR_DECLARE(apr_status_t) apr_ipsubnet_create(apr_ipsubnet_t **ipsub, 759 const char *ipstr, 760 const char *mask_or_numbits, 761 apr_pool_t *p); 762 763 /** 764 * Test the IP address in an apr_sockaddr_t against a pre-built ip-subnet 765 * representation. 766 * @param ipsub The ip-subnet representation 767 * @param sa The socket address to test 768 * @return non-zero if the socket address is within the subnet, 0 otherwise 769 */ 770 APR_DECLARE(int) apr_ipsubnet_test(apr_ipsubnet_t *ipsub, apr_sockaddr_t *sa); 771 772 #if APR_HAS_SO_ACCEPTFILTER || defined(DOXYGEN) 773 /** 774 * Set an OS level accept filter. 775 * @param sock The socket to put the accept filter on. 776 * @param name The accept filter 777 * @param args Any extra args to the accept filter. Passing NULL here removes 778 * the accept filter. 779 * @bug name and args should have been declared as const char *, as they are in 780 * APR 2.0 781 */ 782 apr_status_t apr_socket_accept_filter(apr_socket_t *sock, char *name, 783 char *args); 784 #endif 785 786 /** 787 * Return the protocol of the socket. 788 * @param sock The socket to query. 789 * @param protocol The returned protocol (e.g., APR_PROTO_TCP). 790 */ 791 APR_DECLARE(apr_status_t) apr_socket_protocol_get(apr_socket_t *sock, 792 int *protocol); 793 794 /** 795 * Get the pool used by the socket. 796 */ 797 APR_POOL_DECLARE_ACCESSOR(socket); 798 799 /** 800 * Set a socket to be inherited by child processes. 801 */ 802 APR_DECLARE_INHERIT_SET(socket); 803 804 /** 805 * Unset a socket from being inherited by child processes. 806 */ 807 APR_DECLARE_INHERIT_UNSET(socket); 808 809 /** 810 * @defgroup apr_mcast IP Multicast 811 * @{ 812 */ 813 814 /** 815 * Join a Multicast Group 816 * @param sock The socket to join a multicast group 817 * @param join The address of the multicast group to join 818 * @param iface Address of the interface to use. If NULL is passed, the 819 * default multicast interface will be used. (OS Dependent) 820 * @param source Source Address to accept transmissions from (non-NULL 821 * implies Source-Specific Multicast) 822 */ 823 APR_DECLARE(apr_status_t) apr_mcast_join(apr_socket_t *sock, 824 apr_sockaddr_t *join, 825 apr_sockaddr_t *iface, 826 apr_sockaddr_t *source); 827 828 /** 829 * Leave a Multicast Group. All arguments must be the same as 830 * apr_mcast_join. 831 * @param sock The socket to leave a multicast group 832 * @param addr The address of the multicast group to leave 833 * @param iface Address of the interface to use. If NULL is passed, the 834 * default multicast interface will be used. (OS Dependent) 835 * @param source Source Address to accept transmissions from (non-NULL 836 * implies Source-Specific Multicast) 837 */ 838 APR_DECLARE(apr_status_t) apr_mcast_leave(apr_socket_t *sock, 839 apr_sockaddr_t *addr, 840 apr_sockaddr_t *iface, 841 apr_sockaddr_t *source); 842 843 /** 844 * Set the Multicast Time to Live (ttl) for a multicast transmission. 845 * @param sock The socket to set the multicast ttl 846 * @param ttl Time to live to Assign. 0-255, default=1 847 * @remark If the TTL is 0, packets will only be seen by sockets on 848 * the local machine, and only when multicast loopback is enabled. 849 */ 850 APR_DECLARE(apr_status_t) apr_mcast_hops(apr_socket_t *sock, 851 apr_byte_t ttl); 852 853 /** 854 * Toggle IP Multicast Loopback 855 * @param sock The socket to set multicast loopback 856 * @param opt 0=disable, 1=enable 857 */ 858 APR_DECLARE(apr_status_t) apr_mcast_loopback(apr_socket_t *sock, 859 apr_byte_t opt); 860 861 862 /** 863 * Set the Interface to be used for outgoing Multicast Transmissions. 864 * @param sock The socket to set the multicast interface on 865 * @param iface Address of the interface to use for Multicast 866 */ 867 APR_DECLARE(apr_status_t) apr_mcast_interface(apr_socket_t *sock, 868 apr_sockaddr_t *iface); 869 870 /** @} */ 871 872 /** @} */ 873 874 #ifdef __cplusplus 875 } 876 #endif 877 878 #endif /* ! APR_NETWORK_IO_H */ 879 880