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. MATLAB supports
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 of root certificates
File name of root certificates, specified as a string or character vector denoting the
location of a file containing certificates. The file is 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. If you specify the value
CertificateFilename is set to the
path of the certificate file that ships with MATLAB. To determine the path, create an empty
HTTPOptions object and look at the default value of
If you request an HTTPS connection, then the certificate from the server is validated
against the certification authority certificates in the PEM file. Standard HTTPS mechanisms
use this validation to validate the signature on the server certificate and the entire
certificate chain. If verification fails, a connection is not allowed. You can disable the
verification in cases where the server's certificate does not match the URI used to access
it, by creating a
matlab.net.http.RequestMessage and setting the
matlab.net.http.HTTPOptions.VerifyServerName property to
false. Use this option if you are confident that you are
communicating directly with the intended server.
To add certificates to
rootcerts.pem, copy the file to a working
folder, edit the file, and add your certificates to it. PEM files are ASCII files which are
easily modified. Since security of HTTPS connections depends on the integrity of this file,
protect it appropriately. MATLAB does not manage certificates or certificate files, but there are third-party
tools for managing PEM files.
CertificateFilename is empty, then MATLAB checks if the certificate domain of the server matches the host name of the
server and that it is not expired. The signature is not validated.
CertificateFilename to empty (
'') only if you
cannot establish a connection due to a missing or expired certificate.
ConnectTimeout— Seconds to wait for initial server connection
Seconds to wait for initial server connection, specified as an integer. 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 before throwing an error. This timeout does not limit
how long it takes to receive a complete response.
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
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 message 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 data is encoded,
MessageBody.Payload property contains the raw unencoded
MessageBody.Data property remains empty.
No conversion occurs, regardless of the setting of the
Credentials— Authentication credentials
Authentication credentials, specified as a vector of
used only if the
Authenticate property is true.
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.
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.
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.
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 timeout 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);