3 The owa_cookie Package

The owa_cookie package contains subprograms that send and retrieve HTTP cookies from the client's browser. Cookies are opaque strings sent to the browser to maintain state between HTTP calls. State can be maintained throughout the client's sessions, or longer if an expiration date is included. Your system date is calculated with reference to the information specified in the owa_custom package.

3.1 Summary

owa_cookie.cookie data type - data type to contain cookie name-value pairs.

owa_cookie.get function - gets the value of the specified cookie.

owa_cookie.get_all procedure - gets all cookie name-value pairs.

owa_cookie.remove procedure - removes the specified cookie.

owa_cookie.send procedure - generates a "Set-Cookie" line in the HTTP header.

Note:

All HTTP headers must be in English. If the headers are generated from the database, verify they are created in the English language.

3.2 owa_cookie.cookie data type

Since the HTTP standard allows cookie names to be overloaded (that is, multiple values can be associated with the same cookie name), this is a PL/SQL RECORD holding all values associated with a given cookie name.

Type vc_arr is table of varchar2(4000) index by binary_integer.

Table 3-1 describes the properties of the owa_cookie.cookie data type.

Table 3-1 owa_cookie.cookie data type

Properties	Definitions
Syntax:	type cookie is RECORD ( name varchar2(4000), vals vc_arr, num_vals integer);
Returns:	Not applicable.

3.3 owa_cookie.get function

This function returns the values associated with the specified cookie. The values are returned in a owa_cookie.cookie data type.

Table 3-2 describes the properties of the owa_cookie.get function.

Table 3-2 owa_cookie.get function

Properties	Definitions
Syntax:	owa_cookie.get(name in varchar2) return cookie;
Parameter:	name - the name of the cookie.
Returns:	An owa_cookie.cookie data type.

3.4 owa_cookie.get_all procedure

This procedure returns all cookie names and their values from the client's browser. The values appear in the order in which they were sent from the browser.

Table 3-3 describes the properties of the owa_cookie.get_all procedure.

Table 3-3 owa_cookie.get_all procedures

Properties	Definitions
Syntax:	owa_cookie.get_all( names out vc_arr, vals out vc_arr, num_vals out integer);
Parameters:	names - the names of the cookies. vals - the values of the cookies. num_vals - the number of cookie-value pairs.
Generates:	Arrays of the names and values in the order received, and the count of the combinations.

Properties

Definitions

Syntax:

owa_cookie.get_all(
   names          out      vc_arr,
   vals           out      vc_arr,
   num_vals       out      integer);

Parameters:

names - the names of the cookies.

vals - the values of the cookies.

num_vals - the number of cookie-value pairs.

Generates:

Arrays of the names and values in the order received, and the count of the combinations.

3.5 owa_cookie.remove procedure

This procedure forces a cookie to expire immediately by setting the "expires" field of a Set-Cookie line in the HTTP header to "01-Jan-1990". This procedure must be called within the context of an HTTP header.

Table 3-4 describes the properties of the owa_cookie.remove procedure.

Table 3-4 owa_cookie.remove procedure

Properties	Definitions
Syntax:	owa_cookie.remove( name in varchar2, val in varchar2, path in varchar2 DEFAULT NULL);
Parameters:	name - the name of the cookie to expire. value - the value of the cookie. path - currently unused.
Generates:	Set-Cookie: <name>=<value> expires=01-JAN-1990

Properties

Definitions

Syntax:

owa_cookie.remove(
   name           in       varchar2,
   val            in       varchar2,
   path           in       varchar2   DEFAULT NULL);

Parameters:

name - the name of the cookie to expire.

value - the value of the cookie.

path - currently unused.

Generates:

Set-Cookie: <name>=<value> expires=01-JAN-1990

3.6 owa_cookie.send procedure

This procedure generates a Set-Cookie line, which transmits a cookie to the client. This procedure must occur in the context of an HTTP header.

Table 3-5 describes the properties of the owa_cookie.send procedure.

Table 3-5 owa_cookie.send procedure

Properties	Definitions
Syntax	owa_cookie.send( name in varchar2, value in varchar2, expires in date DEFAULT NULL, path in varchar2 DEFAULT NULL, domain in varchar2 DEFAULT NULL, secure in varchar2 DEFAULT NULL), httponly in varchar2 DEFAULT NULL),
Parameters:	name -the name of the cookie. value - the value of the cookie. expires - the date at which the cookie will expire. path - the value for the path field. domain - the value for the domain field. secure - if the value of this parameter is not NULL, the "secure" field is added to the line. httponly - if the value of this parameter is not NULL, the "HttpOnly" field is added to the line.
Generates:	Set-Cookie: <name>=<value> expires=<expires> path=<path> domain=<domain> secure HttpOnly

Properties

Definitions

Syntax

owa_cookie.send(
   name           in       varchar2,
   value          in       varchar2,
   expires        in       date       DEFAULT NULL,
   path           in       varchar2   DEFAULT NULL,
   domain         in       varchar2   DEFAULT NULL,
   secure         in       varchar2   DEFAULT NULL),
   httponly       in       varchar2   DEFAULT NULL),

Parameters:

name -the name of the cookie.

value - the value of the cookie.

expires - the date at which the cookie will expire.

path - the value for the path field.

domain - the value for the domain field.

secure - if the value of this parameter is not NULL, the "secure" field is added to the line.

httponly - if the value of this parameter is not NULL, the "HttpOnly" field is added to the line.

Generates:

Set-Cookie: <name>=<value> expires=<expires> path=<path> domain=<domain> secure HttpOnly

Note:

For more information about HTTP-only, see the section on Mitigating Cross-site Scripting With HTTP-only Cookies, in http://msdn.microsoft.com/en-us/default.aspx.