Method HttpClient():setOption() Foundation

Changes a HttpClient option.

:setOption( <cName>[, <xValue>] ) --> self
<cName> is a character string identifying an option.
The expression <xValue> specifies the value for a option. The data type and value is dependent on the HttpClient option designated by <cName>.

:setOption() returns the object executing the method.


The method :setOption() changes a HttpClient option. The option is identified by the character string passed in the parameter <cName>. The method :setOption() must be called before one of the methods :send(), :sendAsync() or :getFile() is executed for the first time. Afterwards, the options can no longer be changed.

The following table lists the valid options and their respective values.

Available options
Option-Name Value *) Description
disable-redirect n/a Disables automatic redirects.
secure-protocol "ssl-2.0", "ssl-3.0", "tls-1.0", "tls-1.1", "tls-1.2", "tls-1.3" Enforces a specific Transport Layer Security protocol for communication.
ignore-cert-error "ignore-name", "ignore-date", "ignore-authority", "ignore-role", "ignore-all" Specifies how server certificates are validated.
status-100-timeout numeric Timeout in milliseconds before the body of the http request is sent after the header.
  1. n/a indicates no xValue parameter required


Disables automatic redirects. By default, HTTP clients automatically follow redirects by re-sending the request to the redirected address. If redirect is disabled, it cannot be enabled without creating a new HttpClient object.


By default, all secure protocols of the operating system are offered to the server. Using the "secure-protocol" option, the offered secure protocols can be restricted to either a single or a specific set of desired secure protocols. In order to enforce usage of a single secure protocol, a character string with the desired TLS protocol version must be passed in the <xValue> parameter. If the communication is to be limited to more than one TLS protocol version, the desired versions must be passed in an array. Example: {"tls-1.1","tls-1.2"}


By default, a connection is aborted if a secure protocol is being used and the server uses an invalid SSL certificate. With the option "ignore-cert-error", an application can override this behavior by instructing the HttpClient object to ignore certain certificate errors, allowing the connection to be established even if the server's certificate does not meet all security requirements. Ignoring invalid server certificates is not recommended in production. However, invalid or self-signed certificates are sometimes used in development or testing.

In order to have an HttpClient instance ignore a certificate error when validating a certificate, the corresponding value must be specified in the <xValue> parameter. If more than one value is to be set for the "ignore-cert-error" option, these values must be passed in an array. Example: {"ignore-name", "ignore-date"}. The following table lists the available options:

Value Description
"ignore-all" Combines all other values
"ignore-name" Allow an invalid common name in a certificate
"ignore-date" Allow an invalid certificate date
"ignore-authority" Allow an invalid certificate authority
"ignore-role" Allow non-server certificates (eg. client certificates)


When a HTTP request includes an "Expect: 100-continue" header, this prompts the server to send an intermediate HTTP status code of 100 to indicate that the server is prepared to accept the request's body. The option "status-100-timeout" allows configuration of how long the client should wait after sending the header before transmitting the request body.

By default, if an "Expect: 100-continue" header is included in the request and no timeout is explicitly set via :setOption(), the client will wait for 1000 milliseconds (1 second) after sending the header before it begins to send the request body. This default behavior ensures that the client does not send large amounts of data prematurely, that is, before the server has indicated its readiness to receive it.

The "status-100-timeout" option can be used to adjust this waiting period. Setting this option to 0 milliseconds instructs the client to send the request body immediately after the header, without waiting for the 100 status code response. The option provides flexibility in handling server responses, particularly in situations where the server's behavior is known in advance or when optimizing for network conditions.


If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.