HttpRequest Lua Reference Documentation
chilkat.HttpRequest
Current Version: 11.7.0
Markdown version of this page for AI tools (v 11.7.0) · all AI docs
Chilkat.HttpRequest
Build an HTTP request object with the method, path, version, headers,
parameters, and body settings required by the target endpoint.
Add name/value parameters for form posts and API requests that expect
structured form data.
Set request headers such as content type, accept headers, authorization
headers, or application-specific metadata.
Provide body content for POST, PUT, PATCH, or other methods that send
data to a server.
Construct multipart/form-data requests, attach file parts, or stream a
file as the request body when the API requires upload content.
Generate a textual representation of the request to inspect headers,
paths, parameters, body structure, and upload formatting before sending.
For an extended overview, see
HttpRequest Class Overview.
Build structured HTTP requests for use with Chilkat.Http.
Chilkat.HttpRequest is a helper class for constructing HTTP
requests that are sent by Chilkat.Http. It does not perform
network communication on its own. Instead, it provides structured control
over the request method, HTTP version, path, headers, query parameters,
form parameters, content type, request body, multipart uploads, streamed
file bodies, and diagnostic request generation.
Request construction
Form parameters
Custom headers
Request bodies
Multipart and file uploads
Diagnostics
HttpRequest, set the HTTP method and path, add any
headers, parameters, body data, or file parts, then pass the request object
to the appropriate Chilkat.Http method for sending. Use
HttpRequest for structured or multipart requests; use simpler
Http methods directly when only a basic GET, POST, upload, or
download is needed.
Object Creation
local chilkat = require("chilkat")
local http_request = chilkat.HttpRequest.new()Creates the object (chilkat.HttpRequest() does the same). Lua's garbage collector frees it when it is no longer referenced; http_request:dispose() frees it at once, and in Lua 5.4 and later local http_request <close> = chilkat.HttpRequest.new() frees it when the block ends. Calling a method of a disposed object raises an error.
Errors
A method that fails returns nil followed by the error text, as io.open does: local body, err = http_request:method(...), where err is the object's last_error_text. Wrap the call in assert() to raise an error with that text instead. Methods that answer a question return true or false, numbers are returned as they are (check last_method_success where the description says a value means failure), and property reads and writes never fail for Chilkat reasons.
Misuse raises a Lua error: a wrong argument type or a missing argument (bad argument #1 to ...), an unknown property name, a write to a read-only property, an out-of-range integer, or an object of the wrong class.
Names are Chilkat's in snake_case: QuickGetStr is quick_get_str, LastErrorText is last_error_text. Properties are fields (http_request.verbose_logging = true) and methods use the colon (http_request:method(...)). Strings are UTF-8; binary data is a Lua string of bytes. Indexes are 0-based, as in every Chilkat API. Unlocking: call chilkat.unlock_bundle("...") once at startup.
Properties
Boundary
local strVal = http_request.boundary
http_request.boundary = strVal
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
local strVal = http_request.charset
http_request.charset = strVal
Controls the character encoding used in the URL encoding of query params. The default value of this propoerty is utf-8.
ContentType
local strVal = http_request.content_type
http_request.content_type = strVal
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
local strVal = http_request.debug_log_file_path
http_request.debug_log_file_path = strVal
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
local strVal = http_request.entire_header
http_request.entire_header = strVal
Composes and returns the entire MIME header of the HTTP request.
topHttpVerb
local strVal = http_request.http_verb
http_request.http_verb = strVal
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
local strVal = http_request.http_version
http_request.http_version = strVal
The HTTP version in the request header. Defaults to 1.1. Can only be set to 1.0 or 1.1.
LastErrorHtml
local strVal = http_request.last_error_html
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
local strVal = http_request.last_error_text
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
local strVal = http_request.last_error_xml
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
local boolVal = http_request.last_method_success
http_request.last_method_success = boolVal
Indicates the success or failure of the most recent method call: true means success, false 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. Note: This property does not apply to methods that return integer values or to boolean-returning methods where the boolean does not indicate success or failure.
NumHeaderFields
local intVal = http_request.num_header_fields
Returns the number of request header fields.
topNumParams
local intVal = http_request.num_params
Path
local strVal = http_request.path
http_request.path = strVal
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
local boolVal = http_request.send_charset
http_request.send_charset = boolVal
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 false.
VerboseLogging
local boolVal = http_request.verbose_logging
http_request.verbose_logging = boolVal
If set to true, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. The default value is false. Verbose logging should only be used for debugging. The potentially large quantity of logged information may adversely affect peformance.
Version
local strVal = http_request.version
Methods
AddBdForUpload
-- remote_filename is a string
-- byte_data is a chilkat.BinData
-- content_type is a string
-- ok is true, or nil and err on failure
local ok, err = http_request:add_bd_for_upload(name, remote_filename, byte_data, content_type)
Adds a file to an upload request where the contents of the file come from byte_data.
name is an arbitrary name. (In HTML, it is the form field name of the input tag.)
remote_filename is the name of the file to be created on the HTTP server.
byte_data contains the bytes to be uploaded.
content_type 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 true on success, nil, err on failure. The second return value, err, is the object's last_error_text; wrap the call in assert() to raise an error instead.
AddFileForUpload
-- file_path is a string
-- ok is true, or nil and err on failure
local ok, err = http_request:add_file_for_upload(name, file_path)
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.)
file_path is the path to an existing file in the local filesystem.
Returns true on success, nil, err on failure. The second return value, err, is the object's last_error_text; wrap the call in assert() to raise an error instead.
AddFileForUpload2
-- file_path is a string
-- content_type is a string
-- ok is true, or nil and err on failure
local ok, err = http_request:add_file_for_upload2(name, file_path, content_type)
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.)
file_path is the path to an existing file in the local filesystem.
Returns true on success, nil, err on failure. The second return value, err, is the object's last_error_text; wrap the call in assert() to raise an error instead.
AddHeader
-- value is a string
http_request:add_header(name, value)
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
-- mws_secret_key is a string
-- ok is true, or nil and err on failure
local ok, err = http_request:add_mws_signature(domain, mws_secret_key)
Computes the Amazon MWS signature using the mws_secret_key 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 true on success, nil, err on failure. The second return value, err, is the object's last_error_text; wrap the call in assert() to raise an error instead.
AddParam
-- value is a string
http_request:add_param(name, value)
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
-- filename is a string
-- str_data is a string
-- charset is a string
-- ok is true, or nil and err on failure
local ok, err = http_request:add_string_for_upload(name, filename, str_data, charset)
Same as AddFileForUpload, but the upload data comes from an in-memory string instead of a file.
Returns true on success, nil, err on failure. The second return value, err, is the object's last_error_text; wrap the call in assert() to raise an error instead.
AddStringForUpload2
-- filename is a string
-- str_data is a string
-- charset is a string
-- content_type is a string
-- ok is true, or nil and err on failure
local ok, err = http_request:add_string_for_upload2(name, filename, str_data, charset, content_type)
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 true on success, nil, err on failure. The second return value, err, is the object's last_error_text; wrap the call in assert() to raise an error instead.
AddSubHeader
-- name is a string
-- value is a string
-- ok is true, or nil and err on failure
local ok, err = http_request:add_sub_header(index, name, value)
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 true on success, nil, err on failure. The second return value, err, is the object's last_error_text; wrap the call in assert() to raise an error instead.
GenerateRequestFile
-- ok is true, or nil and err on failure
local ok, err = http_request:generate_request_file(path)
The same as GenerateRequestText, except the generated request is written to the file specified by path.
Returns true on success, nil, err on failure. The second return value, err, is the object's last_error_text; wrap the call in assert() to raise an error instead.
GenerateRequestText
local str, err = http_request:generate_request_text()
Returns the request text that would be sent if Http.SynchronousRequest was called.
Returns the string, or nil, err on failure (or when nothing is found). The second return value, err, is the object's last_error_text; wrap the call in assert() to raise an error instead.
GetHeaderField
-- str is a string, or nil and err on failure
local str, err = http_request:get_header_field(name)
Returns the value of a request header field.
Returns the string, or nil, err on failure (or when nothing is found). The second return value, err, is the object's last_error_text; wrap the call in assert() to raise an error instead.
GetHeaderName
-- str is a string, or nil and err on failure
local str, err = http_request:get_header_name(index)
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 the string, or nil, err on failure (or when nothing is found). The second return value, err, is the object's last_error_text; wrap the call in assert() to raise an error instead.
GetHeaderValue
-- str is a string, or nil and err on failure
local str, err = http_request:get_header_value(index)
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 the string, or nil, err on failure (or when nothing is found). The second return value, err, is the object's last_error_text; wrap the call in assert() to raise an error instead.
GetParam
-- str is a string, or nil and err on failure
local str, err = http_request:get_param(name)
Returns a request query parameter value by name.
Returns the string, or nil, err on failure (or when nothing is found). The second return value, err, is the object's last_error_text; wrap the call in assert() to raise an error instead.
GetParamName
-- str is a string, or nil and err on failure
local str, err = http_request:get_param_name(index)
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 the string, or nil, err on failure (or when nothing is found). The second return value, err, is the object's last_error_text; wrap the call in assert() to raise an error instead.
GetParamValue
-- str is a string, or nil and err on failure
local str, err = http_request:get_param_value(index)
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 the string, or nil, err on failure (or when nothing is found). The second return value, err, is the object's last_error_text; wrap the call in assert() to raise an error instead.
GetUrlEncodedParams
local str, err = http_request:get_url_encoded_params()
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 the string, or nil, err on failure (or when nothing is found). The second return value, err, is the object's last_error_text; wrap the call in assert() to raise an error instead.
LoadBodyFromBd
-- ok is true, or nil and err on failure
local ok, err = http_request:load_body_from_bd(request_body)
Uses the contents of the request_body as the HTTP request body.
Returns true on success, nil, err on failure. The second return value, err, is the object's last_error_text; wrap the call in assert() to raise an error instead.
LoadBodyFromFile
-- ok is true, or nil and err on failure
local ok, err = http_request:load_body_from_file(file_path)
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 file_path.
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 true on success, nil, err on failure. The second return value, err, is the object's last_error_text; wrap the call in assert() to raise an error instead.
LoadBodyFromSb
-- charset is a string
-- ok is true, or nil and err on failure
local ok, err = http_request:load_body_from_sb(request_body, charset)
Uses the contents of the request_body 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 true on success, nil, err on failure. The second return value, err, is the object's last_error_text; wrap the call in assert() to raise an error instead.
LoadBodyFromString
-- charset is a string
-- ok is true, or nil and err on failure
local ok, err = http_request:load_body_from_string(body_str, charset)
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 body_str.
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 body_str converted to this character encoding.
Returns true on success, nil, err on failure. The second return value, err, is the object's last_error_text; wrap the call in assert() to raise an error instead.
RemoveAllParams
RemoveHeader
-- ok is true, or nil and err on failure
local ok, err = http_request:remove_header(name)
Removes all occurrences of a HTTP request header field. Always returns true.
Returns true on success, nil, err on failure. The second return value, err, is the object's last_error_text; wrap the call in assert() to raise an error instead.
RemoveParam
http_request:remove_param(name)
SetFromUrl
http_request:set_from_url(url)
Parses a URL and sets the Path and query parameters (NumParams, GetParam, GetParamName, GetParamValue).
StreamBodyFromFile
-- ok is true, or nil and err on failure
local ok, err = http_request:stream_body_from_file(file_path)
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 true on success, nil, err on failure. The second return value, err, is the object's last_error_text; wrap the call in assert() to raise an error instead.
StreamChunkFromFile
-- offset is a string
-- num_bytes is a string
-- ok is true, or nil and err on failure
local ok, err = http_request:stream_chunk_from_file(path, offset, num_bytes)
This method is the same as StreamBodyFromFile, but allows for an offset and number of bytes to be specified. The offset and num_bytes are integers passed as strings.
Returns true on success, nil, err on failure. The second return value, err, is the object's last_error_text; wrap the call in assert() to raise an error instead.