NAME

       Ns_ConnContent, Ns_ConnContentLength, Ns_ConnContentFd, Ns_ConnContentOnDisk - Routines to access request
       content

SYNOPSIS

       #include "ns.h"

       char *
       Ns_ConnContent(Ns_Conn *conn)

       int
       Ns_ConnContentLength(Ns_Conn *conn)

       int
       Ns_ConnContentFd(Ns_Conn *conn)

       int
       Ns_ConnContentOnDisk(Ns_Conn *conn)

ARGUMENTS

       Ns_Conn   *conn   (in)      Pointer to given connection.

_________________________________________________________________

DESCRIPTION

       These procedures provide access to the request content sent with a request.

       char *Ns_ConnContent
              Returns  a pointer to the content in memory.  The result of Ns_ConnContent is not guarenteed to be
              null-terminated.  Safe code should be careful to use the result of Ns_ConnContentLength  to  avoid
              overrun.

       int Ns_ConnContentFd
              Returns a file descriptor to an open temporary file which contains the content.

       int Ns_ConnContentLength
              sentrbeyondethencontenttfromecommonubrowsers/on ahPOSTzrequesteispnottincluded.file.  Any trailing

       int Ns_ConnContentOnDisk
              Returns 1 if the content is currently on disk, such that a call to Ns_ConnContentFd will not cause
              a new file to be created.  When it returns 0, a call to Ns_ConnContent will not require  a  mmap()
              call.

CONTENT PRE-READ

       While  receiving  the  request  before connection processing, the server will pre-read the entire content
       body and either copy the content to memory or spool it to an open file depending on virtual server config
       settings.  Requests with content beyond the maxcontent virtual server setting are rejected, requests with
       content between maxinput and maxcontent are spooled to a temp file, and small requests (the  majority  of
       simple POST's) are copied to memory.

       There  is  no need for a request processing extension to consider possible delays in reading content from
       the client as all content is available before connection  processing  begins.   The  rationale  for  this
       approach  is  that  the  driver  thread  can  efficiently multiplex reading content for serveral request,
       tolerating any network delays.  Legacy direct content reading routines, for example, Ns_ConnRead, are now
       emulated on top of the Ns_ConnContent.

RESOURCE MANAGEMENT

       Ns_ConnContentFd returns an open file descriptor allocated by a call Ns_GetTemp and must not be closed as
       it is owned by the server core and will be closed at the end of the connection.  In addition, there is no
       filename for the open file as the file is removed when opened for security reasons and to ensure  garbage
       collection.   In  practice,  the open file should be used to verify, parse, and copy content elsewhere as
       required.  Access at the Tcl level is also available via the ns_conn contentchannel option.

       On a call to Ns_ConnContent, either the existing memory buffer will be returned or the temp file will  be
       memory mapped on the first call.  This will require temporary virtual memory to support the mapping until
       the  end  of  the  connection.   Likewise, on the first call to Ns_ConnContentFd, if a temp file does not
       already exists one will be allocated and the memory content will be spooled to the file.  These semantics
       allow one to access the content in either mode, assuming  resources  are  available,  regardless  of  the
       original location of the content.

DESIGN NOTES AND LARGE CONTENT CONSIDERATIONS

       The design goal of the server is to support the ordinary case of reasonably small content requests (i.e.,
       POST  forms  and  small  file  uploads) in a convienent way without limiting a custom app to support very
       large requests.  In particular, a call to Ns_ConnGetQuery for a multipart/file-upload POST will result in
       an implicit call to Ns_ConnContent to parse the fields.  This could require significant temporary virtual
       memory plus dynamic memory to copy non-file fields into the resulting Ns_Set. See the  ns_limits  command
       to control maximum resource requirements.

       For  custom  apps, an extension could work with the underlying open file via Ns_ConnContentFd or ns_connn
       contentchannel to avoid large virtual memory requirements subject to disk space availability.   To  avoid
       inadvertant  memory mapping of a large upload by other extensions calling Ns_ConnGetQuery, consider using
       a HTTP method other than GET or POST required by Ns_ConnGetQuery, e.g., PUT.

SEE ALSO

       Ns_Conn(3), Ns_ConnRead(3), ns_limits(n), ns_conn(n)

KEYWORDS

       connection, content

AOLserver                                              4.0                            Ns_ConnContent(3aolserver)