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