.TH "src/apreq_params.h" 3 "30 Aug 2004" "Version 2.04-dev" "libapreq2" \" -*- nroff -*-
.ad l
.nh
.SH NAME
src/apreq_params.h \- Request parsing and parameter API. 
.SH SYNOPSIS
.br
.PP
\fC#include 'apreq.h'\fP
.br

.SS "Data Structures"

.in +1c
.ti -1c
.RI "struct \fBapreq_param_t\fP"
.br
.ti -1c
.RI "struct \fBapreq_request_t\fP"
.br
.ti -1c
.RI "struct \fBapreq_hook_t\fP"
.br
.ti -1c
.RI "struct \fBapreq_parser_t\fP"
.br
.in -1c
.SS "Defines"

.in +1c
.ti -1c
.RI "#define \fBapreq_value_to_param\fP(ptr)   apreq_attr_to_type(\fBapreq_param_t\fP, v, ptr)"
.br
.ti -1c
.RI "#define \fBapreq_param_name\fP(p)   ((p)->v.name)"
.br
.ti -1c
.RI "#define \fBapreq_param_value\fP(p)   ((p)->v.data)"
.br
.ti -1c
.RI "#define \fBapreq_param_info\fP(p)   ((p)->info)"
.br
.ti -1c
.RI "#define \fBapreq_param_brigade\fP(p)   ((p)->bb ? apreq_copy_brigade((p)->bb) : NULL)"
.br
.ti -1c
.RI "#define \fBAPREQ_PARSER_ARGS\fP"
.br
.ti -1c
.RI "#define \fBAPREQ_HOOK_ARGS\fP"
.br
.ti -1c
.RI "#define \fBAPREQ_DECLARE_PARSER\fP(f)"
.br
.ti -1c
.RI "#define \fBAPREQ_DECLARE_HOOK\fP(f)"
.br
.ti -1c
.RI "#define \fBAPREQ_RUN_PARSER\fP(psr, env, t, bb)   (psr)->parser(psr,env,t,bb)"
.br
.ti -1c
.RI "#define \fBAPREQ_RUN_HOOK\fP(h, env, param, bb)   (h)->hook(h,env,param,bb)"
.br
.in -1c
.SS "Typedefs"

.in +1c
.ti -1c
.RI "typedef \fBapreq_param_t\fP \fBapreq_param_t\fP"
.br
.ti -1c
.RI "typedef \fBapreq_hook_t\fP \fBapreq_hook_t\fP"
.br
.ti -1c
.RI "typedef \fBapreq_parser_t\fP \fBapreq_parser_t\fP"
.br
.ti -1c
.RI "typedef \fBapreq_request_t\fP \fBapreq_request_t\fP"
.br
.in -1c
.SS "Functions"

.in +1c
.ti -1c
.RI "\fBapreq_param_t\fP * \fBapreq_make_param\fP (\fBapr_pool_t\fP *p, const char *name, const \fBapr_size_t\fP nlen, const char *val, const \fBapr_size_t\fP vlen)"
.br
.ti -1c
.RI "\fBapreq_request_t\fP * \fBapreq_request\fP (void *env, const char *qs)"
.br
.ti -1c
.RI "\fBapreq_param_t\fP * \fBapreq_param\fP (const \fBapreq_request_t\fP *req, const char *name)"
.br
.ti -1c
.RI "\fBapr_table_t\fP * \fBapreq_params\fP (\fBapr_pool_t\fP *p, const \fBapreq_request_t\fP *req)"
.br
.ti -1c
.RI "\fBapr_array_header_t\fP * \fBapreq_params_as_array\fP (\fBapr_pool_t\fP *p, \fBapreq_request_t\fP *req, const char *key)"
.br
.ti -1c
.RI "const char * \fBapreq_params_as_string\fP (\fBapr_pool_t\fP *p, \fBapreq_request_t\fP *req, const char *key, \fBapreq_join_t\fP mode)"
.br
.ti -1c
.RI "\fBapreq_param_t\fP * \fBapreq_decode_param\fP (\fBapr_pool_t\fP *pool, const char *word, const \fBapr_size_t\fP nlen, const \fBapr_size_t\fP vlen)"
.br
.ti -1c
.RI "char * \fBapreq_encode_param\fP (\fBapr_pool_t\fP *pool, const \fBapreq_param_t\fP *param)"
.br
.ti -1c
.RI "\fBapr_status_t\fP \fBapreq_parse_query_string\fP (\fBapr_pool_t\fP *pool, \fBapr_table_t\fP *t, const char *qs)"
.br
.ti -1c
.RI "\fBapr_status_t\fP \fBapreq_parse_request\fP (\fBapreq_request_t\fP *req, \fBapr_bucket_brigade\fP *bb)"
.br
.ti -1c
.RI "\fBapr_table_t\fP * \fBapreq_uploads\fP (\fBapr_pool_t\fP *pool, const \fBapreq_request_t\fP *req)"
.br
.ti -1c
.RI "\fBapreq_param_t\fP * \fBapreq_upload\fP (const \fBapreq_request_t\fP *req, const char *key)"
.br
.ti -1c
.RI "\fBapr_status_t\fP \fBapreq_brigade_concat\fP (void *env, \fBapr_bucket_brigade\fP *out, \fBapr_bucket_brigade\fP *in)"
.br
.ti -1c
.RI "\fBAPREQ_DECLARE_PARSER\fP (apreq_parse_headers)"
.br
.ti -1c
.RI "\fBAPREQ_DECLARE_PARSER\fP (apreq_parse_urlencoded)"
.br
.ti -1c
.RI "\fBAPREQ_DECLARE_PARSER\fP (apreq_parse_multipart)"
.br
.ti -1c
.RI "\fBapreq_parser_t\fP * \fBapreq_make_parser\fP (\fBapr_pool_t\fP *pool, const char *enctype, \fBapr_status_t\fP(*parser)(APREQ_PARSER_ARGS), \fBapreq_hook_t\fP *hook, void *ctx)"
.br
.ti -1c
.RI "\fBapreq_hook_t\fP * \fBapreq_make_hook\fP (\fBapr_pool_t\fP *pool, \fBapr_status_t\fP(*hook)(APREQ_HOOK_ARGS), \fBapreq_hook_t\fP *next, void *ctx)"
.br
.ti -1c
.RI "void \fBapreq_add_hook\fP (\fBapreq_parser_t\fP *p, \fBapreq_hook_t\fP *h)"
.br
.ti -1c
.RI "\fBapreq_parser_t\fP * \fBapreq_parser\fP (void *env, \fBapreq_hook_t\fP *hook)"
.br
.ti -1c
.RI "\fBAPREQ_DECLARE_HOOK\fP (apreq_hook_disable_uploads)"
.br
.in -1c
.SH "Detailed Description"
.PP 
Request parsing and parameter API. 


.SH "Define Documentation"
.PP 
.SS "#define APREQ_DECLARE_HOOK(f)"
.PP
\fBValue:\fP
.PP
.nf
APREQ_DECLARE(apr_status_t) \
                                (f) (APREQ_HOOK_ARGS)
.fi
Declares an API hook. 
.SS "#define APREQ_DECLARE_PARSER(f)"
.PP
\fBValue:\fP
.PP
.nf
APREQ_DECLARE(apr_status_t) \
                                (f) (APREQ_PARSER_ARGS)
.fi
Declares a API parser. 
.SS "#define APREQ_HOOK_ARGS"
.PP
\fBValue:\fP
.PP
.nf
apreq_hook_t *hook,         \
                           void *env,                  \
                           apreq_param_t *param,       \
                           apr_bucket_brigade *bb
.fi
Hook arguments 
.SS "#define APREQ_PARSER_ARGS"
.PP
\fBValue:\fP
.PP
.nf
apreq_parser_t *parser,     \
                           void *env,                  \
                           apr_table_t *t,             \
                           apr_bucket_brigade *bb
.fi
Parser arguments. 
.SS "#define APREQ_RUN_HOOK(h, env, param, bb)   (h)->hook(h,env,param,bb)"
.PP
Run the hook with the current parameter and the incoming bucket brigade. The hook may modify the brigade if necessary. Once all hooks have completed, the contents of the brigade will be added to the parameter's bb attribute. 
.SS "#define APREQ_RUN_PARSER(psr, env, t, bb)   (psr)->parser(psr,env,t,bb)"
.PP
Parse the incoming brigade into a table. Parsers normally consume all the buckets of the brigade during parsing. However parsers may leave 'rejected' data in the brigade, even during a successful parse, so callers may need to clean up the brigade themselves (in particular, rejected buckets should not be passed back to the parser again). 
.PP
\fBRemarks:\fP
.RS 4
bb == NULL is valid: the parser should return its public status: APR_INCOMPLETE, APR_SUCCESS, or an error code. 
.RE
.PP

.SS "#define apreq_value_to_param(ptr)   apreq_attr_to_type(\fBapreq_param_t\fP, v, ptr)"
.PP
accessor macros 
.SH "Typedef Documentation"
.PP 
.SS "typedef struct \fBapreq_param_t\fP  \fBapreq_param_t\fP"
.PP
Common data structure for params and file uploads 
.SS "typedef struct \fBapreq_request_t\fP  \fBapreq_request_t\fP"
.PP
Structure which manages the request data. 
.SH "Function Documentation"
.PP 
.SS "void apreq_add_hook (\fBapreq_parser_t\fP * p, \fBapreq_hook_t\fP * h)"
.PP
Add a new hook to the end of the parser's hook list.
.PP
\fBParameters:\fP
.RS 4
\fIp\fP Parser. 
.br
\fIh\fP Hook to append. 
.RE
.PP

.SS "\fBapr_status_t\fP apreq_brigade_concat (void * env, \fBapr_bucket_brigade\fP * out, \fBapr_bucket_brigade\fP * in)"
.PP
Concatenates the brigades, spooling large brigades into a tempfile bucket according to the environment's max_brigade setting- see \fBapreq_env_max_brigade()\fP. 
.PP
\fBParameters:\fP
.RS 4
\fIenv\fP Environment. 
.br
\fIout\fP Resulting brigade. 
.br
\fIin\fP Brigade to append. 
.RE
.PP
\fBReturns:\fP
.RS 4
APR_SUCCESS on success, error code otherwise. 
.RE
.PP

.SS "APREQ_DECLARE_HOOK (apreq_hook_disable_uploads)"
.PP
Returns APR_EGENERAL. Effectively disables mfd parser if a file-upload field is present. 
.SS "APREQ_DECLARE_PARSER (apreq_parse_multipart)"
.PP
Rfc2388 multipart/form-data parser. It will reject any buckets representing preamble and postamble text (this is normal behavior, not an error condition). See \fBAPREQ_RUN_PARSER\fP for more info on rejected data. 
.SS "APREQ_DECLARE_PARSER (apreq_parse_urlencoded)"
.PP
Rfc2396 application/x-www-form-urlencoded parser. 
.SS "APREQ_DECLARE_PARSER (apreq_parse_headers)"
.PP
Rfc822 Header parser. It will reject all data after the first CRLF CRLF sequence (an empty line). See \fBAPREQ_RUN_PARSER\fP for more info on rejected data. 
.SS "\fBapreq_param_t\fP* apreq_decode_param (\fBapr_pool_t\fP * pool, const char * word, const \fBapr_size_t\fP nlen, const \fBapr_size_t\fP vlen)"
.PP
Url-decodes a name=value pair into a param. 
.PP
\fBParameters:\fP
.RS 4
\fIpool\fP Pool from which the param is allocated. 
.br
\fIword\fP Start of the name=value pair. 
.br
\fInlen\fP Length of urlencoded name. 
.br
\fIvlen\fP Length of urlencoded value. 
.RE
.PP
\fBRemarks:\fP
.RS 4
Unless vlen == 0, this function assumes there is exactly one character ('=') which separates the pair. 
.RE
.PP

.SS "char* apreq_encode_param (\fBapr_pool_t\fP * pool, const \fBapreq_param_t\fP * param)"
.PP
Url-encodes the param into a name-value pair. 
.PP
\fBParameters:\fP
.RS 4
\fIpool\fP Pool which allocates the returned string. 
.br
\fIparam\fP Param to encode. 
.RE
.PP
\fBReturns:\fP
.RS 4
name-value pair representing the param. 
.RE
.PP

.SS "\fBapreq_hook_t\fP* apreq_make_hook (\fBapr_pool_t\fP * pool, \fBapr_status_t\fP(* hook)(APREQ_HOOK_ARGS), \fBapreq_hook_t\fP * next, void * ctx)"
.PP
Construct a hook.
.PP
\fBParameters:\fP
.RS 4
\fIpool\fP used to allocate the hook. 
.br
\fIhook\fP The hook function. 
.br
\fInext\fP List of other hooks for this hook to call on. 
.br
\fIctx\fP Hook's internal scratch pad. 
.RE
.PP
\fBReturns:\fP
.RS 4
New hook. 
.RE
.PP

.SS "\fBapreq_param_t\fP* apreq_make_param (\fBapr_pool_t\fP * p, const char * name, const \fBapr_size_t\fP nlen, const char * val, const \fBapr_size_t\fP vlen)"
.PP
creates a param from name/value information 
.SS "\fBapreq_parser_t\fP* apreq_make_parser (\fBapr_pool_t\fP * pool, const char * enctype, \fBapr_status_t\fP(* parser)(APREQ_PARSER_ARGS), \fBapreq_hook_t\fP * hook, void * ctx)"
.PP
Construct a parser.
.PP
\fBParameters:\fP
.RS 4
\fIpool\fP Pool used to allocate the parser. 
.br
\fIenctype\fP Content-type that this parser can deal with. 
.br
\fIparser\fP The parser function. 
.br
\fIhook\fP Hooks to asssociate this parser with. 
.br
\fIctx\fP Parser's internal scratch pad. 
.RE
.PP
\fBReturns:\fP
.RS 4
New parser. 
.RE
.PP

.SS "\fBapreq_param_t\fP* apreq_param (const \fBapreq_request_t\fP * req, const char * name)"
.PP
Returns the first parameter value with the desired name, NULL if none found. The name is case-insensitive. 
.PP
\fBParameters:\fP
.RS 4
\fIreq\fP The current \fBapreq_request_t\fP object. 
.br
\fIname\fP Nul-terminated search key. Returns the first table value if NULL. 
.RE
.PP
\fBReturns:\fP
.RS 4
First matching parameter. 
.RE
.PP
\fBRemarks:\fP
.RS 4
Also parses the request as necessary. 
.RE
.PP

.SS "\fBapr_table_t\fP* apreq_params (\fBapr_pool_t\fP * p, const \fBapreq_request_t\fP * req)"
.PP
Returns a table containing key-value pairs for the full request (args + body). 
.PP
\fBParameters:\fP
.RS 4
\fIp\fP Allocates the returned table. 
.br
\fIreq\fP The current \fBapreq_request_t\fP object. 
.RE
.PP
\fBRemarks:\fP
.RS 4
Also parses the request if necessary. 
.RE
.PP

.SS "\fBapr_array_header_t\fP* apreq_params_as_array (\fBapr_pool_t\fP * p, \fBapreq_request_t\fP * req, const char * key)"
.PP
Returns an array of parameters (\fBapreq_param_t\fP *) matching the given key. The key is case-insensitive. 
.PP
\fBParameters:\fP
.RS 4
\fIp\fP Allocates the returned array. 
.br
\fIreq\fP The current \fBapreq_request_t\fP object. 
.br
\fIkey\fP Null-terminated search key. key==NULL fetches all parameters. 
.RE
.PP
\fBRemarks:\fP
.RS 4
Also parses the request if necessary. 
.RE
.PP

.SS "const char* apreq_params_as_string (\fBapr_pool_t\fP * p, \fBapreq_request_t\fP * req, const char * key, \fBapreq_join_t\fP mode)"
.PP
Returns a ', ' -separated string containing all parameters for the requested key, NULL if none are found. The key is case-insensitive. 
.PP
\fBParameters:\fP
.RS 4
\fIp\fP Allocates the return string. 
.br
\fIreq\fP The current \fBapreq_request_t\fP object. 
.br
\fIkey\fP Null-terminated parameter name. key==NULL fetches all values. 
.br
\fImode\fP Join type- see \fBapreq_join()\fP. 
.RE
.PP
\fBReturns:\fP
.RS 4
Returned string is the data attribute of an \fBapreq_value_t\fP, so it is safe to use in \fBapreq_strlen()\fP and apreq_strtoval(). 
.RE
.PP
\fBRemarks:\fP
.RS 4
Also parses the request if necessary. 
.RE
.PP

.SS "\fBapr_status_t\fP apreq_parse_query_string (\fBapr_pool_t\fP * pool, \fBapr_table_t\fP * t, const char * qs)"
.PP
Parse a url-encoded string into a param table. 
.PP
\fBParameters:\fP
.RS 4
\fIpool\fP pool used to allocate the param data. 
.br
\fIt\fP table to which the params are added. 
.br
\fIqs\fP Query string to url-decode. 
.RE
.PP
\fBReturns:\fP
.RS 4
APR_SUCCESS if successful, error otherwise. 
.RE
.PP
\fBRemarks:\fP
.RS 4
This function uses [&;] as the set of tokens to delineate words, and will treat a word w/o '=' as a name-value pair with value-length = 0. 
.RE
.PP

.SS "\fBapr_status_t\fP apreq_parse_request (\fBapreq_request_t\fP * req, \fBapr_bucket_brigade\fP * bb)"
.PP
Parse a brigade as incoming POST data. 
.PP
\fBParameters:\fP
.RS 4
\fIreq\fP Current request. 
.br
\fIbb\fP Brigade to parse. See remarks below. 
.RE
.PP
\fBReturns:\fP
.RS 4
APR_INCOMPLETE if the parse is incomplete, APR_SUCCESS if the parser is finished (saw eos), APR_ENOTIMPL if no parser is available for this request (i.e. unrecognized Content-Type header), unrecoverable error value otherwise. 
.RE
.PP

.SS "\fBapreq_parser_t\fP* apreq_parser (void * env, \fBapreq_hook_t\fP * hook)"
.PP
Create the default parser associated with the current request's Content-Type (if possible). 
.PP
\fBParameters:\fP
.RS 4
\fIenv\fP The current environment. 
.br
\fIhook\fP Hook(s) to add to the parser. 
.RE
.PP
\fBReturns:\fP
.RS 4
New parser, NULL if the Content-Type is unrecognized. apreq_parser() currently recognizes APREQ_URL_ENCTYPE and APREQ_MFD_ENCTYPE.
.RE
.PP
\fBParameters:\fP
.RS 4
\fIenv\fP The current environment. 
.br
\fIhook\fP Additional hooks to supply the parser with. 
.RE
.PP
\fBReturns:\fP
.RS 4
The built-in parser; NULL if the environment's Content-Type is unrecognized. 
.RE
.PP

.SS "\fBapreq_request_t\fP* apreq_request (void * env, const char * qs)"
.PP
Creates an \fBapreq_request_t\fP object. 
.PP
\fBParameters:\fP
.RS 4
\fIenv\fP The current request environment. 
.br
\fIqs\fP The query string. 
.RE
.PP
\fBRemarks:\fP
.RS 4
'qs = NULL' has special behavior. In this case, apreq_request(env,NULL) will attempt to fetch a cached object from the environment via apreq_env_request. Failing that, it will replace 'qs' with the result of apreq_env_query_string(env), parse that, and store the resulting \fBapreq_request_t\fP object back within the environment. This maneuver is designed to both mimimize parsing work and allow the environent to place the parsed POST data in req->body (otherwise the caller may need to do this manually). For details on this, see the environment's documentation for the apreq_env_read function. 
.RE
.PP

.SS "\fBapreq_param_t\fP* apreq_upload (const \fBapreq_request_t\fP * req, const char * key)"
.PP
Returns the first param in req->body which has both param->v.name matching key and param->bb != NULL. 
.PP
\fBParameters:\fP
.RS 4
\fIreq\fP The current request. 
.br
\fIkey\fP Parameter name. key == NULL returns first upload. 
.RE
.PP
\fBReturns:\fP
.RS 4
Corresponding upload, NULL if none found. 
.RE
.PP
\fBRemarks:\fP
.RS 4
Will parse the request as necessary. 
.RE
.PP

.SS "\fBapr_table_t\fP* apreq_uploads (\fBapr_pool_t\fP * pool, const \fBapreq_request_t\fP * req)"
.PP
Returns a table of all params in req->body with non-NULL bucket brigades. 
.PP
\fBParameters:\fP
.RS 4
\fIpool\fP Pool which allocates the table struct. 
.br
\fIreq\fP Current request. 
.RE
.PP
\fBReturns:\fP
.RS 4
Upload table. 
.RE
.PP
\fBRemarks:\fP
.RS 4
Will parse the request if necessary. 
.RE
.PP

.SH "Author"
.PP 
Generated automatically by Doxygen for libapreq2 from the source code.