apr_network_io.h

Go to the documentation of this file.
00001 /* Licensed to the Apache Software Foundation (ASF) under one or more
00002  * contributor license agreements.  See the NOTICE file distributed with
00003  * this work for additional information regarding copyright ownership.
00004  * The ASF licenses this file to You under the Apache License, Version 2.0
00005  * (the "License"); you may not use this file except in compliance with
00006  * the License.  You may obtain a copy of the License at
00007  *
00008  *     http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an "AS IS" BASIS,
00012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 
00017 #ifndef APR_NETWORK_IO_H
00018 #define APR_NETWORK_IO_H
00019 /**
00020  * @file apr_network_io.h
00021  * @brief APR Network library
00022  */
00023 
00024 #include "apr.h"
00025 #include "apr_pools.h"
00026 #include "apr_file_io.h"
00027 #include "apr_errno.h"
00028 #include "apr_inherit.h" 
00029 
00030 #if APR_HAVE_NETINET_IN_H
00031 #include <netinet/in.h>
00032 #endif
00033 
00034 #ifdef __cplusplus
00035 extern "C" {
00036 #endif /* __cplusplus */
00037 
00038 /**
00039  * @defgroup apr_network_io Network Routines
00040  * @ingroup APR 
00041  * @{
00042  */
00043 
00044 #ifndef APR_MAX_SECS_TO_LINGER
00045 /** Maximum seconds to linger */
00046 #define APR_MAX_SECS_TO_LINGER 30
00047 #endif
00048 
00049 #ifndef APRMAXHOSTLEN
00050 /** Maximum hostname length */
00051 #define APRMAXHOSTLEN 256
00052 #endif
00053 
00054 #ifndef APR_ANYADDR
00055 /** Default 'any' address */
00056 #define APR_ANYADDR "0.0.0.0"
00057 #endif
00058 
00059 /**
00060  * @defgroup apr_sockopt Socket option definitions
00061  * @{
00062  */
00063 #define APR_SO_LINGER        1    /**< Linger */
00064 #define APR_SO_KEEPALIVE     2    /**< Keepalive */
00065 #define APR_SO_DEBUG         4    /**< Debug */
00066 #define APR_SO_NONBLOCK      8    /**< Non-blocking IO */
00067 #define APR_SO_REUSEADDR     16   /**< Reuse addresses */
00068 #define APR_SO_SNDBUF        64   /**< Send buffer */
00069 #define APR_SO_RCVBUF        128  /**< Receive buffer */
00070 #define APR_SO_DISCONNECTED  256  /**< Disconnected */
00071 #define APR_TCP_NODELAY      512  /**< For SCTP sockets, this is mapped
00072                                    * to STCP_NODELAY internally.
00073                                    */
00074 #define APR_TCP_NOPUSH       1024 /**< No push */
00075 #define APR_RESET_NODELAY    2048 /**< This flag is ONLY set internally
00076                                    * when we set APR_TCP_NOPUSH with
00077                                    * APR_TCP_NODELAY set to tell us that
00078                                    * APR_TCP_NODELAY should be turned on
00079                                    * again when NOPUSH is turned off
00080                                    */
00081 #define APR_INCOMPLETE_READ 4096  /**< Set on non-blocking sockets
00082                                    * (timeout != 0) on which the
00083                                    * previous read() did not fill a buffer
00084                                    * completely.  the next apr_socket_recv() 
00085                                    * will first call select()/poll() rather than
00086                                    * going straight into read().  (Can also
00087                                    * be set by an application to force a
00088                                    * select()/poll() call before the next
00089                                    * read, in cases where the app expects
00090                                    * that an immediate read would fail.)
00091                                    */
00092 #define APR_INCOMPLETE_WRITE 8192 /**< like APR_INCOMPLETE_READ, but for write
00093                                    * @see APR_INCOMPLETE_READ
00094                                    */
00095 #define APR_IPV6_V6ONLY     16384 /**< Don't accept IPv4 connections on an
00096                                    * IPv6 listening socket.
00097                                    */
00098 #define APR_TCP_DEFER_ACCEPT 32768 /**< Delay accepting of new connections 
00099                                     * until data is available.
00100                                     * @see apr_socket_accept_filter
00101                                     */
00102 
00103 /** @} */
00104 
00105 /** Define what type of socket shutdown should occur. */
00106 typedef enum {
00107     APR_SHUTDOWN_READ,          /**< no longer allow read request */
00108     APR_SHUTDOWN_WRITE,         /**< no longer allow write requests */
00109     APR_SHUTDOWN_READWRITE      /**< no longer allow read or write requests */
00110 } apr_shutdown_how_e;
00111 
00112 #define APR_IPV4_ADDR_OK  0x01  /**< @see apr_sockaddr_info_get() */
00113 #define APR_IPV6_ADDR_OK  0x02  /**< @see apr_sockaddr_info_get() */
00114 
00115 #if (!APR_HAVE_IN_ADDR)
00116 /**
00117  * We need to make sure we always have an in_addr type, so APR will just
00118  * define it ourselves, if the platform doesn't provide it.
00119  */
00120 struct in_addr {
00121     apr_uint32_t  s_addr; /**< storage to hold the IP# */
00122 };
00123 #endif
00124 
00125 /** @def APR_INADDR_NONE
00126  * Not all platforms have a real INADDR_NONE.  This macro replaces
00127  * INADDR_NONE on all platforms.
00128  */
00129 #ifdef INADDR_NONE
00130 #define APR_INADDR_NONE INADDR_NONE
00131 #else
00132 #define APR_INADDR_NONE ((unsigned int) 0xffffffff)
00133 #endif
00134 
00135 /**
00136  * @def APR_INET
00137  * Not all platforms have these defined, so we'll define them here
00138  * The default values come from FreeBSD 4.1.1
00139  */
00140 #define APR_INET     AF_INET
00141 /** @def APR_UNSPEC
00142  * Let the system decide which address family to use
00143  */
00144 #ifdef AF_UNSPEC
00145 #define APR_UNSPEC   AF_UNSPEC
00146 #else
00147 #define APR_UNSPEC   0
00148 #endif
00149 #if APR_HAVE_IPV6
00150 /** @def APR_INET6
00151 * IPv6 Address Family. Not all platforms may have this defined.
00152 */
00153 
00154 #define APR_INET6    AF_INET6
00155 #endif
00156 
00157 /**
00158  * @defgroup IP_Proto IP Protocol Definitions for use when creating sockets
00159  * @{
00160  */
00161 #define APR_PROTO_TCP       6   /**< TCP  */
00162 #define APR_PROTO_UDP      17   /**< UDP  */
00163 #define APR_PROTO_SCTP    132   /**< SCTP */
00164 /** @} */
00165 
00166 /**
00167  * Enum used to denote either the local and remote endpoint of a
00168  * connection.
00169  */
00170 typedef enum {
00171     APR_LOCAL,   /**< Socket information for local end of connection */
00172     APR_REMOTE   /**< Socket information for remote end of connection */
00173 } apr_interface_e;
00174 
00175 /**
00176  * The specific declaration of inet_addr's ... some platforms fall back
00177  * inet_network (this is not good, but necessary)
00178  */
00179 
00180 #if APR_HAVE_INET_ADDR
00181 #define apr_inet_addr    inet_addr
00182 #elif APR_HAVE_INET_NETWORK        /* only DGUX, as far as I know */
00183 /**
00184  * @warning
00185  * not generally safe... inet_network() and inet_addr() perform
00186  * different functions */
00187 #define apr_inet_addr    inet_network
00188 #endif
00189 
00190 /** A structure to represent sockets */
00191 typedef struct apr_socket_t     apr_socket_t;
00192 /**
00193  * A structure to encapsulate headers and trailers for apr_socket_sendfile
00194  */
00195 typedef struct apr_hdtr_t       apr_hdtr_t;
00196 /** A structure to represent in_addr */
00197 typedef struct in_addr          apr_in_addr_t;
00198 /** A structure to represent an IP subnet */
00199 typedef struct apr_ipsubnet_t apr_ipsubnet_t;
00200 
00201 /** @remark use apr_uint16_t just in case some system has a short that isn't 16 bits... */
00202 typedef apr_uint16_t            apr_port_t;
00203 
00204 /** @remark It's defined here as I think it should all be platform safe...
00205  * @see apr_sockaddr_t
00206  */
00207 typedef struct apr_sockaddr_t apr_sockaddr_t;
00208 /**
00209  * APRs socket address type, used to ensure protocol independence
00210  */
00211 struct apr_sockaddr_t {
00212     /** The pool to use... */
00213     apr_pool_t *pool;
00214     /** The hostname */
00215     char *hostname;
00216     /** Either a string of the port number or the service name for the port */
00217     char *servname;
00218     /** The numeric port */
00219     apr_port_t port;
00220     /** The family */
00221     apr_int32_t family;
00222     /** How big is the sockaddr we're using? */
00223     apr_socklen_t salen;
00224     /** How big is the ip address structure we're using? */
00225     int ipaddr_len;
00226     /** How big should the address buffer be?  16 for v4 or 46 for v6
00227      *  used in inet_ntop... */
00228     int addr_str_len;
00229     /** This points to the IP address structure within the appropriate
00230      *  sockaddr structure.  */
00231     void *ipaddr_ptr;
00232     /** If multiple addresses were found by apr_sockaddr_info_get(), this 
00233      *  points to a representation of the next address. */
00234     apr_sockaddr_t *next;
00235     /** Union of either IPv4 or IPv6 sockaddr. */
00236     union {
00237         /** IPv4 sockaddr structure */
00238         struct sockaddr_in sin;
00239 #if APR_HAVE_IPV6
00240         /** IPv6 sockaddr structure */
00241         struct sockaddr_in6 sin6;
00242 #endif
00243 #if APR_HAVE_SA_STORAGE
00244         /** Placeholder to ensure that the size of this union is not
00245          * dependent on whether APR_HAVE_IPV6 is defined. */
00246         struct sockaddr_storage sas;
00247 #endif
00248     } sa;
00249 };
00250 
00251 #if APR_HAS_SENDFILE
00252 /** 
00253  * Support reusing the socket on platforms which support it (from disconnect,
00254  * specifically Win32.
00255  * @remark Optional flag passed into apr_socket_sendfile() 
00256  */
00257 #define APR_SENDFILE_DISCONNECT_SOCKET      1
00258 #endif
00259 
00260 /** A structure to encapsulate headers and trailers for apr_socket_sendfile */
00261 struct apr_hdtr_t {
00262     /** An iovec to store the headers sent before the file. */
00263     struct iovec* headers;
00264     /** number of headers in the iovec */
00265     int numheaders;
00266     /** An iovec to store the trailers sent after the file. */
00267     struct iovec* trailers;
00268     /** number of trailers in the iovec */
00269     int numtrailers;
00270 };
00271 
00272 /* function definitions */
00273 
00274 /**
00275  * Create a socket.
00276  * @param new_sock The new socket that has been set up.
00277  * @param family The address family of the socket (e.g., APR_INET).
00278  * @param type The type of the socket (e.g., SOCK_STREAM).
00279  * @param protocol The protocol of the socket (e.g., APR_PROTO_TCP).
00280  * @param cont The pool for the apr_socket_t and associated storage.
00281  */
00282 APR_DECLARE(apr_status_t) apr_socket_create(apr_socket_t **new_sock, 
00283                                             int family, int type,
00284                                             int protocol,
00285                                             apr_pool_t *cont);
00286 
00287 /**
00288  * Shutdown either reading, writing, or both sides of a socket.
00289  * @param thesocket The socket to close 
00290  * @param how How to shutdown the socket.  One of:
00291  * <PRE>
00292  *            APR_SHUTDOWN_READ         no longer allow read requests
00293  *            APR_SHUTDOWN_WRITE        no longer allow write requests
00294  *            APR_SHUTDOWN_READWRITE    no longer allow read or write requests 
00295  * </PRE>
00296  * @see apr_shutdown_how_e
00297  * @remark This does not actually close the socket descriptor, it just
00298  *      controls which calls are still valid on the socket.
00299  */
00300 APR_DECLARE(apr_status_t) apr_socket_shutdown(apr_socket_t *thesocket,
00301                                               apr_shutdown_how_e how);
00302 
00303 /**
00304  * Close a socket.
00305  * @param thesocket The socket to close 
00306  */
00307 APR_DECLARE(apr_status_t) apr_socket_close(apr_socket_t *thesocket);
00308 
00309 /**
00310  * Bind the socket to its associated port
00311  * @param sock The socket to bind 
00312  * @param sa The socket address to bind to
00313  * @remark This may be where we will find out if there is any other process
00314  *      using the selected port.
00315  */
00316 APR_DECLARE(apr_status_t) apr_socket_bind(apr_socket_t *sock, 
00317                                           apr_sockaddr_t *sa);
00318 
00319 /**
00320  * Listen to a bound socket for connections.
00321  * @param sock The socket to listen on 
00322  * @param backlog The number of outstanding connections allowed in the sockets
00323  *                listen queue.  If this value is less than zero, the listen
00324  *                queue size is set to zero.  
00325  */
00326 APR_DECLARE(apr_status_t) apr_socket_listen(apr_socket_t *sock, 
00327                                             apr_int32_t backlog);
00328 
00329 /**
00330  * Accept a new connection request
00331  * @param new_sock A copy of the socket that is connected to the socket that
00332  *                 made the connection request.  This is the socket which should
00333  *                 be used for all future communication.
00334  * @param sock The socket we are listening on.
00335  * @param connection_pool The pool for the new socket.
00336  */
00337 APR_DECLARE(apr_status_t) apr_socket_accept(apr_socket_t **new_sock, 
00338                                             apr_socket_t *sock,
00339                                             apr_pool_t *connection_pool);
00340 
00341 /**
00342  * Issue a connection request to a socket either on the same machine 
00343  * or a different one.
00344  * @param sock The socket we wish to use for our side of the connection 
00345  * @param sa The address of the machine we wish to connect to.
00346  */
00347 APR_DECLARE(apr_status_t) apr_socket_connect(apr_socket_t *sock,
00348                                              apr_sockaddr_t *sa);
00349 
00350 /**
00351  * Create apr_sockaddr_t from hostname, address family, and port.
00352  * @param sa The new apr_sockaddr_t.
00353  * @param hostname The hostname or numeric address string to resolve/parse, or
00354  *               NULL to build an address that corresponds to 0.0.0.0 or ::
00355  * @param family The address family to use, or APR_UNSPEC if the system should 
00356  *               decide.
00357  * @param port The port number.
00358  * @param flags Special processing flags:
00359  * <PRE>
00360  *       APR_IPV4_ADDR_OK          first query for IPv4 addresses; only look
00361  *                                 for IPv6 addresses if the first query failed;
00362  *                                 only valid if family is APR_UNSPEC and hostname
00363  *                                 isn't NULL; mutually exclusive with
00364  *                                 APR_IPV6_ADDR_OK
00365  *       APR_IPV6_ADDR_OK          first query for IPv6 addresses; only look
00366  *                                 for IPv4 addresses if the first query failed;
00367  *                                 only valid if family is APR_UNSPEC and hostname
00368  *                                 isn't NULL and APR_HAVE_IPV6; mutually exclusive
00369  *                                 with APR_IPV4_ADDR_OK
00370  * </PRE>
00371  * @param p The pool for the apr_sockaddr_t and associated storage.
00372  */
00373 APR_DECLARE(apr_status_t) apr_sockaddr_info_get(apr_sockaddr_t **sa,
00374                                           const char *hostname,
00375                                           apr_int32_t family,
00376                                           apr_port_t port,
00377                                           apr_int32_t flags,
00378                                           apr_pool_t *p);
00379 
00380 /**
00381  * Look up the host name from an apr_sockaddr_t.
00382  * @param hostname The hostname.
00383  * @param sa The apr_sockaddr_t.
00384  * @param flags Special processing flags.
00385  */
00386 APR_DECLARE(apr_status_t) apr_getnameinfo(char **hostname,
00387                                           apr_sockaddr_t *sa,
00388                                           apr_int32_t flags);
00389 
00390 /**
00391  * Parse hostname/IP address with scope id and port.
00392  *
00393  * Any of the following strings are accepted:
00394  *   8080                  (just the port number)
00395  *   www.apache.org        (just the hostname)
00396  *   www.apache.org:8080   (hostname and port number)
00397  *   [fe80::1]:80          (IPv6 numeric address string only)
00398  *   [fe80::1%eth0]        (IPv6 numeric address string and scope id)
00399  *
00400  * Invalid strings:
00401  *                         (empty string)
00402  *   [abc]                 (not valid IPv6 numeric address string)
00403  *   abc:65536             (invalid port number)
00404  *
00405  * @param addr The new buffer containing just the hostname.  On output, *addr 
00406  *             will be NULL if no hostname/IP address was specfied.
00407  * @param scope_id The new buffer containing just the scope id.  On output, 
00408  *                 *scope_id will be NULL if no scope id was specified.
00409  * @param port The port number.  On output, *port will be 0 if no port was 
00410  *             specified.
00411  *             ### FIXME: 0 is a legal port (per RFC 1700). this should
00412  *             ### return something besides zero if the port is missing.
00413  * @param str The input string to be parsed.
00414  * @param p The pool from which *addr and *scope_id are allocated.
00415  * @remark If scope id shouldn't be allowed, check for scope_id != NULL in 
00416  *         addition to checking the return code.  If addr/hostname should be 
00417  *         required, check for addr == NULL in addition to checking the 
00418  *         return code.
00419  */
00420 APR_DECLARE(apr_status_t) apr_parse_addr_port(char **addr,
00421                                               char **scope_id,
00422                                               apr_port_t *port,
00423                                               const char *str,
00424                                               apr_pool_t *p);
00425 
00426 /**
00427  * Get name of the current machine
00428  * @param buf A buffer to store the hostname in.
00429  * @param len The maximum length of the hostname that can be stored in the
00430  *            buffer provided.  The suggested length is APRMAXHOSTLEN + 1.
00431  * @param cont The pool to use.
00432  * @remark If the buffer was not large enough, an error will be returned.
00433  */
00434 APR_DECLARE(apr_status_t) apr_gethostname(char *buf, int len, apr_pool_t *cont);
00435 
00436 /**
00437  * Return the data associated with the current socket
00438  * @param data The user data associated with the socket.
00439  * @param key The key to associate with the user data.
00440  * @param sock The currently open socket.
00441  */
00442 APR_DECLARE(apr_status_t) apr_socket_data_get(void **data, const char *key,
00443                                               apr_socket_t *sock);
00444 
00445 /**
00446  * Set the data associated with the current socket.
00447  * @param sock The currently open socket.
00448  * @param data The user data to associate with the socket.
00449  * @param key The key to associate with the data.
00450  * @param cleanup The cleanup to call when the socket is destroyed.
00451  */
00452 APR_DECLARE(apr_status_t) apr_socket_data_set(apr_socket_t *sock, void *data,
00453                                               const char *key,
00454                                               apr_status_t (*cleanup)(void*));
00455 
00456 /**
00457  * Send data over a network.
00458  * @param sock The socket to send the data over.
00459  * @param buf The buffer which contains the data to be sent. 
00460  * @param len On entry, the number of bytes to send; on exit, the number
00461  *            of bytes sent.
00462  * @remark
00463  * <PRE>
00464  * This functions acts like a blocking write by default.  To change 
00465  * this behavior, use apr_socket_timeout_set() or the APR_SO_NONBLOCK
00466  * socket option.
00467  *
00468  * It is possible for both bytes to be sent and an error to be returned.
00469  *
00470  * APR_EINTR is never returned.
00471  * </PRE>
00472  */
00473 APR_DECLARE(apr_status_t) apr_socket_send(apr_socket_t *sock, const char *buf, 
00474                                           apr_size_t *len);
00475 
00476 /**
00477  * Send multiple packets of data over a network.
00478  * @param sock The socket to send the data over.
00479  * @param vec The array of iovec structs containing the data to send 
00480  * @param nvec The number of iovec structs in the array
00481  * @param len Receives the number of bytes actually written
00482  * @remark
00483  * <PRE>
00484  * This functions acts like a blocking write by default.  To change 
00485  * this behavior, use apr_socket_timeout_set() or the APR_SO_NONBLOCK
00486  * socket option.
00487  * The number of bytes actually sent is stored in argument 3.
00488  *
00489  * It is possible for both bytes to be sent and an error to be returned.
00490  *
00491  * APR_EINTR is never returned.
00492  * </PRE>
00493  */
00494 APR_DECLARE(apr_status_t) apr_socket_sendv(apr_socket_t *sock, 
00495                                            const struct iovec *vec,
00496                                            apr_int32_t nvec, apr_size_t *len);
00497 
00498 /**
00499  * @param sock The socket to send from
00500  * @param where The apr_sockaddr_t describing where to send the data
00501  * @param flags The flags to use
00502  * @param buf  The data to send
00503  * @param len  The length of the data to send
00504  */
00505 APR_DECLARE(apr_status_t) apr_socket_sendto(apr_socket_t *sock, 
00506                                             apr_sockaddr_t *where,
00507                                             apr_int32_t flags, const char *buf, 
00508                                             apr_size_t *len);
00509 
00510 /**
00511  * Read data from a socket.  On success, the address of the peer from
00512  * which the data was sent is copied into the @a from parameter, and the
00513  * @a len parameter is updated to give the number of bytes written to
00514  * @a buf.
00515  *
00516  * @param from Updated with the address from which the data was received
00517  * @param sock The socket to use
00518  * @param flags The flags to use
00519  * @param buf  The buffer to use
00520  * @param len  The length of the available buffer
00521  */
00522 
00523 APR_DECLARE(apr_status_t) apr_socket_recvfrom(apr_sockaddr_t *from, 
00524                                               apr_socket_t *sock,
00525                                               apr_int32_t flags, char *buf, 
00526                                               apr_size_t *len);
00527  
00528 #if APR_HAS_SENDFILE || defined(DOXYGEN)
00529 
00530 /**
00531  * Send a file from an open file descriptor to a socket, along with 
00532  * optional headers and trailers
00533  * @param sock The socket to which we're writing
00534  * @param file The open file from which to read
00535  * @param hdtr A structure containing the headers and trailers to send
00536  * @param offset Offset into the file where we should begin writing
00537  * @param len (input)  - Number of bytes to send from the file 
00538  *            (output) - Number of bytes actually sent, 
00539  *                       including headers, file, and trailers
00540  * @param flags APR flags that are mapped to OS specific flags
00541  * @remark This functions acts like a blocking write by default.  To change 
00542  *         this behavior, use apr_socket_timeout_set() or the
00543  *         APR_SO_NONBLOCK socket option.
00544  * The number of bytes actually sent is stored in the len parameter.
00545  * The offset parameter is passed by reference for no reason; its
00546  * value will never be modified by the apr_socket_sendfile() function.
00547  */
00548 APR_DECLARE(apr_status_t) apr_socket_sendfile(apr_socket_t *sock, 
00549                                               apr_file_t *file,
00550                                               apr_hdtr_t *hdtr,
00551                                               apr_off_t *offset,
00552                                               apr_size_t *len,
00553                                               apr_int32_t flags);
00554 
00555 #endif /* APR_HAS_SENDFILE */
00556 
00557 /**
00558  * Read data from a network.
00559  * @param sock The socket to read the data from.
00560  * @param buf The buffer to store the data in. 
00561  * @param len On entry, the number of bytes to receive; on exit, the number
00562  *            of bytes received.
00563  * @remark
00564  * <PRE>
00565  * This functions acts like a blocking read by default.  To change 
00566  * this behavior, use apr_socket_timeout_set() or the APR_SO_NONBLOCK
00567  * socket option.
00568  * The number of bytes actually received is stored in argument 3.
00569  *
00570  * It is possible for both bytes to be received and an APR_EOF or
00571  * other error to be returned.
00572  *
00573  * APR_EINTR is never returned.
00574  * </PRE>
00575  */
00576 APR_DECLARE(apr_status_t) apr_socket_recv(apr_socket_t *sock, 
00577                                    char *buf, apr_size_t *len);
00578 
00579 /**
00580  * Setup socket options for the specified socket
00581  * @param sock The socket to set up.
00582  * @param opt The option we would like to configure.  One of:
00583  * <PRE>
00584  *            APR_SO_DEBUG      --  turn on debugging information 
00585  *            APR_SO_KEEPALIVE  --  keep connections active
00586  *            APR_SO_LINGER     --  lingers on close if data is present
00587  *            APR_SO_NONBLOCK   --  Turns blocking on/off for socket
00588  *                                  When this option is enabled, use
00589  *                                  the APR_STATUS_IS_EAGAIN() macro to
00590  *                                  see if a send or receive function
00591  *                                  could not transfer data without
00592  *                                  blocking.
00593  *            APR_SO_REUSEADDR  --  The rules used in validating addresses
00594  *                                  supplied to bind should allow reuse
00595  *                                  of local addresses.
00596  *            APR_SO_SNDBUF     --  Set the SendBufferSize
00597  *            APR_SO_RCVBUF     --  Set the ReceiveBufferSize
00598  * </PRE>
00599  * @param on Value for the option.
00600  */
00601 APR_DECLARE(apr_status_t) apr_socket_opt_set(apr_socket_t *sock,
00602                                              apr_int32_t opt, apr_int32_t on);
00603 
00604 /**
00605  * Setup socket timeout for the specified socket
00606  * @param sock The socket to set up.
00607  * @param t Value for the timeout.
00608  * <PRE>
00609  *   t > 0  -- read and write calls return APR_TIMEUP if specified time
00610  *             elapsess with no data read or written
00611  *   t == 0 -- read and write calls never block
00612  *   t < 0  -- read and write calls block
00613  * </PRE>
00614  */
00615 APR_DECLARE(apr_status_t) apr_socket_timeout_set(apr_socket_t *sock,
00616                                                  apr_interval_time_t t);
00617 
00618 /**
00619  * Query socket options for the specified socket
00620  * @param sock The socket to query
00621  * @param opt The option we would like to query.  One of:
00622  * <PRE>
00623  *            APR_SO_DEBUG      --  turn on debugging information 
00624  *            APR_SO_KEEPALIVE  --  keep connections active
00625  *            APR_SO_LINGER     --  lingers on close if data is present
00626  *            APR_SO_NONBLOCK   --  Turns blocking on/off for socket
00627  *            APR_SO_REUSEADDR  --  The rules used in validating addresses
00628  *                                  supplied to bind should allow reuse
00629  *                                  of local addresses.
00630  *            APR_SO_SNDBUF     --  Set the SendBufferSize
00631  *            APR_SO_RCVBUF     --  Set the ReceiveBufferSize
00632  *            APR_SO_DISCONNECTED -- Query the disconnected state of the socket.
00633  *                                  (Currently only used on Windows)
00634  * </PRE>
00635  * @param on Socket option returned on the call.
00636  */
00637 APR_DECLARE(apr_status_t) apr_socket_opt_get(apr_socket_t *sock, 
00638                                              apr_int32_t opt, apr_int32_t *on);
00639 
00640 /**
00641  * Query socket timeout for the specified socket
00642  * @param sock The socket to query
00643  * @param t Socket timeout returned from the query.
00644  */
00645 APR_DECLARE(apr_status_t) apr_socket_timeout_get(apr_socket_t *sock, 
00646                                                  apr_interval_time_t *t);
00647 
00648 /**
00649  * Query the specified socket if at the OOB/Urgent data mark
00650  * @param sock The socket to query
00651  * @param atmark Is set to true if socket is at the OOB/urgent mark,
00652  *               otherwise is set to false.
00653  */
00654 APR_DECLARE(apr_status_t) apr_socket_atmark(apr_socket_t *sock, 
00655                                             int *atmark);
00656 
00657 /**
00658  * Return an address associated with a socket; either the address to
00659  * which the socket is bound locally or the the address of the peer
00660  * to which the socket is connected.
00661  * @param sa The returned apr_sockaddr_t.
00662  * @param which Whether to retrieve the local or remote address
00663  * @param sock The socket to use
00664  */
00665 APR_DECLARE(apr_status_t) apr_socket_addr_get(apr_sockaddr_t **sa,
00666                                               apr_interface_e which,
00667                                               apr_socket_t *sock);
00668  
00669 /**
00670  * Return the IP address (in numeric address string format) in
00671  * an APR socket address.  APR will allocate storage for the IP address 
00672  * string from the pool of the apr_sockaddr_t.
00673  * @param addr The IP address.
00674  * @param sockaddr The socket address to reference.
00675  */
00676 APR_DECLARE(apr_status_t) apr_sockaddr_ip_get(char **addr, 
00677                                               apr_sockaddr_t *sockaddr);
00678 
00679 /**
00680  * Write the IP address (in numeric address string format) of the APR
00681  * socket address @a sockaddr into the buffer @a buf (of size @a buflen).
00682  * @param sockaddr The socket address to reference.
00683  */
00684 APR_DECLARE(apr_status_t) apr_sockaddr_ip_getbuf(char *buf, apr_size_t buflen,
00685                                                  apr_sockaddr_t *sockaddr);
00686 
00687 /**
00688  * See if the IP addresses in two APR socket addresses are
00689  * equivalent.  Appropriate logic is present for comparing
00690  * IPv4-mapped IPv6 addresses with IPv4 addresses.
00691  *
00692  * @param addr1 One of the APR socket addresses.
00693  * @param addr2 The other APR socket address.
00694  * @remark The return value will be non-zero if the addresses
00695  * are equivalent.
00696  */
00697 APR_DECLARE(int) apr_sockaddr_equal(const apr_sockaddr_t *addr1,
00698                                     const apr_sockaddr_t *addr2);
00699 
00700 /**
00701 * Return the type of the socket.
00702 * @param sock The socket to query.
00703 * @param type The returned type (e.g., SOCK_STREAM).
00704 */
00705 APR_DECLARE(apr_status_t) apr_socket_type_get(apr_socket_t *sock,
00706                                               int *type);
00707  
00708 /**
00709  * Given an apr_sockaddr_t and a service name, set the port for the service
00710  * @param sockaddr The apr_sockaddr_t that will have its port set
00711  * @param servname The name of the service you wish to use
00712  */
00713 APR_DECLARE(apr_status_t) apr_getservbyname(apr_sockaddr_t *sockaddr, 
00714                                             const char *servname);
00715 /**
00716  * Build an ip-subnet representation from an IP address and optional netmask or
00717  * number-of-bits.
00718  * @param ipsub The new ip-subnet representation
00719  * @param ipstr The input IP address string
00720  * @param mask_or_numbits The input netmask or number-of-bits string, or NULL
00721  * @param p The pool to allocate from
00722  */
00723 APR_DECLARE(apr_status_t) apr_ipsubnet_create(apr_ipsubnet_t **ipsub, 
00724                                               const char *ipstr, 
00725                                               const char *mask_or_numbits, 
00726                                               apr_pool_t *p);
00727 
00728 /**
00729  * Test the IP address in an apr_sockaddr_t against a pre-built ip-subnet
00730  * representation.
00731  * @param ipsub The ip-subnet representation
00732  * @param sa The socket address to test
00733  * @return non-zero if the socket address is within the subnet, 0 otherwise
00734  */
00735 APR_DECLARE(int) apr_ipsubnet_test(apr_ipsubnet_t *ipsub, apr_sockaddr_t *sa);
00736 
00737 #if APR_HAS_SO_ACCEPTFILTER || defined(DOXYGEN)
00738 /**
00739  * Set an OS level accept filter.
00740  * @param sock The socket to put the accept filter on.
00741  * @param name The accept filter
00742  * @param args Any extra args to the accept filter.  Passing NULL here removes
00743  *             the accept filter. 
00744  */
00745 apr_status_t apr_socket_accept_filter(apr_socket_t *sock, char *name,
00746                                       char *args);
00747 #endif
00748 
00749 /**
00750  * Return the protocol of the socket.
00751  * @param sock The socket to query.
00752  * @param protocol The returned protocol (e.g., APR_PROTO_TCP).
00753  */
00754 APR_DECLARE(apr_status_t) apr_socket_protocol_get(apr_socket_t *sock,
00755                                                   int *protocol);
00756 
00757 /**
00758  * Get the pool used by the socket.
00759  */
00760 APR_POOL_DECLARE_ACCESSOR(socket);
00761 
00762 /**
00763  * Set a socket to be inherited by child processes.
00764  */
00765 APR_DECLARE_INHERIT_SET(socket);
00766 
00767 /**
00768  * Unset a socket from being inherited by child processes.
00769  */
00770 APR_DECLARE_INHERIT_UNSET(socket);
00771 
00772 /**
00773  * @defgroup apr_mcast IP Multicast
00774  * @{
00775  */
00776 
00777 /**
00778  * Join a Multicast Group
00779  * @param sock The socket to join a multicast group
00780  * @param join The address of the multicast group to join
00781  * @param iface Address of the interface to use.  If NULL is passed, the 
00782  *              default multicast interface will be used. (OS Dependent)
00783  * @param source Source Address to accept transmissions from (non-NULL 
00784  *               implies Source-Specific Multicast)
00785  */
00786 APR_DECLARE(apr_status_t) apr_mcast_join(apr_socket_t *sock,
00787                                          apr_sockaddr_t *join,
00788                                          apr_sockaddr_t *iface,
00789                                          apr_sockaddr_t *source);
00790 
00791 /**
00792  * Leave a Multicast Group.  All arguments must be the same as
00793  * apr_mcast_join.
00794  * @param sock The socket to leave a multicast group
00795  * @param addr The address of the multicast group to leave
00796  * @param iface Address of the interface to use.  If NULL is passed, the 
00797  *              default multicast interface will be used. (OS Dependent)
00798  * @param source Source Address to accept transmissions from (non-NULL 
00799  *               implies Source-Specific Multicast)
00800  */
00801 APR_DECLARE(apr_status_t) apr_mcast_leave(apr_socket_t *sock,
00802                                           apr_sockaddr_t *addr,
00803                                           apr_sockaddr_t *iface,
00804                                           apr_sockaddr_t *source);
00805 
00806 /**
00807  * Set the Multicast Time to Live (ttl) for a multicast transmission.
00808  * @param sock The socket to set the multicast ttl
00809  * @param ttl Time to live to Assign. 0-255, default=1
00810  * @remark If the TTL is 0, packets will only be seen by sockets on 
00811  * the local machine, and only when multicast loopback is enabled.
00812  */
00813 APR_DECLARE(apr_status_t) apr_mcast_hops(apr_socket_t *sock,
00814                                          apr_byte_t ttl);
00815 
00816 /**
00817  * Toggle IP Multicast Loopback
00818  * @param sock The socket to set multicast loopback
00819  * @param opt 0=disable, 1=enable
00820  */
00821 APR_DECLARE(apr_status_t) apr_mcast_loopback(apr_socket_t *sock,
00822                                              apr_byte_t opt);
00823 
00824 
00825 /**
00826  * Set the Interface to be used for outgoing Multicast Transmissions.
00827  * @param sock The socket to set the multicast interface on
00828  * @param iface Address of the interface to use for Multicast
00829  */
00830 APR_DECLARE(apr_status_t) apr_mcast_interface(apr_socket_t *sock,
00831                                               apr_sockaddr_t *iface);
00832 
00833 /** @} */
00834 
00835 /** @} */
00836 
00837 #ifdef __cplusplus
00838 }
00839 #endif
00840 
00841 #endif  /* ! APR_NETWORK_IO_H */
00842 

Generated on Sun Nov 10 18:38:48 2013 for Apache Portable Runtime by  doxygen 1.4.6