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_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)
apreq_hook_t *	apreq_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

APREQ_DECLARE_HOOK

#define APREQ_DECLARE_HOOK

(

f

)

Value:

                                APREQ_DECLARE_NONSTD(apr_status_t) \
                                f (APREQ_HOOK_ARGS)

Declares an API hook.

APREQ_DECLARE_PARSER

#define APREQ_DECLARE_PARSER

(

f

)

Value:

                                APREQ_DECLARE_NONSTD(apr_status_t) \
                                f (APREQ_PARSER_ARGS)

Declares a API parser.

APREQ_HOOK_ARGS

#define APREQ_HOOK_ARGS

Value:

                           apreq_hook_t *hook,         \
                           apreq_param_t *param,       \
                           apr_bucket_brigade *bb

Hook arguments

APREQ_PARSER_ARGS

#define APREQ_PARSER_ARGS

Value:

                           apreq_parser_t *parser,     \
                           apr_table_t *t,             \
                           apr_bucket_brigade *bb

Parser arguments.

Typedef Documentation

apreq_hook_find_param_ctx_t

typedef struct apreq_hook_find_param_ctx_t apreq_hook_find_param_ctx_t

Context struct for the apreq_hook_find_param hook.

apreq_hook_function_t

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.

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().

apreq_parser_function_t

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.

apreq_parser_t

typedef struct apreq_parser_t apreq_parser_t

A request body parser instance.

Function Documentation

apreq_hook_apr_xml_parser()

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.

apreq_hook_disable_uploads()

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.

apreq_hook_discard_brigade()

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.

apreq_hook_find_param()

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 should 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_make()

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

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_parse_generic()

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 **).

apreq_parse_headers()

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.

apreq_parse_multipart()

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.

apreq_parse_urlencoded()

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()

apreq_parser_function_t apreq_parser

(

const char *

enctype

)

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

Parameters

enctype

The desired enctype (can also be a full "Content-Type" header).

Returns

The parser function, or NULL if the enctype is unrecognized.

apreq_parser_add_hook()

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

p	Parser.
h	Hook to append.

apreq_parser_make()

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

pool	Pool used to allocate the parser.
ba	bucket allocator used to create bucket brigades
content_type	Content-type that this parser can deal with.
pfn	The parser function.
brigade_limit	the maximum in-memory bytes a brigade may use
temp_dir	the directory used by the parser for temporary files
hook	Hooks to associate this parser with.
ctx	Parser's internal scratch pad.

Returns

New parser.

apreq_register_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

enctype	The MIME type.
pfn	The function to use during parsing. Setting parser == NULL will remove an existing parser.

Returns

APR_SUCCESS or error.