Indy 9 | Content | Index | Reference

TIdCustomHTTP
Hierarchy, Properties, Methods, Events, See Also, Unit: IdHTTP
Specifies an HTTP client implementation.

    TIdCustomHTTP = class(TIdTCPClient)

Unit
IdHTTP
Description
TIdCustomHTTP is a TIdTCPClient descendant that specifies 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)

Note: Application do not normally create instances of TIdCustomHTTP. Use TIdHTTP which publishes propeties and event handlers used in client applications.

TIdCustomHTTP 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 and/or improper HTTP server support for the HTTP 1.1 specification.

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

TIdCustomHTTP 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.

TIdCustomHTTP.AllowCookies
TIdCustomHTTP, See Also
Indicates if the HTTP client accepts Cookies in response headers.

    property AllowCookies: Boolean;

Description
AllowCookies is a Boolean property that 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.

TIdCustomHTTP.AuthenticationManager
TIdCustomHTTP, See Also
AuthenticationManager is not currently used in TIdCustomHTTP.

    property AuthenticationManager: TIdAuthenticationManager;

Description
AuthenticationManager is not currently used in TIdCustomHTTP. AuthenticationManager is not currently used in TIdCustomHTTP. AuthenticationManager is not currently used in TIdCustomHTTP. AuthenticationManager is not currently used in TIdCustomHTTP.

TIdCustomHTTP.AuthRetries
TIdCustomHTTP, See Also
Maximum number of authentication requests allowed for the client connection.

    property AuthRetries: Integer;

Description
AuthRetries is an Integer property that 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.

TIdCustomHTTP.CookieManager
TIdCustomHTTP, See Also
Maintains client persistent state information using Cookies.

    property CookieManager: TIdCookieManager;

Description
CookieManager is a TIdCookieManager property that 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.

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

    property HandleRedirects: Boolean;

Description
HandleRedirects is a Boolean property that 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.

TIdCustomHTTP.HTTPOptions
TIdCustomHTTP, See Also
Indicates the HTTP protocol options applied to the client connection.

    property HTTPOptions: TIdHTTPOptions;

Description
HTTPOptions is a TIdHTTPOptions property that 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.

TIdCustomHTTP.ProtocolVersion
TIdCustomHTTP, See Also
Specifies the HTTP version.

    property ProtocolVersion: TIdHTTPProtocolVersion;

Description
ProtocolVersion is a TIdHTTPProtocolVersion property that 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.

TIdCustomHTTP.ProxyParams
TIdCustomHTTP, See Also
Represents connection and user authorization values used for a Proxied client connection.

    property ProxyParams: TIdProxyConnectionInfo;

Description
ProxyParams is a read-only TIdProxyConnectionInfo property that represents vaslues used in a 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.

TIdCustomHTTP.RedirectMaximum
TIdCustomHTTP, See Also
Specifies the maximum number of redirects for the HTTP client.

    property RedirectMaximum: Integer;

Description
RedirectMaximum is an Integer property that 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.

TIdCustomHTTP.Request
TIdCustomHTTP, See Also
Specifies the header values to send to the HTTP server.

    property Request: TIdHTTPRequest;

Description
Request is a TIdHTTPRequest property 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.

TIdCustomHTTP.Response
TIdCustomHTTP, See Also
Specifies the header values received from the HTTP server.

    property Response: TIdHTTPResponse;

Description
Response is a TIdHTTPResponse property used to specify the header values received in amessage from the HTTP server. Respose headers allow the server to pass additional information about the values returned for an HTTP Request.

Response is used in DoRequest to perform the HTTP transfer, or in Head when retrieving only the header values for the resource identified in URL. Response contains the raw data for headers received in the HTTP reponse, and also copies header values into propeties for the object instance. Response may also contain the raw data for Cookies maintained by CookieManager in the HTTP client.

Response is used in DoRequest when capturing the headers, cookies, and contents for an HTTP response after a Request.

Use Request to examine header values to be sent in a request to the HTTP server.

TIdCustomHTTP.ResponseCode
TIdCustomHTTP, See Also
Specifies the response code received from a HTTP server.

    property ResponseCode: Integer;

Description
ResponseCode is a read-only Integer property that specifies the numeric response code received from a HTTP server. ResponseCode normally contains one of the following values:

- 200 - OK

- 201 - Created

- 202 - Accepted

- 203 - Non-authoritative Information

- 204 - No Content

- 205 - Reset Content

- 206 - Partial Content

- 301 - Moved Permanently

- 302 - Moved Temporarily

- 303 - See Other

- 304 - Not Modified

- 305 - Use Proxy

- 400 - Bad Request

- 401 - Unauthorized

- 403 - Forbidden

- 404 - Not Found

- 405 - Method not allowed

- 406 - Not Acceptable

- 407 - Proxy Authentication Required

- 408 - Request Timeout

- 409 - Conflict

- 410 - Gone

- 411 - Length Required

- 412 - Precondition Failed

- 413 - Request Entity To Long

- 414 - Request-URI Too Long. 256 Chars max

- 415 - Unsupported Media Type

- 500 - Internal Server Error

- 501 - Not Implemented

- 502 - Bad Gateway

- 503 - Service Unavailable

- 504 - Gateway timeout

- 505 - HTTP version not supported

ResponseCode is updated in the DoRequest method when a HTTP server response is retrieved. Use ResponseText to access the textual description of the numeric response code.

TIdCustomHTTP.ResponseText
TIdCustomHTTP, See Also
Specifies the text for a response received from a HTTP server.

    property ResponseText: string;

Description
ResponseText is a read-only String property that specifies the textual message for a response received from a HTTP server. ResponseText normally contains one of the following values messages for the associated ResponseCode:

- 200 - OK

- 201 - Created

- 202 - Accepted

- 203 - Non-authoritative Information

- 204 - No Content

- 205 - Reset Content

- 206 - Partial Content

- 301 - Moved Permanently

- 302 - Moved Temporarily

- 303 - See Other

- 304 - Not Modified

- 305 - Use Proxy

- 400 - Bad Request

- 401 - Unauthorized

- 403 - Forbidden

- 404 - Not Found

- 405 - Method not allowed

- 406 - Not Acceptable

- 407 - Proxy Authentication Required

- 408 - Request Timeout

- 409 - Conflict

- 410 - Gone

- 411 - Length Required

- 412 - Precondition Failed

- 413 - Request Entity To Long

- 414 - Request-URI Too Long. 256 Chars max

- 415 - Unsupported Media Type

- 500 - Internal Server Error

- 501 - Not Implemented

- 502 - Bad Gateway

- 503 - Service Unavailable

- 504 - Gateway timeout

- 505 - HTTP version not supported

ResponseText is updated in the DoRequest method when a HTTP server response is retrieved. Use ResponseCode to access the numeric value for the HTTP server response.

TIdCustomHTTP.URL
TIdCustomHTTP, See Also
Represents the attributes of a resource accessed by an HTTP request.

    property URL: TIdURI;

Description
URL is a read-only TIdURI property that represents the attributes of a server resource in an HTTP Request, including the Protocol, Host, Port, Path, Document, and Bookmark for a resource.

URL is used in DoRequest when provided by the implementation for the HTTP command verb.

TIdCustomHTTP.Create
TIdCustomHTTP
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, and relies on the inherited Create method to initialize properties of the object. Create sets the default value for properties, including:

- Port - IdPORT_HTTP

- AllowCookies - True

- RedirectMaximum - Id_TIdHTTP_RedirectMax

- HandleRedirects - Id_TIdHTTP_HandleRedirects

- AuthRetries - Id_TIdHTTP_MaxAuthRetries

- ProxyAuthRetriesMax - Id_TIdHTTP_MaxAuthRetries

- ProtocolVersion - Id_TIdHTTP_ProtocolVersion

Create also allocates resources required for the Request, Response, and URI properties.

TIdCustomHTTP.Destroy
TIdCustomHTTP
Frees the object instance.

    destructor Destroy; override;

Description
Destroy is the Destructor for the object instance. Destroy is responsible for freeing resources allocated in the Create constructor, and includes the CookieManager created during header processing. Destroy calls the inherited Destroy method prior to exiting.

TIdCustomHTTP.DoRequest
TIdCustomHTTP
Performs a HTTP request and retrieves the HTTP response.

    procedure DoRequest(const AMethod: TIdHTTPMethod; AURL: string; const ASource: TStream; const AResponseContent: TStream); virtual;

Parameters
const AMethod: TIdHTTPMethod
The HTTP method to perform.
AURL: string
The location of the resource.
const ASource: TStream
Source of the Request data.
const AResponseContent: TStream
Destination for the Response content.
Description
DoRequest is a procedure used to implement and execute a HTTP request and retrieve the HTTP response. DoRequest is used in the Get, Head, Post, Put, and Trace methods to perform HTTP transfers. DoRequest recognizes the HTTP methods represented in TIdHTTPMethod, but checks to insure that ProtocolVersion indicates HTTP 1.1 for the hmTrace, hmPut, hmOptions, and hmDelete methods. An exception will be raised if HTTP 1.1 methods are used when the Proctocol version indicates HTTP 1.0.

AMethod is the TIdHTTPMethod value that identifies the request to be performed. AURL is the URL-encode location of the resource to be affected by the HTTP request. ASource is a TObject descendant containing the data for the HTTP request. ASource must be either a TStrings or a TStream descendant or an EIdObjectTypeNotSupported exception will be raised. AResponseContent is a TStream where the content for the HTTP response will be stored.

DoRequest will parse AURL into components to determine if the URL contains a user name and password that should be used for authenticating the Request. DoRequest also normalizes the value in AURL to conform to URI notation.

DoRequest will call Connect when the client is not already Connected, and can raise a EIdSSLProtocolReplyError when using HTTPS and the connection fails or a timeout occurs.

DoRequest sets the content length of the Request to the size of the stream specified in ASource for HTTP PUT or POST methods, or zero (0) when using other HTTP methods. DoRequest also updates headers and optional cookies for the Request. DoRequest calls OpenWriteBuffer prior to construct and sending the HTTP Request to accomodate HTTP servers which do not fully implement the HTTP Protocol, and calls CloseWriteBuffer to complete the write transaction.

DoRequest reads the HTTP Server Response for the HTTP Client Request. DoRequest repeatedly calls ReadLn to retrieve headers and ResponseText from the server, until the server returns a ResponseCode other 100 Continue. This allows the HTTP client to accomodate servers which do not fully implement HTTP 1.1, and respond with 100 Continue for HTTP GET and HEAD methods.

DoRequest detects an HTTP Response with Redirection that requires further action to fulfill the Request. When HandleRedirects is True, and the current number of Redirects is less than the value specified in RedirectMaximum, AResponseContent is cleared and the OnRedirect event handler is triggered. Use OnRedirect to close the connection if no further processing is desired for the HTTP Response. When HandleRedirects is False, or RedirectMaximum is exceeded, the OnRedirect event handler is still triggered. An EIdProtocolReplyError can be raised when the redirect action is not handled in the OnRedirect event handler.

DoRequest also triggers event handlers when the HTTP ResponseCode indicates that HTTP Server or Proxy Server authentication is required for the HTTP Response. If the authentication is handled by the OnAuthorization or OnProxyAuthorization event handlers, DoRequest is called to perform the authentication request.

TIdCustomHTTP.Get
TIdCustomHTTP, See Also
Retrieves an HTTP resource.

    procedure Get(AURL: string; const AResponseContent: TStream); overload;
    function Get(AURL: string): string; overload;

Parameters
AURL: string
The resource to be retrieved.
const AResponseContent: TStream
Destination for the data retrieved.
Return Value
String - Contents of the retrieve resource. (Optional)
Description
Get is an overloaded method used to retrieve the file or data for the resource specified in AURL.

AURL is the complete, fully-qualified location of the resource.

AResponseContent is the TStream or descendant that is the destination for data retrieved using the specified URL .

Use Get(AUrl) to retrieve the data from AURL and return the contents as the String result of the function.

Use Get(AUrl, AResponseContent) to retrieve data from the URL and write the return values to the TStream descendant specified by AResponseContent.

Get relies on the DoRequest method to perform the HTTP transfer.

TIdCustomHTTP.Get
TIdCustomHTTP, See Also
Retrieves an HTTP resource.

    procedure Get(AURL: string; const AResponseContent: TStream); overload;
    function Get(AURL: string): string; overload;

Parameters
AURL: string
The resource to be retrieved.
const AResponseContent: TStream
Destination for the data retrieved.
Return Value
String - Contents of the retrieve resource. (Optional)
Description
Get is an overloaded method used to retrieve the file or data for the resource specified in AURL.

AURL is the complete, fully-qualified location of the resource.

AResponseContent is the TStream or descendant that is the destination for data retrieved using the specified URL .

Use Get(AUrl) to retrieve the data from AURL and return the contents as the String result of the function.

Use Get(AUrl, AResponseContent) to retrieve data from the URL and write the return values to the TStream descendant specified by AResponseContent.

Get relies on the DoRequest method to perform the HTTP transfer.

TIdCustomHTTP.Head
TIdCustomHTTP, See Also
Requests header values for a resource.

    procedure Head(AURL: string);

Parameters
URL
Location of the resource.
Description
Head is a procedure used to request the header values for the resource specified in URL. Head is identical to Get, except that the server does not return a message body in the Response. Head can be used to obtain metainformation about the entity implied by the request without transferring the full content of the resource. Head is often used for testing the valuein URL for validity, accessibility, and recent modification.

Head calls the DoRequest method to perform the HTTP transfer. The returned header values can be found in Response.

TIdCustomHTTP.Options
TIdCustomHTTP
Retrieves options and capabilities for a server resource.

    procedure Options(AURL: string); overload;

Parameters
AURL: string
Identifies the resource location for options and capabilities.
Description
Options is a procedure that implements the HTTP 1.1 command verb used to retrieve information about the communication options available for Request and Response resulting from the URI specified in AURL. Options allows the HTTP client to determine the options and/or requirements associated with a resource, or the capabilities of a server, without implying a resource action or initiating a resource retrieval.

When AURL contains the value '*' (Asterisk), the Options Request applies to all resources on the HTTP server. Since server communication options typically depend on the resource, the "*" request is only useful as a "ping" or "no-op" type of Request. For example, this can be used to test a proxy for HTTP/1.1 compliance. When AURL contains a valid server resource, the Request applies only to that target.

Response will contain the ResponseCode 200, and header information that indicates optional features implemented by the server and applicable to the resource.

Options calls the DoRequest method to perform the HTTP transfer for the Request.

TIdCustomHTTP.Post
TIdCustomHTTP, See Also
Send HTTP data to a web server or CGI program.

    function Post(AURL: string; const ASource: TStrings): string; overload;
    function Post(AURL: string; const ASource: TStream): string; overload;
    function Post(AURL: string; const ASource: TIdMultiPartFormDataStream): string; overload;
    procedure Post(AURL: string; const ASource: TStrings; const AResponseContent: TStream); overload;
    procedure Post(AURL: string; const ASource: TStream; const AResponseContent: TStream); overload;
    procedure Post(AURL: string; const ASource: TIdMultiPartFormDataStream; AResponseContent: TStream); overload;

Parameters
const ASource: TStrings
TStrings or stream containing the request data.
const AResponseContent: TStream
Destination for response data.
URL
Location of the host or CGI application.
Return Value
String - Values received in a Response for the HTTP POST method.
Description
Post is an overloaded method in TIdHTTP that is used to send data specified in ASource to the resource location in AURL. Post is overloaded to allow use of either TStrings or TStream object instances in ASource, and also provides procedure- and function-based variants of the method to allow String return values or storage of return values in AResponseContent.

Indy currently reverts the HTTP version to 1.0 in a call to the Post method. This occurs because some HTTP servers do not respect the RFC for HTTP 1.1 to the full extent of the specification. In particular, most servers do not send or expect to receive the 100-Continue HTTP header. Until an optimum solution that does NOT break the RFC is discovered, Indy will restrict all POST requests to version HTTP 1.0 compliance.

When ASource is a TStrings instance, Post will replace all occurrences of the End-Of-Line (EOL) character in ASource with the value '&' prior to transfer to the HTTP server. When ASource is a TStream instance, no preprocessing of the stream content is performed.

Post calls the DoRequest method to perform the HTTP transfer.

TIdCustomHTTP.Post
TIdCustomHTTP, See Also
Send HTTP data to a web server or CGI program.

    function Post(AURL: string; const ASource: TStrings): string; overload;
    function Post(AURL: string; const ASource: TStream): string; overload;
    function Post(AURL: string; const ASource: TIdMultiPartFormDataStream): string; overload;
    procedure Post(AURL: string; const ASource: TStrings; const AResponseContent: TStream); overload;
    procedure Post(AURL: string; const ASource: TStream; const AResponseContent: TStream); overload;
    procedure Post(AURL: string; const ASource: TIdMultiPartFormDataStream; AResponseContent: TStream); overload;

Parameters
const ASource: TStrings
TStrings or stream containing the request data.
const AResponseContent: TStream
Destination for response data.
URL
Location of the host or CGI application.
Return Value
String - Values received in a Response for the HTTP POST method.
Description
Post is an overloaded method in TIdHTTP that is used to send data specified in ASource to the resource location in AURL. Post is overloaded to allow use of either TStrings or TStream object instances in ASource, and also provides procedure- and function-based variants of the method to allow String return values or storage of return values in AResponseContent.

Indy currently reverts the HTTP version to 1.0 in a call to the Post method. This occurs because some HTTP servers do not respect the RFC for HTTP 1.1 to the full extent of the specification. In particular, most servers do not send or expect to receive the 100-Continue HTTP header. Until an optimum solution that does NOT break the RFC is discovered, Indy will restrict all POST requests to version HTTP 1.0 compliance.

When ASource is a TStrings instance, Post will replace all occurrences of the End-Of-Line (EOL) character in ASource with the value '&' prior to transfer to the HTTP server. When ASource is a TStream instance, no preprocessing of the stream content is performed.

Post calls the DoRequest method to perform the HTTP transfer.

TIdCustomHTTP.Post
TIdCustomHTTP, See Also
Send HTTP data to a web server or CGI program.

    function Post(AURL: string; const ASource: TStrings): string; overload;
    function Post(AURL: string; const ASource: TStream): string; overload;
    function Post(AURL: string; const ASource: TIdMultiPartFormDataStream): string; overload;
    procedure Post(AURL: string; const ASource: TStrings; const AResponseContent: TStream); overload;
    procedure Post(AURL: string; const ASource: TStream; const AResponseContent: TStream); overload;
    procedure Post(AURL: string; const ASource: TIdMultiPartFormDataStream; AResponseContent: TStream); overload;

Parameters
const ASource: TStrings
TStrings or stream containing the request data.
const AResponseContent: TStream
Destination for response data.
URL
Location of the host or CGI application.
Return Value
String - Values received in a Response for the HTTP POST method.
Description
Post is an overloaded method in TIdHTTP that is used to send data specified in ASource to the resource location in AURL. Post is overloaded to allow use of either TStrings or TStream object instances in ASource, and also provides procedure- and function-based variants of the method to allow String return values or storage of return values in AResponseContent.

Indy currently reverts the HTTP version to 1.0 in a call to the Post method. This occurs because some HTTP servers do not respect the RFC for HTTP 1.1 to the full extent of the specification. In particular, most servers do not send or expect to receive the 100-Continue HTTP header. Until an optimum solution that does NOT break the RFC is discovered, Indy will restrict all POST requests to version HTTP 1.0 compliance.

When ASource is a TStrings instance, Post will replace all occurrences of the End-Of-Line (EOL) character in ASource with the value '&' prior to transfer to the HTTP server. When ASource is a TStream instance, no preprocessing of the stream content is performed.

Post calls the DoRequest method to perform the HTTP transfer.

TIdCustomHTTP.Post
TIdCustomHTTP, See Also
Send HTTP data to a web server or CGI program.

    function Post(AURL: string; const ASource: TStrings): string; overload;
    function Post(AURL: string; const ASource: TStream): string; overload;
    function Post(AURL: string; const ASource: TIdMultiPartFormDataStream): string; overload;
    procedure Post(AURL: string; const ASource: TStrings; const AResponseContent: TStream); overload;
    procedure Post(AURL: string; const ASource: TStream; const AResponseContent: TStream); overload;
    procedure Post(AURL: string; const ASource: TIdMultiPartFormDataStream; AResponseContent: TStream); overload;

Parameters
const ASource: TStrings
TStrings or stream containing the request data.
const AResponseContent: TStream
Destination for response data.
URL
Location of the host or CGI application.
Return Value
String - Values received in a Response for the HTTP POST method.
Description
Post is an overloaded method in TIdHTTP that is used to send data specified in ASource to the resource location in AURL. Post is overloaded to allow use of either TStrings or TStream object instances in ASource, and also provides procedure- and function-based variants of the method to allow String return values or storage of return values in AResponseContent.

Indy currently reverts the HTTP version to 1.0 in a call to the Post method. This occurs because some HTTP servers do not respect the RFC for HTTP 1.1 to the full extent of the specification. In particular, most servers do not send or expect to receive the 100-Continue HTTP header. Until an optimum solution that does NOT break the RFC is discovered, Indy will restrict all POST requests to version HTTP 1.0 compliance.

When ASource is a TStrings instance, Post will replace all occurrences of the End-Of-Line (EOL) character in ASource with the value '&' prior to transfer to the HTTP server. When ASource is a TStream instance, no preprocessing of the stream content is performed.

Post calls the DoRequest method to perform the HTTP transfer.

TIdCustomHTTP.Post
TIdCustomHTTP, See Also
Send HTTP data to a web server or CGI program.

    function Post(AURL: string; const ASource: TStrings): string; overload;
    function Post(AURL: string; const ASource: TStream): string; overload;
    function Post(AURL: string; const ASource: TIdMultiPartFormDataStream): string; overload;
    procedure Post(AURL: string; const ASource: TStrings; const AResponseContent: TStream); overload;
    procedure Post(AURL: string; const ASource: TStream; const AResponseContent: TStream); overload;
    procedure Post(AURL: string; const ASource: TIdMultiPartFormDataStream; AResponseContent: TStream); overload;

Parameters
const ASource: TStrings
TStrings or stream containing the request data.
const AResponseContent: TStream
Destination for response data.
URL
Location of the host or CGI application.
Return Value
String - Values received in a Response for the HTTP POST method.
Description
Post is an overloaded method in TIdHTTP that is used to send data specified in ASource to the resource location in AURL. Post is overloaded to allow use of either TStrings or TStream object instances in ASource, and also provides procedure- and function-based variants of the method to allow String return values or storage of return values in AResponseContent.

Indy currently reverts the HTTP version to 1.0 in a call to the Post method. This occurs because some HTTP servers do not respect the RFC for HTTP 1.1 to the full extent of the specification. In particular, most servers do not send or expect to receive the 100-Continue HTTP header. Until an optimum solution that does NOT break the RFC is discovered, Indy will restrict all POST requests to version HTTP 1.0 compliance.

When ASource is a TStrings instance, Post will replace all occurrences of the End-Of-Line (EOL) character in ASource with the value '&' prior to transfer to the HTTP server. When ASource is a TStream instance, no preprocessing of the stream content is performed.

Post calls the DoRequest method to perform the HTTP transfer.

TIdCustomHTTP.Post
TIdCustomHTTP, See Also
Send HTTP data to a web server or CGI program.

    function Post(AURL: string; const ASource: TStrings): string; overload;
    function Post(AURL: string; const ASource: TStream): string; overload;
    function Post(AURL: string; const ASource: TIdMultiPartFormDataStream): string; overload;
    procedure Post(AURL: string; const ASource: TStrings; const AResponseContent: TStream); overload;
    procedure Post(AURL: string; const ASource: TStream; const AResponseContent: TStream); overload;
    procedure Post(AURL: string; const ASource: TIdMultiPartFormDataStream; AResponseContent: TStream); overload;

Parameters
const ASource: TStrings
TStrings or stream containing the request data.
const AResponseContent: TStream
Destination for response data.
URL
Location of the host or CGI application.
Return Value
String - Values received in a Response for the HTTP POST method.
Description
Post is an overloaded method in TIdHTTP that is used to send data specified in ASource to the resource location in AURL. Post is overloaded to allow use of either TStrings or TStream object instances in ASource, and also provides procedure- and function-based variants of the method to allow String return values or storage of return values in AResponseContent.

Indy currently reverts the HTTP version to 1.0 in a call to the Post method. This occurs because some HTTP servers do not respect the RFC for HTTP 1.1 to the full extent of the specification. In particular, most servers do not send or expect to receive the 100-Continue HTTP header. Until an optimum solution that does NOT break the RFC is discovered, Indy will restrict all POST requests to version HTTP 1.0 compliance.

When ASource is a TStrings instance, Post will replace all occurrences of the End-Of-Line (EOL) character in ASource with the value '&' prior to transfer to the HTTP server. When ASource is a TStream instance, no preprocessing of the stream content is performed.

Post calls the DoRequest method to perform the HTTP transfer.

TIdCustomHTTP.Put
TIdCustomHTTP
Implements the HTTP PUT command verb.

    function Put(AURL: string; const ASource: TStream): string; overload;
    procedure Put(AURL: string; const ASource: TStream; const AResponseContent: TStream); overload;

Parameters
AURL: string
Location to store the resource on the server.
const ASource: TStream
Values tyo be stored at the specified location.
const AResponseContent: TStream
Destination for response values from the operation.
Description
Put is an overloaded method in TIdHTTP, that implements the HTTP PUT command verb used to store the entity contained in ASource at the URI specified in AURL.

If AURL refers to an existing server resource, the values in ASource are considered to be a modified version of the server resource. When AURL does not exist on the server, a new server resource is created for the values in ASource.

Put is overloaded to provide a String function that returns the Response from the HTTP Request, or a procedure that stores Response values in the stream specified by AResponseContent.

Put differs from Post through its use of the values in AURL. For a Put operation, the valuein AURL always refers to the values included in the Response content.

Put calls DoRequest to perform the HTTP transfer.

TIdCustomHTTP.Put
TIdCustomHTTP
Implements the HTTP PUT command verb.

    function Put(AURL: string; const ASource: TStream): string; overload;
    procedure Put(AURL: string; const ASource: TStream; const AResponseContent: TStream); overload;

Parameters
AURL: string
Location to store the resource on the server.
const ASource: TStream
Values tyo be stored at the specified location.
const AResponseContent: TStream
Destination for response values from the operation.
Description
Put is an overloaded method in TIdHTTP, that implements the HTTP PUT command verb used to store the entity contained in ASource at the URI specified in AURL.

If AURL refers to an existing server resource, the values in ASource are considered to be a modified version of the server resource. When AURL does not exist on the server, a new server resource is created for the values in ASource.

Put is overloaded to provide a String function that returns the Response from the HTTP Request, or a procedure that stores Response values in the stream specified by AResponseContent.

Put differs from Post through its use of the values in AURL. For a Put operation, the valuein AURL always refers to the values included in the Response content.

Put calls DoRequest to perform the HTTP transfer.

TIdCustomHTTP.Trace
TIdCustomHTTP
Implements the HTTP TRACE command verb for diagnostics.

    procedure Trace(AURL: string; const AResponseContent: TStream); overload;
    function Trace(AURL: string): string; overload;

Parameters
AURL: string
Resource to be examined in Trace.
const AResponseContent: TStream
Destination for the test or diagnostic messages.
Return Value
String - Test or diagnostic messages for the resource.
Description
Trace is an overloaded method in TIdHTTP that implements the HTTP TRACE command verb. Trace is used to a remote application-layer loop- back for the Request message, and allows the HTTP client to see the data received at the host or proxy server that is the target for the Request. Trace will return information that can be used for testing and diagnostic purposes.

If the Request is valid, the Response to a Trace Request will contain the entire Request message with a Content-Type of "message/http".

Trace is overloade to allow the response content to be returned a String, using the function-based variant of the method, or in the stream specified in AResponseContent.

TIdCustomHTTP.Trace
TIdCustomHTTP
Implements the HTTP TRACE command verb for diagnostics.

    procedure Trace(AURL: string; const AResponseContent: TStream); overload;
    function Trace(AURL: string): string; overload;

Parameters
AURL: string
Resource to be examined in Trace.
const AResponseContent: TStream
Destination for the test or diagnostic messages.
Return Value
String - Test or diagnostic messages for the resource.
Description
Trace is an overloaded method in TIdHTTP that implements the HTTP TRACE command verb. Trace is used to a remote application-layer loop- back for the Request message, and allows the HTTP client to see the data received at the host or proxy server that is the target for the Request. Trace will return information that can be used for testing and diagnostic purposes.

If the Request is valid, the Response to a Trace Request will contain the entire Request message with a Content-Type of "message/http".

Trace is overloade to allow the response content to be returned a String, using the function-based variant of the method, or in the stream specified in AResponseContent.

TIdCustomHTTP.OnAuthorization
TIdCustomHTTP
Event handler for authentication of an HTTP connection.

    property OnAuthorization: TIdOnAuthorization;

Parameters
Handled
Indicatesd if the authentication was successful.
Sender
HTTP Client generating the event notification.
VPassword
User authorization for the HTTP request.
VUserName
User identity for the HTTP request.
Description
OnAuthorization is a TIdOnAuthorization property that 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.

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

    property OnProxyAuthorization: TIdOnAuthorization;

Parameters
AuthenticationClass
Authentication class to use for the connection.
AuthInfo
Header values to use in authectication.
Sender
HTTP client generating the event notification.
Description
OnProxyAuthorization is a TIdProxyOnAuthorization property that 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.

TIdCustomHTTP.OnRedirect
TIdCustomHTTP
Event handler triggered for redirect requests.

    property OnRedirect: TIdHTTPOnRedirectEvent;

Parameters
dest
URL for the new resource location.
Handled
Indicated that redirects should be handled.
NumRedirect
An accumulator for the number of redirection requests.
Sender
Client triggering the event.
VMethod
HTTP method to be used to fulfill the redirect.
Description
OnRedirect is a TIdHTTPOnRedirectEvent property that represents the event handler used 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.

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

    property OnSelectAuthorization: TIdOnSelectAuthorization;

Parameters
AuthenticationClass
Authentication class to use for the connection.
AuthInfo
Header values to use in authectication.
Sender
HTTP client generating the event notification.
Description
OnSelectAuthorization is a TIdOnSelectAuthorization property that 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.

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

    property OnSelectProxyAuthorization: TIdOnSelectAuthorization;

Parameters
AuthenticationClass
Authentication class to use for the connection.
AuthInfo
Header values to use in authectication.
Sender
HTTP client generating the event notification.
Description
OnSelectProxyAuthorization is a TIdOnSelectAuthorization property that 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.

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