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 (\0).  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   argument   using   the    Ns_ParseHeader    routine    with    the
              Ns_HeaderCaseDisposition  specified  by  the  "headercase"  server option (default:
              Preserve).  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  useful  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 number of bytes copied.  The line will
              not  include  the  trailing  \r\n or \n if present.  The function will return NS_OK
              unless an underlying 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