TChilkatHttpRequest Delphi ActiveX Reference Documentation

TChilkatHttpRequest

Represents a complete HTTP request.

Importing the Chilkat ActiveX into Delphi

Important: Whenever upgrading to a new version of Chilkat, make sure to re-imported ActiveX DLL into Delphi to regenerate the files described below.

Two things are required to use an ActiveX in Delphi:

  1. The ActiveX DLL needs to be registered via regsvr32 on the system where the Delphi application runs. See How To Register ActiveX DLLs for detailed information.
  2. The ActiveX component needs to be "imported". Use the Delphi Import Component Wizard to import the Chilkat type library. This creates the following files: Chilkat_v9_5_0_TLB.pas and Chilkat_v9_5_0_TLB.dcr. The Chilkat_v9_5_0_TLB.pas should be added to your project.

To import the Chilkat type library, do the following:

  1. In the Delphi RAD Studio, select the menu item "Component" --> "Import a Type Library".
  2. Find "Chilkat ActiveX v9.5.0" in the list and select it. This will only appear in the list if the ChilkatAx-9.5.0-win32.dll (or ChilkatAx-9.5.0-x64.dll) has been registered w/ regsvr32.
  3. Check the "Generate Component Wrappers" checkbox.
  4. Select a directory where the unit files (.pas and .dcr) will be generated.
  5. Select "Create Unit" and then "Finish".
  6. Add the .pas to your Delphi project.

To use a Chilkat ActiveX object in your Delphi code, add "Chilkat_v9_5_0_TLB" to the "uses" statement. For example:

uses
  Winapi.Windows, Winapi.Messages, System.SysUtils, System.Variants, System.Classes, Vcl.Graphics,
  Vcl.Controls, Vcl.Forms, Vcl.Dialogs, Vcl.StdCtrls, Chilkat_v9_5_0_TLB;

Object Creation

var
obj: TChilkatHttpRequest;
...
begin
obj := TChilkatHttpRequest.Create(Self);
...
// When finished, free the object instance.
obj.Free();

Properties

property Boundary: WideString

Introduced in version 9.5.0.49

Sets an explicit boundary string to be used in multipart/form-data requests. If no Boundary is set, then a boundary string is automaticaly generated as needed during the sending of a request.

HTTP Request Boundary Property

property Charset: WideString

Controls the character encoding used for HTTP request parameters for POST requests. The default value is the ANSI charset of the computer. The charset should match the charset expected by the form target.

The "charset" attribute is only included in the Content-Type header of the request if the SendCharset property is set to 1.

property ContentType: WideString

The ContentType property sets the "Content-Type" header field, and identifies the content-type of the HTTP request body. Common values are:

application/x-www-form-urlencoded
multipart/form-data
text/xml
application/jsonrequest
If ContentType is set equal to the empty string, then no Content-Type header is included in the HTTP request.

Building a multipart/form-data Request for HTTP Upload

Creating an application/json HTTP POST Request

property DebugLogFilePath: WideString

If set to a file path, causes each Chilkat method or property call to automatically append it's LastErrorText to the specified log file. The information is appended such that if a hang or crash occurs, it is possible to see the context in which the problem occurred, as well as a history of all Chilkat calls up to the point of the problem. The VerboseLogging property can be set to provide more detailed information.

This property is typically used for debugging the rare cases where a Chilkat method call hangs or generates an exception that halts program execution (i.e. crashes). A hang or crash should generally never happen. The typical causes of a hang are:

  1. a timeout related property was set to 0 to explicitly indicate that an infinite timeout is desired,
  2. the hang is actually a hang within an event callback (i.e. it is a hang within the application code), or
  3. there is an internal problem (bug) in the Chilkat code that causes the hang.

property EntireHeader: WideString

Composes and returns the entire MIME header of the HTTP request.

property HttpVerb: WideString

The HttpVerb property should be set to the name of the HTTP method that appears on the "start line" of an HTTP request, such as GET, POST, PUT, DELETE, etc. It is also possible to use the various WebDav verbs such as PROPFIND, PROPPATCH, MKCOL, COPY, MOVE, LOCK, UNLOCK, etc. In general, the HttpVerb may be set to anything, even custom verbs recognized by a custom server-side app.

HTTP Verb - How to use any Verb (GET, PUT, POST, DELETE, PROPFIND, etc.)

property HttpVersion: WideString

The HTTP version in the request header. Defaults to "1.1".

property LastBinaryResult: OleVariant readonly

Introduced in version 9.5.0.52

The binary data returned by the last (binary data returning) method called. Only available if Chilkat.Global.KeepBinaryResult is set to 1. This provides a means for obtaining large varbinary results in the SQL Server environment (where limitations exist in getting large amounts of data returned by method calls, but where temp tables can be used for binary properties).

property LastErrorHtml: WideString readonly

Provides information in HTML format about the last method/property called. If a method call returns a value indicating failure, or behaves unexpectedly, examine this property to get more information.

property LastErrorText: WideString readonly

Provides information in plain-text format about the last method/property called. If a method call returns a value indicating failure, or behaves unexpectedly, examine this property to get more information.

Concept of LastErrorText

LastErrorText Standard Information

property LastErrorXml: WideString readonly

Provides information in XML format about the last method/property called. If a method call returns a value indicating failure, or behaves unexpectedly, examine this property to get more information.

property LastMethodSuccess: Integer

Introduced in version 9.5.0.52

Indicate whether the last method call succeeded or failed. A value of 1 indicates success, a value of 0 indicates failure. This property is automatically set for method calls. It is not modified by property accesses. The property is automatically set to indicate success for the following types of method calls:

  • Any method that returns a string.
  • Any method returning a Chilkat object, binary bytes, or a date/time.
  • Any method returning a standard boolean status value where success = 1 and failure = 0.
  • Any method returning an integer where failure is defined by a return value less than zero.

Note: Methods that do not fit the above requirements will always set this property equal to 1. For example, a method that returns no value (such as a "void" in C++) will technically always succeed.

property LastStringResult: WideString readonly

Introduced in version 9.5.0.52

The string return value of the last (string returning) method called. Only available if Chilkat.Global.KeepStringResult is set to 1. This provides a means for obtaining large string results in the SQL Server environment (where limitations exist in getting long strings returned by method calls, but where temp tables can be used for string properties).

Long Strings Returned by ActiveX Methods in SQL Server

property LastStringResultLen: Integer readonly

Introduced in version 9.5.0.53

The length, in characters, of the string contained in the LastStringResult property.

property NumHeaderFields: Integer readonly

Returns the number of request header fields.

property NumParams: Integer readonly

Returns the number of query parameters.

Initialize an HTTP Request from a URL

property Path: WideString

The path of the resource requested. A path of "/" indicates the default document for a domain.

Explaining the Path Part of a URL

property SendCharset: Integer

Controls whether the charset is explicitly included in the content-type header field of the HTTP POST request. The default value of this property is 0.

property VerboseLogging: Integer

If set to 1, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. The default value is 0. Verbose logging should only be used for debugging. The potentially large quantity of logged information may adversely affect peformance.

property Version: WideString readonly

Version of the component/library, such as "9.5.0.63"

Methods

function AddBytesForUpload(name: WideString; remoteFileName: WideString; byteData: OleVariant): Integer;

Adds a file to an upload request where the contents of the file come from an in-memory byte array. To create a file upload request, call UseUpload and then call AddBytesForUpload, AddStringForUpload, or AddFileForUpload for each file to be uploaded.

name is an arbitrary name. (In HTML, it is the form field name of the input tag.)
remoteFileName is the name of the file to be created on the HTTP server.
byteData contains the contents (bytes) to be uploaded.

Returns 1 for success, 0 for failure.

function AddBytesForUpload2(name: WideString; remoteFileName: WideString; byteData: OleVariant; contentType: WideString): Integer;

Same as AddBytesForUpload, but allows the Content-Type header field to be directly specified. (Otherwise, the Content-Type header is automatically determined based on the remoteFileName's file extension.)

Returns 1 for success, 0 for failure.

function AddFileForUpload(name: WideString; filePath: WideString): Integer;

Adds a file to an upload request. To create a file upload request, call UseUpload and then call AddFileForUpload, AddBytesForUpload, or AddStringForUpload for each file to be uploaded. This method does not read the file into memory. When the upload occurs, the data is streamed directly from the file, thus allowing for very large files to be uploaded without consuming large amounts of memory.

name is an arbitrary name. (In HTML, it is the form field name of the input tag.)
filePath is the path to an existing file in the local filesystem.

Returns 1 for success, 0 for failure.

(Facebook) Upload Photo from Local File

function AddFileForUpload2(name: WideString; filePath: WideString; contentType: WideString): Integer;

Same as AddFileForUpload, but allows the Content-Type header field to be directly specified. (Otherwise, the Content-Type header is automatically determined based on the file extension.)

name is an arbitrary name. (In HTML, it is the form field name of the input tag.)
filePath is the path to an existing file in the local filesystem.

Returns 1 for success, 0 for failure.

SOAP with MTOM XOP Attachment

procedure AddHeader(name: WideString; value: WideString);

Adds a request header to the HTTP request. If a header having the same field name is already present, this method replaces it.

Note: Never explicitly set the Content-Length header field. Chilkat will automatically compute the correct length and add the Content-Length header to all POST, PUT, or any other request where the Content-Length needs to be specified. (GET requests always have a 0 length body, and therefore never need a Content-Length header field.)

Adding Cookies to an HTTP Request

function AddMwsSignature(domain: WideString; mwsSecretKey: WideString): Integer;

Introduced in version 9.5.0.66

Computes the Amazon MWS signature using the mwsSecretKey and adds the "Signature" parameter to the request. This method should be called for all Amazon Marketplace Web Service (Amazon MWS) HTTP requests. It should be called after all request parameters have been added.

The domain should be the domain of the request, such as one of the following:

  • mws.amazonservices.com
  • mws-eu.amazonservices.com
  • mws.amazonservices.in
  • mws.amazonservices.com.cn
  • mws.amazonservices.jp

Note: This method automatically adds or replaces the existing Timestamp parameter to the current system date/time.

Returns 1 for success, 0 for failure.

HTTPS MWS List Orders (Amazon Marketplace Web Service)

procedure AddParam(name: WideString; value: WideString);

Adds a request query parameter (name/value pair) to the HTTP request. The name and value strings passed to this method should not be URL encoded.

Add Parameters to Multipart Form-Data POSTs

Initialize an HTTP Request from a URL

function AddStringForUpload(name: WideString; filename: WideString; strData: WideString; charset: WideString): Integer;

Same as AddFileForUpload, but the upload data comes from an in-memory string instead of a file.

Returns 1 for success, 0 for failure.

Building a multipart/form-data Request for HTTP Upload

function AddStringForUpload2(name: WideString; filename: WideString; strData: WideString; charset: WideString; contentType: WideString): Integer;

Same as AddStringForUpload, but allows the Content-Type header field to be directly specified. (Otherwise, the Content-Type header is automatically determined based on the filename's file extension.)

Returns 1 for success, 0 for failure.

HTTP multipart-mixed POST (for a UPS Package Level Detail PLD Request)

function AddSubHeader(index: Integer; name: WideString; value: WideString): Integer;

Introduced in version 9.5.0.55

Adds a request header to the Nth sub-header of the HTTP request. If a header having the same field name is already present, this method replaces it.

Returns 1 for success, 0 for failure.

function GenerateRequestFile(path: WideString): Integer;

Introduced in version 9.5.0.64

The same as GenerateRequestText, except the generated request is written to the file specified by path.

Returns 1 for success, 0 for failure.

function GenerateRequestText(): WideString;

Returns the request text that would be sent if Http.SynchronousRequest was called.

Returns a zero-length WideString on failure

function GetHeaderField(name: WideString): WideString;

Returns the value of a request header field.

Returns a zero-length WideString on failure

function GetHeaderName(index: Integer): WideString;

Returns the Nth request header field name. Indexing begins at 0, and the number of request header fields is specified by the NumHeaderFields property.

Returns a zero-length WideString on failure

function GetHeaderValue(index: Integer): WideString;

Returns the Nth request header field value. Indexing begins at 0, and the number of request header fields is specified by the NumHeaderFields property.

Returns a zero-length WideString on failure

function GetParam(name: WideString): WideString;

Returns a request query parameter value by name.

Returns a zero-length WideString on failure

function GetParamName(index: Integer): WideString;

Returns the Nth request query parameter field name. Indexing begins at 0, and the number of request query parameter fields is specified by the NumParams property.

Returns a zero-length WideString on failure

Initialize an HTTP Request from a URL

function GetParamValue(index: Integer): WideString;

Returns the Nth request query parameter field value. Indexing begins at 0, and the number of request query parameter fields is specified by the NumParams property.

Returns a zero-length WideString on failure

Initialize an HTTP Request from a URL

function GetUrlEncodedParams(): WideString;

Returns the request parameters in URL encoded form (i.e. in the exact form that would be sent if the ContentType property was application/x-www-form-urlencoded). For example, if a request has two params: param1="abc 123" and param2="abc-123", then GetUrlEncodedParams would return "abc+123<param2=abc%2D123"

Returns a zero-length WideString on failure

HTTP multipart-mixed POST (for a UPS Package Level Detail PLD Request)

function LoadBodyFromBd(requestBody: TChilkatBinData): Integer;

Introduced in version 9.5.0.67

Uses the contents of the requestBody as the HTTP request body.

Returns 1 for success, 0 for failure.

function LoadBodyFromBytes(byteData: OleVariant): Integer;

The HTTP protocol is such that all HTTP requests are MIME. For non-multipart requests, this method may be called to set the MIME body of the HTTP request to the exact contents of the byteData.
Note: A non-multipart HTTP request consists of (1) the HTTP start line, (2) MIME header fields, and (3) the MIME body. This method sets the MIME body.

Returns 1 for success, 0 for failure.

function LoadBodyFromFile(filePath: WideString): Integer;

The HTTP protocol is such that all HTTP requests are MIME. For non-multipart requests, this method may be called to set the MIME body of the HTTP request to the exact contents of filePath.
Note: A non-multipart HTTP request consists of (1) the HTTP start line, (2) MIME header fields, and (3) the MIME body. This method sets the MIME body.

Returns 1 for success, 0 for failure.

function LoadBodyFromSb(requestBody: TChilkatStringBuilder; charset: WideString): Integer;

Introduced in version 9.5.0.67

Uses the contents of the requestBody as the HTTP request body. The charset indicates the binary representation of the string, such as "utf-8", "utf-16", "iso-8859-*", "windows-125*", etc. Any of the character encodings supported at the link below are valid.

Returns 1 for success, 0 for failure.

Chilkat Supported Character Encodings

function LoadBodyFromString(bodyStr: WideString; charset: WideString): Integer;

The HTTP protocol is such that all HTTP requests are MIME. For non-multipart requests, this method may be called to set the MIME body of the HTTP request to the exact contents of bodyStr.
Note: A non-multipart HTTP request consists of (1) the HTTP start line, (2) MIME header fields, and (3) the MIME body. This method sets the MIME body.

charset indicates the charset, such as "utf-8" or "iso-8859-1", to be used. The HTTP body will contain the bodyStr converted to this character encoding.

Returns 1 for success, 0 for failure.

Creating an application/json HTTP POST Request

procedure RemoveAllParams();

Removes all request parameters.

Demonstrate HttpRequest.RemoveAllParams

function RemoveHeader(name: WideString): Integer;

Removes all occurrences of a HTTP request header field. Always returns 1.

Returns 1 for success, 0 for failure.

procedure RemoveParam(name: WideString);

Removes a single HTTP request parameter by name.

Initialize an HTTP Request from a URL

procedure SetFromUrl(url: WideString);

Parses a URL and sets the Path and query parameters (NumParams, GetParam, GetParamName, GetParamValue).

Initialize an HTTP Request from a URL

function StreamBodyFromFile(filePath: WideString): Integer;

Useful for sending HTTP requests where the body is a very large file. For example, to send an XML HttpRequest containing a very large XML document, one would set the HttpVerb = "POST", the ContentType = "text/xml", and then call StreamBodyFromFile to indicate that the XML body of the request is to be streamed directly from a file. When the HTTP request is actually sent, the body is streamed directly from the file, and thus the file never needs to be loaded in its entirety in memory.

Returns 1 for success, 0 for failure.

OneDrive -- Streaming File Upload

function StreamChunkFromFile(path: WideString; offset: WideString; numBytes: WideString): Integer;

Introduced in version 9.5.0.55

This method is the same as StreamBodyFromFile, but allows for an offset and number of bytes to be specified. The offset and numBytes are integers passed as strings.

Returns 1 for success, 0 for failure.

procedure UseGet();

This method is deprecated. It will be removed in a future version.

Makes the HttpRequest a GET request.

Important: This method is deprecated. An application should instead set the HttpVerb property equal to "GET", and the ContentType equal to an empty string (because GET requests have no request body).

procedure UseHead();

This method is deprecated. It will be removed in a future version.

Makes the HttpRequest a HEAD request.

Important: This method is deprecated. An application should instead set the HttpVerb property equal to "HEAD", and the ContentType equal to an empty string (because HEAD requests have no body).

procedure UsePost();

This method is deprecated. It will be removed in a future version.

Makes the HttpRequest a POST request that uses the "application/x-www-form-urlencoded" content type.

Important: This method is deprecated. An application should instead set the HttpVerb property equal to "POST", and the ContentType equal to "application/x-www-form-urlencoded".

procedure UsePostMultipartForm();

This method is deprecated. It will be removed in a future version.

Makes the HttpRequest a POST request that uses the "multipart/form-data" content type.

Important: This method is deprecated. An application should instead set the HttpVerb property equal to "POST", and the ContentType equal to "multipart/form-data".

procedure UsePut();

This method is deprecated. It will be removed in a future version.

Makes the HttpRequest a PUT request.

Important: This method is deprecated. An application should instead set the HttpVerb property equal to "PUT", and the ContentType equal to "application/x-www-form-urlencoded".

procedure UseUpload();

This method is deprecated. It will be removed in a future version.

Makes the HttpRequest a POST request that uses the "multipart/form-data" content type. To create a file upload request, call UseUpload and then call AddFileForUpload for each file to be uploaded.

Important: This method is deprecated. An application should instead set the HttpVerb property equal to "POST", and the ContentType equal to "multipart/form-data".

procedure UseUploadPut();

This method is deprecated. It will be removed in a future version.

Makes the HttpRequest a PUT request that uses the "multipart/form-data" content type. To create a file upload request (using the PUT verb), call UseUploadPut and then call AddFileForUpload for each file to be uploaded.

Important: This method is deprecated. An application should instead set the HttpVerb property equal to "PUT", and the ContentType equal to "multipart/form-data".

procedure UseXmlHttp(xmlBody: WideString);

This method is deprecated. It will be removed in a future version.

Makes the HttpRequest a POST request using the "application/xml" content type. The request body is set to the XML string passed to this method.

Important: This method is deprecated. An application should instead set the HttpVerb property equal to "POST", the ContentType equal to "text/xml", and the request body should contain the XML document text.