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