Options controlling HTTP message exchange
HTTPOptions class to create options for HTTP request messages. Use
this object to specify options that are constant across several requests.
obj = matlab.net.http.HTTPOptions creates HTTP options with
default property values.
obj = matlab.net.http.HTTPOptions(Name,Value) creates HTTP
options with additional properties specified by one or more name-value pair arguments.
Name is the property name and
Value is the
corresponding value. You can specify several name-value pair arguments in any order as
Name1,Value1,...,NameN,ValueN. Unspecified properties are set to
their default values.
Authenticate— Whether Credentials used for authentication
Whether Credentials are used for authentication, specified as
Authenticate is true, then implement the supported
authentication method requested by the server or proxy. The authentication is based on
Credentials property and the proxy user name and password set
Web Preferences, if
any. For information about MATLAB authentication support, see Server Authentication.
The response message contains the server or proxy authentication challenge when any of these conditions exist.
Authenticate is false.
Credentials properties are found for this
CertificateFilename— File name
'default'(default) | string | character vector
File name, specified as a string scalar or character vector denoting the name and location of a file containing root certificates. The file must be in privacy-enhanced mail (PEM) format. The location must be in the current folder, in a folder on the MATLAB path, or a full or relative path to a file. The certificates contained in this file are used to validate server certificates for HTTPS connections. Since the security of HTTPS connections depends on the integrity of this file, please protect it appropriately. MATLAB does not manage certificates or certificate files, but there are third-party tools available for managing PEM files.
By default when options are not specified, MATLAB validates server certificates using the system-provided certificate store.
This is also the behavior if
CertificateFilename is set to
CertificateFilename is empty (
''), then the
validation of the server certificate is turned off. MATLAB only verifies that the domain name of the server certificate matches that of
If you encounter a server certificate validation failure using
'default', then check the connection using your system
If you encounter a connection issue, consider the following:
For an expired or revoked server certificate, contact the website owner or server administrator.
For a missing Root CA certificate, you can choose one of the following:
Add the Root CA certificate to the file denoted by
Disable certificate validation by setting
CertificateFilename to empty
For a mismatch between the domain name of the server certificate and the domain
name of the server, you can disable this validation by creating a
matlab.net.http.RequestMessage object and setting the
matlab.net.http.HTTPOptions.VerifyServerName property to
These options are temporary workarounds and MathWorks strongly recommends that you resolve the root cause of any server certificate validation failure by using a valid/correct server certificate.
ConnectTimeout— Seconds to wait for initial server connection
Seconds to wait for initial server connection, specified as an integer. If a proxy is involved, the timeout applies to the connection to the proxy; otherwise it applies to the connection to the server.
The default is 10 seconds. If the timeout period is exceeded, then
ConnectTimeout throws an error. To disable timeouts, set
ConnectTimeout determines how long to wait to complete a
connection attempt with a server or proxy before throwing an error. This timeout does
not limit how long it takes to receive a complete response.
When sending a request to a server through a proxy, consider using ResponseTimeout to limit the wait time.
Some operating systems have a maximum timeout enforced by the system. This timeout
takes effect even if the value of
ConnectTimeout is greater than
the maximum. For example, on Windows® 10, this timeout is 21 seconds.
ConvertResponse— How to process raw payload from server
How to process raw payload received from a server in a
ResponseMessage, specified as
ConvertResponse is true, then
ContentConsumer is specified, then
uint8 payload is passed to the
for further processing.
Otherwise, MATLAB converts the payload in the
property to MATLAB data based on the Content-Type in the response message. See the
property for conversion rules. If the conversion is successful, then
Data contains the converted data and
Payload is empty.
ConvertResponse is false, then any specified
ContentConsumer is ignored and the behavior depends on whether the
Content-Type specifies character data.
If the Content-Type has an explicit or default charset attribute, then the
payload is converted to text and stored in
Data without further
If the Content-Type does not specify character data or there is no charset, and
MATLAB does not support the Content-Type, then
contains the raw
In all cases, the
Payload property is deleted unless you also
SavePayload property to
ConvertResponse is ignored if the message was encoded
(compressed) and one of these:
DecodeResponse property is false
DataTimeout— Seconds to wait between data packets
Inf(default) | integer
Seconds to wait between data packets on the network, specified as an integer. The
default value is
Inf, meaning no timeout. This timeout, enforced once
an initial connection is established, is useful for communications with potentially slow
servers. If this timeout is exceeded while waiting to send or receive the next expected
packet, then MATLAB closes the connection and throws an error. In this case, use the
History property to obtain any partial data.
DecodeResponse— Whether to decode compressed data
Whether to decode compressed data, specified as
false. Decoding means to decompress (decode) the response payload
when the server returns compressed (encoded) data. Decoding occurs before conversion
based on the Content-Type field.
A response is encoded when there is a Content-Encoding field that specifies a
compression algorithm. MATLAB supports content coding values
deflate. The value
identity means that there is no encoding, which is equivalent to
the message having no Content-Encoding field. If MATLAB does not support the Content-Encoding type, decoding does not occur even
DecodeResponse is true.
DecodeResponse is false and the payload is encoded,
MessageBody.Payload property contains the raw unencoded
MessageBody.Data property remains empty.
No conversion occurs, regardless of the setting of the
Do not set this value to false for compressed responses if you are using a
ContentConsumer that cannot process compressed data, unless you also
ConvertResponse to false to suppress use of the consumer.
BinaryConsumer are the only consumers
provided by MATLAB that can process compressed data.
Credentials— Authentication credentials
matlab.net.http.Credentials(default) | vector of
matlab.net.http.Credentialsobjects | empty
Authentication credentials, specified as one or more
matlab.net.http.Credentials objects. The default value is a default
matlab.net.http.Credentials object. Use a default
Credentials object to allow authentication for schemes such as Kerberos
and NTLM on Windows. These schemes do not require specifying a user name or password.
Credentials are used only if the
Authenticate property is true. You must specify at least one
Credentials object for authentication to take place. If you set
Credentials to empty, then no authentication takes place.
When you access the same server multiple times during a session, for maximum
performance specify the same
Credentials vector or same
HTTPOptions object for each request.
contains cached information that speeds up subsequent authentications.
If you provide
Credentials for use with a proxy, and you want
Credentials to override a different user name and
password specified in the Web Preferences in the
Preferences window, then specify the host and port of the proxy in the
ProxyURI property of this
HTTPOptions object or clear the Use a proxy
with authentication option in the Preferences window.
KeepAliveTimeout— Seconds to keep server connection open
Seconds to keep a server connection open after the initial connect, specified as
Inf. Use this property to enable
multiple successive messages to be sent over the same connection. An
Inf value (the default) enables persistent connections, keeping the
connection open as long as the server is able. A value of
the connection after each message. Other values are not supported.
KeepAliveTimeout property has no effect on success of an
operation. MATLAB always keeps the connection open long enough to get the expected response
from the server, unless other timeouts are exceeded. However, a
value can seriously affect performance of sending many short messages to the same
MaxRedirects— Number of redirects allowed
Number of redirects allowed, specified as an integer for a given request. The
default number of redirects is 20. Set to 0 to disable redirection. Set to
Inf to allow unlimited redirections.
MaxRedirects is nonzero, then cookies received from the
server in each redirect response are copied into the redirected message. After
MaxRedirects, the response message contains the next redirect
ProgressMonitorFcn— Progress monitor handler
Progress monitor handler, specified as a function handle to a
matlab.net.http.ProgressMonitor object. If
UseProgressMonitor is true, then MATLAB calls the
ProgressMonitor function to report the progress
of a transfer. If
UseProgressMonitor is false or
ProgressMonitorFcn is empty, then no progress is reported.
ProxyURI— Proxy server address
Proxy server address, specified as a
matlab.net.URI object or a string of the form
ProxyURI is used only if the
property is true.
ProxyURI overrides the proxy specified in
MATLAB Web Preferences and any proxy set in Windows system settings.
ResponseTimeout— Seconds to wait to receive initial response
Inf(default) | integer
Seconds to wait to receive the initial response (header) from the server after
sending the last packet of a request, specified as an integer. The default value is
Inf, meaning no timeout. If this timeout is exceeded, then
MATLAB closes the connection and throws an error.
ResponseTimeout to limit the wait time when sending a
request to a server through a proxy, since
applies to the proxy connection time.
ResponseTimeout is equivalent to the
Timeout property set by
SavePayload— Whether Payload saved
Whether Payload is saved, specified as
false. The payload is the raw bytes received from or sent to the
server, saved in the
In a request message, setting
true saves the payload after data conversion. In a response
message, the bytes are saved before conversion.
SavePayload as a debugging tool. For example, the server
cannot process the body of a request, or there is a failure converting a response body
to a MATLAB type. Setting
might consume a considerable amount of memory because the payload is at least equal to
the size of the converted data.
To retrieve the response payload without conversion, set the
ConvertResponse property to
false and read
HTTPException occurs during message processing, then the
payload received up to the point of failure is in
RequestMessage.Body is a
ContentProvider object, then MATLAB saves the provider's converted data in
UseProgressMonitor— Whether to display progress
Whether to display progress, specified as
true to report progress of a transfer using the function specified
UseProxy— Whether using proxy
Whether using a proxy, specified as
UseProxy is true, then MATLAB selects the first one of these proxies.
The value in the
ProxyURI property, if any.
The proxy specified in MATLAB Web Preferences, if any.
The proxy specified in your system preferences (Windows only).
All requests go directly to the destination URI without a proxy when any of the following is true.
UseProxy is false.
UseProxy is true but
ProxyURI is empty
and there is no proxy set in preferences.
MATLAB automatically diverts a message to a proxy when
UseProxy is true.
VerifyServerName— Whether server name matches certificate
Whether server name matches certificate, specified as
In a secure connection using
https protocol, MATLAB verifies that the name of the server in the certificate matches
Host property in the URI of the request, or in the URI of the
latest redirect request. This verification ensures that you are communicating with the
intended server. To disable the verification in cases where the server certificate does
not match the URI used to access it, set this property to false. For example, you want
to access the server using an IP address or "localhost" and you are confident that you
are communicating directly with the intended server.
Increase connection time out to 20 seconds.
Change the default timeout option for the request message specified in the variable
request sent to the server specified in the variable
options = matlab.net.http.HTTPOptions('ConnectTimeout',20); response = request.send(url,options);