.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\&.