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);
        }
    }
}

KEYWORDS

form, query