Apache Software Foundation > HTTP Server Project > Request Library Subproject

Apache HTTP Server Request Library

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

apreq_util.h File Reference

Utility functions for apreq. More...

#include "apr_file_io.h"
#include "apr_buckets.h"
#include "apreq.h"

Go to the source code of this file.

Functions

char * apreq_join (apr_pool_t *p, const char *sep, const apr_array_header_t *arr, apreq_join_t mode)
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_size_t apreq_cp1252_to_utf8 (char *dest, const char *src, apr_size_t slen)
apreq_charset_t apreq_charset_divine (const char *src, apr_size_t slen)
apr_status_t apreq_decode (char *dest, apr_size_t *dlen, const char *src, apr_size_t slen)
apr_status_t apreq_decodev (char *dest, apr_size_t *dlen, struct iovec *v, int nelts)
static APR_INLINE char * apreq_escape (apr_pool_t *p, const char *src, const apr_size_t slen)
static APR_INLINE apr_ssize_t apreq_unescape (char *str)
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)
static APR_INLINE apr_status_t apreq_brigade_setaside (apr_bucket_brigade *bb, apr_pool_t *p)
static APR_INLINE apr_status_t apreq_brigade_copy (apr_bucket_brigade *d, apr_bucket_brigade *s)
static APR_INLINE void apreq_brigade_move (apr_bucket_brigade *d, apr_bucket_brigade *s, apr_bucket *e)
apr_status_t apreq_header_attribute (const char *hdr, const char *name, const apr_size_t nlen, const char **val, apr_size_t *vlen)
apr_status_t apreq_brigade_concat (apr_pool_t *pool, const char *temp_dir, apr_size_t brigade_limit, apr_bucket_brigade *out, apr_bucket_brigade *in)
apr_file_t * apreq_brigade_spoolfile (apr_bucket_brigade *bb)

Detailed Description

Utility functions for apreq.

This header contains useful functions for creating new parsers, hooks or modules. It includes

Function Documentation

apr_int64_t apreq_atoi64f (  const char *  s  ) 
 

Converts file sizes (KMG) to bytes

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

Todo:
What happens when s is malformed? Should this return an unsigned value instead?

apr_int64_t apreq_atoi64t (  const char *  s  ) 
 

Converts time strings (YMDhms) to seconds

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

Todo:
What happens when s is malformed? Should this return an unsigned value instead?

apr_status_t apreq_brigade_concat (  apr_pool_t *  pool,
const char *  temp_dir,
apr_size_t  brigade_limit,
apr_bucket_brigade *  out,
apr_bucket_brigade *  in
) 
 

Concatenates the brigades, spooling large brigades into a tempfile (APREQ_SPOOL) bucket.

Parameters:
pool Pool for creating a tempfile bucket.
temp_dir Directory for tempfile creation.
brigade_limit If out's length would exceed this value, the appended buckets get written to a tempfile.
out Resulting brigade.
in Brigade to append.
Returns:
APR_SUCCESS.

Error status code resulting from either apr_brigade_length(), apreq_file_mktemp(), apreq_brigade_fwrite(), or apr_file_seek().

Todo:
Flesh out these error codes, making them as explicit as possible.

static APR_INLINE apr_status_t apreq_brigade_copy (  apr_bucket_brigade *  d,
apr_bucket_brigade *  s
)  [static]
 

Copy a brigade.

Parameters:
d (destination) Copied buckets are appended to this brigade.
s (source) Brigade to copy from.
Returns:
APR_SUCCESS.

Error status code from an unsuccessful apr_bucket_copy().

Remarks:
s == d produces Undefined Behavior.

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.
Returns:
APR_SUCCESS.

Error status code from either an unsuccessful apr_bucket_read(), or a failed apr_file_writev().

Remarks:
In the future, this function may do something intelligent with file buckets.

static APR_INLINE void apreq_brigade_move (  apr_bucket_brigade *  d,
apr_bucket_brigade *  s,
apr_bucket *  e
)  [static]
 

Move the front of a brigade.

Parameters:
d (destination) Append buckets to this brigade.
s (source) Brigade to take buckets from.
e First bucket of s after the move. All buckets before e are appended to d.
Remarks:
This moves all buckets when e == APR_BRIGADE_SENTINEL(s).

static APR_INLINE apr_status_t apreq_brigade_setaside (  apr_bucket_brigade *  bb,
apr_pool_t *  p
)  [static]
 

Set aside all buckets in the brigade.

Parameters:
bb Brigade.
p Setaside buckets into this pool.
Returns:
APR_SUCCESS.

Error status code from an unsuccessful apr_bucket_setaside().

apr_file_t* apreq_brigade_spoolfile (  apr_bucket_brigade *  bb  ) 
 

Determines the spool file used by the brigade. Returns NULL if the brigade is not spooled in a file (does not use an APREQ_SPOOL bucket).

Parameters:
bb the bucket brigade
Returns:
the spool file, or NULL.

apreq_charset_t apreq_charset_divine (  const char *  src,
apr_size_t  slen
) 
 

Heuristically determine the charset of a string.

Parameters:
src String to scan.
slen Length of string.
Returns:
APREQ_CHARSET_ASCII if the string contains only 7-bit chars;

APREQ_CHARSET_UTF8 if the string is a valid utf8 byte sequence;

APREQ_CHARSET_LATIN1 if the string has no control chars;

APREQ_CHARSET_CP1252 if the string has control chars.

apr_size_t apreq_cp1252_to_utf8 (  char *  dest,
const char *  src,
apr_size_t  slen
) 
 

Convert a string from cp1252 to utf8. Caller must ensure it is large enough to hold the encoded string and trailing '\0'.

Parameters:
dest Location of utf8-encoded result string. Caller must ensure it is large enough to hold the encoded string and trailing '\0'.
src Original string.
slen Length of original string.
Returns:
length of utf8-encoded string in dest; does not exceed 3 * slen.

apr_status_t apreq_decode (  char *  dest,
apr_size_t *  dlen,
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.
dlen points to resultant length of url-decoded string in dest
src Original string.
slen Length of original string.
Returns:
APR_SUCCESS.

APR_INCOMPLETE if the string ends in the middle of an escape sequence.

APREQ_ERROR_BADSEQ or APREQ_ERROR_BADCHAR on malformed input.

Remarks:
In the non-success case, dlen will be set to include the last succesfully decoded value. This function decodes %uXXXX into a utf8 (wide) character, following ECMA-262 (the Javascript spec) Section B.2.1.

apr_status_t apreq_decodev (  char *  dest,
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.

APR_INCOMPLETE if the iovec ends in the middle of an escape sequence.

APREQ_ERROR_BADSEQ or APREQ_ERROR_BADCHAR on malformed input.

Remarks:
In the non-APR_SUCCESS case, dlen will be set to include the last succesfully decoded value. This function decodes %uXXXX into a utf8 (wide) character, following ECMA-262 (the Javascript spec) Section B.2.1.

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 '\0'.
src Original string.
slen Length of original string.
Returns:
length of url-encoded string in dest; does not exceed 3 * slen.

static APR_INLINE char* apreq_escape (  apr_pool_t *  p,
const char *  src,
const apr_size_t  slen
)  [static]
 

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.
Returns:
The url-encoded string.
Remarks:
Use this function insead of apreq_encode if its caller might otherwise overflow dest.

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.

Error status code from unsuccessful apr_filepath_merge(), or a failed apr_file_mktemp().

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.

APREQ_ERROR_NOATTR if the attribute is not found.

APREQ_ERROR_BADSEQ if an unpaired quote mark was detected.

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 no match is found.

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. The result is an empty string if there are no values.

Parameters:
p Pool to allocate return value.
sep String that is inserted between the joined values.
arr Array of apreq_value_t entries.
mode Join type- see apreq_join_t.
Returns:
Joined string, or NULL on error

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.

static APR_INLINE apr_ssize_t apreq_unescape (  char *  str  )  [static]
 

An in-situ url-decoder.

Parameters:
str The string to decode
Returns:
Length of decoded string, or < 0 on error.