Other Alias
Ns_ConnClearQuery, Ns_ConnGetFile, Ns_ConnFirstFile, Ns_ConnNextFileSYNOPSIS
#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>
-
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