.TH "src/apreq_env.h" 3 "30 Aug 2004" "Version 2.04-dev" "libapreq2" \" -*- nroff -*-
.ad l
.nh
.SH NAME
src/apreq_env.h \- Logging and environment (module) declarations. 
.SH SYNOPSIS
.br
.PP
\fC#include 'apreq_params.h'\fP
.br
\fC#include 'apreq_cookie.h'\fP
.br
\fC#include <stdarg.h>\fP
.br

.SS "Data Structures"

.in +1c
.ti -1c
.RI "struct \fBapreq_env_t\fP"
.br
.RI "\fIVtable describing the necessary environment functions. \fP"
.in -1c
.SS "Defines"

.in +1c
.ti -1c
.RI "#define \fBAPREQ_LOG_EMERG\fP   0"
.br
.ti -1c
.RI "#define \fBAPREQ_LOG_ALERT\fP   1"
.br
.ti -1c
.RI "#define \fBAPREQ_LOG_CRIT\fP   2"
.br
.ti -1c
.RI "#define \fBAPREQ_LOG_ERR\fP   3"
.br
.ti -1c
.RI "#define \fBAPREQ_LOG_WARNING\fP   4"
.br
.ti -1c
.RI "#define \fBAPREQ_LOG_NOTICE\fP   5"
.br
.ti -1c
.RI "#define \fBAPREQ_LOG_INFO\fP   6"
.br
.ti -1c
.RI "#define \fBAPREQ_LOG_DEBUG\fP   7"
.br
.ti -1c
.RI "#define \fBAPREQ_LOG_LEVELMASK\fP   7"
.br
.ti -1c
.RI "#define \fBAPREQ_LOG_MARK\fP   __FILE__ , __LINE__"
.br
.ti -1c
.RI "#define \fBAPREQ_DEBUG\fP   APREQ_LOG_MARK, APREQ_LOG_DEBUG,"
.br
.ti -1c
.RI "#define \fBAPREQ_WARN\fP   APREQ_LOG_MARK, APREQ_LOG_WARNING,"
.br
.ti -1c
.RI "#define \fBAPREQ_ERROR\fP   APREQ_LOG_MARK, APREQ_LOG_ERR,"
.br
.ti -1c
.RI "#define \fBapreq_env_content_type\fP(env)   apreq_env_header_in(env, 'Content-Type')"
.br
.ti -1c
.RI "#define \fBapreq_env_cookie\fP(env)   apreq_env_header_in(env, 'Cookie')"
.br
.ti -1c
.RI "#define \fBapreq_env_cookie2\fP(env)   apreq_env_header_in(env, 'Cookie2')"
.br
.ti -1c
.RI "#define \fBapreq_env_set_cookie\fP(e, s)   apreq_env_header_out(e,'Set-Cookie',s)"
.br
.ti -1c
.RI "#define \fBapreq_env_set_cookie2\fP(e, s)   apreq_env_header_out(e,'Set-Cookie2',s)"
.br
.ti -1c
.RI "#define \fBAPREQ_ENV_MODULE\fP(pre, name, mmn)"
.br
.ti -1c
.RI "#define \fBapreq_env_name\fP   (apreq_env_module(NULL)->name)"
.br
.ti -1c
.RI "#define \fBapreq_env_magic_number\fP   (apreq_env_module(NULL)->magic_number)"
.br
.in -1c
.SS "Typedefs"

.in +1c
.ti -1c
.RI "typedef \fBapreq_env_t\fP \fBapreq_env_t\fP"
.br
.RI "\fIVtable describing the necessary environment functions. \fP"
.in -1c
.SS "Functions"

.in +1c
.ti -1c
.RI "void \fBapreq_log\fP (const char *file, int line, int level, \fBapr_status_t\fP status, void *env, const char *fmt,...)"
.br
.ti -1c
.RI "\fBapr_pool_t\fP * \fBapreq_env_pool\fP (void *env)"
.br
.ti -1c
.RI "\fBapreq_jar_t\fP * \fBapreq_env_jar\fP (void *env, \fBapreq_jar_t\fP *jar)"
.br
.ti -1c
.RI "\fBapreq_request_t\fP * \fBapreq_env_request\fP (void *env, \fBapreq_request_t\fP *req)"
.br
.ti -1c
.RI "const char * \fBapreq_env_query_string\fP (void *env)"
.br
.ti -1c
.RI "const char * \fBapreq_env_header_in\fP (void *env, const char *name)"
.br
.ti -1c
.RI "\fBapr_status_t\fP \fBapreq_env_header_out\fP (void *env, const char *name, char *val)"
.br
.ti -1c
.RI "\fBapr_status_t\fP \fBapreq_env_read\fP (void *env, \fBapr_read_type_e\fP block, \fBapr_off_t\fP bytes)"
.br
.ti -1c
.RI "const char * \fBapreq_env_temp_dir\fP (void *env, const char *path)"
.br
.ti -1c
.RI "\fBapr_off_t\fP \fBapreq_env_max_body\fP (void *env, \fBapr_off_t\fP bytes)"
.br
.ti -1c
.RI "\fBapr_ssize_t\fP \fBapreq_env_max_brigade\fP (void *env, \fBapr_ssize_t\fP bytes)"
.br
.ti -1c
.RI "const \fBapreq_env_t\fP * \fBapreq_env_module\fP (const \fBapreq_env_t\fP *mod)"
.br
.in -1c
.SH "Detailed Description"
.PP 
Logging and environment (module) declarations. 


.SH "Define Documentation"
.PP 
.SS "#define apreq_env_content_type(env)   apreq_env_header_in(env, 'Content-Type')"
.PP
Fetch the environment's 'Content-Type' header. 
.PP
\fBParameters:\fP
.RS 4
\fIenv\fP The current environment. 
.RE
.PP
\fBReturns:\fP
.RS 4
The value of the Content-Type header, NULL if not found. 
.RE
.PP

.SS "#define apreq_env_cookie(env)   apreq_env_header_in(env, 'Cookie')"
.PP
Fetch the environment's 'Cookie' header. 
.PP
\fBParameters:\fP
.RS 4
\fIenv\fP The current environment. 
.RE
.PP
\fBReturns:\fP
.RS 4
The value of the 'Cookie' header, NULL if not found. 
.RE
.PP

.SS "#define apreq_env_cookie2(env)   apreq_env_header_in(env, 'Cookie2')"
.PP
Fetch the environment's 'Cookie2' header. 
.PP
\fBParameters:\fP
.RS 4
\fIenv\fP The current environment. 
.RE
.PP
\fBReturns:\fP
.RS 4
The value of the 'Cookie2' header, NULL if not found. 
.RE
.PP

.SS "#define apreq_env_magic_number   (apreq_env_module(NULL)->magic_number)"
.PP
The current environment's magic (ie. version) number. 
.SS "#define APREQ_ENV_MODULE(pre, name, mmn)"
.PP
\fBValue:\fP
.PP
.nf
const apreq_env_t pre##_module = { \
  name, mmn, pre##_log, pre##_pool, pre##_jar, pre##_request,               \
  pre##_query_string, pre##_header_in, pre##_header_out, pre##_read,        \
  pre##_temp_dir, pre##_max_body, pre##_max_brigade }
.fi
Convenience macro for defining an environment module by mapping a function prefix to an associated environment structure. 
.PP
\fBParameters:\fP
.RS 4
\fIpre\fP Prefix to define new environment. All attributes of the \fBapreq_env_t\fP struct are defined with this as their prefix. The generated struct is named by appending '_module' to the prefix. 
.br
\fIname\fP Name of this environment. 
.br
\fImmn\fP Magic number (i.e. version number) of this environment. 
.RE
.PP

.SS "#define apreq_env_name   (apreq_env_module(NULL)->name)"
.PP
The current environment's name. 
.SS "#define apreq_env_set_cookie(e, s)   apreq_env_header_out(e,'Set-Cookie',s)"
.PP
Add a 'Set-Cookie' header to the outgoing response headers. 
.PP
\fBParameters:\fP
.RS 4
\fIe\fP The current environment. 
.br
\fIs\fP The cookie string. 
.RE
.PP
\fBReturns:\fP
.RS 4
APR_SUCCESS on success, error code otherwise. 
.RE
.PP

.SS "#define apreq_env_set_cookie2(e, s)   apreq_env_header_out(e,'Set-Cookie2',s)"
.PP
Add a 'Set-Cookie2' header to the outgoing response headers. 
.PP
\fBParameters:\fP
.RS 4
\fIe\fP The current environment. 
.br
\fIs\fP The cookie string. 
.RE
.PP
\fBReturns:\fP
.RS 4
APR_SUCCESS on success, error code otherwise. 
.RE
.PP

.SH "Typedef Documentation"
.PP 
.SS "typedef struct \fBapreq_env_t\fP  \fBapreq_env_t\fP"
.PP
Vtable describing the necessary environment functions. 
.PP
This must be fully defined for libapreq2 to operate properly in a given environment. Normally it is set once, with an \fBapreq_env_module()\fP call during process initialization, and should remain fixed thereafter. 
.SH "Function Documentation"
.PP 
.SS "const char* apreq_env_header_in (void * env, const char * name)"
.PP
Fetch the header value (joined by ', ' if there are multiple headers) for a given header name. 
.PP
\fBParameters:\fP
.RS 4
\fIenv\fP The current environment. 
.br
\fIname\fP The header name. 
.RE
.PP
\fBReturns:\fP
.RS 4
The value of the header, NULL if not found. 
.RE
.PP

.SS "\fBapr_status_t\fP apreq_env_header_out (void * env, const char * name, char * val)"
.PP
Add a header field to the environment's outgoing response headers 
.PP
\fBParameters:\fP
.RS 4
\fIenv\fP The current environment. 
.br
\fIname\fP The name of the outgoing header. 
.br
\fIval\fP Value of the outgoing header. 
.RE
.PP
\fBReturns:\fP
.RS 4
APR_SUCCESS on success, error code otherwise. 
.RE
.PP

.SS "\fBapreq_jar_t\fP* apreq_env_jar (void * env, \fBapreq_jar_t\fP * jar)"
.PP
Get/set the jar currently associated to the environment. 
.PP
\fBParameters:\fP
.RS 4
\fIenv\fP The current environment. 
.br
\fIjar\fP New Jar to associate. 
.RE
.PP
\fBReturns:\fP
.RS 4
The previous jar associated to the environment. jar == NULL gets the current jar, which will remain associated after the call. 
.RE
.PP

.SS "\fBapr_off_t\fP apreq_env_max_body (void * env, \fBapr_off_t\fP bytes)"
.PP
Get/set the current max_body setting. This is the maximum amount of bytes that will be read into the environment's parser. 
.PP
\fBParameters:\fP
.RS 4
\fIenv\fP The current environment. 
.br
\fIbytes\fP The new max_body setting. 
.RE
.PP
\fBReturns:\fP
.RS 4
The previous max_body setting. Note: a call using bytes == -1 fetches the current max_body setting without modifying it. 
.RE
.PP

.SS "\fBapr_ssize_t\fP apreq_env_max_brigade (void * env, \fBapr_ssize_t\fP bytes)"
.PP
Get/set the current max_brigade setting. This is the maximum amount of heap-allocated buckets libapreq2 will use for its brigades. If additional buckets are necessary, they will be created from a temporary file. 
.PP
\fBParameters:\fP
.RS 4
\fIenv\fP The current environment. 
.br
\fIbytes\fP The new max_brigade setting. 
.RE
.PP
\fBReturns:\fP
.RS 4
The previous max_brigade setting. Note: a call using bytes == -1 fetches the current max_brigade setting without modifying it. 
.RE
.PP

.SS "const \fBapreq_env_t\fP* apreq_env_module (const \fBapreq_env_t\fP * mod)"
.PP
Get/set function for the active environment stucture. Usually this is called only once per process, to define the correct environment. 
.PP
\fBParameters:\fP
.RS 4
\fImod\fP The new active environment. 
.RE
.PP
\fBReturns:\fP
.RS 4
The previous active environment. Note: a call using mod == NULL fetches the current environment module without modifying it. 
.RE
.PP

.SS "\fBapr_pool_t\fP* apreq_env_pool (void * env)"
.PP
Pool associated with the environment. 
.PP
\fBParameters:\fP
.RS 4
\fIenv\fP The current environment 
.RE
.PP
\fBReturns:\fP
.RS 4
The associated pool. 
.RE
.PP

.SS "const char* apreq_env_query_string (void * env)"
.PP
Fetch the query string. 
.PP
\fBParameters:\fP
.RS 4
\fIenv\fP The current environment. 
.RE
.PP
\fBReturns:\fP
.RS 4
The query string. 
.RE
.PP

.SS "\fBapr_status_t\fP apreq_env_read (void * env, \fBapr_read_type_e\fP block, \fBapr_off_t\fP bytes)"
.PP
Read data from the environment and into the current active parser. 
.PP
\fBParameters:\fP
.RS 4
\fIenv\fP The current environment. 
.br
\fIblock\fP Read type (APR_READ_BLOCK or APR_READ_NONBLOCK). 
.br
\fIbytes\fP Maximum number of bytes to read. 
.RE
.PP
\fBReturns:\fP
.RS 4
APR_INCOMPLETE if there's more data to read, APR_SUCCESS if everything was read & parsed successfully, error code otherwise. 
.RE
.PP

.SS "\fBapreq_request_t\fP* apreq_env_request (void * env, \fBapreq_request_t\fP * req)"
.PP
Get/set the request currently associated to the environment. 
.PP
\fBParameters:\fP
.RS 4
\fIenv\fP The current environment. 
.br
\fIreq\fP New request to associate. 
.RE
.PP
\fBReturns:\fP
.RS 4
The previous request associated to the environment. req == NULL gets the current request, which will remain associated after the call. 
.RE
.PP

.SS "const char* apreq_env_temp_dir (void * env, const char * path)"
.PP
Get/set the current temporary directory. 
.PP
\fBParameters:\fP
.RS 4
\fIenv\fP The current environment. 
.br
\fIpath\fP The full pathname of the new directory. 
.RE
.PP
\fBReturns:\fP
.RS 4
The path of the previous temporary directory. Note: a call using path==NULL fetches the current directory without resetting it to NULL. 
.RE
.PP

.SS "void apreq_log (const char * file, int line, int level, \fBapr_status_t\fP status, void * env, const char * fmt,  ...)"
.PP
Analog of Apache's ap_log_rerror(). 
.PP
\fBParameters:\fP
.RS 4
\fIfile\fP Filename to list in the log message. 
.br
\fIline\fP Line number from the file. 
.br
\fIlevel\fP Log level. 
.br
\fIstatus\fP Status code. 
.br
\fIenv\fP Current environment. 
.br
\fIfmt\fP Format string for the log message. 
.RE
.PP

.SH "Author"
.PP 
Generated automatically by Doxygen for libapreq2 from the source code.