HttpRequest ActiveX Reference Documentation
HttpRequest
Current Version: 10.1.2
Represents a complete HTTP request.
Object Creation
Note: For versions of Chilkat < 10.0.0, use "Chilkat_9_5_0.HttpRequest" instead of "Chilkat.HttpRequest" For a specific major version, use "Chilkat.HttpRequest.<major_version>", such as "Chilkat.HttpRequest.10" for Chilkat v10.*.* See Chilkat ActiveX Object Creation (ASP) set obj = Server.CreateObject("Chilkat.HttpRequest") (AutoIt) $obj = ObjCreate("Chilkat.HttpRequest") (Visual Basic 6.0) Dim obj As New ChilkatHttpRequest (VBScript) set obj = CreateObject("Chilkat.HttpRequest") (Delphi) obj := TChilkatHttpRequest.Create(Self); (FoxPro) loObject = CreateObject('Chilkat.HttpRequest') (PowerBuilder) lole_object = create oleobject li_rc = lole_object.ConnectToNewObject("Chilkat.HttpRequest") (SQL Server) EXEC @hr = sp_OACreate 'Chilkat.HttpRequest', @obj OUT (Javascript) var obj = new ActiveXObject("Chilkat.HttpRequest");
Properties
Boundary
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.
Charset
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.
ContentType
The ContentType property sets the "Content-Type" header field, and identifies the content-type of the HTTP request body. Common values are:
If ContentType is set equal to the empty string, then no Content-Type header is included in the HTTP request.application/x-www-form-urlencoded multipart/form-data application/json application/xml
DebugLogFilePath
If set to a file path, this property logs the LastErrorText of each Chilkat method or property call to the specified file. This logging helps identify the context and history of Chilkat calls leading up to any crash or hang, aiding in debugging.
Enabling the VerboseLogging property provides more detailed information. This property is mainly used for debugging rare instances where a Chilkat method call causes a hang or crash, which should generally not happen.
Possible causes of hangs include:
- A timeout property set to 0, indicating an infinite timeout.
- A hang occurring within an event callback in the application code.
- An internal bug in the Chilkat code causing the hang.
EntireHeader
Composes and returns the entire MIME header of the HTTP request.
topHttpVerb
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.
HttpVersion
The HTTP version in the request header. Defaults to "1.1". Can only be set to "1.0" or "1.1".
topLastBinaryResult
This property is mainly used in SQL Server stored procedures to retrieve binary data from the last method call that returned binary data. It is only accessible if Chilkat.Global.KeepBinaryResult is set to 1. This feature allows for the retrieval of large varbinary results in an SQL Server environment, which has restrictions on returning large data via method calls, though temp tables can handle binary properties.
topLastErrorHtml
Provides HTML-formatted information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.
topLastErrorText
Provides plain text information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.
LastErrorXml
Provides XML-formatted information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.
topLastMethodSuccess
Indicates the success or failure of the most recent method call: 1 means success, 0 means failure. This property remains unchanged by property setters or getters. This method is present to address challenges in checking for null or Nothing returns in certain programming languages.
topLastStringResult
In SQL Server stored procedures, this property holds the string return value of the most recent method call that returns a string. It is accessible only when Chilkat.Global.KeepStringResult is set to TRUE. SQL Server has limitations on string lengths returned from methods and properties, but temp tables can be used to access large strings.
LastStringResultLen
The length, in characters, of the string contained in the LastStringResult property.
topNumHeaderFields
Returns the number of request header fields.
topNumParams
Returns the number of query parameters.
Path
The path of the resource requested. A path of "/" indicates the default document of a domain.
Explaining the Parts of a URL
http://example.com:8042/over/there?name=ferret#nose \__/ \______________/\_________/ \________/ \__/ | | | | | scheme domain+port path query fragment
This property should be set to the path part of the URL. You may also include the query part in this property value. If the Content-Type of the request is NOT application/x-www-form-urlencoded, then you would definitely want to include query parameters in the path. If the Content-Type of the request IS application/x-www-form-urlencoded, the query parameters are passed in the body of the request. It is also possible to pass some query parameters via the path, and some in the body of a application/x-www-form-urlencoded request, but you shouldn't include the same parameter in both places. You would never need to include the fragment part. The fragment is nothing more than an instruction for a browser to automatically navigate to a particular location in the HTML page (assuming the request returns HTML, otherwise a fragment makes no sense).
SendCharset
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.
VerboseLogging
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.
topVersion
Version of the component/library, such as "10.1.0"
Methods
AddBdForUpload
Adds a file to an upload request where the contents of the file come from byteData.
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 bytes to be uploaded.
contentType contains is the value of the Content-Type header. An empty string may be passed to allow Chilkat to automatically determine the Content-Type based on the filename extension.
Returns 1 for success, 0 for failure.
AddBytesForUpload
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, set the ContentType property = "multipart/form-data" 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.
topAddBytesForUpload2
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.
topAddFileForUpload
Adds a file to an upload request. To create a file upload request, set the ContentType property = "multipart/form-data" 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.
AddFileForUpload2
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.
AddHeader
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.)
AddMwsSignature
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.
Important: The Chilkat v9.5.0.75 release accidentally breaks Amazon MWS (not AWS) authentication. If you need MWS with 9.5.0.75, send email to support@chilkatsoft.com for a hotfix, or revert back to v9.5.0.73, or update to a version after 9.5.0.75.
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.
AddParam
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.
AddStringForUpload
Same as AddFileForUpload, but the upload data comes from an in-memory string instead of a file.
Returns 1 for success, 0 for failure.
AddStringForUpload2
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.
AddSubHeader
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.
topGenerateRequestFile
The same as GenerateRequestText, except the generated request is written to the file specified by path.
Returns 1 for success, 0 for failure.
GenerateRequestText
Returns the request text that would be sent if Http.SynchronousRequest was called.
Returns Nothing on failure
topGetHeaderField
GetHeaderName
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 Nothing on failure
topGetHeaderValue
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 Nothing on failure
topGetParam
GetParamName
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 Nothing on failure
GetParamValue
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 Nothing on failure
GetUrlEncodedParams
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¶m2=abc%2D123"
Returns Nothing on failure
LoadBodyFromBd
Uses the contents of the requestBody as the HTTP request body.
Returns 1 for success, 0 for failure.
topLoadBodyFromBytes
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.
topLoadBodyFromFile
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.
topLoadBodyFromSb
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.
LoadBodyFromString
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.
RemoveAllParams
Removes all request parameters.
RemoveHeader
Removes all occurrences of a HTTP request header field. Always returns 1.
Returns 1 for success, 0 for failure.
topRemoveParam
Removes a single HTTP request parameter by name.
SetFromUrl
Parses a URL and sets the Path and query parameters (NumParams, GetParam, GetParamName, GetParamValue).
StreamBodyFromFile
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.
StreamChunkFromFile
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.
top