libapreq2-2.05-dev: libapreq2: include/apreq_module.h File Reference

Apache HTTP Server Request Library

Main Page | Modules | Data Structures | Directories | File List | Data Fields | Globals | Related Pages

# apreq_module.h File Reference

Module API. More...

`#include "apreq_cookie.h"`
`#include "apreq_parser.h"`
`#include "apreq_error.h"`

Go to the source code of this file.

## 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.