Indy 9
|
TIdCustomHTTP = class(TIdTCPClient)
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:
TIdCustomHTTP also supports the Secure Hypertext Transport protocol (HTTPS) as described in the Internet Standards document:
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.
property AllowCookies: Boolean;
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.
property AuthenticationManager: TIdAuthenticationManager;
property AuthRetries: Integer;
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.
property CookieManager: TIdCookieManager;
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.
property HandleRedirects: Boolean;
Redirection ResponseCodes include the following:
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.
property HTTPOptions: TIdHTTPOptions;
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.
property ProtocolVersion: TIdHTTPProtocolVersion;
The default value for ProtocolVersion is pv1_1.
property ProxyParams: TIdProxyConnectionInfo;
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.
property RedirectMaximum: Integer;
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.
property Request: TIdHTTPRequest;
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.
property Response: TIdHTTPResponse;
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.
property ResponseCode: Integer;
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.
property ResponseText: string;
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.
property URL: TIdURI;
constructor Create(AOwner: TComponent); override;
Create also allocates resources required for the Request, Response, and URI properties.
destructor Destroy; override;
procedure DoRequest(const AMethod: TIdHTTPMethod; AURL: string; const ASource: TStream; const AResponseContent: TStream); virtual;
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.
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.
procedure Get(AURL: string; const AResponseContent: TStream); overload; function Get(AURL: string): string; overload;
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.
procedure Head(AURL: string);
Head calls the DoRequest method to perform the HTTP transfer. The returned header values can be found in Response.
procedure Options(AURL: string); overload;
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.
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;
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.
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;
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.
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;
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.
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;
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.
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;
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.
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;
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.
function Put(AURL: string; const ASource: TStream): string; overload; procedure Put(AURL: string; const ASource: TStream; const AResponseContent: TStream); overload;
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.
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.
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.
procedure Trace(AURL: string; const AResponseContent: TStream); overload; function Trace(AURL: string): string; overload;
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.
property OnAuthorization: TIdOnAuthorization;
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.
property OnProxyAuthorization: TIdOnAuthorization;
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.
property OnRedirect: TIdHTTPOnRedirectEvent;
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.
property OnSelectAuthorization: TIdOnSelectAuthorization;
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.
property OnSelectProxyAuthorization: TIdOnSelectAuthorization;
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.