.TH "include/apreq_module.h" 3 "Wed Mar 10 2021" "Version 2.16" "libapreq2" \" -*- nroff -*-
.ad l
.nh
.SH NAME
include/apreq_module.h \- Module API\&.  

.SH SYNOPSIS
.br
.PP
\fC#include 'apreq_cookie\&.h'\fP
.br
\fC#include 'apreq_parser\&.h'\fP
.br
\fC#include 'apreq_error\&.h'\fP
.br

.SS "Data Structures"

.in +1c
.ti -1c
.RI "struct \fBapreq_handle_t\fP"
.br
.ti -1c
.RI "struct \fBapreq_module_t\fP"
.br
.RI "Vtable describing the necessary module functions\&. "
.in -1c
.SS "Macros"

.in +1c
.ti -1c
.RI "#define \fBAPREQ_MODULE\fP(pre,  mmn)"
.br
.ti -1c
.RI "#define \fBapreq_cookie\fP(req,  name)   \fBapreq_jar_get\fP(req, name)"
.br
.in -1c
.SS "Typedefs"

.in +1c
.ti -1c
.RI "typedef struct \fBapreq_handle_t\fP \fBapreq_handle_t\fP"
.br
.ti -1c
.RI "typedef struct \fBapreq_module_t\fP \fBapreq_module_t\fP"
.br
.RI "Vtable describing the necessary module functions\&. "
.in -1c
.SS "Functions"

.in +1c
.ti -1c
.RI "static APR_INLINE unsigned \fBapreq_module_status_is_error\fP (apr_status_t s)"
.br
.ti -1c
.RI "static APR_INLINE apr_status_t \fBapreq_jar\fP (\fBapreq_handle_t\fP *req, const apr_table_t **t)"
.br
.ti -1c
.RI "static APR_INLINE apr_status_t \fBapreq_args\fP (\fBapreq_handle_t\fP *req, const apr_table_t **t)"
.br
.ti -1c
.RI "static APR_INLINE apr_status_t \fBapreq_body\fP (\fBapreq_handle_t\fP *req, const apr_table_t **t)"
.br
.ti -1c
.RI "static APR_INLINE \fBapreq_cookie_t\fP * \fBapreq_jar_get\fP (\fBapreq_handle_t\fP *req, const char *name)"
.br
.ti -1c
.RI "static APR_INLINE \fBapreq_param_t\fP * \fBapreq_args_get\fP (\fBapreq_handle_t\fP *req, const char *name)"
.br
.ti -1c
.RI "static APR_INLINE \fBapreq_param_t\fP * \fBapreq_body_get\fP (\fBapreq_handle_t\fP *req, const char *name)"
.br
.ti -1c
.RI "static APR_INLINE apr_status_t \fBapreq_parser_get\fP (\fBapreq_handle_t\fP *req, const \fBapreq_parser_t\fP **parser)"
.br
.ti -1c
.RI "static APR_INLINE apr_status_t \fBapreq_parser_set\fP (\fBapreq_handle_t\fP *req, \fBapreq_parser_t\fP *parser)"
.br
.ti -1c
.RI "static APR_INLINE apr_status_t \fBapreq_hook_add\fP (\fBapreq_handle_t\fP *req, \fBapreq_hook_t\fP *hook)"
.br
.ti -1c
.RI "static APR_INLINE apr_status_t \fBapreq_brigade_limit_set\fP (\fBapreq_handle_t\fP *req, apr_size_t bytes)"
.br
.ti -1c
.RI "static APR_INLINE apr_status_t \fBapreq_brigade_limit_get\fP (\fBapreq_handle_t\fP *req, apr_size_t *bytes)"
.br
.ti -1c
.RI "static APR_INLINE apr_status_t \fBapreq_read_limit_set\fP (\fBapreq_handle_t\fP *req, apr_uint64_t bytes)"
.br
.ti -1c
.RI "static APR_INLINE apr_status_t \fBapreq_read_limit_get\fP (\fBapreq_handle_t\fP *req, apr_uint64_t *bytes)"
.br
.ti -1c
.RI "static APR_INLINE apr_status_t \fBapreq_temp_dir_set\fP (\fBapreq_handle_t\fP *req, const char *path)"
.br
.ti -1c
.RI "static APR_INLINE apr_status_t \fBapreq_temp_dir_get\fP (\fBapreq_handle_t\fP *req, const char **path)"
.br
.ti -1c
.RI "\fBapreq_handle_t\fP * \fBapreq_handle_cgi\fP (apr_pool_t *pool)"
.br
.ti -1c
.RI "\fBapreq_handle_t\fP * \fBapreq_handle_custom\fP (apr_pool_t *pool, const char *query_string, const char *cookie, \fBapreq_parser_t\fP *parser, apr_uint64_t read_limit, apr_bucket_brigade *in)"
.br
.ti -1c
.RI "\fBapreq_param_t\fP * \fBapreq_param\fP (\fBapreq_handle_t\fP *req, const char *key)"
.br
.ti -1c
.RI "apr_table_t * \fBapreq_params\fP (\fBapreq_handle_t\fP *req, apr_pool_t *p)"
.br
.ti -1c
.RI "apr_table_t * \fBapreq_cookies\fP (\fBapreq_handle_t\fP *req, apr_pool_t *p)"
.br
.in -1c
.SH "Detailed Description"
.PP 
Module API\&. 


.SH "Macro Definition Documentation"
.PP 
.SS "#define apreq_cookie(req, name)   \fBapreq_jar_get\fP(req, name)"
Find the first cookie with the specified name\&. The match is case-insensitive\&.
.PP
\fBParameters\fP
.RS 4
\fIreq\fP request handle\&. 
.br
\fIname\fP desired cookie name
.RE
.PP
\fBReturns\fP
.RS 4
The first matching cookie or NULL\&. 
.RE
.PP

.SS "#define APREQ_MODULE(pre, mmn)"
\fBValue:\fP
.PP
.nf
  const apreq_module_t     \
  pre##_module = { #pre, mmn,                           \
  pre##_jar,        pre##_args,       pre##_body,       \
  pre##_jar_get,    pre##_args_get,   pre##_body_get,   \
  pre##_parser_get, pre##_parser_set, pre##_hook_add,   \
  pre##_brigade_limit_get, pre##_brigade_limit_set,     \
  pre##_read_limit_get,    pre##_read_limit_set,        \
  pre##_temp_dir_get,      pre##_temp_dir_set,          \
  }
.fi
Convenience macro for defining a module by mapping a function prefix to an associated \fBapreq_module_t\fP structure\&.
.PP
\fBParameters\fP
.RS 4
\fIpre\fP Prefix to define new module\&. All attributes of the \fBapreq_module_t\fP struct are defined with this as their prefix\&. The generated struct is named by appending '_module' to the prefix\&. 
.br
\fImmn\fP Magic number (i\&.e\&. version number) of this module\&. 
.RE
.PP

.SH "Typedef Documentation"
.PP 
.SS "typedef struct \fBapreq_handle_t\fP \fBapreq_handle_t\fP"
An apreq handle associated with a module\&. The structure may have variable size, because the module may append its own data structures after it\&. 
.SH "Function Documentation"
.PP 
.SS "static APR_INLINE apr_status_t apreq_args (\fBapreq_handle_t\fP * req, const apr_table_t ** t)\fC [static]\fP"
Expose the parsed 'query string' associated to this handle\&.
.PP
\fBParameters\fP
.RS 4
\fIreq\fP The request handle 
.br
\fIt\fP The resulting table, which will either be NULL or a valid table object on return\&.
.RE
.PP
\fBReturns\fP
.RS 4
APR_SUCCESS or a module-specific error status code\&. 
.RE
.PP

.SS "static APR_INLINE \fBapreq_param_t\fP* apreq_args_get (\fBapreq_handle_t\fP * req, const char * name)\fC [static]\fP"
Fetch the first query string param with the given name\&.
.PP
\fBParameters\fP
.RS 4
\fIreq\fP The request handle 
.br
\fIname\fP Case-insensitive param name\&.
.RE
.PP
\fBReturns\fP
.RS 4
First matching param, or NULL if none match\&. 
.RE
.PP

.SS "static APR_INLINE apr_status_t apreq_body (\fBapreq_handle_t\fP * req, const apr_table_t ** t)\fC [static]\fP"
Expose the parsed 'request body' associated to this handle\&.
.PP
\fBParameters\fP
.RS 4
\fIreq\fP The request handle 
.br
\fIt\fP The resulting table, which will either be NULL or a valid table object on return\&.
.RE
.PP
\fBReturns\fP
.RS 4
APR_SUCCESS or a module-specific error status code\&. 
.RE
.PP

.SS "static APR_INLINE \fBapreq_param_t\fP* apreq_body_get (\fBapreq_handle_t\fP * req, const char * name)\fC [static]\fP"
Fetch the first body param with the given name\&.
.PP
\fBParameters\fP
.RS 4
\fIreq\fP The request handle 
.br
\fIname\fP Case-insensitive cookie name\&.
.RE
.PP
\fBReturns\fP
.RS 4
First matching param, or NULL if none match\&. 
.RE
.PP

.SS "static APR_INLINE apr_status_t apreq_brigade_limit_get (\fBapreq_handle_t\fP * req, apr_size_t * bytes)\fC [static]\fP"
Get the active brigade limit\&.
.PP
\fBParameters\fP
.RS 4
\fIreq\fP The handle\&. 
.br
\fIbytes\fP Pointer to resulting (current) limit\&.
.RE
.PP
\fBReturns\fP
.RS 4
APR_SUCCESS or a module-specific error, which may leave bytes undefined\&. 
.RE
.PP

.SS "static APR_INLINE apr_status_t apreq_brigade_limit_set (\fBapreq_handle_t\fP * req, apr_size_t bytes)\fC [static]\fP"
Set the active brigade limit\&.
.PP
\fBParameters\fP
.RS 4
\fIreq\fP The handle\&. 
.br
\fIbytes\fP New limit to use\&.
.RE
.PP
\fBReturns\fP
.RS 4
APR_SUCCESS or module-specific error\&. 
.RE
.PP

.SS "apr_table_t* apreq_cookies (\fBapreq_handle_t\fP * req, apr_pool_t * p)"
Returns a table containing all request cookies\&.
.PP
\fBParameters\fP
.RS 4
\fIreq\fP the apreq request handle 
.br
\fIp\fP Allocates the returned table\&. 
.RE
.PP

.SS "\fBapreq_handle_t\fP* apreq_handle_cgi (apr_pool_t * pool)"
Create an apreq handle which is suitable for a CGI program\&. It reads input from stdin and writes output to stdout\&.
.PP
\fBParameters\fP
.RS 4
\fIpool\fP Pool associated to this handle\&.
.RE
.PP
\fBReturns\fP
.RS 4
New handle; can only be NULL if the pool allocation failed\&.
.RE
.PP
\fBRemarks\fP
.RS 4
The handle gets cached in the pool's userdata, so subsequent calls will retrieve the original cached handle\&. 
.RE
.PP

.SS "\fBapreq_handle_t\fP* apreq_handle_custom (apr_pool_t * pool, const char * query_string, const char * cookie, \fBapreq_parser_t\fP * parser, apr_uint64_t read_limit, apr_bucket_brigade * in)"
Create a custom apreq handle which knows only some static values\&. Useful if you want to test the parser code or if you have got data from a custom source (neither Apache 2 nor CGI)\&.
.PP
\fBParameters\fP
.RS 4
\fIpool\fP allocates the parse data, 
.br
\fIquery_string\fP parsed into args table 
.br
\fIcookie\fP value of the request 'Cookie' header 
.br
\fIparser\fP parses the request body 
.br
\fIread_limit\fP maximum bytes to read from the body 
.br
\fIin\fP brigade containing the request body
.RE
.PP
\fBReturns\fP
.RS 4
new handle; can only be NULL if the pool allocation failed\&. 
.RE
.PP

.SS "static APR_INLINE apr_status_t apreq_hook_add (\fBapreq_handle_t\fP * req, \fBapreq_hook_t\fP * hook)\fC [static]\fP"
Add a parser hook for this request\&.
.PP
\fBParameters\fP
.RS 4
\fIreq\fP The request handle 
.br
\fIhook\fP Hook to add\&.
.RE
.PP
\fBReturns\fP
.RS 4
APR_SUCCESS or module-specific error\&. 
.RE
.PP

.SS "static APR_INLINE apr_status_t apreq_jar (\fBapreq_handle_t\fP * req, const apr_table_t ** t)\fC [static]\fP"
Expose the parsed 'cookie' header associated to this handle\&.
.PP
\fBParameters\fP
.RS 4
\fIreq\fP The request handle 
.br
\fIt\fP The resulting table, which will either be NULL or a valid table object on return\&.
.RE
.PP
\fBReturns\fP
.RS 4
APR_SUCCESS or a module-specific error status code\&. 
.RE
.PP

.SS "static APR_INLINE \fBapreq_cookie_t\fP* apreq_jar_get (\fBapreq_handle_t\fP * req, const char * name)\fC [static]\fP"
Fetch the first cookie with the given name\&.
.PP
\fBParameters\fP
.RS 4
\fIreq\fP The request handle 
.br
\fIname\fP Case-insensitive cookie name\&.
.RE
.PP
\fBReturns\fP
.RS 4
First matching cookie, or NULL if none match\&. 
.RE
.PP

.SS "static APR_INLINE unsigned apreq_module_status_is_error (apr_status_t s)\fC [static]\fP"
Defines the module-specific status codes which are commonly considered to be non-fatal\&.
.PP
\fBParameters\fP
.RS 4
\fIs\fP status code returned by an \fBapreq_module_t\fP method\&.
.RE
.PP
\fBReturns\fP
.RS 4
1 if s is fatal, 0 otherwise\&. 
.RE
.PP

.SS "\fBapreq_param_t\fP* apreq_param (\fBapreq_handle_t\fP * req, const char * key)"
Find the first query string parameter or body parameter with the specified name\&. The match is case-insensitive\&.
.PP
\fBParameters\fP
.RS 4
\fIreq\fP request handle\&. 
.br
\fIkey\fP desired parameter name
.RE
.PP
\fBReturns\fP
.RS 4
The first matching parameter (with args searched first) or NULL\&. 
.RE
.PP

.SS "apr_table_t* apreq_params (\fBapreq_handle_t\fP * req, apr_pool_t * p)"
Returns a table containing key-value pairs for the full request (args + body)\&.
.PP
\fBParameters\fP
.RS 4
\fIreq\fP request handle 
.br
\fIp\fP allocates the returned table\&.
.RE
.PP
\fBReturns\fP
.RS 4
table representing all available params; is never NULL\&. 
.RE
.PP

.SS "static APR_INLINE apr_status_t apreq_parser_get (\fBapreq_handle_t\fP * req, const \fBapreq_parser_t\fP ** parser)\fC [static]\fP"
Fetch the active body parser\&.
.PP
\fBParameters\fP
.RS 4
\fIreq\fP The request handle 
.br
\fIparser\fP Points to the active parser on return\&.
.RE
.PP
\fBReturns\fP
.RS 4
APR_SUCCESS or module-specific error\&. 
.RE
.PP

.SS "static APR_INLINE apr_status_t apreq_parser_set (\fBapreq_handle_t\fP * req, \fBapreq_parser_t\fP * parser)\fC [static]\fP"
Set the body parser for this request\&.
.PP
\fBParameters\fP
.RS 4
\fIreq\fP The request handle 
.br
\fIparser\fP New parser to use\&.
.RE
.PP
\fBReturns\fP
.RS 4
APR_SUCCESS or module-specific error\&. 
.RE
.PP

.SS "static APR_INLINE apr_status_t apreq_read_limit_get (\fBapreq_handle_t\fP * req, apr_uint64_t * bytes)\fC [static]\fP"
Get the active read limit\&.
.PP
\fBParameters\fP
.RS 4
\fIreq\fP The request handle\&. 
.br
\fIbytes\fP Pointer to resulting (current) limit\&.
.RE
.PP
\fBReturns\fP
.RS 4
APR_SUCCESS or a module-specific error, which may leave bytes undefined\&. 
.RE
.PP

.SS "static APR_INLINE apr_status_t apreq_read_limit_set (\fBapreq_handle_t\fP * req, apr_uint64_t bytes)\fC [static]\fP"
Set the active read limit\&.
.PP
\fBParameters\fP
.RS 4
\fIreq\fP The handle\&. 
.br
\fIbytes\fP New limit to use\&.
.RE
.PP
\fBReturns\fP
.RS 4
APR_SUCCESS or a module-specific error\&. 
.RE
.PP

.SS "static APR_INLINE apr_status_t apreq_temp_dir_get (\fBapreq_handle_t\fP * req, const char ** path)\fC [static]\fP"
Get the active temp directory\&.
.PP
\fBParameters\fP
.RS 4
\fIreq\fP The handle\&. 
.br
\fIpath\fP Resulting path to temp dir\&.
.RE
.PP
\fBReturns\fP
.RS 4
APR_SUCCESS implies path is valid, but may also be NULL\&. Any other return value is module-specific, and may leave path undefined\&. 
.RE
.PP

.SS "static APR_INLINE apr_status_t apreq_temp_dir_set (\fBapreq_handle_t\fP * req, const char * path)\fC [static]\fP"
Set the active temp directory\&.
.PP
\fBParameters\fP
.RS 4
\fIreq\fP The handle\&. 
.br
\fIpath\fP New path to use; may be NULL\&.
.RE
.PP
\fBReturns\fP
.RS 4
APR_SUCCESS or a module-specific error \&. 
.RE
.PP

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