You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@apr.apache.org by Ian Holsman <ia...@cnet.com> on 2001/08/12 01:19:31 UTC
[DOX] apr_network_io
Index: srclib/apr/include/apr_network_io.h
===================================================================
RCS file: /home/cvspublic/apr/include/apr_network_io.h,v
retrieving revision 1.109
diff -u -r1.109 apr_network_io.h
--- srclib/apr/include/apr_network_io.h 2001/08/08 19:11:25 1.109
+++ srclib/apr/include/apr_network_io.h 2001/08/11 23:14:59
@@ -54,9 +54,14 @@
#ifndef APR_NETWORK_IO_H
#define APR_NETWORK_IO_H
-
+/**
+ * @file apr_network_io.h
+ * @brief APR Network library
+ */
/**
- * @package APR Network library
+ * @defgroup APR_Net Network Routines
+ * @ingroup APR
+ * @{
*/
#include "apr.h"
@@ -85,7 +90,10 @@
#define APR_ANYADDR "0.0.0.0"
#endif
-/* Socket option definitions */
+/**
+ * @defgroup Sock_opt Socket option definitions
+ * @{
+ */
#define APR_SO_LINGER 1
#define APR_SO_KEEPALIVE 2
#define APR_SO_DEBUG 4
@@ -97,13 +105,13 @@
#define APR_SO_DISCONNECTED 256
#define APR_TCP_NODELAY 512
#define APR_TCP_NOPUSH 1024
-#define APR_RESET_NODELAY 2048 /* This flag is ONLY set internally
+#define APR_RESET_NODELAY 2048 /**< This flag is ONLY set internally
* when we set APR_TCP_NOPUSH with
* APR_TCP_NODELAY set to tell us that
* APR_TCP_NODELAY should be turned on
* again when NOPUSH is turned off
*/
-#define APR_INCOMPLETE_READ 4096 /* Set on non-blocking sockets
+#define APR_INCOMPLETE_READ 4096 /**< Set on non-blocking sockets
* (APR_SO_TIMEOUT != 0) on which the
* previous read() did not fill a buffer
* completely. the next apr_recv() will
@@ -121,23 +129,29 @@
#define APR_POLLERR 0x010
#define APR_POLLHUP 0x020
#define APR_POLLNVAL 0x040
-
+/** @} */
typedef enum {APR_SHUTDOWN_READ, APR_SHUTDOWN_WRITE,
APR_SHUTDOWN_READWRITE} apr_shutdown_how_e;
-/* We need to make sure we always have an in_addr type, so APR will just
+#if (!APR_HAVE_IN_ADDR)
+/**
+ * We need to make sure we always have an in_addr type, so APR will just
* define it ourselves, if the platform doesn't provide it.
*/
-#if (!APR_HAVE_IN_ADDR)
struct in_addr {
- apr_uint32_t s_addr;
+ apr_uint32_t s_addr; /**< storage to hold the IP# */
}
#endif
-/* Not all platforms have these defined, so we'll define them here
+/**
+ * @def APR_INET
+ * Not all platforms have these defined, so we'll define them here
* The default values come from FreeBSD 4.1.1
*/
#define APR_INET AF_INET
+/** @def APR_UNSPEC
+ * Let the system decide which address family to use
+ */
#ifdef AF_UNSPEC
#define APR_UNSPEC AF_UNSPEC
#else
@@ -147,7 +161,9 @@
#define APR_INET6 AF_INET6
#endif
-/* Enum to tell us if we're interested in remote or local socket */
+/**
+ * Enum to tell us if we're interested in remote or local socket
+ */
typedef enum {
APR_LOCAL,
APR_REMOTE
@@ -160,25 +176,31 @@
#if APR_HAVE_INET_ADDR
#define apr_inet_addr inet_addr
#elif APR_HAVE_INET_NETWORK /* only DGUX, as far as I know */
-/* not generally safe... inet_network() and inet_addr() perform
+/**
+ * @warning
+ * not generally safe... inet_network() and inet_addr() perform
* different functions */
#define apr_inet_addr inet_network
#endif
typedef struct apr_socket_t apr_socket_t;
typedef struct apr_pollfd_t apr_pollfd_t;
+/**
+ * A structure to encapsulate headers and trailers for apr_sendfile
+ */
typedef struct apr_hdtr_t apr_hdtr_t;
typedef struct in_addr apr_in_addr_t;
-/* use apr_uint16_t just in case some system has a short that isn't 16
bits... */
+/** @remark use apr_uint16_t just in case some system has a short that
isn't 16 bits... */
typedef apr_uint16_t apr_port_t;
/* It's defined here as I think it should all be platform safe...
*/
-typedef struct apr_sockaddr_t apr_sockaddr_t;
/**
* APRs socket address type, used to ensure protocol independence
*/
+typedef struct apr_sockaddr_t apr_sockaddr_t;
+
struct apr_sockaddr_t {
/** The pool to use... */
apr_pool_t *pool;
@@ -253,7 +275,6 @@
* @param family The address family of the socket (e.g., APR_INET).
* @param type The type of the socket (e.g., SOCK_STREAM).
* @param cont The pool to use
- * @deffunc apr_status_t apr_socket_create(apr_socket_t **new_sock, int
family, int type, apr_pool_t *cont)
*/
APR_DECLARE(apr_status_t) apr_socket_create(apr_socket_t **new_sock,
int family, int type,
@@ -268,8 +289,7 @@
* APR_SHUTDOWN_WRITE no longer allow write requests
* APR_SHUTDOWN_READWRITE no longer allow read or write
requests
* </PRE>
- * @deffunc apr_status_t apr_shutdown(apr_socket_t *thesocket,
apr_shutdown_how_e how)
- * @tip This does not actually close the socket descriptor, it just
+ * @remark This does not actually close the socket descriptor, it just
* controls which calls are still valid on the socket.
*/
APR_DECLARE(apr_status_t) apr_shutdown(apr_socket_t *thesocket,
@@ -278,7 +298,6 @@
/**
* Close a tcp socket.
* @param thesocket The socket to close
- * @deffunc apr_status_t apr_socket_close(apr_socket_t *thesocket)
*/
APR_DECLARE(apr_status_t) apr_socket_close(apr_socket_t *thesocket);
@@ -286,9 +305,8 @@
* Bind the socket to its associated port
* @param sock The socket to bind
* @param sa The socket address to bind to
- * @tip This may be where we will find out if there is any other process
+ * @remark This may be where we will find out if there is any other process
* using the selected port.
- * @deffunc apr_status_t apr_bind(apr_socket_t *sock, apr_sockaddr_t *sa)
*/
APR_DECLARE(apr_status_t) apr_bind(apr_socket_t *sock, apr_sockaddr_t *sa);
@@ -298,7 +316,6 @@
* @param backlog The number of outstanding connections allowed in the
sockets
* listen queue. If this value is less than zero, the
listen
* queue size is set to zero.
- * @deffunc apr_status_t apr_listen(apr_socket_t *sock, apr_int32_t
backlog)
*/
APR_DECLARE(apr_status_t) apr_listen(apr_socket_t *sock, apr_int32_t
backlog);
@@ -309,7 +326,6 @@
* be used for all future communication.
* @param sock The socket we are listening on.
* @param connection_pool The pool for the new socket.
- * @deffunc apr_status_t apr_accept(apr_socket_t **new_sock,
apr_socket_t *sock, apr_pool_t *connection_pool)
*/
APR_DECLARE(apr_status_t) apr_accept(apr_socket_t **new_sock,
apr_socket_t *sock,
@@ -322,7 +338,6 @@
* @param sa The address of the machine we wish to connect to. If NULL,
* APR assumes that the sockaddr_in in the apr_socket is
* completely filled out.
- * @deffunc apr_status_t apr_connect(apr_socket_t *sock, apr_sockaddr_t
*sa)
*/
APR_DECLARE(apr_status_t) apr_connect(apr_socket_t *sock,
apr_sockaddr_t *sa);
@@ -335,7 +350,6 @@
* @param port The port number.
* @param flags Special processing flags.
* @param p The pool for the apr_sockaddr_t and associated storage.
- * @deffunc apr_status_t apr_sockaddr_info_get(apr_sockaddr_t **sa,
const char *hostname, apr_int32_t family, apr_port_t port, apr_int32_t
flags, apr_pool_t *p)
*/
APR_DECLARE(apr_status_t) apr_sockaddr_info_get(apr_sockaddr_t **sa,
const char *hostname,
@@ -349,7 +363,6 @@
* @param hostname The hostname.
* @param sa The apr_sockaddr_t.
* @param flags Special processing flags.
- * @deffunc apr_status_t apr_getnameinfo(char **hostname,
apr_sockaddr_t *sa, apr_int32_t flags)
*/
APR_DECLARE(apr_status_t) apr_getnameinfo(char **hostname,
apr_sockaddr_t *sa,
@@ -378,10 +391,9 @@
* specified.
* @param str The input string to be parsed.
* @param p The pool from which *addr and *scope_id are allocated.
- * @tip If scope id shouldn't be allowed, check for scope_id != NULL in
addition
+ * @remark If scope id shouldn't be allowed, check for scope_id != NULL
in addition
* to checking the return code. If addr/hostname should be
required, check
* for addr == NULL in addition to checking the return code.
- * @deffunc apr_status_t apr_parse_addr_port(char **addr, char
**scope_id, apr_port_t *port, const char *str, apr_pool_t *p)
*/
APR_DECLARE(apr_status_t) apr_parse_addr_port(char **addr,
char **scope_id,
@@ -395,7 +407,6 @@
* @param len The maximum length of the hostname that can be stored in the
* buffer provided.
* @param cont The pool to use.
- * @deffunc apr_status_t apr_gethostname(char *buf, int len, apr_pool_t
*cont)
*/
APR_DECLARE(apr_status_t) apr_gethostname(char *buf, int len,
apr_pool_t *cont);
@@ -404,7 +415,6 @@
* @param data The user data associated with the socket.
* @param key The key to associate with the user data.
* @param sock The currently open socket.
- * @deffunc apr_status_t apr_socket_data_get(void **data, const char
*key, apr_socket_t *sock)
*/
APR_DECLARE(apr_status_t) apr_socket_data_get(void **data, const char *key,
apr_socket_t *sock);
@@ -415,7 +425,6 @@
* @param data The user data to associate with the socket.
* @param key The key to associate with the data.
* @param cleanup The cleanup to call when the socket is destroyed.
- * @deffunc apr_status_t apr_socket_data_set(apr_socket_t *sock, void
*data, const char *key, apr_status_t (*cleanup)(void*))
*/
APR_DECLARE(apr_status_t) apr_socket_data_set(apr_socket_t *sock, void
*data,
const char *key,
@@ -427,8 +436,7 @@
* @param buf The buffer which contains the data to be sent.
* @param len On entry, the number of bytes to send; on exit, the number
* of bytes sent.
- * @deffunc apr_status_t apr_send(apr_socket_t *sock, const char *buf,
apr_size_t *len)
- * @tip
+ * @remark
* <PRE>
* This functions acts like a blocking write by default. To change
* this behavior, use apr_setsocketopt with the APR_SO_TIMEOUT option.
@@ -447,8 +455,7 @@
* @param vec The array of iovec structs containing the data to send
* @param nvec The number of iovec structs in the array
* @param len Receives the number of bytes actually written
- * @deffunc apr_status_t apr_sendv(apr_socket_t *sock, const struct
iovec *vec, apr_int32_t nvec, apr_size_t *len)
- * @tip
+ * @remark
* <PRE>
* This functions acts like a blocking write by default. To change
* this behavior, use apr_setsocketopt with the APR_SO_TIMEOUT option.
@@ -497,8 +504,7 @@
* (output) - Number of bytes actually sent,
* including headers, file, and trailers
* @param flags APR flags that are mapped to OS specific flags
- * @deffunc apr_status_t apr_sendfile(apr_socket_t *sock, apr_file_t
*file, apr_hdtr_t *hdtr, apr_off_t *offset, apr_size_t *len, apr_int32_t
flags)
- * @tip This functions acts like a blocking write by default. To change
+ * @remark This functions acts like a blocking write by default. To
change
* this behavior, use apr_setsocketopt with the APR_SO_TIMEOUT option.
* The number of bytes actually sent is stored in argument 5.
*/
@@ -514,8 +520,7 @@
* @param buf The buffer to store the data in.
* @param len On entry, the number of bytes to receive; on exit, the number
* of bytes received.
- * @deffunc apr_status_t apr_recv(apr_socket_t *sock, char *buf,
apr_size_t *len)
- * @tip
+ * @remark
* <PRE>
* This functions acts like a blocking read by default. To change
* this behavior, use apr_setsocketopt with the APR_SO_TIMEOUT option.
@@ -549,7 +554,6 @@
* APR_SO_RCVBUF -- Set the ReceiveBufferSize
* </PRE>
* @param on Value for the option.
- * @deffunc apr_status_t apr_setsocketopt(apr_socket_t *sock,
apr_int32_t opt, apr_int32_t on)
*/
APR_DECLARE(apr_status_t) apr_setsocketopt(apr_socket_t *sock,
apr_int32_t opt, apr_int32_t
on);
@@ -575,7 +579,6 @@
* (Currently only used on Windows)
* </PRE>
* @param on Socket option returned on the call.
- * @deffunc apr_status_t apr_getsocketopt(apr_socket_t *sock,
apr_int32_t opt, apr_int32_t *on)
*/
APR_DECLARE(apr_status_t) apr_getsocketopt(apr_socket_t *sock,
apr_int32_t opt, apr_int32_t
*on);
@@ -585,7 +588,6 @@
* @param sa The returned apr_sockaddr_t.
* @param which Which interface do we want the apr_sockaddr_t for?
* @param sock The socket to use
- * @deffunc apr_status_t apr_socket_addr_get(apr_sockaddr_t **sa,
apr_interface_e which, apr_socket_t *sock)
*/
APR_DECLARE(apr_status_t) apr_socket_addr_get(apr_sockaddr_t **sa,
apr_interface_e which,
@@ -595,7 +597,6 @@
* Set the port in an APR socket address.
* @param sockaddr The socket address to set.
* @param port The port to be stored in the socket address.
- * @deffunc apr_status_t apr_sockaddr_port_set(apr_sockaddr_t
*sockaddr, apr_port_t port)
*/
APR_DECLARE(apr_status_t) apr_sockaddr_port_set(apr_sockaddr_t *sockaddr,
apr_port_t port);
@@ -604,7 +605,6 @@
* Return the port in an APR socket address.
* @param port The port from the socket address.
* @param sockaddr The socket address to reference.
- * @deffunc apr_status_t apr_sockaddr_port_get(apr_port_t *port,
apr_sockaddr_t *sockaddr)
*/
APR_DECLARE(apr_status_t) apr_sockaddr_port_get(apr_port_t *port,
apr_sockaddr_t *sockaddr);
@@ -614,7 +614,6 @@
* @param sockaddr The socket address to use
* @param addr The IP address to attach to the socket.
* Use APR_ANYADDR to use any IP addr on the machine.
- * @deffunc apr_status_t apr_sockaddr_ip_set(apr_sockaddr_t *sockaddr,
const char *addr)
*/
APR_DECLARE(apr_status_t) apr_sockaddr_ip_set(apr_sockaddr_t *sockaddr,
const char *addr);
@@ -624,7 +623,6 @@
* an APR socket address.
* @param addr The IP address.
* @param sockaddr The socket address to reference.
- * @deffunc apr_status_t apr_sockaddr_ip_get(char **addr,
apr_sockaddr_t *sockaddr)
*/
APR_DECLARE(apr_status_t) apr_sockaddr_ip_get(char **addr,
apr_sockaddr_t *sockaddr);
@@ -634,7 +632,6 @@
* @param new_poll The poll structure to be used.
* @param num The number of socket descriptors to be polled.
* @param cont The pool to operate on.
- * @deffunc apr_status_t apr_poll_setup(apr_pollfd_t **new_poll,
apr_int32_t num, apr_pool_t *cont)
*/
APR_DECLARE(apr_status_t) apr_poll_setup(apr_pollfd_t **new_poll,
apr_int32_t num,
@@ -648,14 +645,13 @@
* a maximum, not a minimum. If a socket is signalled, we
* will wake up before this time. A negative number means
* wait until a socket is signalled.
- * @tip
+ * @remark
* <PRE>
* The number of sockets signalled is returned in the second argument.
*
* This is a blocking call, and it will not return until either a
* socket has been signalled, or the timeout has expired.
* </PRE>
- * @deffunc apr_status_t apr_poll(apr_pollfd_t *aprset, apr_int32_t
*nsds, apr_interval_time_t timeout)
*/
APR_DECLARE(apr_status_t) apr_poll(apr_pollfd_t *aprset, apr_int32_t
*nsds,
apr_interval_time_t timeout);
@@ -670,7 +666,6 @@
* APR_POLLPRI signal if prioirty data is availble to
be read
* APR_POLLOUT signal if write will not block
* </PRE>
- * @deffunc apr_status_t apr_poll_socket_add(apr_pollfd_t *aprset,
apr_socket_t *sock, apr_int16_t event)
*/
APR_DECLARE(apr_status_t) apr_poll_socket_add(apr_pollfd_t *aprset,
apr_socket_t *sock,
@@ -686,7 +681,6 @@
* APR_POLLPRI signal if prioirty data is availble to
be read
* APR_POLLOUT signal if write will not block
* </PRE>
- * @deffunc apr_status_t apr_poll_socket_mask(apr_pollfd_t *aprset,
apr_socket_t *sock, apr_int16_t events)
*/
APR_DECLARE(apr_status_t) apr_poll_socket_mask(apr_pollfd_t *aprset,
apr_socket_t *sock,
@@ -695,7 +689,6 @@
* Remove a socket from the poll structure.
* @param aprset The poll structure we will be using.
* @param sock The socket to remove from the current poll structure.
- * @deffunc apr_status_t apr_poll_socket_remove(apr_pollfd_t *aprset,
apr_socket_t *sock)
*/
APR_DECLARE(apr_status_t) apr_poll_socket_remove(apr_pollfd_t *aprset,
apr_socket_t *sock);
@@ -709,7 +702,6 @@
* APR_POLLPRI signal if prioirty data is availble to
be read
* APR_POLLOUT signal if write will not block
* </PRE>
- * @deffunc apr_status_t apr_poll_socket_clear(apr_pollfd_t *aprset,
apr_int16_t events)
*/
APR_DECLARE(apr_status_t) apr_poll_socket_clear(apr_pollfd_t *aprset,
apr_int16_t events);
@@ -728,7 +720,6 @@
* </PRE>
* @param sock The socket we wish to get information about.
* @param aprset The poll structure we will be using.
- * @deffunc apr_status_t apr_poll_revents_get(apr_int16_t *event,
apr_socket_t *sock, apr_pollfd_t *aprset)
*/
APR_DECLARE(apr_status_t) apr_poll_revents_get(apr_int16_t *event,
apr_socket_t *sock,
@@ -739,7 +730,6 @@
* @param pollfd The currently open pollfd.
* @param key The key to use for retreiving data associated with a poll
struct.
* @param data The user data associated with the pollfd.
- * @deffunc apr_status_t apr_poll_data_get(apr_pollfd_t *pollfd, const
char *key, void *data)
*/
APR_DECLARE(apr_status_t) apr_poll_data_get(apr_pollfd_t *pollfd,
const char *key, void *data);
@@ -750,7 +740,6 @@
* @param data The key to associate with the data.
* @param key The user data to associate with the pollfd.
* @param cleanup The cleanup function
- * @deffunc apr_status_t apr_poll_data_set(apr_pollfd_t *pollfd, void
*data, const char *key, apr_status_t (*cleanup)(void *))
*/
APR_DECLARE(apr_status_t) apr_poll_data_set(apr_pollfd_t *pollfd, void
*data,
const char *key,
@@ -762,7 +751,6 @@
* Convert a File type to a socket so that it can be used in a poll
operation.
* @param newsock the newly created socket which represents a file.
* @param file the file to mask as a socket.
- * @deffunc apr_status_t apr_socket_from_file(apr_socket_t **newsock,
apr_file_t *file)
* @warning This is not available on all platforms. Platforms that
have the
* ability to poll files for data to be read/written/exceptions will
* have the APR_FILES_AS_SOCKETS macro defined as true.
@@ -776,7 +764,6 @@
* Given an apr_sockaddr_t and a service name, set the port for the service
* @param sockaddr The apr_sockaddr_t that will have it's port set
* @param servname The name of the service you wish to use
- * @deffunc apr_status_t apr_getservbyname(apr_sockaddr_t *sockaddr,
const char *servname)
*/
APR_DECLARE(apr_status_t) apr_getservbyname(apr_sockaddr_t *sockaddr,
const char *servname);
@@ -816,20 +803,18 @@
/**
* Set a socket to be inherited by child processes.
* @param socket The socket to enable inheritance.
- * @deffunc void apr_socket_set_inherit(apr_socket_t *socket)
*/
APR_DECLARE(void) apr_socket_set_inherit(apr_socket_t *skt);
/**
* Unset a socket from being inherited by child processes.
* @param socket The socket to disable inheritance.
- * @deffunc void apr_socket_unset_inherit(apr_socket_t *socket)
*/
APR_DECLARE(void) apr_socket_unset_inherit(apr_socket_t *skt);
#ifdef __cplusplus
}
#endif
-
+/** @} */
#endif /* ! APR_NETWORK_IO_H */