Ns_ConnContent(3aolserver)				   AOLserver Library Procedures 				Ns_ConnContent(3aolserver)

__________________________________________________________________________________________________________________________________________________

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 										sent beyond the content from  com-
	      Returns the length of the memory buffer and/or the size of the open temporary file.  Any trailing
	      mon browsers on a POST request is not included.

       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 avail-
       able before connection processing begins.  The rationale for this approach is that the driver thread can efficiently multiplex reading con-
       tent  for  serveral request, tolerating any network delays.  Legacy direct content reading routines, for example, Ns_ConnRead, are now emu-
       lated 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  else-
       where 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_Con-
       nContentFd,  if a temp file does not already exists one will be allocated and the memory content will be spooled to the file.  These seman-
       tics 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  vir-
       tual  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)