NAME

       Ns_ConnGetQuery,  Ns_ConnClearQuery,  Ns_ConnGetFile,  Ns_ConnFirstFile,  Ns_ConnNextFile  -  Routines to
       access query data included with a connection request

SYNOPSIS

       #include "ns.h"

       Ns_Set *
       Ns_ConnGetQuery(Ns_Conn *conn)

       void
       Ns_ConnClearQuery(Ns_Conn *conn)

       Ns_ConnFile *
       Ns_ConnGetFile(Ns_Conn *conn, char *file)

       Ns_ConnFile *
       Ns_ConnFirstFile(Ns_Conn *conn, Tcl_HashSearch *searchPtr)

       Ns_ConnFile *
       Ns_ConnNextFile(Ns_Conn *conn, Tcl_HashSearch *searchPtr)

ARGUMENTS

       Ns_Conn          *conn        (in)      Pointer to given connection.

       char             *file        (in)      Name of embedded file.

       Tcl_HashSearch   *searchPtr   (in/out)  Pointer to buffer to maintain state of an active search.

_________________________________________________________________

DESCRIPTION

       These routines provide access to connection query data, derived from either URL  query  arguments  (i.e.,
       key/value  pairs  after  the  ? in an URL) or via an HTTP POST.  The server supports ordinary URL encoded
       forms  as well as multipart/form-data forms which may include one or more embedded files.

       As form processing is a common and important aspect of dynamic web applications, AOLserver provides  easy
       access  to  the  query data within the core.  The parsing occurs on demand and the results are cached for
       reuse throughout  the  connection;  there  is  no  need  to  copy  the  returned  Ns_Set  or  Ns_ConnFile
       structure(s).  The results of these routines should be considered read-only.

       Ns_Set *Ns_ConnGetQuery(conn)
              Returns  a  pointer to an Ns_Set with the fields of the connection query or NULL if no valid query
              was present.  The keys and values are in UTF-8, decoded from  the  request  based  on  the  server
              urlencoding  config  option.   Subsequent calls to Ns_ConnGetQuery will return the same set unless
              the server detects the connection encoding has changed in which case the previous query is cleared
              and a new query result is generated.

              Data for the query is based on any URL query arguments which may be present (i.e., key/value pairs
              following the ? in the URL).  If there is no URL query data, the server will parse the content  of
              an HTTP POST.

       void Ns_ConnClearQuery(conn)
              Frees  the previous parsed query, if any.  There is normally no need to call this routine as it is
              called automatically at the end of  a  connection  if  necessary.   It  is  normally  only  called
              internally  when  Ns_ConnGetQuery  detects  the  url  encoding  has  been manually updated for the
              connection, potentially invalidating the character encoding on the previous form parsing.

       Ns_ConnFile *Ns_ConnGetFile(file) Returns the Ns_ConnFile structure for the given file if  present  which
       includes the following fields:

                typedef struct Ns_ConnFile {
                    char   *name;
                    Ns_Set *headers;
                    off_t   offset;
                    off_t   length;
                } Ns_ConnFile;

       The  name  field  is  a  pointer to a string which matches the name as provided by the corresponding form
       <input> tag.  The headers field is a pointer to an Ns_Set with the key/value pairs  for  the  file  input
       meta data, e.g., a Content-Type header.  The offset and length fields specfy where within the content the
       actual file bytes are located.  See the Ns_ConnContent man page for  details  on  accessing  the  content
       bytes either through an in-memory buffer or open temp file.

       Ns_ConnFirstFile  and  Ns_ConnNextFile  routines allow you to manage a search through the underlying hash
       table of uploaded files.

EXAMPLE

       Given the following HTML form:

              <form enctype=multipart/form-data method=post>
              <textarea name=stringdata></textarea>
              <input type=file name=filedata>
              <input type=submit>
              </form>
       the following code would dump the form strings and file info to the server log:

              void
              DumpQuery(Ns_Conn *conn)
              {
                  Ns_Set *query;
                  Ns_ConnFile *filePtr;
                  Tcl_HashSearch search;

                  query = Ns_ConnGetQuery(conn);
                  if (query != NULL) {
                      /* Dump key/values of all fields. */
                      Ns_SetPrint(query);
                      /* Dump info on each embedded file. */
                      filePtr = Ns_ConnFirstFile(conn);
                      while (filePtr != NULL) {
                          Ns_Log(Notice, "file: %s %d %d", filePtr->name,
                                 filePtr->offset, filePtr->length);
                          filePtr = Ns_ConnNextFile(conn);
                      }
                  }
              }

SEE ALSO

       Ns_Set(3), Ns_Conn(3), Ns_ConnContent(3), ns_conn(n), ns_parsequery(n)

KEYWORDS

       form, query