libapreq2-2.17: include/apreq_cookie.h File Reference

Apache HTTP Server Request Library

Data Structures | Macros | Typedefs | Functions
apreq_cookie.h File Reference
Apache Request Library

Cookies and Jars. More...

`#include "apreq.h"`
`#include "apr_time.h"`

Go to the source code of this file.

## Data Structures
struct | apreq_cookie_t
| Cookie type, supporting both Netscape and RFC cookie specifications. More...

## Macros
#define | APREQ_COOKIE_MAX_LENGTH 4096

## Typedefs
typedef struct apreq_cookie_t | apreq_cookie_t
| Cookie type, supporting both Netscape and RFC cookie specifications.

## Functions
static APR_INLINE apreq_cookie_t * | apreq_value_to_cookie (const char *val)
static APR_INLINE unsigned | apreq_cookie_version (const apreq_cookie_t *c)
static APR_INLINE void | apreq_cookie_version_set (apreq_cookie_t *c, unsigned v)
static APR_INLINE unsigned | apreq_cookie_is_secure (const apreq_cookie_t *c)
static APR_INLINE void | apreq_cookie_secure_on (apreq_cookie_t *c)
static APR_INLINE void | apreq_cookie_secure_off (apreq_cookie_t *c)
static APR_INLINE unsigned | apreq_cookie_is_httponly (const apreq_cookie_t *c)
static APR_INLINE void | apreq_cookie_httponly_on (apreq_cookie_t *c)
static APR_INLINE void | apreq_cookie_httponly_off (apreq_cookie_t *c)
static APR_INLINE unsigned | apreq_cookie_is_tainted (const apreq_cookie_t *c)
static APR_INLINE void | apreq_cookie_tainted_on (apreq_cookie_t *c)
static APR_INLINE void | apreq_cookie_tainted_off (apreq_cookie_t *c)
apr_status_t | apreq_parse_cookie_header (apr_pool_t *pool, apr_table_t *jar, const char *header)
apreq_cookie_t * | apreq_cookie_make (apr_pool_t *pool, const char *name, const apr_size_t nlen, const char *value, const apr_size_t vlen)
char * | apreq_cookie_as_string (const apreq_cookie_t *c, apr_pool_t *p)
int | apreq_cookie_serialize (const apreq_cookie_t *c, char *buf, apr_size_t len)
void | apreq_cookie_expires (apreq_cookie_t *c, const char *time_str)

## Detailed Description

Cookies and Jars.

apreq_cookie.h describes a common server-side API for request (incoming) and response (outgoing) cookies. It aims towards compliance with the standard cookie specifications listed below.

See also
  http://wp.netscape.com/newsref/std/cookie_spec.html
  http://www.ietf.org/rfc/rfc2109.txt
  http://www.ietf.org/rfc/rfc2964.txt
  http://www.ietf.org/rfc/rfc2965.txt

## Macro Definition Documentation

## ◆ APREQ_COOKIE_MAX_LENGTH

#define APREQ_COOKIE_MAX_LENGTH 4096

This macro is deprecated.

Maximum length of a single Set-Cookie(2) header.

## Function Documentation

## ◆ apreq_cookie_as_string()

char* apreq_cookie_as_string | ( | const apreq_cookie_t * | c,
|  | apr_pool_t * | p
| ) |  |

Returns a string that represents the cookie as it would appear in a valid "Set-Cookie*" header.

Parameters

  c | cookie.
  p | pool which allocates the returned string.

Returns
  header string.

## ◆ apreq_cookie_expires()

void apreq_cookie_expires | ( | apreq_cookie_t * | c,
|  | const char * | time_str
| ) |  |

Set the Cookie's expiration date.

Parameters

  c | The cookie.
  time_str | If NULL, the Cookie's expiration date is unset, making it a session cookie. This means no "expires" or "max-age" attribute will appear in the cookie's serialized form. If time_str is not NULL, the expiration date will be reset to the offset (from now) represented by time_str. The time_str should be in a format that apreq_atoi64t() can understand, namely /[+-]?\d+\s*[YMDhms]/.

Remarks
  Now time_str may also be a fixed date; see apr_date_parse_rfc() for admissible formats.

## ◆ apreq_cookie_httponly_off()

static APR_INLINE void apreq_cookie_httponly_off | ( | apreq_cookie_t * | c | ) |
| static

Turns off the cookie's HttpOnly flag.

## ◆ apreq_cookie_httponly_on()

static APR_INLINE void apreq_cookie_httponly_on | ( | apreq_cookie_t * | c | ) |
| static

Sets the cookie's HttpOnly flag, meaning it is not accessible through client-side script in supported browsers.

## ◆ apreq_cookie_is_httponly()

static APR_INLINE unsigned apreq_cookie_is_httponly | ( | const apreq_cookie_t * | c | ) |
| static

Returns
  1 if the HttpOnly flag is set, 0 otherwise.

## ◆ apreq_cookie_is_secure()

static APR_INLINE unsigned apreq_cookie_is_secure | ( | const apreq_cookie_t * | c | ) |
| static

Returns
  1 if the secure flag is set, 0 otherwise.

## ◆ apreq_cookie_is_tainted()

static APR_INLINE unsigned apreq_cookie_is_tainted | ( | const apreq_cookie_t * | c | ) |
| static

Returns
  1 if the taint flag is set, 0 otherwise.

## ◆ apreq_cookie_make()

apreq_cookie_t* apreq_cookie_make | ( | apr_pool_t * | pool,
|  | const char * | name,
|  | const apr_size_t | nlen,
|  | const char * | value,
|  | const apr_size_t | vlen
| ) |  |

Returns a new cookie, made from the argument list.

Parameters

  pool | Pool which allocates the cookie.
  name | The cookie's name.
  nlen | Length of name.
  value | The cookie's value.
  vlen | Length of value.

Returns
  the new cookie

## ◆ apreq_cookie_secure_off()

static APR_INLINE void apreq_cookie_secure_off | ( | apreq_cookie_t * | c | ) |
| static

Turns off the cookie's secure flag.

## ◆ apreq_cookie_secure_on()

static APR_INLINE void apreq_cookie_secure_on | ( | apreq_cookie_t * | c | ) |
| static

Sets the cookie's secure flag, meaning it only comes back over an SSL-encrypted connction.

## ◆ apreq_cookie_serialize()

int apreq_cookie_serialize | ( | const apreq_cookie_t * | c,
|  | char * | buf,
|  | apr_size_t | len
| ) |  |

Same functionality as apreq_cookie_as_string. Stores the string representation in buf, using up to len bytes in buf as storage. The return value has the same semantics as that of apr_snprintf, including the special behavior for a "len = 0" argument.

Parameters

  c | cookie.
  buf | storage location for the result.
  len | size of buf's storage area.

Returns
  size of resulting header string.

## ◆ apreq_cookie_tainted_off()

static APR_INLINE void apreq_cookie_tainted_off | ( | apreq_cookie_t * | c | ) |
| static

Turns off the cookie's tainted flag.

## ◆ apreq_cookie_tainted_on()

static APR_INLINE void apreq_cookie_tainted_on | ( | apreq_cookie_t * | c | ) |
| static

Sets the cookie's tainted flag.

## ◆ apreq_cookie_version()

static APR_INLINE unsigned apreq_cookie_version | ( | const apreq_cookie_t * | c | ) |
| static

Returns
  1 if this is an RFC cookie, 0 if its a Netscape cookie.

## ◆ apreq_cookie_version_set()

static APR_INLINE void apreq_cookie_version_set | ( | apreq_cookie_t * | c,
|  | unsigned | v
| ) |  |
| static

Sets the cookie's protocol version.

## ◆ apreq_parse_cookie_header()

apr_status_t apreq_parse_cookie_header | ( | apr_pool_t * | pool,
|  | apr_table_t * | jar,
|  | const char * | header
| ) |  |

Parse a cookie header and store the cookies in an apr_table_t.

Parameters

  pool | pool which allocates the cookies
  jar | table where parsed cookies are stored
  header | the header value

Returns
  APR_SUCCESS.
  APREQ_ERROR_BADSEQ if an unparsable character sequence appears.
  APREQ_ERROR_MISMATCH if an rfc-cookie attribute appears in a netscape cookie header.
  ::APR_ENOTIMPL if an unrecognized rfc-cookie attribute appears.
  APREQ_ERROR_NOTOKEN if a required token was not present.
  APREQ_ERROR_BADCHAR if an unexpected token was present.

## ◆ apreq_value_to_cookie()

static APR_INLINE apreq_cookie_t* apreq_value_to_cookie | ( | const char * | val | ) |
| static

Upgrades a jar's table values to apreq_cookie_t structs.