Main Page | Modules | Data Structures | File List | Data Fields | Globals | Related Pages

src/apreq_cookie.h File Reference

Cookies and Jars. More...

#include "apreq.h"
#include "apr_tables.h"

Go to the source code of this file.

Data Structures

struct  apreq_jar_t
 This is the container class for libapreq cookies. More...
struct  apreq_cookie_t
 Cookie type, supporting both Netscape and RFC cookie specifications. More...

Defines

#define APREQ_COOKIE_VERSION_DEFAULT   APREQ_COOKIE_VERSION_NETSCAPE
#define APREQ_COOKIE_MAX_LENGTH   4096
#define apreq_value_to_cookie(ptr)
#define apreq_cookie_name(c)   ((c)->v.name)
#define apreq_cookie_value(c)   ((c)->v.data)
#define apreq_jar_items(j)   apr_table_elts(j->cookies)->nelts
#define apreq_jar_nelts(j)   apr_table_elts(j->cookies)->nelts
#define apreq_add_cookie(j, c)   apreq_jar_add(j,c)
#define apreq_make_cookie(p, n, nl, v, vl)   apreq_cookie_make(p,n,nl,v,vl)
#define apreq_serialize_cookie(buf, len, c)   apreq_cookie_serialize(c,buf,len)

Typedefs

typedef apreq_jar_t apreq_jar_t
 This is the container class for libapreq cookies.
typedef apreq_cookie_t apreq_cookie_t
 Cookie type, supporting both Netscape and RFC cookie specifications.

Enumerations

enum  apreq_cookie_version_t { APREQ_COOKIE_VERSION_NETSCAPE, APREQ_COOKIE_VERSION_RFC }

Functions

apreq_cookie_tapreq_cookie (const apreq_jar_t *jar, const char *name)
void apreq_jar_add (apreq_jar_t *jar, const apreq_cookie_t *c)
apreq_jar_tapreq_jar (void *env, const char *hdr)
apreq_cookie_tapreq_cookie_make (apr_pool_t *pool, const char *name, const apr_size_t nlen, const char *value, const apr_size_t vlen)
apr_status_t apreq_cookie_attr (apr_pool_t *p, apreq_cookie_t *c, const char *attr, apr_size_t alen, const char *val, 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)
apr_status_t apreq_cookie_bake (const apreq_cookie_t *c, void *env)
apr_status_t apreq_cookie_bake2 (const apreq_cookie_t *c, void *env)
apreq_cookie_version_t apreq_ua_cookie_version (void *env)


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
 

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

#define APREQ_COOKIE_VERSION_DEFAULT   APREQ_COOKIE_VERSION_NETSCAPE
 

Default version, used when creating a new cookie. See apreq_cookie_make().

#define apreq_value_to_cookie ptr   ) 
 

Value:

apreq_attr_to_type(apreq_cookie_t, \ v, ptr)


Enumeration Type Documentation

enum apreq_cookie_version_t
 

Cookie Version. libapreq does not distinguish between rfc2109 and its successor rfc2965; both are referred to as APREQ_COOKIE_VERSION_RFC. Users can distinguish between them in their outgoing cookies by using apreq_cookie_bake() for sending rfc2109 cookies, or apreq_cookie_bake2() for rfc2965. The original Netscape cookie spec is still preferred for its greater portability, it is named APREQ_COOKIE_VERSION_NETSCAPE.


Function Documentation

apreq_cookie_t* apreq_cookie const apreq_jar_t jar,
const char *  name
 

Fetches a cookie from the jar

Parameters:
jar The cookie jar.
name The name of the desired cookie.

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 The cookie.
p The pool.

apr_status_t apreq_cookie_attr apr_pool_t p,
apreq_cookie_t c,
const char *  attr,
apr_size_t  alen,
const char *  val,
apr_size_t  vlen
 

Sets the associated cookie attribute.

Parameters:
p Pool for allocating the new attribute.
c Cookie.
attr Name of attribute- leading '-' or '$' characters are ignored.
alen Length of attr.
val Value of new attribute.
vlen Length of new attribute.
Remarks:
Ensures cookie version & time are kept in sync.

apr_status_t apreq_cookie_bake const apreq_cookie_t c,
void *  env
 

Add the cookie to the outgoing "Set-Cookie" headers.

Parameters:
c The cookie.
env Environment.

apr_status_t apreq_cookie_bake2 const apreq_cookie_t c,
void *  env
 

Add the cookie to the outgoing "Set-Cookie2" headers.

Parameters:
c The cookie.
env Environment.

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 /[+-]?+*[YMDhms]/.

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.

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 The cookie.
buf Storage location for the result.
len Size of buf's storage area.

apreq_jar_t* apreq_jar void *  env,
const char *  hdr
 

Parse the incoming "Cookie:" headers into a cookie jar.

Parameters:
env The current environment.
hdr String to parse as a HTTP-merged "Cookie" header.
Remarks:
"data = NULL" has special behavior. In this case, apreq_jar(env,NULL) will attempt to fetch a cached object from the environment via apreq_env_jar. Failing that, it will replace "hdr" with the result of apreq_env_cookie(env), parse that, and store the resulting object back within the environment. This maneuver is designed to mimimize parsing work, since generating the cookie jar is relatively expensive.

void apreq_jar_add apreq_jar_t jar,
const apreq_cookie_t c
 

Adds a cookie by pushing it to the bottom of the jar.

Parameters:
jar The cookie jar.
c The cookie to add.

apreq_cookie_version_t apreq_ua_cookie_version void *  env  ) 
 

Looks for the presence of a "Cookie2" header to determine whether or not the current User-Agent supports rfc2965.

Parameters:
env The current environment.
Returns:
APREQ_COOKIE_VERSION_RFC if rfc2965 is supported, APREQ_COOKIE_VERSION_NETSCAPE otherwise.