libapreq2-2.08: libapreq2: include/apreq_util.h File Reference

Apache HTTP Server Request Library

- Main Page
- Modules
- Data Structures
- Files
- Related Pages
- Examples

- File List
- Globals

# 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: 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.