HttpRequest Rust Reference Documentation

HttpRequest

Current Version: 11.6.1
Requires Chilkat Bundle License

Chilkat.HttpRequest

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

Build an HTTP request object with the method, path, version, headers, parameters, and body settings required by the target endpoint.

Form parameters

Add name/value parameters for form posts and API requests that expect structured form data.

Custom headers

Set request headers such as content type, accept headers, authorization headers, or application-specific metadata.

Request bodies

Provide body content for POST, PUT, PATCH, or other methods that send data to a server.

Multipart and file uploads

Construct multipart/form-data requests, attach file parts, or stream a file as the request body when the API requires upload content.

Diagnostics

Generate a textual representation of the request to inspect headers, paths, parameters, body structure, and upload formatting before sending.

Common pattern: Create a 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.

For an extended overview, see HttpRequest Class Overview.

Object Creation

// Cargo.toml:
//     [dependencies]
//     chilkat = "11.6"

use chilkat::HttpRequest;

// Once per process, before any other Chilkat call:
chilkat::unlock_bundle("Anything for 30-day trial")?;  // shorthand for Global::new().unlock_bundle(..)

let http_request = HttpRequest::new();
// ... the native object is freed when `http_request` goes out of scope.
pub fn new() -> HttpRequest

Creates the underlying native Chilkat object (HttpRequest also implements Default). Every method takes &self, so the object never needs to be declared mut. A HttpRequest is Send but not Sync: it may be moved to another thread, but a reference to it cannot be shared between threads at the same time.

impl Drop for HttpRequest

The native object is freed when the HttpRequest is dropped — when it goes out of scope, or explicitly with drop(http_request). There is no Dispose method to call.

Errors

Methods that can fail return chilkat::Result<T>, which is Result<T, chilkat::Error>: a method whose only outcome is success or failure returns Result<()>, a method producing a string or an object returns Result<String> or Result<HttpRequest>. The error carries the object's LastErrorText at the time of the failure (Error::last_error_text), the class and method names, and implements std::error::Error, so ? works in any function returning chilkat::Result or a Box<dyn Error>. Properties never fail, and methods that answer a question (has_..., is_..., ...) return a plain bool.

match http_request.some_method(...) {
    Ok(value) => println!("{value:?}"),
    Err(e) => eprintln!("{}", e.last_error_text()),
}

Properties

Boundary
// read/write
pub fn boundary(&self) -> String
pub fn set_boundary(&self, value: &str)
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.

More Information and Examples
HTTP Request Boundary Property
top
Charset
// read/write
pub fn charset(&self) -> String
pub fn set_charset(&self, value: &str)

Controls the character encoding used in the URL encoding of query params. The default value of this propoerty is utf-8.

More Information and Examples
How Charset Matters with HTTP Query ParametersSend HTTP POST using non-UTF8 such as Windows-1250
top
ContentType
// read/write
pub fn content_type(&self) -> String
pub fn set_content_type(&self, value: &str)

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
application/json
application/xml
If ContentType is set equal to the empty string, then no Content-Type header is included in the HTTP request.

More Information and Examples
Building a multipart/form-data Request for HTTP UploadCreating an application/json HTTP POST Request
top
DebugLogFilePath
// read/write
pub fn debug_log_file_path(&self) -> String
pub fn set_debug_log_file_path(&self, value: &str)

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.

More Information and Examples
Example showing how to use DebugLogFilePath.
top
EntireHeader
// read/write
pub fn entire_header(&self) -> String
pub fn set_entire_header(&self, value: &str)

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

top
HttpVerb
// read/write
pub fn http_verb(&self) -> String
pub fn set_http_verb(&self, value: &str)

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.

More Information and Examples
HTTP Verb - How to use any Verb (GET, PUT, POST, DELETE, PROPFIND, etc.)
top
HttpVersion
// read/write
pub fn http_version(&self) -> String
pub fn set_http_version(&self, value: &str)

The HTTP version in the request header. Defaults to 1.1. Can only be set to 1.0 or 1.1.

top
LastErrorHtml
// read-only
pub fn last_error_html(&self) -> String

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.

top
LastErrorText
// read-only
pub fn last_error_text(&self) -> String

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.

More Information and Examples
Concept of LastErrorTextLastErrorText Standard Information
top
LastErrorXml
// read-only
pub fn last_error_xml(&self) -> String

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.

top
LastMethodSuccess
// read/write
pub fn last_method_success(&self) -> bool
pub fn set_last_method_success(&self, value: bool)

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.

top
NumHeaderFields
// read-only
pub fn num_header_fields(&self) -> i32

Returns the number of request header fields.

top
NumParams
// read-only
pub fn num_params(&self) -> i32

Returns the number of query parameters.

More Information and Examples
Initialize an HTTP Request from a URL
top
Path
// read/write
pub fn path(&self) -> String
pub fn set_path(&self, value: &str)

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

More Information and Examples
Explaining the Path Part of a URL
top
SendCharset
// read/write
pub fn send_charset(&self) -> bool
pub fn set_send_charset(&self, value: bool)

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.

More Information and Examples
Send HTTP POST using non-UTF8 such as Windows-1250
top
VerboseLogging
// read/write
pub fn verbose_logging(&self) -> bool
pub fn set_verbose_logging(&self, value: bool)

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.

top
Version
// read-only
pub fn version(&self) -> String

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

More Information and Examples
How to get the Chilkat version at runtime.
top

Methods

AddBdForUpload
pub fn add_bd_for_upload(&self, name: &str, remote_filename: &str, byte_data: &BinData, content_type: &str) -> Result<()>
Introduced in version 9.5.0.76

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 Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Add Data to multipart/form-data Request
top
AddFileForUpload
pub fn add_file_for_upload(&self, name: &str, file_path: &str) -> Result<()>

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 Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
(Facebook) Upload Photo from Local File
top
AddFileForUpload2
pub fn add_file_for_upload2(&self, name: &str, file_path: &str, content_type: &str) -> Result<()>

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 Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
SOAP with MTOM XOP Attachment
top
AddHeader
pub fn add_header(&self, name: &str, value: &str)

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

More Information and Examples
Adding Cookies to an HTTP Request
top
AddMwsSignature
pub fn add_mws_signature(&self, domain: &str, mws_secret_key: &str) -> Result<()>
Introduced in version 9.5.0.66

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 Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
HTTPS MWS List Orders (Amazon Marketplace Web Service)
top
AddParam
pub fn add_param(&self, name: &str, value: &str)

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.

More Information and Examples
Add Parameters to Multipart Form-Data POSTsInitialize an HTTP Request from a URL
top
AddStringForUpload
pub fn add_string_for_upload(&self, name: &str, filename: &str, str_data: &str, charset: &str) -> Result<()>

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

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Building a multipart/form-data Request for HTTP Upload
top
AddStringForUpload2
pub fn add_string_for_upload2(&self, name: &str, filename: &str, str_data: &str, charset: &str, content_type: &str) -> Result<()>

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 Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
HTTP multipart-mixed POST (for a UPS Package Level Detail PLD Request)
top
AddSubHeader
pub fn add_sub_header(&self, index: i32, name: &str, value: &str) -> Result<()>
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 Ok(()) for success, Err(chilkat::Error) for failure.

top
GenerateRequestFile
pub fn generate_request_file(&self, path: &str) -> Result<()>
Introduced in version 9.5.0.64

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

Returns Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Add Data to multipart/form-data Request
top
GenerateRequestText
pub fn generate_request_text(&self) -> Result<String>

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

Returns Err(chilkat::Error) on failure.

top
GetHeaderField
pub fn get_header_field(&self, name: &str) -> Result<String>

Returns the value of a request header field.

Returns Err(chilkat::Error) on failure.

top
GetHeaderName
pub fn get_header_name(&self, index: i32) -> Result<String>

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 Err(chilkat::Error) on failure.

top
GetHeaderValue
pub fn get_header_value(&self, index: i32) -> Result<String>

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 Err(chilkat::Error) on failure.

top
GetParam
pub fn get_param(&self, name: &str) -> Result<String>

Returns a request query parameter value by name.

Returns Err(chilkat::Error) on failure.

top
GetParamName
pub fn get_param_name(&self, index: i32) -> Result<String>

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 Err(chilkat::Error) on failure.

More Information and Examples
Initialize an HTTP Request from a URL
top
GetParamValue
pub fn get_param_value(&self, index: i32) -> Result<String>

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 Err(chilkat::Error) on failure.

More Information and Examples
Initialize an HTTP Request from a URL
top
GetUrlEncodedParams
pub fn get_url_encoded_params(&self) -> Result<String>

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 Err(chilkat::Error) on failure.

More Information and Examples
HTTP multipart-mixed POST (for a UPS Package Level Detail PLD Request)
top
LoadBodyFromBd
pub fn load_body_from_bd(&self, request_body: &BinData) -> Result<()>
Introduced in version 9.5.0.67

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

Returns Ok(()) for success, Err(chilkat::Error) for failure.

top
LoadBodyFromFile
pub fn load_body_from_file(&self, file_path: &str) -> Result<()>

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 Ok(()) for success, Err(chilkat::Error) for failure.

top
LoadBodyFromSb
pub fn load_body_from_sb(&self, request_body: &StringBuilder, charset: &str) -> Result<()>
Introduced in version 9.5.0.67

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 Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Chilkat Supported Character Encodings
top
LoadBodyFromString
pub fn load_body_from_string(&self, body_str: &str, charset: &str) -> Result<()>

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 Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
Creating an application/json HTTP POST Request
top
RemoveAllParams
pub fn remove_all_params(&self)

Removes all request parameters.

More Information and Examples
Demonstrate HttpRequest.RemoveAllParams
top
RemoveHeader
pub fn remove_header(&self, name: &str) -> Result<()>

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

Returns Ok(()) for success, Err(chilkat::Error) for failure.

top
RemoveParam
pub fn remove_param(&self, name: &str)

Removes a single HTTP request parameter by name.

More Information and Examples
Initialize an HTTP Request from a URL
top
SetFromUrl
pub fn set_from_url(&self, url: &str)

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

More Information and Examples
Initialize an HTTP Request from a URL
top
StreamBodyFromFile
pub fn stream_body_from_file(&self, file_path: &str) -> Result<()>

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 Ok(()) for success, Err(chilkat::Error) for failure.

More Information and Examples
OneDrive -- Streaming File Upload
top
StreamChunkFromFile
pub fn stream_chunk_from_file(&self, path: &str, offset: &str, num_bytes: &str) -> Result<()>
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 num_bytes are integers passed as strings.

Returns Ok(()) for success, Err(chilkat::Error) for failure.

top