Date: 12 Apr 1999 18:23:13 -0000
Message-ID: <19990412182313.24980.qmail@hyperreal.org>
From: rbb@hyperreal.org
To: apache-apr-cvs@hyperreal.org
Subject: cvs commit: apache-apr/docs networkio.txt
Sender: apache-cvs-owner@apache.org
Precedence: bulk
Reply-To: new-httpd@apache.org

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.