Implements an HTTP client.

TIdHTTP = class(TIdCustomHTTP)

TIdHTTP is a TIdCustomHTTP descendant that is a client implementation of the Hypertext Transfer Protocol (HTTP) as described in the Internet Standards documents:

• RFC 1945 - Hypertext Transfer Protocol version 1.0 [HTTP/1.0] (http://www.rfc-editor.org/rfc/rfc1945.txt)

• RFC 2616 - Hypertext Transfer Protocol version 1.1 [HTTP/1.1] (http://www.rfc-editor.org/rfc/rfc2616.txt)

TIdHTTP publishes properties and event handlers on the ancestor classes to allow access from the client application, and the VCL streaming mechanism.

TIdHTTP provides support for both HTTP 1.0 and HTTP 1.1 protocols. NOte: Post is restricted to support for the HTTP 1.0 protocol due to limited HTTP server support for the HTTP 1.1 specification.

TIdHTTP also provides a CookieManager that implements an HTTP State Management mechanism as specified in the Internet Standards documents, and reference materials:

• 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)

TIdHTTP also supports the Secure Hypertext Transport protocol (HTTPS) as described in the Internet Standards document:

• RFC 2660 - The Secure HyperText Transfer Protocol (http://www.rfc-editor.org/rfc/rfc2660.txt)

Assign an instance of TIdConnectionInterceptOpenSSL to the Intercept property to allow use of the HTTPS protocol. For the Windows platform, you must install the Indy OpenSSL support .DLL's available at http://www.intelicom.si to enable Secure Socket Layer support.

Indicates if the HTTP client accepts Cookies in response headers.

property AllowCookies: Boolean;

AllowCookies is a published Boolean property in TIdHTTP, and indicates if the HTTP client allows use of persistent state information using TIdCookie instances handled by CookieManager. AllowCookies is used when an HTTP client retrieves headers for an HTTP Response, and processes Response headers and cookie values.

When AllowCookies is True, the HTTP client will insure that CookieManager is instantiated prior to adding any TIdCookieRFC2109 or TIdCookieRFC2965 cookie instances detected in Response headers.

The default value for AllowCookies is True, as assigned in the Create constructor.

Maximum number of authentication requests allowed for the client connection.

property AuthRetries: Integer;

AuthRetries is a published Integer property in TIdHTTP, and represents the maximum number of retries permitted when performing authentication for the TIdHTTP client connection. AuthRetries is used when an HTTP protocol handler for the client connection attempts to process a protocol response code that indicates authentication or proxy authentication is required (401 or 407).

AuthRetries is compared to the current number of authentication requests issued to determine if additional authentication requests are allowed. When permitted, the request is performed using the OnAuthorization event handler.

The default value for AuthRetries is 3, as assigned in the Create constructor.

Maintains client persistent state information using Cookies.

property CookieManager: TIdCookieManager;

CookieManager is a published TIdCookieManager property in TIdHTTP, and enables maintenance of persistent state information using Cookies for the HTTP Client connection. CookieManager is accessed when Cookies are detected during processing of headers in an HTTP response, or when preparing headers for an HTTP request.

CookieManager is used by the HTTP client when AllowCookies is True.

The client will insure that CookieManager is instantiated prior to adding TIdCookieRFC2109 or TIdCookieRFC2965 class instances to the collection maintained in CookieManager. CookieManager is freed in the Destroy method.

Indicates if the HTTP client can handle redirections to an alternate resource location.

property HandleRedirects: Boolean;

HandleRedirects is a published Boolean property in TIdHTTP, and indicates if the HTTP client should handle redirects in a response from the HTTP server. Redirects are indicated by the HTTP Response having a ResponseCode in the range 300 to 307, and requires further action needs by the HTTP Client to fulfill the request.

Redirection ResponseCodes include the following:

• 300 - Multiple Choices. The request can be fulfilled with one of a set of resources, each with its own specific location. The HTTP client can select a preferred representation and redirect its request to that location.

• 301 - Moved Permanently. The requested resource has been assigned a new permanent URI and any future references to this resource should use the new location specified in the Response.

• 302 - Found. The requested resource resides temporarily under a different URI. Since the redirection might be altered on occasion, the client should continue to use the URI in the Request for future requests.

• 304 - Not Modified. If the client has performed a conditional GET request and access is allowed, but the document has not been modified, the server should respond with this status code. The 304 response should not contain a message body, and is always terminated by the first empty line after the header fields, and must include a Date header.

• 305 - Use Proxy. The requested resource must be accessed through the proxy given by the Location header in the HTTP Response containing the URI of the Proxy.

• 307 - Temporary Redirect. The requested resource resides temporarily under a different URI. Since the redirection may be altered on occasion, the HTTP client should continue to use the URI in the RequestI for future requests.

HandleRedirects is used with RedirectMaximum in DoRequest to detect and prevent infinite redirection loops, by limiting the number of active redirections for the client to the value specified in RedirectMaximum.

When HandleRedirects is True, the HTTP Client will trigger the OnRedirect event handler to determine if the client can accept the redirection location found in an HTTP response. When accepted, the redirect causes a new HTTP request with the new location to be issued to fulfill the original request.

When HandleRedirects is False, the OnRedirect event handler will be triggered, and an EIdProtocolReplyError exception will be raised when the redirect cannot be handled by the HTTP client.

The default value for HandleRedirects is Id_TIdHTTP_HandleRedirects, as assigned in the Create constuctor.

Specifies the name or address of the server accessed by an HTTP request.

property Host: string;

Host is a String property that specifies the Internet address or host name of the server accessed by an HTTP Request for a specified URL. Host is included in the HTTP Request as a header field for HTTP 1.1 Requests. Host may also refer to the name or address of a Proxy server when Proxy Connections are used to access the resource identified in URL. The exact resource identified by an HTTP request is determined by examining both the URL and the Host properties.

Indicates the HTTP protocol options applied to the client connection.

property HTTPOptions: TIdHTTPOptions;

HTTPOptions is a published TIdHTTPOptions property in TIdHTTP, and represents the TIdHTTPOption protocol options in use for an HTTP client.

HTTPOptions is used at various times when the client or the HTTP protocol handler needs to perform some action, including processing HTTP responses, preparing request parameters, and authentication of the client connection to a server or proxy.

Identifies the port number used for the connection to an HTTP server.

property Port: integer;

Port is an Integer property that contains the port number used for establishing a connection to the HTTP server. The default value for Port is IdPORT_HTTP, as assigned by the Create constructor.

Port is used with Host to establish an endpoint for the client connection, and may refer to a Proxy server when the Request contains headers that require use of a proxied connection.

Port is used in DoRequest to perform the HTTP transfer method, and receive a Response from the HTTP server.

Specifies the HTTP version.

property ProtocolVersion: TIdHTTPProtocolVersion;

ProtocolVersion is a published TIdHTTPProtocolVersion property in TIdHTTP, and specifies the HTTP version used for Get, Head, and Post methods for the HTTP client. ProtocolVersion allows the following values:

• pv1_0 - HTTP 1.0

• pv1_1 - HTTP 1.1

The default value for ProtocolVersion is pv1_1.

Represents connection and user authorization values used for a Proxied client connection.

property ProxyParams: TIdProxyConnectionInfo;

ProxyParams is a published TIdProxyConnectionInfo property in TIdHTTP, and represents values used in an HTTP request that requires a Proxy connection.

ProxyParams contains properties that relect the Server, Port, Username, and Password used to open and authorize a connection to a Proxy server. ProxyParams also indicates if authentication uses the Basic Authentication algorithm.

ProxyParams is used when TIdHTTP attempts to set the Host and Port number for the client connection, and when OnProxyAuthorization is triggered for the client connection. The Header representation for ProxyParams is used when the HTTP Protocol handler builds the HTTP request packet and tranmits its content to the host server.

The Authetication mechanism in ProxyParams is reset when the OnDisconnected event handler is triggered for the HTTP client connection.

Specifies the maximum number of redirects for the HTTP client.

property RedirectMaximum: Integer;

RedirectMaximum is a published Integer property in TIdHTTP, and specifies the maximum number of redirects that should be handled by the HTTP client. The default value for RedirectMaximum is 15.

RedirectMaximum is provided to limit the effect of web-sites that perform numerous redirects, and to prevent stack overflow due to recursion. RedirectMaximum is used when HandleRedirects is True, otherwise it has no effect.

RedirectMaximum is used with the internally maintained redirect count to determine when redirect handling is deferred to the application. When the redirect count exceeds the value of RedirectMaximum, DoRequest will signal the OnRedirect event handler to allow the application to respond to the redirect request. If the redirect is not handled by the application, an EIdProtocolReplyError exception will be raised.

Specifies the header values to send to the HTTP server.

property Request: TIdHTTPRequest;

Request is a published TIdHTTPRequest property in TIdHTTP, and is used to specify the header values to send to the HTTP server. Request headers allow the HTTP client to pass additional information about the request, or the request client, to the HTTP server.

Request may contain the textual representation of Cookie values from the HTTP client, Host and Port information for a proxied connection, as well as values from TIdHTTP properties transmitted as message headers.

Request is used in DoRequest to perform the HTTP transfer.

Use Response to examine header values received in an HTTP protocol response from the server.

Event handler for authentication of an HTTP connection.

property OnAuthorization: TIdOnAuthorization;

Indicatesd if the authentication was successful.

HTTP Client generating the event notification.

User authorization for the HTTP request.

User identity for the HTTP request.

OnAuthorization is a published TIdOnAuthorization property in TIdHTTP, and represents the event handler signalled when an HTTP client connection needs to provide authentication data as part of an HTTP request.

VUserName and VPassword are the authentication credentials found in the HTTP Request, and can be updated in the event handler. Handled indicates if the event handler has successfully authenticated using the client account credentials and method.

Event handler for selecting the HTTP client authentication mechanism for a proxy connection.

property OnProxyAuthorization: TIdOnAuthorization;

Authentication class to use for the connection.

Header values to use in authectication.

HTTP client generating the event notification.

OnProxyAuthorization is a published TIdProxyOnAuthorization property in TIdHTTP, and represents the event handler signalled when an HTTP client selects an authentication class to be used when session or proxy authentication is required for a connection. OnProxyAuthorization is signalled prior to triggering the OnAuthorization event handler.

AuthenticationClass is the class instance to be used to perform authentication for the mechanisms required in an HTTP request.

AuthInfo is the header values to be be used in the HTTP response that includes the authentication results.

Event handler triggered for redirect requests.

property OnRedirect: TIdHTTPOnRedirectEvent;

URL for the new resource location.

Indicated that redirects should be handled.

An accumulator for the number of redirection requests.

Client triggering the event.

HTTP method to be used to fulfill the redirect.

OnRedirect is a published TIdHTTPOnRedirectEvent property in TIdHTTP, and represents the event handler signalled when the HTTP client receives a redirection ResponseCode in the Response for an HTTP Request.

OnRedirect is signalled during handling of an HTTP Response in the DoRequest method when the ResponseCode contains a value in the range 300-307, and the Response contains a Location header.

When HandleRedirects is True, and the number of active redirects does not exceed RedirectMaximum, the event handler is signalled to allow the HTTP client to handle any processing required for the Location, Method, or current number of redirection requests. If the client is not Disconnected, the pending redirection request is automatically executed using a nested call to DoRequest.

When HandleRedirects is False, the event handler is signalled to allow the HTTP client to handle all aspects of the redirection request. If the redirection request is not handled, an EIdProtocolReplyError exception will be raised.

An Application must assign a procedure to the event handler in order to respond to the event notification. The event handler procedure can used to alter the redirection location specified in Dest, or to change the HTTP method for a pending redirection request. The event handler procedure should also set Handled to True to indicate that the redirection request can/should be allowed for the client.

Event handler triggered when the client selects an authentication mechanism for the connection.

property OnSelectAuthorization: TIdOnSelectAuthorization;

Authentication class to use for the connection.

Header values to use in authectication.

HTTP client generating the event notification.

OnSelectAuthorization is a published TIdOnSelectAuthorization property in TIdHTTP, and represents the event handler triggered when the HTTP client chooses an Authentication method and class for authorizing a connection.

OnSelectAuthorization is triggered when a Request needs Authentication using a supported Authentication method for the WWWAuthenticate headers found in Response. OnSelectAuthorization can be used to set the class instance in Auth used for authenticating the client Request based on header values found in AuthInfo.

OnSelectAuthorization is used prior to triggering the OnAuthorization event handler for the client connection.

Event handler triggered when the client selects an authentication mechanism for the Proxied connection.

property OnSelectProxyAuthorization: TIdOnSelectAuthorization;

Authentication class to use for the connection.

Header values to use in authectication.

HTTP client generating the event notification.

OnSelectProxyAuthorization is a published TIdOnSelectAuthorization property in TIdHTTP, and represents the event handler triggered when the HTTP client chooses an Authentication method and class for authorizing a Proxied connection.

OnSelectProxyAuthorization is triggered when a Request needs Authentication using a supported Authentication method for the Proxy headers found in Response. OnSelectProxyAuthorization can be used to set the class instance in Auth used for authenticating the client Request based on header values found in AuthInfo.

OnSelectProxyAuthorization is used prior to triggering the OnProxyAuthorization event handler for the client connection.