Ns_ConnGetQuery(3aolserver)				   AOLserver Library Procedures 			       Ns_ConnGetQuery(3aolserver)

__________________________________________________________________________________________________________________________________________________

NAME

       Ns_ConnGetQuery,  Ns_ConnClearQuery, Ns_ConnGetFile, Ns_ConnFirstFile, Ns_ConnNextFile - Routines to access query data included with a con-
       nection 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

AOLserver								4.5					       Ns_ConnGetQuery(3aolserver)