Apache2
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
apreq_util.h File Reference

Utility functions for apreq. More...

#include "apr_file_io.h"
#include "apr_buckets.h"
#include "apreq.h"
Include dependency graph for apreq_util.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)
 
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_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_tapreq_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

  • string <-> array converters
  • substring search functions
  • simple encoders & decoders for urlencoded strings
  • simple time, date, & file-size converters

Function Documentation

apr_int64_t apreq_atoi64f ( const char *  s)

Converts file sizes (KMG) to bytes

Parameters
sfile 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
stime 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
poolPool for creating a tempfile bucket.
temp_dirDirectory for tempfile creation.
brigade_limitIf out's length would exceed this value, the appended buckets get written to a tempfile.
outResulting brigade.
inBrigade 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.
apr_status_t apreq_brigade_fwrite ( apr_file_t f,
apr_off_t wlen,
apr_bucket_brigade bb 
)

Writes brigade to a file.

Parameters
fFile that gets the brigade.
wlenOn a successful return, wlen holds the length of the brigade, which is the amount of data written to the file.
bbBucket brigade.
Returns
APR_SUCCESS.
Error status code from either an unsuccessful apr_bucket_read(), or a failed apr_file_writev().
Remarks
This function leaks a bucket brigade into bb->p whenever the final bucket in bb is a spool bucket.
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
bbthe 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
srcString to scan.
slenLength 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
destLocation of utf8-encoded result string. Caller must ensure it is large enough to hold the encoded string and trailing '\0'.
srcOriginal string.
slenLength 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
destLocation of url-encoded result string. Caller must ensure dest is large enough to hold the encoded string and trailing null character.
dlenpoints to resultant length of url-decoded string in dest
srcOriginal string.
slenLength 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
destLocation of url-encoded result string. Caller must ensure dest is large enough to hold the encoded string and trailing null character.
dlenResultant length of dest.
vArray of iovecs that represent the source string
neltsNumber 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
destLocation of url-encoded result string. Caller must ensure it is large enough to hold the encoded string and trailing '\0'.
srcOriginal string.
slenLength of original string.
Returns
length of url-encoded string in dest; does not exceed 3 * slen.
apr_status_t apreq_file_mktemp ( apr_file_t **  fp,
apr_pool_t pool,
const char *  path 
)

Makes a temporary file.

Parameters
fpPoints to the temporary apr_file_t on success.
poolPool to associate with the temp file. When the pool is destroyed, the temp file will be closed and deleted.
pathThe 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
hdrHeader string to scan.
nameName of attribute to search for.
nlenLength of name.
valLocation of (first) matching value.
vlenLength 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
hayLocation of bytes to scan.
hlenNumber of bytes available for scanning.
ndlSearch string
nlenLength of search string.
typeMatch 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
pPool to allocate return value.
sepString that is inserted between the joined values.
arrArray of apreq_value_t entries.
modeJoin 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
destLocation of quoted copy. Must be large enough to hold the copy and trailing null byte.
srcOriginal string.
slenLength of original string.
destDestination 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
destLocation of quoted copy. Must be large enough to hold the copy and trailing null byte.
srcOriginal string.
slenLength of original string.
destDestination string.
Returns
length of quoted copy in dest.