include/apreq_module.h(3)

NAME
include/apreq_module.h - Module API.

SYNOPSIS

#include 'apreq_cookie.h'
#include 'apreq_parser.h'
#include 'apreq_error.h'

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

  Typedefs
typedef apreq_handle_t apreq_handle_t
typedef apreq_module_t apreq_module_t
Vtable describing the necessary environment 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_t * apreq_jar_get (apreq_handle_t *req, const char *name)
static APR_INLINE apreq_param_t * apreq_args_get (apreq_handle_t *req, const char *name)
static APR_INLINE apreq_param_t * apreq_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_t * apreq_handle_cgi (apr_pool_t *pool)
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)
apr_status_t apreq_cookie_bake (const apreq_cookie_t *c, apreq_handle_t *req)
apr_status_t apreq_cookie_bake2 (const apreq_cookie_t *c, apreq_handle_t *req)
unsigned apreq_ua_cookie_version (apreq_handle_t *req)
apreq_param_t * apreq_param (apreq_handle_t *req, const char *key)
apr_table_t * apreq_params (apreq_handle_t *req, apr_pool_t *p)
apr_table_t * apreq_cookies (apreq_handle_t *req, apr_pool_t *p)
static APR_INLINE apr_status_t apreq_parse (apreq_handle_t *req)

Detailed Description

Module API.

Define Documentation

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

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

Parameters:
    req request handle.
    key desired cookie name

Returns:
    The first matching parameter (with args searched first) or NULL.

  #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:
    pre Prefix to define new environment. All attributes of the apreq_env_module_t struct are defined with this as their prefix. The generated struct is named by appending '_module' to the prefix.
    mmn Magic number (i.e. version number) of this environment.

Typedef Documentation

  typedef struct apreq_handle_t 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

  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:
    req The request handle
    t The resulting table, which will either be NULL or a valid table object on return.

Returns:
    APR_SUCCESS or a module-specific error status code.

  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:
    req The request handle
    name Case-insensitive param name.

Returns:
    First matching param, or NULL if none match.

  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:
    req The request handle
    t The resulting table, which will either be NULL or a valid table object on return.

Returns:
    APR_SUCCESS or a module-specific error status code.

  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:
    req The request handle
    name Case-insensitive cookie name.

Returns:
    First matching param, or NULL if none match.

  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:
    req The handle.
    bytes Pointer to resulting (current) limit.

Returns:
    APR_SUCCESS or a module-specific error, which may leave bytes undefined.

  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:
    req The handle.
    bytes New limit to use.

Returns:
    APR_SUCCESS or module-specific error.

  apr_status_t apreq_cookie_bake (const apreq_cookie_t * c, apreq_handle_t * req)

Add the cookie to the outgoing 'Set-Cookie' headers.

Parameters:
    c The cookie.
    req The request handle which set the outgoing header.

Returns:
    APR_SUCCESS or error.

  apr_status_t apreq_cookie_bake2 (const apreq_cookie_t * c, apreq_handle_t * req)

Add the cookie to the outgoing 'Set-Cookie2' headers.

Parameters:
    c cookie
    req request handle

Returns:
    APR_SUCCESS or error.

  apr_table_t* apreq_cookies (apreq_handle_t * req, apr_pool_t * p)

Returns a table containing all request cookies.

Parameters:
    req the apreq request handle
    p Allocates the returned table.

  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:
    pool Pool 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_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:
    pool allocates the parse data,
    query_string parsed into args table
    cookie value of the request 'Cookie' header
    parser parses the request body
    read_limit maximum bytes to read from the body
    in brigade containing the request body

Returns:
    new handle; can only be NULL if the pool allocation failed.

  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:
    req The request handle
    hook Hook to add.

Returns:
    APR_SUCCESS or module-specific error.

  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:
    req The request handle
    t The resulting table, which will either be NULL or a valid table object on return.

Returns:
    APR_SUCCESS or a module-specific error status code.

  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:
    req The request handle
    name Case-insensitive cookie name.

Returns:
    First matching cookie, or NULL if none match.

  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:
    s status code returned by an apreq_module_t method.

Returns:
    1 if s is fatal, 0 otherwise.

  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:
    req request handle.
    key desired parameter name

Returns:
    The first matching parameter (with args searched first) or NULL.

  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:
    req request handle
    p allocates the returned table.

Returns:
    table representing all available params; is never NULL.

  static APR_INLINE apr_status_t apreq_parse (apreq_handle_t * req) [static]

Force a complete parse of everything.

Parameters:
    req The request handle

Returns:
    APR_SUCCESS on an error-free parse of the request data. Any other status code indicates a potential problem somewhere.

  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:
    req The request handle
    parser Points to the active parser on return.

Returns:
    APR_SUCCESS or module-specific error.

  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:
    req The request handle
    parser New parser to use.

Returns:
    APR_SUCCESS or module-specific error.

  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:
    req The request handle.
    bytes Pointer to resulting (current) limit.

Returns:
    APR_SUCCESS or a module-specific error, which may leave bytes undefined.

  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:
    req The handle.
    bytes New limit to use.

Returns:
    APR_SUCCESS or a module-specific error.

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

Get the active temp directory.

Parameters:
    req The handle.
    path Resulting 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.

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

Set the active temp directory.

Parameters:
    req The handle.
    path New path to use; may be NULL.

Returns:
    APR_SUCCESS or a module-specific error .

  unsigned apreq_ua_cookie_version (apreq_handle_t * req)

Looks for the presence of a 'Cookie2' header to determine whether or not the current User-Agent responsible for this request supports rfc2965.

Parameters:
    req the apreq request handle

Returns:
    ::APREQ_COOKIE_VERSION_RFC if rfc2965 is supported by the user-agent, ::APREQ_COOKIE_VERSION_NETSCAPE otherwise.

Author

Generated automatically by Doxygen for libapreq2 from the source code.