rbb 99/04/12 11:23:12
Added: docs networkio.txt
Log:
First pass at the network function defs. This will get updated as the
functions
are written.
Revision Changes Path
1.1 apache-apr/docs/networkio.txt
Index: networkio.txt
===================================================================
<h2> Network I/O</h2>
APRStatus apr_send(APRSocket, const void *, APRUInt64, APRUInt64 *)
Sends a message over a socket
Arguments:
arg 1) Pointer to abstracted File descriptor (socket)
arg 2) buffer containing message to send
arg 3) size of buf (in bytes)
arg 4) Amount of data sent in bytes. (Returned by APR)
APRStatus apr_recv(APRSocket, void *, APRUInt64, APRUInt64 *);
Receive a message from a socket
Arguments:
arg 1) Pointer to abstracted File descriptor (socket)
arg 2) buffer to store message in
arg 3) size of buf (in bytes)
<!-- arg 4) OS specific flags to determine how to receive the message.
because of OS differences, it is best to always use zero.
we are including this flag to mimic POSIX, but may take it
out
-->
arg 4) Amount of data received in bytes
APRStatus apr_create_tcp_socket(APSocket *)
Create a new TCP network connection
Arguments:
arg 1) Abstracted out ptr to file descriptor, pointing to
the created Socket. NULL on failure.
APRStatus apr_initializenetaddr(APRNetAddrValue, APRUInt16, APRNetAddr);
Initialize the fields of a APRNetAddr. assigning well known values
as appropriate. This function only sets up values in the APRNetAddr
structure. It does not setup the connection.
Arguments:
arg 1) The value to assign to the IP address portion of the
APRNetAddr struct. Can only specify INADDR_ANY and
INADR_LOOPBACK equivalents.
arg 2) Port number to be assigned in the struct
arg 3) The address of the APRNetAddr struct to be filled out.
APRStatus apr_gethostbyname(char *, APRHostEnt)
Lookup a host by name
Arguments:
arg 1) string defining the host name of interest
arg 2) returns an APRHostEnt structure that has been filled out
on success. On failure, it returns NULL.
APRStatus apr_gethostbyaddr(const void *, APRInt32, APRNetAddrValue,
APRHostEnt)
Lookup a host by address
Arguments:
arg 1) IP addr of host, not Null-terminated string
arg 2) length of IP addr
arg 3) type of address
arg 4) returns an APRHostEnt structure that has been filled out
on success. On failure, it returns NULL.
APRStatus apr_enumeratehostent(APRUInt32, const APRHostEnt *, APRUInt16,
APRNetAddr *, APRInt32);
Evaluate each of the possible address of a Host Entry retrived from
apr_GetHostByName or apr_GetHostByAddr.
Arguments:
arg 1) The index of the enumeration. To start, set to zero. To
continue, set to last returned value.
arg 2) pointer to structure return by apr_GetHostBy* Functions.
arg 3) Port number to be asssigned as part of the APRNetAddr
structure.
arg 4) Input a pointer to an APRNetAddr struct. On output, this
struct
is filled in by the runtime if the returned result is > 0.
arg 5) Next value for the index parameter. If 0, the enumeration
is ended. APR_FAILURE otherwise.
APRStatus apr_familyinet(APRInt16)
Get the value of the address family for IP
Arguments:
return) Returns the address family
APRStatus apr_hton16(APRUInt16, APRUInt16 *)
16 bit conversion from host to network byte order
Arguments:
arg 1) the integer to convert
arg 2) the integer in proper byte order.
APRStatus apr_ntoh16(APRUInt16, APRUInt16 *);
16 bit conversion from network to host byte order
Arguments:
arg 1) the integer to convert
arg 2) the integer in proper byte order.
APRStatus apr_netaddrtostring(const APRNetAddr *, char *, APRUInt32)
Convert an internet address to a String
Arguments:
arg 1) The structure to get the Internet address from
arg 2) the buffer to store the converted address into
arg 3) The size of the buffer
APRStatus apr_stringtonetaddr(const char *, APRNetAddr *)
Convert a string into an internet address
Arguments:
arg 1) the buffer to get the Internet address from
arg 2) The structure to store the converted address into
APRStatus apr_setsocketoption(APRSocket, APRSocketOptionData);
Set options on the specified socket
Arguments:
arg 1) The abstracted socket to apply the options to
arg 2) The options to be applied. Or'ed together
APRStatus apr_poll(APRPollDesc, APRInt32, APRInt32, APRInt32)
Check an array of File Descriptors for specified events
Arguments:
arg 1) The file descriptors to look at.
arg 2) The number of file descriptors.
arg 3) amount of time in seconds to wait if no event has occured on
any of the file descriptors. 0 return immediately. -1 block
until an event occurs. For list of events and meanings, see
below under Events
arg 4) Number of file desriptors selected. 0 means call timed out.
-1 returned on failure.
APRStatus apr_bind(APRSocket, APRNetAddr *)
Assign an address to an unnamed port
Arguments:
arg 1) The file desc of the socket to bind.
arg 2) The structure pointing to address to bind to.
APRStatus apr_listen(APRSocket, APRUInt32)
Mark a socket as accepting connections and limit the size of the
listen queue.
Arguments:
arg 1) The file desc of the socket to mark
arg 2) The size of the listen queue.
APRStatus apr_accept(APRSocket, APRNetAddr *, APRSocket *)
extract first connection from listen queue, and sets up a new
connection on a new socket of the same type and family. It allocates
a new socket for that connection.
Arguments:
arg 1) The file desc of a socket that is listening. The connection
comes from this socket's listen queue.
arg 2) structure to store address of connecting socket.
arg 3) file descriptor of created socket. -1 on failure.
NOTE: accepted socket can not accept more connections. Original socket
remains open, and can accept more connections.
APRStatus apr_getsockname(APRSocket, APRNetAddr *)
retrieves the locally bound name of the specified socket.
Arguments:
arg 1) The file desc of the socket to retrieve the name for.
arg 2) structure to store socket address in.
APRStatus apr_shutdown(APRSocket, APRShutdownHow)
shuts down part of a full-duplex connection on a specified socket
Arguments:
arg 1) File descriptor of socket
arg 2) How to shutdown the socket.
