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

• 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:

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:

This function leaks a bucket brigade into bb->p whenever the final bucket in bb is a spool bucket.

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.