Apache HTTP Server Request Library

Functions
apreq_util.h File Reference
Apache Request Library

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

## ◆ 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_copy()

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.

## ◆ 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_move()

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

## ◆ apreq_brigade_setaside()

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

## ◆ 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_escape()

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.

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

## ◆ apreq_unescape()

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.