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
the corresponding value. You can specify several name-value pair arguments in
any order as
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 the
and the proxy user name and password set in MATLAB® 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.
are found for this request.
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
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
ConvertResponse— Whether to convert to MATLAB type
Whether to convert to MATLAB type, specified as
false. If a
specified, then the consumer is called to convert the data.
ConvertResponse is true, then MATLAB converts the raw
uint8 payload in the
MessageBody.Payload property to MATLAB data based on the Content-Type in the response message. See
the Data property for conversion rules. If the
conversion is successful, then
Data contains the
converted data and
Payload is empty.
ConvertResponse is false and there is no
ContentConsumer, then 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
If the Content-Type does not specify character data
or there is no charset, and MATLAB does not support the Content-Type,
Data contains the raw
In all cases, the
Payload property is deleted
unless you also set the
ConvertResponse is ignored if:
The message was encoded (compressed) and decoding failed.
DecodeResponse property is
DecodeResponse— Whether to decode compressed data
Whether to decode compressed data, specified as
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
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 if
DecodeResponse is false and the data
is encoded, then:
contains the raw unencoded payload.
No conversion occurs, regardless of the setting of
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
HTTPOptions object for each request.
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
response message contains the next redirect message.
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
ProgressMonitorFcn is empty, then no progress
ProxyURI— Proxy server address
Proxy server address, specified as a
or a string of the form
ProxyURI is used only if the
ProxyURI overrides the proxy specified
in MATLAB Web Preferences and any proxy set in Windows® system
SavePayload— Whether Payload saved
Whether Payload is saved, specified as
The payload is the raw bytes received from or sent to the server,
saved in the
In a request message, setting
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
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
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
report progress of a transfer using the function specified by the
UseProxy— Whether using proxy
Whether using a proxy, specified as
UseProxy is true, then MATLAB selects
the first one of the following proxies:
The value in the
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 are true.
UseProxy is false.
UseProxy is true but
empty and there is no proxy set in preferences.
MATLAB automatically diverts a message to a proxy when
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 MATLAB certificate
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
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
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
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 the
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);