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