Collaboration diagram for Network Routines:

Classes
struct	in_addr
struct	apr_sockaddr_t
struct	apr_hdtr_t
Modules
	Socket option definitions
	IP Protocol Definitions for use when creating sockets
	IP Multicast
Defines
#define	APR_MAX_SECS_TO_LINGER 30
#define	APRMAXHOSTLEN 256
#define	APR_ANYADDR "0.0.0.0"
#define	APR_IPV4_ADDR_OK 0x01
#define	APR_IPV6_ADDR_OK 0x02
#define	APR_INADDR_NONE ((unsigned int) 0xffffffff)
#define	APR_INET AF_INET
#define	APR_UNSPEC 0
Typedefs
typedef struct apr_socket_t	apr_socket_t
typedef struct apr_hdtr_t	apr_hdtr_t
typedef struct in_addr	apr_in_addr_t
typedef struct apr_ipsubnet_t	apr_ipsubnet_t
typedef apr_uint16_t	apr_port_t
typedef struct apr_sockaddr_t	apr_sockaddr_t
Enumerations
enum	apr_shutdown_how_e { APR_SHUTDOWN_READ, APR_SHUTDOWN_WRITE, APR_SHUTDOWN_READWRITE }
enum	apr_interface_e { APR_LOCAL, APR_REMOTE }
Functions
	APR_DECLARE (apr_status_t) apr_socket_create(apr_socket_t **new_sock
	APR_POOL_DECLARE_ACCESSOR (socket)
	APR_DECLARE_INHERIT_SET (socket)
	APR_DECLARE_INHERIT_UNSET (socket)
Variables
int	family
int int	type
int int int	protocol
int int int apr_pool_t *	cont
apr_shutdown_how_e	how
apr_sockaddr_t *	sa
apr_int32_t	backlog
apr_socket_t *	sock
apr_socket_t apr_pool_t *	connection_pool
int *	atreadeof
const char *	hostname
const char apr_int32_t apr_port_t	port
const char apr_int32_t apr_port_t apr_int32_t	flags
const char apr_int32_t apr_port_t apr_int32_t apr_pool_t *	p
char **	scope_id
char apr_port_t const char *	str
int	len
const char *	key
void *	data
void const char apr_status_t(*	cleanup )(void *))
const char *	buf
struct iovec *	vec
struct iovec apr_int32_t	nvec
apr_sockaddr_t *	where
apr_int32_t	opt
apr_int32_t apr_int32_t	on
apr_interval_time_t	t
int *	atmark
apr_interface_e	which
apr_sockaddr_t *	sockaddr
apr_size_t	buflen
const apr_sockaddr_t *	addr2
const char *	servname
const char *	ipstr
const char const char *	mask_or_numbits

Define Documentation

#define APR_ANYADDR "0.0.0.0"

Default 'any' address

Definition at line 56 of file apr_network_io.h.

#define APR_INADDR_NONE ((unsigned int) 0xffffffff)

Not all platforms have a real INADDR_NONE. This macro replaces INADDR_NONE on all platforms.

Definition at line 132 of file apr_network_io.h.

#define APR_INET AF_INET

Not all platforms have these defined, so we'll define them here The default values come from FreeBSD 4.1.1

Definition at line 140 of file apr_network_io.h.

#define APR_IPV4_ADDR_OK 0x01

See also:: apr_sockaddr_info_get()

Definition at line 112 of file apr_network_io.h.

#define APR_IPV6_ADDR_OK 0x02

See also:: apr_sockaddr_info_get()

Definition at line 113 of file apr_network_io.h.

#define APR_MAX_SECS_TO_LINGER 30

Maximum seconds to linger

Definition at line 46 of file apr_network_io.h.

#define APR_UNSPEC 0

Let the system decide which address family to use

Definition at line 147 of file apr_network_io.h.

#define APRMAXHOSTLEN 256

Maximum hostname length

Definition at line 51 of file apr_network_io.h.

Typedef Documentation

typedef struct apr_hdtr_t apr_hdtr_t

A structure to encapsulate headers and trailers for apr_socket_sendfile

Definition at line 195 of file apr_network_io.h.

typedef struct in_addr apr_in_addr_t

A structure to represent in_addr

Definition at line 197 of file apr_network_io.h.

typedef struct apr_ipsubnet_t apr_ipsubnet_t

A structure to represent an IP subnet

Definition at line 199 of file apr_network_io.h.

typedef apr_uint16_t apr_port_t

Remarks:: use apr_uint16_t just in case some system has a short that isn't 16 bits...

Definition at line 202 of file apr_network_io.h.

typedef struct apr_sockaddr_t apr_sockaddr_t

Remarks:: It's defined here as I think it should all be platform safe...

See also:: apr_sockaddr_t

Definition at line 207 of file apr_network_io.h.

typedef struct apr_socket_t apr_socket_t

The specific declaration of inet_addr's ... some platforms fall back inet_network (this is not good, but necessary) A structure to represent sockets

Definition at line 191 of file apr_network_io.h.

Enumeration Type Documentation

enum apr_interface_e

Enum used to denote either the local and remote endpoint of a connection.

Enumerator:

APR_LOCAL	Socket information for local end of connection
APR_REMOTE	Socket information for remote end of connection

Definition at line 170 of file apr_network_io.h.

enum apr_shutdown_how_e

Define what type of socket shutdown should occur.

Enumerator:

APR_SHUTDOWN_READ	no longer allow read request
APR_SHUTDOWN_WRITE	no longer allow write requests
APR_SHUTDOWN_READWRITE	no longer allow read or write requests

Definition at line 106 of file apr_network_io.h.

Function Documentation

APR_DECLARE ( apr_status_t )

Create a socket.

Parameters:

new_sock	The new socket that has been set up.
family	The address family of the socket (e.g., APR_INET).
type	The type of the socket (e.g., SOCK_STREAM).
protocol	The protocol of the socket (e.g., APR_PROTO_TCP).
cont	The pool for the apr_socket_t and associated storage.

Shutdown either reading, writing, or both sides of a socket.

Parameters:

thesocket	The socket to close
how	How to shutdown the socket. One of: APR_SHUTDOWN_READ no longer allow read requests APR_SHUTDOWN_WRITE no longer allow write requests APR_SHUTDOWN_READWRITE no longer allow read or write requests

See also:: apr_shutdown_how_e

Remarks:: This does not actually close the socket descriptor, it just controls which calls are still valid on the socket.

Close a socket.

Parameters:

thesocket The socket to close

Bind the socket to its associated port

Parameters:

sock	The socket to bind
sa	The socket address to bind to

Remarks:: This may be where we will find out if there is any other process using the selected port.

Listen to a bound socket for connections.

Parameters:

sock	The socket to listen on
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.

Accept a new connection request

Parameters:

new_sock	A copy of the socket that is connected to the socket that made the connection request. This is the socket which should be used for all future communication.
sock	The socket we are listening on.
connection_pool	The pool for the new socket.

Issue a connection request to a socket either on the same machine or a different one.

Parameters:

sock	The socket we wish to use for our side of the connection
sa	The address of the machine we wish to connect to.

Determine whether the receive part of the socket has been closed by the peer (such that a subsequent call to apr_socket_read would return APR_EOF), if the socket's receive buffer is empty. This function does not block waiting for I/O.

Parameters:

sock	The socket to check
atreadeof	If APR_SUCCESS is returned, *atreadeof is set to non-zero if a subsequent read would return APR_EOF

Returns:: an error is returned if it was not possible to determine the status, in which case *atreadeof is not changed.

Create apr_sockaddr_t from hostname, address family, and port.

Parameters:

sa	The new apr_sockaddr_t.
hostname	The hostname or numeric address string to resolve/parse, or NULL to build an address that corresponds to 0.0.0.0 or ::
family	The address family to use, or APR_UNSPEC if the system should decide.
port	The port number.
flags	Special processing flags: APR_IPV4_ADDR_OK first query for IPv4 addresses; only look for IPv6 addresses if the first query failed; only valid if family is APR_UNSPEC and hostname isn't NULL; mutually exclusive with APR_IPV6_ADDR_OK APR_IPV6_ADDR_OK first query for IPv6 addresses; only look for IPv4 addresses if the first query failed; only valid if family is APR_UNSPEC and hostname isn't NULL and APR_HAVE_IPV6; mutually exclusive with APR_IPV4_ADDR_OK
p	The pool for the apr_sockaddr_t and associated storage.

Look up the host name from an apr_sockaddr_t.

Parameters:

hostname	The hostname.
sa	The apr_sockaddr_t.
flags	Special processing flags.

Parse hostname/IP address with scope id and port.

Any of the following strings are accepted: 8080 (just the port number) www.apache.org (just the hostname) www.apache.org:8080 (hostname and port number) [fe80::1]:80 (IPv6 numeric address string only) [fe80::1eth0] (IPv6 numeric address string and scope id)

Invalid strings: (empty string) [abc] (not valid IPv6 numeric address string) abc:65536 (invalid port number)

Parameters:

addr	The new buffer containing just the hostname. On output, *addr will be NULL if no hostname/IP address was specfied.
scope_id	The new buffer containing just the scope id. On output, *scope_id will be NULL if no scope id was specified.
port	The port number. On output, *port will be 0 if no port was specified. ### FIXME: 0 is a legal port (per RFC 1700). this should ### return something besides zero if the port is missing.
str	The input string to be parsed.
p	The pool from which addr and scope_id are allocated.

Remarks:: 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.

Get name of the current machine

Parameters:

buf	A buffer to store the hostname in.
len	The maximum length of the hostname that can be stored in the buffer provided. The suggested length is APRMAXHOSTLEN + 1.
cont	The pool to use.

Remarks:: If the buffer was not large enough, an error will be returned.

Return the data associated with the current socket

Parameters:

data	The user data associated with the socket.
key	The key to associate with the user data.
sock	The currently open socket.

Set the data associated with the current socket.

Parameters:

sock	The currently open socket.
data	The user data to associate with the socket.
key	The key to associate with the data.
cleanup	The cleanup to call when the socket is destroyed.

Send data over a network.

Parameters:

sock	The socket to send the data over.
buf	The buffer which contains the data to be sent.
len	On entry, the number of bytes to send; on exit, the number of bytes sent.

Remarks:

 This functions acts like a blocking write by default.  To change 
 this behavior, use apr_socket_timeout_set() or the APR_SO_NONBLOCK
 socket option.

It is possible for both bytes to be sent and an error to be returned.

 APR_EINTR is never returned.

Send multiple packets of data over a network.

Parameters:

sock	The socket to send the data over.
vec	The array of iovec structs containing the data to send
nvec	The number of iovec structs in the array
len	Receives the number of bytes actually written

Remarks:

 This functions acts like a blocking write by default.  To change 
 this behavior, use apr_socket_timeout_set() or the APR_SO_NONBLOCK
 socket option.
 The number of bytes actually sent is stored in argument 3.

It is possible for both bytes to be sent and an error to be returned.

 APR_EINTR is never returned.

Parameters:

sock	The socket to send from
where	The apr_sockaddr_t describing where to send the data
flags	The flags to use
buf	The data to send
len	The length of the data to send

Read data from a socket. On success, the address of the peer from which the data was sent is copied into the from parameter, and the len parameter is updated to give the number of bytes written to buf.

Parameters:

from	Updated with the address from which the data was received
sock	The socket to use
flags	The flags to use
buf	The buffer to use
len	The length of the available buffer

Read data from a network.

Parameters:

sock	The socket to read the data from.
buf	The buffer to store the data in.
len	On entry, the number of bytes to receive; on exit, the number of bytes received.

Remarks:

 This functions acts like a blocking read by default.  To change 
 this behavior, use apr_socket_timeout_set() or the APR_SO_NONBLOCK
 socket option.
 The number of bytes actually received is stored in argument 3.

It is possible for both bytes to be received and an APR_EOF or other error to be returned.

 APR_EINTR is never returned.

Setup socket options for the specified socket

Parameters:

sock The socket to set up.

opt

The option we would like to configure. One of:

            APR_SO_DEBUG      --  turn on debugging information 
            APR_SO_KEEPALIVE  --  keep connections active
            APR_SO_LINGER     --  lingers on close if data is present
            APR_SO_NONBLOCK   --  Turns blocking on/off for socket
                                  When this option is enabled, use
                                  the APR_STATUS_IS_EAGAIN() macro to
                                  see if a send or receive function
                                  could not transfer data without
                                  blocking.
            APR_SO_REUSEADDR  --  The rules used in validating addresses
                                  supplied to bind should allow reuse
                                  of local addresses.
            APR_SO_SNDBUF     --  Set the SendBufferSize
            APR_SO_RCVBUF     --  Set the ReceiveBufferSize

on Value for the option.

Setup socket timeout for the specified socket

Parameters:

sock	The socket to set up.
t	Value for the timeout. t > 0 -- read and write calls return APR_TIMEUP if specified time elapsess with no data read or written t == 0 -- read and write calls never block t < 0 -- read and write calls block

Query socket options for the specified socket

Parameters:

sock The socket to query

opt

The option we would like to query. One of:

            APR_SO_DEBUG      --  turn on debugging information 
            APR_SO_KEEPALIVE  --  keep connections active
            APR_SO_LINGER     --  lingers on close if data is present
            APR_SO_NONBLOCK   --  Turns blocking on/off for socket
            APR_SO_REUSEADDR  --  The rules used in validating addresses
                                  supplied to bind should allow reuse
                                  of local addresses.
            APR_SO_SNDBUF     --  Set the SendBufferSize
            APR_SO_RCVBUF     --  Set the ReceiveBufferSize
            APR_SO_DISCONNECTED -- Query the disconnected state of the socket.
                                  (Currently only used on Windows)

on Socket option returned on the call.

Query socket timeout for the specified socket

Parameters:

sock	The socket to query
t	Socket timeout returned from the query.

Query the specified socket if at the OOB/Urgent data mark

Parameters:

sock	The socket to query
atmark	Is set to true if socket is at the OOB/urgent mark, otherwise is set to false.

Return an address associated with a socket; either the address to which the socket is bound locally or the the address of the peer to which the socket is connected.

Parameters:

sa	The returned apr_sockaddr_t.
which	Whether to retrieve the local or remote address
sock	The socket to use

Return the IP address (in numeric address string format) in an APR socket address. APR will allocate storage for the IP address string from the pool of the apr_sockaddr_t.

Parameters:

addr	The IP address.
sockaddr	The socket address to reference.

Write the IP address (in numeric address string format) of the APR socket address sockaddr into the buffer buf (of size buflen).

Parameters:

sockaddr The socket address to reference.

See if the IP addresses in two APR socket addresses are equivalent. Appropriate logic is present for comparing IPv4-mapped IPv6 addresses with IPv4 addresses.

Parameters:

addr1	One of the APR socket addresses.
addr2	The other APR socket address.

Remarks:: The return value will be non-zero if the addresses are equivalent.

Return the type of the socket.

Parameters:

sock	The socket to query.
type	The returned type (e.g., SOCK_STREAM).

Given an apr_sockaddr_t and a service name, set the port for the service

Parameters:

sockaddr	The apr_sockaddr_t that will have its port set
servname	The name of the service you wish to use

Build an ip-subnet representation from an IP address and optional netmask or number-of-bits.

Parameters:

ipsub	The new ip-subnet representation
ipstr	The input IP address string
mask_or_numbits	The input netmask or number-of-bits string, or NULL
p	The pool to allocate from

Test the IP address in an apr_sockaddr_t against a pre-built ip-subnet representation.

Parameters:

ipsub	The ip-subnet representation
sa	The socket address to test

Returns:: non-zero if the socket address is within the subnet, 0 otherwise

Return the protocol of the socket.

Parameters:

sock	The socket to query.
protocol	The returned protocol (e.g., APR_PROTO_TCP).

Join a Multicast Group

Parameters:

sock	The socket to join a multicast group
join	The address of the multicast group to join
iface	Address of the interface to use. If NULL is passed, the default multicast interface will be used. (OS Dependent)
source	Source Address to accept transmissions from (non-NULL implies Source-Specific Multicast)

Leave a Multicast Group. All arguments must be the same as apr_mcast_join.

Parameters:

sock	The socket to leave a multicast group
addr	The address of the multicast group to leave
iface	Address of the interface to use. If NULL is passed, the default multicast interface will be used. (OS Dependent)
source	Source Address to accept transmissions from (non-NULL implies Source-Specific Multicast)

Set the Multicast Time to Live (ttl) for a multicast transmission.

Parameters: