Data Structures | Macros | Typedefs | Functions
apreq_module.h File Reference

Module API. More...

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

Go to the source code of this file.

Data Structures

struct  apreq_handle_t
 
struct  apreq_module_t
 Vtable describing the necessary module functions. More...
 

Macros

#define APREQ_MODULE(pre, mmn)
 
#define apreq_cookie(req, name)   apreq_jar_get(req, name)
 

Typedefs

typedef struct apreq_handle_t apreq_handle_t
 
typedef struct apreq_module_t apreq_module_t
 Vtable describing the necessary module functions.
 

Functions

static APR_INLINE unsigned apreq_module_status_is_error (apr_status_t s)
 
static APR_INLINE apr_status_t apreq_jar (apreq_handle_t *req, const apr_table_t **t)
 
static APR_INLINE apr_status_t apreq_args (apreq_handle_t *req, const apr_table_t **t)
 
static APR_INLINE apr_status_t apreq_body (apreq_handle_t *req, const apr_table_t **t)
 
static APR_INLINE apreq_cookie_tapreq_jar_get (apreq_handle_t *req, const char *name)
 
static APR_INLINE apreq_param_tapreq_args_get (apreq_handle_t *req, const char *name)
 
static APR_INLINE apreq_param_tapreq_body_get (apreq_handle_t *req, const char *name)
 
static APR_INLINE apr_status_t apreq_parser_get (apreq_handle_t *req, const apreq_parser_t **parser)
 
static APR_INLINE apr_status_t apreq_parser_set (apreq_handle_t *req, apreq_parser_t *parser)
 
static APR_INLINE apr_status_t apreq_hook_add (apreq_handle_t *req, apreq_hook_t *hook)
 
static APR_INLINE apr_status_t apreq_brigade_limit_set (apreq_handle_t *req, apr_size_t bytes)
 
static APR_INLINE apr_status_t apreq_brigade_limit_get (apreq_handle_t *req, apr_size_t *bytes)
 
static APR_INLINE apr_status_t apreq_read_limit_set (apreq_handle_t *req, apr_uint64_t bytes)
 
static APR_INLINE apr_status_t apreq_read_limit_get (apreq_handle_t *req, apr_uint64_t *bytes)
 
static APR_INLINE apr_status_t apreq_temp_dir_set (apreq_handle_t *req, const char *path)
 
static APR_INLINE apr_status_t apreq_temp_dir_get (apreq_handle_t *req, const char **path)
 
apreq_handle_tapreq_handle_cgi (apr_pool_t *pool)
 
apreq_handle_tapreq_handle_custom (apr_pool_t *pool, const char *query_string, const char *cookie, apreq_parser_t *parser, apr_uint64_t read_limit, apr_bucket_brigade *in)
 
apreq_param_tapreq_param (apreq_handle_t *req, const char *key)
 
apr_table_tapreq_params (apreq_handle_t *req, apr_pool_t *p)
 
apr_table_tapreq_cookies (apreq_handle_t *req, apr_pool_t *p)
 

Detailed Description

Module API.

Macro Definition Documentation

◆ apreq_cookie

#define apreq_cookie (   req,
  name 
)    apreq_jar_get(req, name)

Find the first cookie with the specified name. The match is case-insensitive.

Parameters
reqrequest handle.
namedesired cookie name
Returns
The first matching cookie or NULL.

◆ APREQ_MODULE

#define APREQ_MODULE (   pre,
  mmn 
)
Value:
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, \
}

Convenience macro for defining a module by mapping a function prefix to an associated apreq_module_t structure.

Parameters
prePrefix to define new module. All attributes of the apreq_module_t struct are defined with this as their prefix. The generated struct is named by appending "_module" to the prefix.
mmnMagic number (i.e. version number) of this module.

Typedef Documentation

◆ apreq_handle_t

An apreq handle associated with a module. The structure may have variable size, because the module may append its own data structures after it.

Function Documentation

◆ apreq_args()

static APR_INLINE apr_status_t apreq_args ( apreq_handle_t req,
const apr_table_t **  t 
)
static

Expose the parsed "query string" associated to this handle.

Parameters
reqThe request handle
tThe resulting table, which will either be NULL or a valid table object on return.
Returns
APR_SUCCESS or a module-specific error status code.

◆ apreq_args_get()

static APR_INLINE apreq_param_t* apreq_args_get ( apreq_handle_t req,
const char *  name 
)
static

Fetch the first query string param with the given name.

Parameters
reqThe request handle
nameCase-insensitive param name.
Returns
First matching param, or NULL if none match.

◆ apreq_body()

static APR_INLINE apr_status_t apreq_body ( apreq_handle_t req,
const apr_table_t **  t 
)
static

Expose the parsed "request body" associated to this handle.

Parameters
reqThe request handle
tThe resulting table, which will either be NULL or a valid table object on return.
Returns
APR_SUCCESS or a module-specific error status code.

◆ apreq_body_get()

static APR_INLINE apreq_param_t* apreq_body_get ( apreq_handle_t req,
const char *  name 
)
static

Fetch the first body param with the given name.

Parameters
reqThe request handle
nameCase-insensitive cookie name.
Returns
First matching param, or NULL if none match.

◆ apreq_brigade_limit_get()

static APR_INLINE apr_status_t apreq_brigade_limit_get ( apreq_handle_t req,
apr_size_t *  bytes 
)
static

Get the active brigade limit.

Parameters
reqThe handle.
bytesPointer to resulting (current) limit.
Returns
APR_SUCCESS or a module-specific error, which may leave bytes undefined.

◆ apreq_brigade_limit_set()

static APR_INLINE apr_status_t apreq_brigade_limit_set ( apreq_handle_t req,
apr_size_t  bytes 
)
static

Set the active brigade limit.

Parameters
reqThe handle.
bytesNew limit to use.
Returns
APR_SUCCESS or module-specific error.

◆ apreq_cookies()

apr_table_t* apreq_cookies ( apreq_handle_t req,
apr_pool_t p 
)

Returns a table containing all request cookies.

Parameters
reqthe apreq request handle
pAllocates the returned table.

◆ apreq_handle_cgi()

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

Parameters
poolPool associated to this handle.
Returns
New handle; can only be NULL if the pool allocation failed.
Remarks
The handle gets cached in the pool's userdata, so subsequent calls will retrieve the original cached handle.

◆ apreq_handle_custom()

apreq_handle_t* apreq_handle_custom ( apr_pool_t pool,
const char *  query_string,
const char *  cookie,
apreq_parser_t 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).

Parameters
poolallocates the parse data,
query_stringparsed into args table
cookievalue of the request "Cookie" header
parserparses the request body
read_limitmaximum bytes to read from the body
inbrigade containing the request body
Returns
new handle; can only be NULL if the pool allocation failed.

◆ apreq_hook_add()

static APR_INLINE apr_status_t apreq_hook_add ( apreq_handle_t req,
apreq_hook_t hook 
)
static

Add a parser hook for this request.

Parameters
reqThe request handle
hookHook to add.
Returns
APR_SUCCESS or module-specific error.

◆ apreq_jar()

static APR_INLINE apr_status_t apreq_jar ( apreq_handle_t req,
const apr_table_t **  t 
)
static

Expose the parsed "cookie" header associated to this handle.

Parameters
reqThe request handle
tThe resulting table, which will either be NULL or a valid table object on return.
Returns
APR_SUCCESS or a module-specific error status code.

◆ apreq_jar_get()

static APR_INLINE apreq_cookie_t* apreq_jar_get ( apreq_handle_t req,
const char *  name 
)
static

Fetch the first cookie with the given name.

Parameters
reqThe request handle
nameCase-insensitive cookie name.
Returns
First matching cookie, or NULL if none match.

◆ apreq_module_status_is_error()

static APR_INLINE unsigned apreq_module_status_is_error ( apr_status_t  s)
static

Defines the module-specific status codes which are commonly considered to be non-fatal.

Parameters
sstatus code returned by an apreq_module_t method.
Returns
1 if s is fatal, 0 otherwise.

◆ apreq_param()

apreq_param_t* apreq_param ( apreq_handle_t req,
const char *  key 
)

Find the first query string parameter or body parameter with the specified name. The match is case-insensitive.

Parameters
reqrequest handle.
keydesired parameter name
Returns
The first matching parameter (with args searched first) or NULL.

◆ apreq_params()

apr_table_t* apreq_params ( apreq_handle_t req,
apr_pool_t p 
)

Returns a table containing key-value pairs for the full request (args + body).

Parameters
reqrequest handle
pallocates the returned table.
Returns
table representing all available params; is never NULL.

◆ apreq_parser_get()

static APR_INLINE apr_status_t apreq_parser_get ( apreq_handle_t req,
const apreq_parser_t **  parser 
)
static

Fetch the active body parser.

Parameters
reqThe request handle
parserPoints to the active parser on return.
Returns
APR_SUCCESS or module-specific error.

◆ apreq_parser_set()

static APR_INLINE apr_status_t apreq_parser_set ( apreq_handle_t req,
apreq_parser_t parser 
)
static

Set the body parser for this request.

Parameters
reqThe request handle
parserNew parser to use.
Returns
APR_SUCCESS or module-specific error.

◆ apreq_read_limit_get()

static APR_INLINE apr_status_t apreq_read_limit_get ( apreq_handle_t req,
apr_uint64_t *  bytes 
)
static

Get the active read limit.

Parameters
reqThe request handle.
bytesPointer to resulting (current) limit.
Returns
APR_SUCCESS or a module-specific error, which may leave bytes undefined.

◆ apreq_read_limit_set()

static APR_INLINE apr_status_t apreq_read_limit_set ( apreq_handle_t req,
apr_uint64_t  bytes 
)
static

Set the active read limit.

Parameters
reqThe handle.
bytesNew limit to use.
Returns
APR_SUCCESS or a module-specific error.

◆ apreq_temp_dir_get()

static APR_INLINE apr_status_t apreq_temp_dir_get ( apreq_handle_t req,
const char **  path 
)
static

Get the active temp directory.

Parameters
reqThe handle.
pathResulting path to temp dir.
Returns
APR_SUCCESS implies path is valid, but may also be NULL. Any other return value is module-specific, and may leave path undefined.

◆ apreq_temp_dir_set()

static APR_INLINE apr_status_t apreq_temp_dir_set ( apreq_handle_t req,
const char *  path 
)
static

Set the active temp directory.

Parameters
reqThe handle.
pathNew path to use; may be NULL.
Returns
APR_SUCCESS or a module-specific error .