Implements a HTTP client Cookie manager.

TIdCookieManager = class(TIdBaseComponent)

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.

Represents a container for Cookies managed by TIdCookieManager.

property CookieCollection: TIdCookies;

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.

Event handler signalled during the Create method.

property OnCreate: TOnCreateEvent;

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.

Event handler signalled during the Create method.

property OnDestroy: TOnDestroyEvent;

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.

Adds a cookie to the collection managed by IdCookieManager.

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

Textual Cookie values as described in RFC 2109.

Host name or address from the URI for the HTTP request.

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.

Adds a cookie to the collection managed by IdCookieManager.

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

Textual Cookie values as described in RFC 2965.

Host name or address from the URI for the HTTP request.

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.

Constructor for the object instance.

constructor Create(AOwner: TComponent); override;

Owner of the object instance.

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.

Frees the object instance.

destructor Destroy; override;

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.

Generates text containing Cookie values that match the specified values.

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

URI specifying the Host and Path for valid Cookie content.

Indicates if a Secure connection is required. Default value is False.

String - Textual representation of the matching Cookies.

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.

Event handler signalled when Cookies are added to the collection.

property OnNewCookie: TOnNewCookieEvent;

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.