htmlCookie

htmlCookie
Persistent cookie class

Description

htmlCookie provides automated access for sending and receiving persistent HTTP cookies to and from web browsers. Cookies are a general mechanism which server applications can use to store and retrieve information from web browsers. Cookies greatly extend the capabilities of html++ applications.

A server, when transmitting a page to a browser, may optionally send a user-defined value, called a cookie, that represents state information which the browser will store. Included in the cookie is a description of the range of URL's for which that state is valid, and a date after which the browser may delete the cookie. The browser will send the cookie back to the server for any future page requests within the range of specified URL's.

The htmlServer class includes an htmlCookie object as a member variable.

For additional details, refer to Persistent Cookies in the Tutorial section of the User's Guide.

Declaration

#include <dcmicro/htmlpp/cookie.h>

Hierarchy

See Also

htmlServer, Julian

Related Constants/Definitions

None.

Constructors

htmlCookie()

Constructs an empty cookie object.

htmlCookie( const String& name, const String& value )

Constructs a cookie object, adding the user-defined name and associated value. Unless an expiration date is specified via the Expires() method, the cookie will expire when the user shuts down the browser.

htmlCookie( const String& name,

   const String& value,

   const String& expires,

   const String& path,

   const String& domain )

Constructs a cookie object, adding the specified name and associated value. expires represents the RFC822-formatted date (see Expires() method below) that the cookie will be discarded by the browser. If specified, path instructs the browser to return the cookie only when a URL containing path is requested. domain specifies the domain for which the cookie will be returned.

htmlCookie( const htmlCookie& rhs )

Copy constructor.

Destructors

virtual ~htmlCookie()

Destroys the object.

Member Methods

Domain htmlCookie& Domain( const String& domain )

Sets the host or domain name for which the cookie is valid to domain, instructing the browser to return the cookie only when communicating with the specified host or domain. domain should contain at least two periods (e.g., ".yourdomain.com") to avoid partial matches with other cookies that might be stored in the browser. The default value is the host name of the server which sent the cookie.

Domain String Domain() const

Returns the host or domain name specified for the cookie, or an empty string if not set.

Path    htmlCookie& Path( const String& path )

If specified, Path() will instruct the browser to return the cookie only if the browser requests a URL of at least path.If no path is specified, most browsers automatically use the same path as that of the original URL request. If you want your cookie to be valid for all pages in the domain, specifiy a path of "/".

Note that there is a bug in Netscape Navigator version 1.1 and earlier. Only cookies whose path attribute is set explicitly to "/" will be properly saved between sessions if they have an expires attribute.

Path    String Path() const

Returns the path specified for the cookie, or an empty string if not set.

Expires htmlCookie& Expires( const String& expires )

Sets the date and time the cookie will expire, in relation to Greenwich Mean Time (GMT), to expires. If no value is specified, the browser will discard the cookie when the user session ends (i.e., the user exits the browser). The expires date should be formatted according to RFC 822, of the form:

Weekday, dd-Mon-yyyy hh:mm:ss GMT

If a number, positive or negative, is specified in expires instead of an RFC 822-formatted string, html++ will interpret the value as an offset in days from the current date (e.g., Expires( "+365" ) ). In such cases, html++ will assume a time of 12pm GMT. This makes it particularly easy to create various future or past expiration dates without complicated date arithmetic.

You may find the Julian date class, and the Julian::RFC822() method, useful for manipulating dates and performing more complex date operations.

Note that there is a bug in Netscape Navigator version 1.1 and earlier. Only cookies whose path attribute is set explicitly to "/" will be properly saved between sessions if they have an expires attribute.

Expires String Expires() const

Returns the expiration date of the cookie as a string, or an empty string if not set.

Secure htmlCookie& Secure( Boolean enable = TRUE )

If enable is TRUE, the cookie will only be transmitted by the browser if using a secure SSL connection.

IsSecure Boolean IsSecure() const

Returns TRUE if the cookie is marked secure, FALSE if not.

<<    friend ostream& operator<< ( ostream& os, const htmlCookie& cookie )

Streaming output.

Print    virtual void Print( ostream& os ) const

Outputs the object to os.

Example Use

#include <stdio.h>

#include <stdlib.h>

#include <dcmicro/htmlpp/htmlpp.h>

#define COOKIENAME   "visitorid"

int main( void )

{

   htmlCgi   server( cin ) ;

   htmlPage  page( "html++ example application" ) ;

   long      visitor_id ;

   if ( server.Cookie().Exists( COOKIENAME ) )

   {

      //  retrieve cookie that was passed from the browser

      visitor_id = server.Cookie().Value( COOKIENAME ).AsLong() ;

      page << "Recognized visitor number "

           << visitor_id << htmlBreak() ;

   }

   else

   {

      //  Create a new cookie for the page

      htmlCookie   cookie ;

      cookie.Domain( ".yourdomain.com" )

            .Path( "/" )      //  root path for the domain

            .Expires( +30 ) ; //  expires in 30 days

      // Create your own number here

      visitor_id = 69 ;

      //  Set the cookie value, and store it in the

      //  browser. Note that the cookie can be inserted

      //  in the server object at any time prior to final

      //  output, and that multiple values may be stored

      //  in the cookie as well.

      cookie.Value( COOKIENAME, visitor_id ) ;

      server << cookie ;

      page << "NEW visitor number "

           << visitor_id << htmlBreak() ;

   }

   server << page ;

   return 0 ;

}

Program Output (first run)

Content-Type: text/html

Set-Cookie: visitorid=69; expires=Wednesday, 31-Dec-1997 12:00:00 GMT; path=/; domain=.yourdomain.com

<HTML>

<HEAD>

<TITLE>html++ example application</TITLE>

</HEAD>

<BODY>

NEW visitor number 69<BR>

</BODY>

</HTML>

Program Output (second run)

Content-Type: text/html

<HTML>

<HEAD>

<TITLE>html++ example application</TITLE>

</HEAD>

<BODY>

Recognized visitor number 69<BR>

</BODY>

</HTML>

©1998 DC Micro Development. All rights reserved.
No portion of this document may be c opied or reproduced without expressed written consent.
html++ is a trademark of DC Micro Development.

	htmlCookie provides automated access for sending and receiving persistent HTTP cookies to and from web browsers. Cookies are a general mechanism which server applications can use to store and retrieve information from web browsers. Cookies greatly extend the capabilities of html++ applications.

	A server, when transmitting a page to a browser, may optionally send a user-defined value, called a cookie, that represents state information which the browser will store. Included in the cookie is a description of the range of URL's for which that state is valid, and a date after which the browser may delete the cookie. The browser will send the cookie back to the server for any future page requests within the range of specified URL's.

	The htmlServer class includes an htmlCookie object as a member variable.

	For additional details, refer to Persistent Cookies in the Tutorial section of the User's Guide.

	htmlCookie( const String& *name, const String& value* )

	Constructs a cookie object, adding the user-defined name and associated value. Unless an expiration date is specified via the Expires() method, the cookie will expire when the user shuts down the browser.

	htmlCookie(	const String& *name*,
		const String& *value*,
		const String& *expires*,
		const String& *path*,
		const String& *domain* )

	Constructs a cookie object, adding the specified name and associated value. expires represents the RFC822-formatted date (see Expires() method below) that the cookie will be discarded by the browser. If specified, path instructs the browser to return the cookie only when a URL containing path is requested. domain specifies the domain for which the cookie will be returned.

	Sets the host or domain name for which the cookie is valid to domain, instructing the browser to return the cookie only when communicating with the specified host or domain. domain should contain at least two periods (e.g., ".yourdomain.com") to avoid partial matches with other cookies that might be stored in the browser. The default value is the host name of the server which sent the cookie.

	Returns the host or domain name specified for the cookie, or an empty string if not set.

	If specified, Path() will instruct the browser to return the cookie only if the browser requests a URL of at least path.If no path is specified, most browsers automatically use the same path as that of the original URL request. If you want your cookie to be valid for all pages in the domain, specifiy a path of "/".

	Note that there is a bug in Netscape Navigator version 1.1 and earlier. Only cookies whose path attribute is set explicitly to "/" will be properly saved between sessions if they have an expires attribute.

	Returns the path specified for the cookie, or an empty string if not set.

	Expires	htmlCookie& Expires( const String& *expires* )

	Sets the date and time the cookie will expire, in relation to Greenwich Mean Time (GMT), to expires. If no value is specified, the browser will discard the cookie when the user session ends (i.e., the user exits the browser). The expires date should be formatted according to RFC 822, of the form:

	Weekday, dd-Mon-yyyy hh:mm:ss GMT

	If a number, positive or negative, is specified in expires instead of an RFC 822-formatted string, html++ will interpret the value as an offset in days from the current date (e.g., Expires( "+365" ) ). In such cases, html++ will assume a time of 12pm GMT. This makes it particularly easy to create various future or past expiration dates without complicated date arithmetic.

	You may find the Julian date class, and the Julian::RFC822() method, useful for manipulating dates and performing more complex date operations.

	Note that there is a bug in Netscape Navigator version 1.1 and earlier. Only cookies whose path attribute is set explicitly to "/" will be properly saved between sessions if they have an expires attribute.

	Returns the expiration date of the cookie as a string, or an empty string if not set.

	If enable is TRUE, the cookie will only be transmitted by the browser if using a secure SSL connection.

	<<	friend ostream& operator<< ( ostream& os, const htmlCookie& *cookie* )


	#include <stdio.h>
	#include <stdlib.h>
	#include <dcmicro/htmlpp/htmlpp.h>

	#define COOKIENAME "visitorid"

	int main( void )
	{
	htmlCgi server( cin ) ;
	htmlPage page( "html++ example application" ) ;
	long visitor_id ;

	if ( server.Cookie().Exists( COOKIENAME ) )
	{
	// retrieve cookie that was passed from the browser
	visitor_id = server.Cookie().Value( COOKIENAME ).AsLong() ;

	page << "Recognized visitor number "
	<< visitor_id << htmlBreak() ;
	}
	else
	{
	// Create a new cookie for the page
	htmlCookie cookie ;
	cookie.Domain( ".yourdomain.com" )
	.Path( "/" ) // root path for the domain
	.Expires( +30 ) ; // expires in 30 days

	// Create your own number here
	visitor_id = 69 ;

	// Set the cookie value, and store it in the
	// browser. Note that the cookie can be inserted
	// in the server object at any time prior to final
	// output, and that multiple values may be stored
	// in the cookie as well.
	cookie.Value( COOKIENAME, visitor_id ) ;
	server << cookie ;

	page << "NEW visitor number "
	<< visitor_id << htmlBreak() ;
	}

	server << page ;
	return 0 ;
	}


	Content-Type: text/html
	Set-Cookie: visitorid=69; expires=Wednesday, 31-Dec-1997 12:00:00 GMT; path=/; domain=.yourdomain.com

	<HTML>
	<HEAD>
	<TITLE>html++ example application</TITLE>
	</HEAD>
	<BODY>
	NEW visitor number 69<BR>
	</BODY>
	</HTML>