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_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

apreq_atoi64f()

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?

apreq_atoi64t()

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?

apreq_brigade_concat()

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.

apreq_brigade_fwrite()

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.

apreq_brigade_spoolfile()

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_divine()

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.

apreq_cp1252_to_utf8()

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.

apreq_decode()

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 successfully decoded value. This function decodes %uXXXX into a utf8 (wide) character, following ECMA-262 (the Javascript spec) Section B.2.1.

apreq_decodev()

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 successfully decoded value. This function decodes %uXXXX into a utf8 (wide) character, following ECMA-262 (the Javascript spec) Section B.2.1.

apreq_encode()

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.

apreq_file_mktemp()

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().

apreq_header_attribute()

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.

apreq_index()

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.

apreq_join()

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

apreq_quote()

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.

apreq_quote_once()

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.