Indy 9 | Content | Index | Reference

TIdCookieManager
Hierarchy, Properties, Methods, Events, See Also, Unit: IdCookieManager
Implements a HTTP client Cookie manager.

    TIdCookieManager = class(TIdBaseComponent)

Unit
IdCookieManager
Description
TIdCookieManager is a TIdBaseComponent descendant that implements a management facility for persistent HTTP state information, as described in the Internet Standards and reference documents:

- RFC 2109 - HTTP State Management Mechanism (http://www.rfc-editor.org/rfc/rfc2109.txt)

- RFC 2965 - HTTP State Management Mechanism (http://www.rfc-editor.org/rfc/rfc2965.txt)

- Netscape Persistent Client State - HTTP Cookies (http://www.netscape.com/newsref/std/cookie_spec.html)

The TIdCookieManager component provides the Add and Add2 methods that enable maintenance of Cookie class instances added to the CookieCollection in an HTTP Client connection. The GenerateCookieList method is provided to create a textual representation of Cookies maintained for a specific URI.

In addition, TIdCookieManager implements event handlers that allow event notifications during creation or destruction of the TIdCookieManager class instance, and when Cookies are added using the Cookie manager.

TIdCookieManager is used by a TIdHTTP client in the CookieMananger property when AllowCookies is True. The HTTP client uses CookieManager to maintain a Cookie collection when 'Set-cookie' or 'Set-cookie2' headers are detected in a response from an HTTP server.

TIdCookieManager.CookieCollection
TIdCookieManager, See Also
Represents a container for Cookies managed by TIdCookieManager.

    property CookieCollection: TIdCookies;

Description
CookieCollection is a read-only TIdCookies property that represents the Cookie class instances maintained by TIdCookieManager for the HTTP client. CookieCollection is accessed when TIdCookieManager creates new Cookie class instances in calls to AddCookie or AddCookie2, and when the textual Cookie content is prepared using GenerateCookieList.

Use the OnNewCookie event handler to manage the CookieCollection when new Cookie class instances are created in AddCookie or AddCookie2.

Use the OnCreate and OnDestroy event handlers to manage the CookieCollection during creation or destruction of the TIdCookieManager class instance.

TIdCookieManager.OnCreate
TIdCookieManager, See Also
Event handler signalled during the Create method.

    property OnCreate: TOnCreateEvent;

Description
OnCreate is a TNotifyEvent property that represents the event handler signalled during creation of the TIdCookieManager object instance. OnCreate can be used to handle management of the CookieCollection when the TIdCookieManager calls the Create method.

Applications must assign a procedure to the event handler to allow responding to the event notification.

Use OnDestroy to handle management of the CookieCollection when the object instance is freed.

TIdCookieManager.OnDestroy
TIdCookieManager, See Also
Event handler signalled during the Create method.

    property OnDestroy: TOnDestroyEvent;

Description
OnDestroy is a TNotifyEvent property that represents the event handler signalled during destruction of the TIdCookieManager object instance. OnDestroy can be used to handle management of the CookieCollection when the TIdCookieManager calls the Destroy method.

Applications must assign a procedure to the event handler to allow responding to the event notification.

Use OnCreate to handle management of the CookieCollection when the object instance is created.

TIdCookieManager.AddCookie
TIdCookieManager, See Also, Example
Adds a cookie to the collection managed by IdCookieManager.

    procedure AddCookie(ACookie: String; AHost: String);

Parameters
ACookie: String
Textual Cookie values as described in RFC 2109.
AHost: String
Host name or address from the URI for the HTTP request.
Description
AddCookie is a procedure that creates a new TIdCookieRFC2109 Cookie class instance for the Cookie values specified in ACookie and the Domain specified in AHost. The internal implementation of AddCookie insures that the Cookie is updated to reflect the values in ACookie, and sets the Domain attribute of the Cookie to AHost when no specific Domain is found in the Cookie contents.

AddCookie checks that the Cookie is valid for the Domain specified in AHost prior to signalling the OnNewCookie event handler. When AHost is not a valid Domain, or the OnNewCookie event handler indicates that the Cookie has been rejected, the Cookie class instance is removed from the CookieCollection and freed.

TIdCookieManager.AddCookie2
TIdCookieManager, See Also, Example
Adds a cookie to the collection managed by IdCookieManager.

    procedure AddCookie2(ACookie: String; AHost: String);

Parameters
ACookie: String
Textual Cookie values as described in RFC 2965.
AHost: String
Host name or address from the URI for the HTTP request.
Description
AddCookie2 is a procedure that creates a new TIdCookieRFC2965 Cookie class instance for the Cookie values specified in ACookie and the Domain specified in AHost. The internal implementation of AddCookie2 insures that the Cookie is updated to reflect the values in ACookie, and sets the Domain attribute of the Cookie to AHost when no specific Domain is found in the Cookie contents.

AddCookie2 checks that the Cookie is valid for the Domain specified in AHost prior to signalling the OnNewCookie event handler. When AHost is not a valid Domain, or the OnNewCookie event handler indicates that the Cookie has been rejected, the Cookie class instance is removed from the CookieCollection and freed.

TIdCookieManager.Create
TIdCookieManager, See Also
Constructor for the object instance.

    constructor Create(AOwner: TComponent); override;

Parameters
AOwner: TComponent
Owner of the object instance.
Description
Create is the constructor for the object instance. Create calls the inherited Create method using AOwner as the owner of the object instance. Create initializes the TIdCookies instance used in the CookieCollection property, and specifies the current object instance as the owner of the Cookie collection.

Calling Create will signal a TNotifyEvent when a procedure has been assigned to the OnCreate event handler. Use OnCreate to handle management of the CookieCollection during creation of the TIdCookieManager object instance.

TIdCookieManager.Destroy
TIdCookieManager, See Also
Frees the object instance.

    destructor Destroy; override;

Description
Destroy is the destructor for the object instance. Destroy will signal a TNotifyEvent event type whan a procedure has been assigned to the OnDestroy event handler. Use OnDestroy to handle management of the CookieCollection during destruction of the TIdCookieManager object instance.

Destroy frees resources allocated in the Create method, including the CookieCollection property, prior to calling the inherited Destroy method.

TIdCookieManager.GenerateCookieList
TIdCookieManager, See Also
Generates text containing Cookie values that match the specified values.

    function GenerateCookieList(URL: TIdURI; SecureConnection: Boolean = false): String;

Parameters
URL: TIdURI
URI specifying the Host and Path for valid Cookie content.
SecureConnection: Boolean = false
Indicates if a Secure connection is required. Default value is False.
Return Value
String - Textual representation of the matching Cookies.
Description
GenerateCookieList is a String function that generates the textual content for Cookies in the CookieCollection that match the Domain and Path for the location specified in URL in the HTTP server request.

SecureConnection indicates whether Cookies must contain a Secure attribute value before they are included in the generated Cookie content for the HTTP client.

Cookies in the CookieCollection will not be used in the generated content when Domain, Path, or Secure Cookie attributes do not match the required values. Cookies can also be ignored when they have Expired.

GenerateCookieList creates and populates a TIdCookieList with Cookie class instances matching the required values, and fills the return value with the CookieName and Value for corresponding Cookies in the list. GenerateCookieList frees the TIdCookieList prior to exiting from the method.

GenerateCookieList is called when an HTTP request is prepared and executed using the Post or Put methods of an HTTP client.

TIdCookieManager.OnNewCookie
TIdCookieManager, See Also
Event handler signalled when Cookies are added to the collection.

    property OnNewCookie: TOnNewCookieEvent;

Description
OnNewCookie is a TOnNewCookieEvent property that represents the event handler signalled when Cookie class instances are added to the CookieCollection. OnNewCookie is signalled when AddCookie or AddCookie2 is used to create the corresponding Cookie class instance used to represent the text for the Cookie.

Applications must assign a procedure to the event handler to allow responding to the event notification. OnNewCookie can indicate if the Cookie is accepted or rejected based on values detected in the Cookie content.

Use OnNewCookie to ovreride the default logic used in management of the CookieCollection when Cookies are added to the collection.

Created with Doc-O-Matic 2 donated to Project JEDI. Commercial license available from the Doc-O-Matic site.