.TH "include/apreq.h" 3 "Wed Mar 10 2021" "Version 2.16" "libapreq2" \" -*- nroff -*-
.ad l
.nh
.SH NAME
include/apreq.h \- Main header file\&.\&.\&.
.SH SYNOPSIS
.br
.PP
\fC#include 'apr_tables\&.h'\fP
.br
\fC#include <stddef\&.h>\fP
.br
.SS "Data Structures"
.in +1c
.ti -1c
.RI "struct \fBapreq_value_t\fP"
.br
.RI "libapreq's pre-extensible string type "
.in -1c
.SS "Macros"
.in +1c
.ti -1c
.RI "#define \fBAPREQ_DECLARE\fP(d) APR_DECLARE(d)"
.br
.ti -1c
.RI "#define \fBAPREQ_DECLARE_NONSTD\fP(d) APR_DECLARE_NONSTD(d)"
.br
.ti -1c
.RI "#define \fBAPREQ_DECLARE_DATA\fP"
.br
.ti -1c
.RI "#define \fBAPREQ_DEFAULT_READ_BLOCK_SIZE\fP (64 * 1024)"
.br
.ti -1c
.RI "#define \fBAPREQ_DEFAULT_READ_LIMIT\fP (64 * 1024 * 1024)"
.br
.ti -1c
.RI "#define \fBAPREQ_DEFAULT_BRIGADE_LIMIT\fP (256 * 1024)"
.br
.ti -1c
.RI "#define \fBAPREQ_DEFAULT_NELTS\fP 8"
.br
.ti -1c
.RI "#define \fBAPREQ_FLAGS_OFF\fP(f, name) ((f) &= ~(name##_MASK << name##_BIT))"
.br
.ti -1c
.RI "#define \fBAPREQ_FLAGS_ON\fP(f, name) ((f) |= (name##_MASK << name##_BIT))"
.br
.ti -1c
.RI "#define \fBAPREQ_FLAGS_GET\fP(f, name) (((f) >> name##_BIT) & name##_MASK)"
.br
.ti -1c
.RI "#define \fBAPREQ_FLAGS_SET\fP(f, name, value)"
.br
.ti -1c
.RI "#define \fBAPREQ_CHARSET_BIT\fP 0"
.br
.ti -1c
.RI "#define \fBAPREQ_CHARSET_MASK\fP 255"
.br
.ti -1c
.RI "#define \fBAPREQ_TAINTED_BIT\fP 8"
.br
.ti -1c
.RI "#define \fBAPREQ_TAINTED_MASK\fP 1"
.br
.ti -1c
.RI "#define \fBAPREQ_COOKIE_VERSION_BIT\fP 11"
.br
.ti -1c
.RI "#define \fBAPREQ_COOKIE_VERSION_MASK\fP 3"
.br
.ti -1c
.RI "#define \fBAPREQ_COOKIE_SECURE_BIT\fP 13"
.br
.ti -1c
.RI "#define \fBAPREQ_COOKIE_SECURE_MASK\fP 1"
.br
.ti -1c
.RI "#define \fBAPREQ_COOKIE_HTTPONLY_BIT\fP 14"
.br
.ti -1c
.RI "#define \fBAPREQ_COOKIE_HTTPONLY_MASK\fP 1"
.br
.ti -1c
.RI "#define \fBapreq_attr_to_type\fP(T, A, P) ( (T*) ((char*)(P)\-offsetof(T,A)) )"
.br
.in -1c
.SS "Typedefs"
.in +1c
.ti -1c
.RI "typedef struct \fBapreq_value_t\fP \fBapreq_value_t\fP"
.br
.RI "libapreq's pre-extensible string type "
.in -1c
.SS "Enumerations"
.in +1c
.ti -1c
.RI "enum \fBapreq_charset_t\fP { \fBAPREQ_CHARSET_ASCII\fP =0, \fBAPREQ_CHARSET_LATIN1\fP =1, \fBAPREQ_CHARSET_CP1252\fP =2, \fBAPREQ_CHARSET_UTF8\fP =8 }"
.br
.ti -1c
.RI "enum \fBapreq_join_t\fP { \fBAPREQ_JOIN_AS_IS\fP, \fBAPREQ_JOIN_ENCODE\fP, \fBAPREQ_JOIN_DECODE\fP, \fBAPREQ_JOIN_QUOTE\fP }"
.br
.ti -1c
.RI "enum \fBapreq_match_t\fP { \fBAPREQ_MATCH_FULL\fP, \fBAPREQ_MATCH_PARTIAL\fP }"
.br
.ti -1c
.RI "enum \fBapreq_expires_t\fP { \fBAPREQ_EXPIRES_HTTP\fP, \fBAPREQ_EXPIRES_NSCOOKIE\fP }"
.br
.in -1c
.SS "Functions"
.in +1c
.ti -1c
.RI "static APR_INLINE void \fBapreq_value_table_add\fP (const \fBapreq_value_t\fP *v, apr_table_t *t)"
.br
.ti -1c
.RI "apr_status_t \fBapreq_initialize\fP (apr_pool_t *pool)"
.br
.ti -1c
.RI "apr_status_t \fBapreq_pre_initialize\fP (apr_pool_t *pool)"
.br
.ti -1c
.RI "apr_status_t \fBapreq_post_initialize\fP (apr_pool_t *pool)"
.br
.in -1c
.SH "Detailed Description"
.PP
Main header file\&.\&.\&.
Define the generic APREQ_ macros and common data structures\&.
.SH "Macro Definition Documentation"
.PP
.SS "#define apreq_attr_to_type(T, A, P) ( (T*) ((char*)(P)\-offsetof(T,A)) )"
.PP
\fBParameters\fP
.RS 4
\fIT\fP type
.br
\fIA\fP attribute
.br
\fIP\fP XXX
.RE
.PP
.SS "#define APREQ_CHARSET_BIT 0"
Charset Bit
.PP
\fBSee also\fP
.RS 4
\fBAPREQ_FLAGS_OFF\fP
.PP
\fBAPREQ_FLAGS_ON\fP
.PP
\fBAPREQ_FLAGS_GET\fP
.PP
\fBAPREQ_FLAGS_SET\fP
.RE
.PP
.SS "#define APREQ_CHARSET_MASK 255"
Charset Mask
.PP
\fBSee also\fP
.RS 4
\fBAPREQ_FLAGS_OFF\fP
.PP
\fBAPREQ_FLAGS_ON\fP
.PP
\fBAPREQ_FLAGS_GET\fP
.PP
\fBAPREQ_FLAGS_SET\fP
.RE
.PP
.SS "#define APREQ_COOKIE_HTTPONLY_BIT 14"
Cookie's HttpOnly Bit
.PP
\fBSee also\fP
.RS 4
\fBAPREQ_FLAGS_OFF\fP
.PP
\fBAPREQ_FLAGS_ON\fP
.PP
\fBAPREQ_FLAGS_GET\fP
.PP
\fBAPREQ_FLAGS_SET\fP
.RE
.PP
.SS "#define APREQ_COOKIE_HTTPONLY_MASK 1"
Cookie's HttpOnly Mask
.PP
\fBSee also\fP
.RS 4
\fBAPREQ_FLAGS_OFF\fP
.PP
\fBAPREQ_FLAGS_ON\fP
.PP
\fBAPREQ_FLAGS_GET\fP
.PP
\fBAPREQ_FLAGS_SET\fP
.RE
.PP
.SS "#define APREQ_COOKIE_SECURE_BIT 13"
Cookie's Secure Bit
.PP
\fBSee also\fP
.RS 4
\fBAPREQ_FLAGS_OFF\fP
.PP
\fBAPREQ_FLAGS_ON\fP
.PP
\fBAPREQ_FLAGS_GET\fP
.PP
\fBAPREQ_FLAGS_SET\fP
.RE
.PP
.SS "#define APREQ_COOKIE_SECURE_MASK 1"
Cookie's Secure Mask
.PP
\fBSee also\fP
.RS 4
\fBAPREQ_FLAGS_OFF\fP
.PP
\fBAPREQ_FLAGS_ON\fP
.PP
\fBAPREQ_FLAGS_GET\fP
.PP
\fBAPREQ_FLAGS_SET\fP
.RE
.PP
.SS "#define APREQ_COOKIE_VERSION_BIT 11"
Cookier Version Bit
.PP
\fBSee also\fP
.RS 4
\fBAPREQ_FLAGS_OFF\fP
.PP
\fBAPREQ_FLAGS_ON\fP
.PP
\fBAPREQ_FLAGS_GET\fP
.PP
\fBAPREQ_FLAGS_SET\fP
.RE
.PP
.SS "#define APREQ_COOKIE_VERSION_MASK 3"
Cookie Version Mask
.PP
\fBSee also\fP
.RS 4
\fBAPREQ_FLAGS_OFF\fP
.PP
\fBAPREQ_FLAGS_ON\fP
.PP
\fBAPREQ_FLAGS_GET\fP
.PP
\fBAPREQ_FLAGS_SET\fP
.RE
.PP
.SS "#define APREQ_DECLARE(d) APR_DECLARE(d)"
The public APREQ functions are declared with \fBAPREQ_DECLARE()\fP, so they may use the most appropriate calling convention\&. Public APR functions with variable arguments must use APR_DECLARE_NONSTD()\&.
.PP
\fBRemarks\fP
.RS 4
Both the declaration and implementations must use the same macro\&. \fBAPREQ_DECLARE(rettype)\fP apeq_func(args)
.RE
.PP
.PP
\fBExamples\fP
.in +1c
\fB/home/jorton/src/asf/apreq\-v2\&.16/include/apreq\&.h\fP\&.
.SS "#define APREQ_DECLARE_DATA"
The public APREQ variables are declared with APREQ_DECLARE_DATA\&. This assures the appropriate indirection is invoked at compile time\&.
.PP
\fBSee also\fP
.RS 4
\fBAPREQ_DECLARE\fP
.PP
\fBAPREQ_DECLARE_NONSTD\fP
.RE
.PP
\fBRemarks\fP
.RS 4
Note that the declaration and implementations use different forms, but both must include the macro\&. extern APREQ_DECLARE_DATA type apr_variable;
.br
APREQ_DECLARE_DATA type apr_variable = value;
.RE
.PP
.SS "#define APREQ_DECLARE_NONSTD(d) APR_DECLARE_NONSTD(d)"
APEQ_DECLARE_NONSTD(rettype) apr_func(args, \&.\&.\&.);
.SS "#define APREQ_DEFAULT_BRIGADE_LIMIT (256 * 1024)"
Maximum number of bytes mod_apreq2 will let accumulate within the heap-buckets in a brigade\&. Excess data will be spooled to an appended file bucket
.PP
\fBSee also\fP
.RS 4
ap_set_brigade_read_limit
.RE
.PP
.SS "#define APREQ_DEFAULT_NELTS 8"
Number of elements in the initial apr_table
.PP
\fBSee also\fP
.RS 4
apr_table_make
.RE
.PP
.SS "#define APREQ_DEFAULT_READ_BLOCK_SIZE (64 * 1024)"
Read chucks of data in 64k blocks from the request
.SS "#define APREQ_DEFAULT_READ_LIMIT (64 * 1024 * 1024)"
Maximum number of bytes mod_apreq2 will send off to libapreq2 for parsing\&. mod_apreq2 will log this event and subsequently remove itself from the filter chain\&.
.br
.PP
\fBSee also\fP
.RS 4
ap_set_read_limit
.br
.RE
.PP
.SS "#define APREQ_FLAGS_GET(f, name) (((f) >> name##_BIT) & name##_MASK)"
Get specified bit f in bitfield name
.SS "#define APREQ_FLAGS_OFF(f, name) ((f) &= ~(name##_MASK << name##_BIT))"
Check to see if specified bit f is off in bitfield name
.SS "#define APREQ_FLAGS_ON(f, name) ((f) |= (name##_MASK << name##_BIT))"
Check to see if specified bit f is on in bitfield name
.SS "#define APREQ_FLAGS_SET(f, name, value)"
\fBValue:\fP
.PP
.nf
((f) = (((f) & ~(name##_MASK << name##_BIT)) \
| ((name##_MASK & (value)) << name##_BIT)))
.fi
Set specified bit f in bitfield name to value Note the below BIT/Mask defines are used sans the _BIT, _MASK because of the this define's ##_MASK, ##_BIT usage\&. Each come in a pair
.SS "#define APREQ_TAINTED_BIT 8"
Tainted Bit
.PP
\fBSee also\fP
.RS 4
\fBAPREQ_FLAGS_OFF\fP
.PP
\fBAPREQ_FLAGS_ON\fP
.PP
\fBAPREQ_FLAGS_GET\fP
.PP
\fBAPREQ_FLAGS_SET\fP
.RE
.PP
.SS "#define APREQ_TAINTED_MASK 1"
Tainted Mask
.PP
\fBSee also\fP
.RS 4
\fBAPREQ_FLAGS_OFF\fP
.PP
\fBAPREQ_FLAGS_ON\fP
.PP
\fBAPREQ_FLAGS_GET\fP
.PP
\fBAPREQ_FLAGS_SET\fP
.RE
.PP
.SH "Enumeration Type Documentation"
.PP
.SS "enum \fBapreq_charset_t\fP"
Character encodings\&.
.PP
\fBExamples\fP
.in +1c
\fB/home/jorton/src/asf/apreq\-v2\&.16/include/apreq\&.h\fP\&.
.SS "enum \fBapreq_expires_t\fP"
Expiration date format
.PP
\fBEnumerator\fP
.in +1c
.TP
\fB\fIAPREQ_EXPIRES_HTTP \fP\fP
Use date formatting consistent with RFC 2616
.TP
\fB\fIAPREQ_EXPIRES_NSCOOKIE \fP\fP
Use format consistent with Netscape's Cookie Spec
.PP
\fBExamples\fP
.in +1c
\fB/home/jorton/src/asf/apreq\-v2\&.16/include/apreq\&.h\fP\&.
.SS "enum \fBapreq_join_t\fP"
Join type
.PP
\fBEnumerator\fP
.in +1c
.TP
\fB\fIAPREQ_JOIN_AS_IS \fP\fP
Join the strings without modification
.TP
\fB\fIAPREQ_JOIN_ENCODE \fP\fP
Url-encode the strings before joining them
.TP
\fB\fIAPREQ_JOIN_DECODE \fP\fP
Url-decode the strings before joining them
.TP
\fB\fIAPREQ_JOIN_QUOTE \fP\fP
Quote the strings, backslashing existing quote marks\&.
.PP
\fBExamples\fP
.in +1c
\fB/home/jorton/src/asf/apreq\-v2\&.16/include/apreq\&.h\fP\&.
.SS "enum \fBapreq_match_t\fP"
Match type
.PP
\fBEnumerator\fP
.in +1c
.TP
\fB\fIAPREQ_MATCH_FULL \fP\fP
Full match only\&.
.TP
\fB\fIAPREQ_MATCH_PARTIAL \fP\fP
Partial matches are ok\&.
.PP
\fBExamples\fP
.in +1c
\fB/home/jorton/src/asf/apreq\-v2\&.16/include/apreq\&.h\fP\&.
.SH "Function Documentation"
.PP
.SS "apr_status_t apreq_initialize (apr_pool_t * pool)"
Initialize libapreq2\&. Applications (except apache modules using mod_apreq) should call this exactly once before they use any libapreq2 modules\&. If you want to modify the list of default parsers with \fBapreq_register_parser()\fP, please use \fBapreq_pre_initialize()\fP and \fBapreq_post_initialize()\fP instead\&.
.PP
\fBParameters\fP
.RS 4
\fIpool\fP a base pool persisting while libapreq2 is used
.RE
.PP
\fBRemarks\fP
.RS 4
after you detroy the pool, you have to call this function again with a new pool if you still plan to use libapreq2
.RE
.PP
.PP
\fBExamples\fP
.in +1c
\fB/home/jorton/src/asf/apreq\-v2\&.16/include/apreq\&.h\fP\&.
.SS "apr_status_t apreq_post_initialize (apr_pool_t * pool)"
Post-initialize libapreq2\&. Applications (except apache modules using mod_apreq2) should this exactly once before they use any libapreq2 modules for parsing\&.
.PP
\fBParameters\fP
.RS 4
\fIpool\fP the same pool that was used in \fBapreq_pre_initialize()\fP\&.
.RE
.PP
.PP
\fBExamples\fP
.in +1c
\fB/home/jorton/src/asf/apreq\-v2\&.16/include/apreq\&.h\fP\&.
.SS "apr_status_t apreq_pre_initialize (apr_pool_t * pool)"
Pre-initialize libapreq2\&. Applications (except apache modules using mod_apreq2) should call this exactly once before they register custom parsers with libapreq2\&. mod_apreq2 does this automatically during the post-config phase, so modules that need call apreq_register_parser should create a post-config hook using APR_HOOK_MIDDLE\&.
.PP
\fBParameters\fP
.RS 4
\fIpool\fP a base pool persisting while libapreq2 is used
.RE
.PP
\fBRemarks\fP
.RS 4
after you detroyed the pool, you have to call this function again with a new pool if you still plan to use libapreq2
.RE
.PP
.PP
\fBExamples\fP
.in +1c
\fB/home/jorton/src/asf/apreq\-v2\&.16/include/apreq\&.h\fP\&.
.SS "static APR_INLINE void apreq_value_table_add (const \fBapreq_value_t\fP * v, apr_table_t * t)\fC [static]\fP"
Adds the specified \fBapreq_value_t\fP to the apr_table_t\&.
.PP
\fBParameters\fP
.RS 4
\fIv\fP value to add
.br
\fIt\fP add v to this table
.RE
.PP
\fBReturns\fP
.RS 4
void
.RE
.PP
@ see apr_table_t
.PP
\fBSee also\fP
.RS 4
apr_value_t
.RE
.PP
.PP
\fBExamples\fP
.in +1c
\fB/home/jorton/src/asf/apreq\-v2\&.16/include/apreq\&.h\fP\&.
.SH "Author"
.PP
Generated automatically by Doxygen for libapreq2 from the source code\&.