include/apreq_cookie.h(3)

NAME
include/apreq_cookie.h - Cookies and Jars.

SYNOPSIS

#include 'apreq.h'
#include 'apr_time.h'

  Defines
#define APREQ_COOKIE_MAX_LENGTH 4096

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

Define Documentation

  #define APREQ_COOKIE_MAX_LENGTH 4096

Todo
    convert this macro to an apreq_module_t method.

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

Function Documentation

  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.

  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.

  static APR_INLINE unsigned apreq_cookie_is_secure (const apreq_cookie_t * c) [static]

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

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

  static APR_INLINE void apreq_cookie_secure_off (apreq_cookie_t * c) [static]

Turns off the cookie's secure flag.

  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.

  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.

  static APR_INLINE void apreq_cookie_tainted_off (apreq_cookie_t * c) [static]

Turns off the cookie's tainted flag.

  static APR_INLINE void apreq_cookie_tainted_on (apreq_cookie_t * c) [static]

Sets the cookie's tainted flag.

  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.

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

Sets the cookie's protocol version.

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

  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.

Author

Generated automatically by Doxygen for libapreq2 from the source code.