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