---

Request params
[libapreq2]

Data Structures
struct	apreq_hook_t
struct	apreq_param_t
struct	apreq_parser_t
struct	apreq_request_t
Defines
#define	apreq_value_to_param(ptr)   apreq_attr_to_type(apreq_param_t, v, ptr)
#define	apreq_param_name(p)   ((p)->v.name)
#define	apreq_param_value(p)   ((p)->v.data)
#define	apreq_param_info(p)   ((p)->info)
#define	apreq_param_status(p)   ((p)->v.status)
#define	apreq_param_brigade(p)   ((p)->bb ? apreq_copy_brigade((p)->bb) : NULL)
#define	APREQ_PARSER_ARGS
#define	APREQ_HOOK_ARGS
#define	APREQ_DECLARE_PARSER(f)
#define	APREQ_DECLARE_HOOK(f)
#define	APREQ_RUN_PARSER(psr, env, t, bb)   (psr)->parser(psr,env,t,bb)
#define	APREQ_RUN_HOOK(h, env, param, bb)   (h)->hook(h,env,param,bb)
Typedefs
typedef apreq_param_t	apreq_param_t
typedef apreq_hook_t	apreq_hook_t
typedef apreq_parser_t	apreq_parser_t
typedef apreq_request_t	apreq_request_t
Functions
apreq_param_t *	apreq_make_param (apr_pool_t *p, const char *name, const apr_size_t nlen, const char *val, const apr_size_t vlen)
apreq_request_t *	apreq_request (void *env, const char *qs)
apreq_param_t *	apreq_param (const apreq_request_t *req, const char *name)
apr_table_t *	apreq_params (apr_pool_t *pool, const apreq_request_t *req)
apr_array_header_t *	apreq_params_as_array (apr_pool_t *p, apreq_request_t *req, const char *key)
const char *	apreq_params_as_string (apr_pool_t *p, apreq_request_t *req, const char *key, apreq_join_t mode)
apreq_param_t *	apreq_decode_param (apr_pool_t *pool, const char *word, const apr_size_t nlen, const apr_size_t vlen)
char *	apreq_encode_param (apr_pool_t *pool, const apreq_param_t *param)
apr_status_t	apreq_parse_query_string (apr_pool_t *pool, apr_table_t *t, const char *qs)
apr_status_t	apreq_parse_request (apreq_request_t *req, apr_bucket_brigade *bb)
apr_table_t *	apreq_uploads (apr_pool_t *pool, const apreq_request_t *req)
apreq_param_t *	apreq_upload (const apreq_request_t *req, const char *key)
apr_status_t	apreq_brigade_concat (void *env, apr_bucket_brigade *out, apr_bucket_brigade *in)
	APREQ_DECLARE_PARSER (apreq_parse_headers)
apreq_parser_t *	apreq_make_parser (apr_pool_t *pool, const char *enctype, apr_status_t(*parser) APREQ_PARSER_ARGS, apreq_hook_t *hook, void *ctx)
apreq_hook_t *	apreq_make_hook (apr_pool_t *pool, apr_status_t(*hook) APREQ_HOOK_ARGS, apreq_hook_t *next, void *ctx)
void	apreq_add_hook (apreq_parser_t *p, apreq_hook_t *h)
apreq_parser_t *	apreq_parser (void *env, apreq_hook_t *hook)

---

Define Documentation

#define APREQ_DECLARE_HOOK (  f    )

Value: APREQ_DECLARE(apr_status_t) \ (f) APREQ_HOOK_ARGS Declares an API hook.

#define APREQ_DECLARE_PARSER (  f    )

Value: APREQ_DECLARE(apr_status_t) \ (f) APREQ_PARSER_ARGS Declares a API parser.

#define APREQ_HOOK_ARGS

Value: (apreq_hook_t *hook, \ void *env, \ const apreq_param_t *param, \ apr_bucket_brigade *bb) Hook arguments

#define APREQ_PARSER_ARGS

Value: (apreq_parser_t *parser, \ void *env, \ apr_table_t *t, \ apr_bucket_brigade *bb) Parser arguments.

#define APREQ_RUN_HOOK (  h, env, param, bb    )     (h)->hook(h,env,param,bb)

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.

#define APREQ_RUN_PARSER (  psr, env, t, bb    )     (psr)->parser(psr,env,t,bb)

Parse the incoming brigade into a table.

#define apreq_value_to_param (  ptr    )     apreq_attr_to_type(apreq_param_t, v, ptr)

accessor macros

---

Typedef Documentation

typedef struct apreq_param_t apreq_param_t

Common data structure for params and file uploads

typedef struct apreq_request_t apreq_request_t

Structure which manages the request data.

---

Function Documentation

void apreq_add_hook (  apreq_parser_t *    p, apreq_hook_t *    h )

Add a new hook to the end of the parser's hook list. Parameters: p  Parser. h  Hook to append.

apr_status_t apreq_brigade_concat (  void *    env, apr_bucket_brigade *    out, apr_bucket_brigade *    in )

Concatenates the brigades, spooling large brigades into a tempfile bucket according to the environment's max_brigade setting- see apreq_env_max_brigade(). Parameters: env  Environment. out  Resulting brigade. in  Brigade to append. Returns: APR_SUCCESS on success, error code otherwise.

APREQ_DECLARE_PARSER (  apreq_parse_headers    )

Rfc822 Header parser.

apreq_param_t* apreq_decode_param (  apr_pool_t *    pool, const char *    word, const apr_size_t    nlen, const apr_size_t    vlen )

Url-decodes a name=value pair into a param. Parameters: pool  Pool from which the param is allocated. word  Start of the name=value pair. nlen  Length of urlencoded name. vlen  Length of urlencoded value. Remarks: Unless vlen == 0, this function assumes there is exactly one character ('=') which separates the pair.

char* apreq_encode_param (  apr_pool_t *    pool, const apreq_param_t *    param )

Url-encodes the param into a name-value pair. Parameters: pool  Pool which allocates the returned string. param  Param to encode. Returns: name-value pair representing the param.

apreq_hook_t* apreq_make_hook (  apr_pool_t *    pool, apr_status_t *hook    APREQ_HOOK_ARGS, apreq_hook_t *    next, void *    ctx )

Construct a hook. Parameters: Pool  used to allocate the hook. hook  The hook function. next  List of other hooks for this hook to call on. ctx  Hook's internal scratch pad. Returns: New hook.

apreq_param_t* apreq_make_param (  apr_pool_t *    p, const char *    name, const apr_size_t    nlen, const char *    val, const apr_size_t    vlen )

creates a param from name/value information

apreq_parser_t* apreq_make_parser (  apr_pool_t *    pool, const char *    enctype, apr_status_t *parser    APREQ_PARSER_ARGS, apreq_hook_t *    hook, void *    ctx )

Construct a parser. Parameters: pool  Pool used to allocate the parser. enctype  Content-type that this parser can deal with. parser  The parser function. hook  Hooks to asssociate this parser with. ctx  Parser's internal scratch pad. Returns: New parser.

apreq_param_t* apreq_param (  const apreq_request_t *    req, const char *    name )

Returns the first parameter value for the requested key, NULL if none found. The key is case-insensitive. Parameters: req  The current apreq_request_t object. key  Nul-terminated search key. Returns the first table value if NULL. Remarks: Also parses the request as necessary.

apr_table_t* apreq_params (  apr_pool_t *    p, const apreq_request_t *    req )

Returns a table containing key-value pairs for the full request (args + body). Parameters: p  Allocates the returned table. req  The current apreq_request_t object. Remarks: Also parses the request if necessary.

apr_array_header_t* apreq_params_as_array (  apr_pool_t *    p, apreq_request_t *    req, const char *    key )

Returns an array of parameters (apreq_param_t *) matching the given key. The key is case-insensitive. Parameters: p  Allocates the returned array. req  The current apreq_request_t object. key  Null-terminated search key. key==NULL fetches all parameters. Remarks: Also parses the request if necessary.

const char* apreq_params_as_string (  apr_pool_t *    p, apreq_request_t *    req, const char *    key, apreq_join_t    mode )

Returns a ", " -separated string containing all parameters for the requested key, NULL if none are found. The key is case-insensitive. Parameters: p  Allocates the return string. req  The current apreq_request_t object. key  Null-terminated parameter name. key==NULL fetches all values. mode  Join type- see apreq_join(). Returns: Returned string is the data attribute of an apreq_value_t, so it is safe to use in apreq_strlen() and apreq_strtoval(). Remarks: Also parses the request if necessary.

apr_status_t apreq_parse_query_string (  apr_pool_t *    pool, apr_table_t *    t, const char *    qs )

Parse a url-encoded string into a param table. Parameters: pool  pool used to allocate the param data. table  table to which the params are added. qs  Query string to url-decode. Returns: APR_SUCCESS if successful, error otherwise. Remarks: 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.

apr_status_t apreq_parse_request (  apreq_request_t *    req, apr_bucket_brigade *    bb )

Parse a brigade as incoming POST data. Parameters: req  Current request. bb  Brigade to parse. See remarks below. Returns: APR_INCOMPLETE if the parse is incomplete, APR_SUCCESS if the parser is finished (saw eos), unrecoverable error value otherwise.

apreq_parser_t* apreq_parser (  void *    env, apreq_hook_t *    hook )

Create the default parser associated with the current request's Content-Type (if possible). Parameters: env  The current environment. hook  Hook(s) to add to the parser. Returns: New parser, NULL if the Content-Type is unrecognized. apreq_parser() currently recognizes APREQ_URL_ENCTYPE and APREQ_MFD_ENCTYPE. Parameters: env  The current environment. hook  Additional hooks to supply the parser with. Returns: The built-in parser; NULL if the environment's Content-Type is unrecognized.

apreq_request_t* apreq_request (  void *    env, const char *    qs )

Creates an apreq_request_t object. Parameters: env  The current request environment. qs  The query string. Remarks: "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 apreq_request_t 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.

apreq_param_t* apreq_upload (  const apreq_request_t *    req, const char *    key )

Returns the first param in req->body which has both param->v.name matching key and param->bb != NULL. Parameters: req  The current request. key  Parameter name. key == NULL returns first upload. Returns: Corresponding upload, NULL if none found. Remarks: Will parse the request as necessary.

apr_table_t* apreq_uploads (  apr_pool_t *    pool, const apreq_request_t *    req )

Returns a table of all params in req->body with non-NULL bucket brigades. Parameters: pool  Pool which allocates the table struct. req  Current request. Returns: Upload table. Remarks: Will parse the request if necessary.

---