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

src/apreq.h File Reference

Common functions, structures and macros. More...

#include "apr_tables.h"
#include "apr_file_io.h"
#include "apr_buckets.h"
#include <stddef.h>

Go to the source code of this file.

Data Structures

struct  apreq_value_t
 libapreq's pre-extensible string type More...

Defines

#define APREQ_DECLARE(d)   APR_DECLARE(d)
#define APREQ_DECLARE_NONSTD(d)   APR_DECLARE_NONSTD(d)
#define APREQ_DECLARE_DATA
#define APREQ_URL_ENCTYPE   "application/x-www-form-urlencoded"
#define APREQ_MFD_ENCTYPE   "multipart/form-data"
#define APREQ_XML_ENCTYPE   "application/xml"
#define APREQ_NELTS   8
#define APREQ_READ_AHEAD   (64 * 1024)
#define APREQ_MAX_BRIGADE_LEN   (256 * 1024)
#define apreq_attr_to_type(T, A, P)   ( (T*) ((char*)(P)-offsetof(T,A)) )
#define apreq_char_to_value(ptr)   apreq_attr_to_type(apreq_value_t, data, ptr)
#define apreq_strtoval(ptr)   apreq_char_to_value(ptr)
#define apreq_strlen(ptr)   (apreq_strtoval(ptr)->size)
#define APREQ_BRIGADE_SETASIDE(bb, p)
#define APREQ_BRIGADE_COPY(d, s)

Typedefs

typedef apreq_value_t apreq_value_t
 libapreq's pre-extensible string type
typedef apreq_value_t *( apreq_value_merge_t )(apr_pool_t *p, const apr_array_header_t *a)
typedef apreq_value_t *( apreq_value_copy_t )(apr_pool_t *p, const apreq_value_t *v)

Enumerations

enum  apreq_join_t { APREQ_JOIN_AS_IS, APREQ_JOIN_ENCODE, APREQ_JOIN_DECODE, APREQ_JOIN_QUOTE }
enum  apreq_match_t { APREQ_MATCH_FULL, APREQ_MATCH_PARTIAL }
enum  apreq_expires_t { APREQ_EXPIRES_HTTP, APREQ_EXPIRES_NSCOOKIE }

Functions

apreq_value_tapreq_make_value (apr_pool_t *p, const char *name, const apr_size_t nlen, const char *val, const apr_size_t vlen)
apreq_value_tapreq_copy_value (apr_pool_t *p, const apreq_value_t *val)
apreq_value_tapreq_merge_values (apr_pool_t *p, const apr_array_header_t *arr)
const char * apreq_enctype (void *env)
const char * apreq_join (apr_pool_t *p, const char *sep, const apr_array_header_t *arr, apreq_join_t mode)
char * apreq_memmem (char *hay, apr_size_t hlen, const char *ndl, apr_size_t nlen, const apreq_match_t type)
apr_ssize_t apreq_index (const char *hay, apr_size_t hlen, const char *ndl, apr_size_t nlen, const apreq_match_t type)
apr_size_t apreq_quote (char *dest, const char *src, const apr_size_t slen)
apr_size_t apreq_quote_once (char *dest, const char *src, const apr_size_t slen)
apr_size_t apreq_encode (char *dest, const char *src, const apr_size_t slen)
apr_ssize_t apreq_decode (char *dest, const char *src, apr_size_t slen)
apr_status_t apreq_decodev (char *d, apr_size_t *dlen, struct iovec *v, int nelts)
char * apreq_escape (apr_pool_t *p, const char *src, const apr_size_t slen)
apr_ssize_t apreq_unescape (char *str)
char * apreq_expires (apr_pool_t *p, const char *time_str, const apreq_expires_t type)
apr_int64_t apreq_atoi64f (const char *s)
apr_int64_t apreq_atoi64t (const char *s)
apr_status_t apreq_brigade_fwrite (apr_file_t *f, apr_off_t *wlen, apr_bucket_brigade *bb)
apr_status_t apreq_file_mktemp (apr_file_t **fp, apr_pool_t *pool, const char *path)
apr_file_tapreq_brigade_spoolfile (apr_bucket_brigade *bb)
apr_status_t apreq_header_attribute (const char *hdr, const char *name, const apr_size_t nlen, const char **val, apr_size_t *vlen)


Detailed Description

Common functions, structures and macros.

The objects in apreq.h are used in various contexts:


Define Documentation

#define APREQ_BRIGADE_COPY d,
 ) 
 

Value:

do { \ apr_bucket *e; \ for (e = APR_BRIGADE_FIRST(s); e != APR_BRIGADE_SENTINEL(s); \ e = APR_BUCKET_NEXT(e)) \ { \ apr_bucket *c; \ apr_bucket_copy(e, &c); \ APR_BRIGADE_INSERT_TAIL(d, c); \ } \ } while (0)
Copy a brigade.
Parameters:
d (destination) Copied buckets are appended to this brigade.
s (source) Brigade to copy from.
Remarks:
s == d produces Undefined Behavior.

#define APREQ_BRIGADE_SETASIDE bb,
 ) 
 

Value:

do { \ apr_bucket *e; \ for (e = APR_BRIGADE_FIRST(bb); e != APR_BRIGADE_SENTINEL(bb); \ e = APR_BUCKET_NEXT(e)) \ { \ apr_bucket_setaside(e, p); \ } \ } while (0)
Set aside all buckets in the brigade.
Parameters:
bb Brigade.
p Setaside buckets into this pool.

#define apreq_char_to_value ptr   )     apreq_attr_to_type(apreq_value_t, data, ptr)
 

Converts (char *) to (apreq_value_t *). The char * is assumed to point at the data attribute of an apreq_value_t struct.

Parameters:
ptr points at the data field of an apreq_value_t struct.

#define APREQ_MAX_BRIGADE_LEN   (256 * 1024)
 

Maximum amount of heap space a brigade may use before switching to file buckets

#define apreq_strlen ptr   )     (apreq_strtoval(ptr)->size)
 

Computes the length of the string, but unlike strlen(), it permits embedded null characters.

Parameters:
ptr points at the data field of an apreq_value_t struct.


Enumeration Type Documentation

enum apreq_expires_t
 

Expiration date format

Enumeration values:
APREQ_EXPIRES_HTTP  Use date formatting consistent with RFC 2616
APREQ_EXPIRES_NSCOOKIE  Use format consistent with Netscape's Cookie Spec

enum apreq_join_t
 

Join type

Enumeration values:
APREQ_JOIN_AS_IS  Join the strings without modification
APREQ_JOIN_ENCODE  Url-encode the strings before joining them
APREQ_JOIN_DECODE  Url-decode the strings before joining them
APREQ_JOIN_QUOTE  Quote the strings, backslashing existing quote marks.

enum apreq_match_t
 

Match type

Enumeration values:
APREQ_MATCH_FULL  Full match only.
APREQ_MATCH_PARTIAL  Partial matches are ok.


Function Documentation

apr_int64_t apreq_atoi64f const char *  s  ) 
 

Converts file sizes (KMG) to bytes

Parameters:
s file size matching m/^+[KMG]b?$/i
Returns:
64-bit integer representation of s.

apr_int64_t apreq_atoi64t const char *  s  ) 
 

Converts time strings (YMDhms) to seconds

Parameters:
s time string matching m/^\+?+[YMDhms]$/
Returns:
64-bit integer representation of s as seconds.

apr_status_t apreq_brigade_fwrite apr_file_t f,
apr_off_t wlen,
apr_bucket_brigade bb
 

Writes brigade to a file.

Parameters:
f File that gets the brigade.
wlen On a successful return, wlen holds the length of the brigade, which is the amount of data written to the file.
bb Bucket brigade.
Remarks:
In the future, this function may do something intelligent with file buckets.

apr_file_t* apreq_brigade_spoolfile apr_bucket_brigade bb  ) 
 

Gets the spoolfile associated to a brigade, if any.

Parameters:
bb Brigade, usually associated to a file upload (apreq_param_t).
Returns:
If the last bucket in the brigade is a file bucket, this function will return its associated file. Otherwise, this function returns NULL.

apreq_value_t* apreq_copy_value apr_pool_t p,
const apreq_value_t val
 

Makes a pool-allocated copy of the value.

Parameters:
p Pool.
val Original value to copy.

apr_ssize_t apreq_decode char *  dest,
const char *  src,
apr_size_t  slen
 

Url-decodes a string.

Parameters:
dest Location of url-encoded result string. Caller must ensure dest is large enough to hold the encoded string and trailing null character.
src Original string.
slen Length of original string.
Returns:
Length of url-decoded string in dest, or < 0 on decoding (bad data) error.

apr_status_t apreq_decodev char *  d,
apr_size_t dlen,
struct iovec *  v,
int  nelts
 

Url-decodes an iovec array.

Parameters:
dest Location of url-encoded result string. Caller must ensure dest is large enough to hold the encoded string and trailing null character.
dlen Resultant length of dest.
v Array of iovecs that represent the source string
nelts Number of iovecs in the array.
Returns:
APR_SUCCESS on success, APR_INCOMPLETE if the iovec ends in the middle of an XX escape sequence, error otherwise.

apr_size_t apreq_encode char *  dest,
const char *  src,
const apr_size_t  slen
 

Url-encodes a string.

Parameters:
dest Location of url-encoded result string. Caller must ensure it is large enough to hold the encoded string and trailing ''.
src Original string.
slen Length of original string.
Returns:
length of url-encoded string in dest.

const char* apreq_enctype void *  env  ) 
 

Fetches the enctype from the environment.

Parameters:
env Environment.

char* apreq_escape apr_pool_t p,
const char *  src,
const apr_size_t  slen
 

Returns an url-encoded copy of a string.

Parameters:
p Pool used to allocate the return value.
src Original string.
slen Length of original string.
Remarks:
Use this function insead of apreq_encode if its caller might otherwise overflow dest.

char* apreq_expires apr_pool_t p,
const char *  time_str,
const apreq_expires_t  type
 

Returns an RFC-822 formatted time string. Similar to ap_gm_timestr_822.

Parameters:
p Pool to allocate return string.
time_str YMDhms time units (from now) until expiry. Understands "now".
type APREQ_EXPIRES_HTTP for RFC822 dates, APREQ_EXPIRES_NSCOOKIE for Netscape cookie dates.
Returns:
Date string, (time_str is offset from "now") formatted according to type.

Deprecated:
Use apr_rfc822_date instead. APREQ_EXPIRES_NSCOOKIE strings are formatted with a '-' (instead of a ' ') character at offsets 7 and 11.

apr_status_t apreq_file_mktemp apr_file_t **  fp,
apr_pool_t pool,
const char *  path
 

Makes a temporary file.

Parameters:
fp Points to the temporary apr_file_t on success.
pool Pool to associate with the temp file. When the pool is destroyed, the temp file will be closed and deleted.
path The base directory which will contain the temp file. If param == NULL, the directory will be selected via tempnam(). See the tempnam manpage for details.
Returns:
APR_SUCCESS on success; error code otherwise.

apr_status_t apreq_header_attribute const char *  hdr,
const char *  name,
const apr_size_t  nlen,
const char **  val,
apr_size_t vlen
 

Search a header string for the value of a particular named attribute.

Parameters:
hdr Header string to scan.
name Name of attribute to search for.
nlen Length of name.
val Location of (first) matching value.
vlen Length of matching value.
Returns:
APR_SUCCESS if found, otherwise APR_NOTFOUND.

apr_ssize_t apreq_index const char *  hay,
apr_size_t  hlen,
const char *  ndl,
apr_size_t  nlen,
const apreq_match_t  type
 

Returns offset of match string's location, or -1 if no match is found.

Parameters:
hay Location of bytes to scan.
hlen Number of bytes available for scanning.
ndl Search string
nlen Length of search string.
type Match type.
Returns:
Offset of match string, or -1 if mo match is found.

const char* apreq_join apr_pool_t p,
const char *  sep,
const apr_array_header_t arr,
apreq_join_t  mode
 

Join an array of values.

Parameters:
p Pool to allocate return value.
sep String that is inserted between the joined values.
arr Array of values.
mode Join type- see apreq_join_t.
Remarks:
Return string can be upgraded to an apreq_value_t with apreq_stroval.

apreq_value_t* apreq_make_value apr_pool_t p,
const char *  name,
const apr_size_t  nlen,
const char *  val,
const apr_size_t  vlen
 

Construcs an apreq_value_t from the name/value info supplied by the arguments.

Parameters:
p Pool for allocating the name and value.
name Name of value.
nlen Length of name.
val Value data.
vlen Length of val.
Returns:
apreq_value_t allocated from pool, with v->data holding a copy of val, v->status = 0, and v->name pointing to a nul-terminated copy of name.

char* apreq_memmem char *  hay,
apr_size_t  hlen,
const char *  ndl,
apr_size_t  nlen,
const apreq_match_t  type
 

Return a pointer to the match string, or NULL if no match is found.

Parameters:
hay Location of bytes to scan.
hlen Number of bytes available for scanning.
ndl Search string
nlen Length of search string.
type Match type.

apreq_value_t* apreq_merge_values apr_pool_t p,
const apr_array_header_t arr
 

Merges an array of values into one.

Parameters:
p Pool from which the new value is generated.
arr Array of apr_value_t *.

apr_size_t apreq_quote char *  dest,
const char *  src,
const apr_size_t  slen
 

Places a quoted copy of src into dest. Embedded quotes are escaped with a backslash ('\').

Parameters:
dest Location of quoted copy. Must be large enough to hold the copy and trailing null byte.
src Original string.
slen Length of original string.
dest Destination string.
Returns:
length of quoted copy in dest.

apr_size_t apreq_quote_once char *  dest,
const char *  src,
const apr_size_t  slen
 

Same as apreq_quote() except when src begins and ends in quote marks. In that case it assumes src is quoted correctly, and just copies src to dest.

Parameters:
dest Location of quoted copy. Must be large enough to hold the copy and trailing null byte.
src Original string.
slen Length of original string.
dest Destination string.
Returns:
length of quoted copy in dest.

apr_ssize_t apreq_unescape char *  str  ) 
 

An in-situ url-decoder.

Parameters:
str The string to decode
Returns:
Length of decoded string, or < 0 on error.
Remarks:
Equivalent to apreq_decode(str,str,strlen(str)).