Apache2
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
apreq_parser.h File Reference

Request body parser API. More...

#include "apreq_param.h"
Include dependency graph for apreq_parser.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  apreq_hook_t
 
struct  apreq_parser_t
 
struct  apreq_hook_find_param_ctx_t
 

Macros

#define APREQ_PARSER_ARGS
 
#define APREQ_HOOK_ARGS
 
#define APREQ_DECLARE_PARSER(f)
 
#define APREQ_DECLARE_HOOK(f)
 

Typedefs

typedef struct apreq_hook_t apreq_hook_t
 
typedef struct apreq_parser_t apreq_parser_t
 
typedef apr_status_t(* apreq_parser_function_t )(apreq_parser_t *parser, apr_table_t *t, apr_bucket_brigade *bb)
 
typedef apr_status_t(* apreq_hook_function_t )(apreq_hook_t *hook, apreq_param_t *param, apr_bucket_brigade *bb)
 
typedef struct
apreq_hook_find_param_ctx_t 
apreq_hook_find_param_ctx_t
 

Functions

apr_status_t apreq_parse_headers (apreq_parser_t *parser, apr_table_t *t, apr_bucket_brigade *bb)
 
apr_status_t apreq_parse_urlencoded (apreq_parser_t *parser, apr_table_t *t, apr_bucket_brigade *bb)
 
apr_status_t apreq_parse_multipart (apreq_parser_t *parser, apr_table_t *t, apr_bucket_brigade *bb)
 
apr_status_t apreq_parse_generic (apreq_parser_t *parser, apr_table_t *t, apr_bucket_brigade *bb)
 
apr_status_t apreq_hook_apr_xml_parser (apreq_hook_t *hook, apreq_param_t *param, apr_bucket_brigade *bb)
 
apreq_parser_tapreq_parser_make (apr_pool_t *pool, apr_bucket_alloc_t *ba, const char *content_type, apreq_parser_function_t pfn, apr_size_t brigade_limit, const char *temp_dir, apreq_hook_t *hook, void *ctx)
 
apreq_hook_tapreq_hook_make (apr_pool_t *pool, apreq_hook_function_t hook, apreq_hook_t *next, void *ctx)
 
apr_status_t apreq_parser_add_hook (apreq_parser_t *p, apreq_hook_t *h)
 
apreq_parser_function_t apreq_parser (const char *enctype)
 
apr_status_t apreq_register_parser (const char *enctype, apreq_parser_function_t pfn)
 
apr_status_t apreq_hook_disable_uploads (apreq_hook_t *hook, apreq_param_t *param, apr_bucket_brigade *bb)
 
apr_status_t apreq_hook_discard_brigade (apreq_hook_t *hook, apreq_param_t *param, apr_bucket_brigade *bb)
 
apr_status_t apreq_hook_find_param (apreq_hook_t *hook, apreq_param_t *param, apr_bucket_brigade *bb)
 

Detailed Description

Request body parser API.

Macro Definition Documentation

#define APREQ_DECLARE_HOOK (   f)
Value:
#define APREQ_DECLARE_NONSTD(d)
Definition: ap_config.h:125
#define APREQ_HOOK_ARGS
Definition: apreq_parser.h:52
int apr_status_t
Definition: apr_errno.h:44

Declares an API hook.

#define APREQ_DECLARE_PARSER (   f)
Value:
#define APREQ_DECLARE_NONSTD(d)
Definition: ap_config.h:125
#define APREQ_PARSER_ARGS
Definition: apreq_parser.h:47
int apr_status_t
Definition: apr_errno.h:44

Declares a API parser.

#define APREQ_HOOK_ARGS
Value:
Definition: apreq_parser.h:83
struct apreq_param_t apreq_param_t
apr_bucket_brigade * bb
Definition: mod_dav.h:556
struct apr_bucket_brigade apr_bucket_brigade
Definition: apr_buckets.h:119

Hook arguments

#define APREQ_PARSER_ARGS
Value:
apreq_parser_t *parser, \
Definition: apreq_parser.h:93
apr_bucket_brigade * bb
Definition: mod_dav.h:556
struct apr_bucket_brigade apr_bucket_brigade
Definition: apr_buckets.h:119
struct apr_table_t apr_table_t
Definition: apr_tables.h:56

Parser arguments.

Typedef Documentation

Context struct for the apreq_hook_find_param hook.

typedef apr_status_t(* apreq_hook_function_t)(apreq_hook_t *hook, apreq_param_t *param, apr_bucket_brigade *bb)

The callback function of a hook. See apreq_hook_t.

typedef struct apreq_hook_t apreq_hook_t

A hook is called by the parser whenever data arrives in a file upload parameter of the request body. You may associate any number of hooks with a parser instance with apreq_parser_add_hook().

typedef apr_status_t(* apreq_parser_function_t)(apreq_parser_t *parser, apr_table_t *t, apr_bucket_brigade *bb)

The callback function implementing a request body parser.

A request body parser instance.

Function Documentation

apr_status_t apreq_hook_apr_xml_parser ( apreq_hook_t hook,
apreq_param_t param,
apr_bucket_brigade bb 
)

apr_xml_parser hook. It will parse until EOS appears. The parsed document isn't available until parsing has completed successfully. The hook's ctx pointer may be cast as (apr_xml_doc **) to retrieve the parsed document.

apr_status_t apreq_hook_disable_uploads ( apreq_hook_t hook,
apreq_param_t param,
apr_bucket_brigade bb 
)

Returns APREQ_ERROR_GENERAL. Effectively disables mfd parser if a file-upload field is present.

apr_status_t apreq_hook_discard_brigade ( apreq_hook_t hook,
apreq_param_t param,
apr_bucket_brigade bb 
)

Calls apr_brigade_cleanup on the incoming brigade after passing the brigade to any subsequent hooks.

apr_status_t apreq_hook_find_param ( apreq_hook_t hook,
apreq_param_t param,
apr_bucket_brigade bb 
)

Special purpose utility for locating a parameter during parsing. The hook's ctx shoud be initialized to an apreq_hook_find_param_ctx_t *, with the name attribute set to the sought parameter name, the param attribute set to NULL, and the prev attribute set to the address of the previous hook. The param attribute will be reassigned to the first param found, and once that happens this hook is immediately removed from the chain.

Remarks
When used, this should always be the first hook invoked, so add it manually with ctx->prev = &parser->hook instead of using apreq_parser_add_hook.
apreq_hook_t* apreq_hook_make ( apr_pool_t pool,
apreq_hook_function_t  hook,
apreq_hook_t next,
void ctx 
)

Construct a hook.

Parameters
poolused to allocate the hook.
hookThe hook function.
nextList of other hooks for this hook to call on.
ctxHook's internal scratch pad.
Returns
New hook.
apr_status_t apreq_parse_generic ( apreq_parser_t parser,
apr_table_t t,
apr_bucket_brigade bb 
)

Generic parser. No table entries will be added to the req->body table by this parser. The parser creates a dummy apreq_param_t to pass to any configured hooks. If no hooks are configured, the dummy param's bb slot will contain a copy of the request body. It can be retrieved by casting the parser's ctx pointer to (apreq_param_t **).

apr_status_t apreq_parse_headers ( apreq_parser_t parser,
apr_table_t t,
apr_bucket_brigade bb 
)

RFC 822 Header parser. It will reject all data after the first CRLF CRLF sequence (an empty line). See apreq_parser_run() for more info on rejected data.

apr_status_t apreq_parse_multipart ( apreq_parser_t parser,
apr_table_t t,
apr_bucket_brigade bb 
)

RFC 2388 multipart/form-data (and XForms 1.0 multipart/related) parser. It will reject any buckets representing preamble and postamble text (this is normal behavior, not an error condition). See apreq_parser_run() for more info on rejected data.

apr_status_t apreq_parse_urlencoded ( apreq_parser_t parser,
apr_table_t t,
apr_bucket_brigade bb 
)

RFC 2396 application/x-www-form-urlencoded parser.

apreq_parser_function_t apreq_parser ( const char *  enctype)

Fetch the default parser function associated with the given MIME type.

Parameters
enctypeThe desired enctype (can also be a full "Content-Type" header).
Returns
The parser function, or NULL if the enctype is unrecognized.
apr_status_t apreq_parser_add_hook ( apreq_parser_t p,
apreq_hook_t h 
)

Add a new hook to the end of the parser's hook list.

Parameters
pParser.
hHook to append.
apreq_parser_t* apreq_parser_make ( apr_pool_t pool,
apr_bucket_alloc_t ba,
const char *  content_type,
apreq_parser_function_t  pfn,
apr_size_t  brigade_limit,
const char *  temp_dir,
apreq_hook_t hook,
void ctx 
)

Construct a parser.

Parameters
poolPool used to allocate the parser.
babucket allocator used to create bucket brigades
content_typeContent-type that this parser can deal with.
pfnThe parser function.
brigade_limitthe maximum in-memory bytes a brigade may use
temp_dirthe directory used by the parser for temporary files
hookHooks to associate this parser with.
ctxParser's internal scratch pad.
Returns
New parser.
apr_status_t apreq_register_parser ( const char *  enctype,
apreq_parser_function_t  pfn 
)

Register a new parsing function with a MIME enctype. Registered parsers are added to apreq_parser()'s internal lookup table.

Parameters
enctypeThe MIME type.
pfnThe function to use during parsing. Setting parser == NULL will remove an existing parser.
Returns
APR_SUCCESS or error.