Ns_ConnRead(3aolserver) 				   AOLserver Library Procedures 				   Ns_ConnRead(3aolserver)

__________________________________________________________________________________________________________________________________________________

NAME

       Ns_ConnGets, Ns_ConnRead, Ns_ConnFlushHeaders, Ns_ConnReadHeaders, Ns_ConnReadLine - Routines to copy connection content

SYNOPSIS

       #include "ns.h"

       char *
       Ns_ConnGets(buf, bufsize, conn)

       int
       Ns_ConnFlushContent(conn)

       int
       Ns_ConnRead(conn, vbuf, toread)

       int
       Ns_ConnReadHeaders(conn, set, nreadPtr)

       int
       Ns_ConnReadLine(conn, dsPtr, nreadPtr)

ARGUMENTS

       char	    *buf    (in)      Pointer to string buffer of length bufsize.

       int	    bufsize (in)      Length of buffer pointer to by buf.

       Ns_Conn	    conn    (in)      Pointer to open connection.

       Ns_DString   dsPtr   (out)     Pointer to initialized dstring to receive copied line.

       int	    *nreadPtr(out)    Pointer to integer to receive number of bytes copied.

       Ns_Set	    set     (in/out)  Pointer to initialized Ns_Set to copy headers.

       int	    toread  (in)      Number of bytes to copy to location starting at vbuf

       void	    *vbuf   (in)      Pointer to memory location to copy content.
_________________________________________________________________

DESCRIPTION

       These  routines	support  copying  content  from the connection.  They all operate by copying from the content buffer returned by a call to
       Ns_ConnContent, maintaining a private, shared offset into the content.  This means that these routines are not  actually  reading  directly
       from  the network and thus will not block waiting for input.  See the man page on Ns_ConnContent for details on how the content is pre-read
       by the server and how resources are managed for small and large content requests.

       char *Ns_ConnGets(buf, bufsize, conn)
	      Copies the next available line of text from the content to the given buf string, up to the given bufsize less space for  a  trailing
	      null ().  The result is a pointer to buf or NULL if an underlying call to Ns_ConnRead fails.

       int Ns_ConnFlushContent(conn)
	      Performs	a  logical  flush of the underlying content available to these routines.  It simply moves the private offset to the end of
	      the content.  The result is NS_OK unless an underlying call to Ns_ConnContent failed in which case NS_ERROR is returned.

       int Ns_ConnRead(conn, vbuf, toread)
	      Copies up to toread bytes from the content to the memory location pointed to by vbuf.  The result is  the  number  of  bytes  copied
	      which will match toread unless less bytes are available in the input or -1 if an underlying call to Ns_ConnContent failed.

       int Ns_ConnReadHeaders(conn, set, nreadPtr)
	      Copies lines up to the first blank line or end of content up to the maximum header read size specified with the communication driver
	      "maxheader" parameter (default: 32k).  Each line is parsed into "key: value" pairs into the given Ns_Set pointed to be the set argu-
	      ment  using  the Ns_ParseHeader routine with the Ns_HeaderCaseDisposition specified by the "headercase" server option (default: Pre-
	      serve).  The result is NS_OK if all lines were consumed or NS_ERROR on overflow beyond the max header limit or if there was an error
	      with  the  underlying  call  to Ns_ConnRead (including an error of a single line beyond the max line limit as described below).  The
	      integer pointed to by the nreadPtr argument, if given, is updated with the total number of bytes consumed.  This routine can be use-
	      ful when parsing multipart/form-data content to collect headers for each part.

       int Ns_ConnReadLine(conn, dsPtr, nreadPtr)
	      Copies the next available line to the given dsPtr dstring.  The integer pointed to by nreadPtr, if present, is updated with the num-
	      ber of bytes copied.  The line will not include the trailing 
 or 
 if present.  The function will return NS_OK unless an under-
	      lying  call  to Ns_ConnContent failed or the line exceeds the maximum line read size specified by the communication driver "maxline"
	      parameter (default: 4k).	This routine differs from Ns_ConnGets in that it copies the result to a dstring  instead  of  a  character
	      buffer, requires a full or end-of-content terminated line, and enforces the maxline limit.

SEE ALSO

       Ns_ConnContent(3), Ns_ParseHeader(3)

KEYWORDS

       connection, read, content

AOLserver								4.0						   Ns_ConnRead(3aolserver)