matlab.net.http.HTTPOptions Class
Namespace: matlab.net.http
Options controlling HTTP message exchange
Description
Use the HTTPOptions
class to create options for HTTP request messages. Use
this object to specify options that are constant across several requests.
Creation
Description
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.
Properties
Authenticate
— Whether Credentials used for authentication
true
(default) | false
Whether Credentials are used for authentication, specified as
true
or false
.
If Authenticate
is true, then implement the supported
authentication method requested by the server or proxy. The authentication is based on
the Credentials
property and the proxy user name and password set
in MATLAB®
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.No appropriate
Credentials
properties are found for this request.Authentication fails.
Attributes:
GetAccess | public |
SetAccess | public |
Data Types: logical
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
'default'
.
If 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
the server.
If you encounter a server certificate validation failure using
'default'
, then check the connection using your system
browser.
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
CertificateFilename
.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 thematlab.net.http.HTTPOptions.VerifyServerName
property tofalse
.
Note
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.
Attributes:
GetAccess | public |
SetAccess | public |
Data Types: char
| string
ConnectTimeout
— Seconds to wait for initial server connection
10 (default) | nonnegative real | Inf
Seconds to wait for initial server connection, specified as nonnegative real. 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
to Inf
.
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.
Attributes:
GetAccess | public |
SetAccess | public |
ConvertResponse
— How to process raw payload from server
true
(default) | false
How to process raw payload received from a server in a
ResponseMessage
, specified as true
or
false
.
If ConvertResponse
is true, then
If a
ContentConsumer
is specified, then theuint8
payload is passed to theContentConsumer
for further processing.Otherwise, MATLAB converts the 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, thenData
contains the converted data andPayload
is empty.
If 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 processing.If the Content-Type does not specify character data or there is no charset, and MATLAB does not support the Content-Type, then
Data
contains the rawuint8
payload.
In all cases, the Payload
property is deleted unless you also
set the SavePayload
property to true
.
ConvertResponse
is ignored if the message was encoded
(compressed) and one of these:
Decoding failed
DecodeResponse
property is false
Attributes:
GetAccess | public |
SetAccess | public |
Data Types: logical
DataTimeout
— Seconds to wait between data packets
Inf
(default) | nonnegative real
Seconds to wait between data packets on the network, specified as nonnegative real.
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 matlab.net.http.HTTPException
History
property to obtain any partial data.
Attributes:
GetAccess | public |
SetAccess | public |
DecodeResponse
— Whether to decode compressed data
true
(default) | false
Whether to decode compressed data, specified as true
or
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 gzip
,
x-gzip
, and 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 true.
If DecodeResponse
is false and the payload is encoded,
then:
The
MessageBody.Payload
property contains the raw unencoded payload.The
MessageBody.Data
property remains empty.No conversion occurs, regardless of the setting of the
ConvertResponse
property.
Do not set this value to false for compressed responses if you are using a
ContentConsumer
that cannot process compressed data, unless you also
set ConvertResponse
to false to suppress use of the consumer.
FileConsumer
and BinaryConsumer
are the only consumers
provided by MATLAB that can process compressed data.
Attributes:
GetAccess | public |
SetAccess | public |
Data Types: logical
Credentials
— Authentication credentials
matlab.net.http.Credentials
(default) | vector of matlab.net.http.Credentials
objects | 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. Credentials
contains cached information that speeds up subsequent authentications.
If you provide Credentials
for use with a proxy, and you want
those 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.
Attributes:
GetAccess | public |
SetAccess | public |
KeepAliveTimeout
— Seconds to keep server connection open
Inf
(default) | 0
Seconds to keep a server connection open after the initial connect, specified as
0
or 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 0
closes
the connection after each message. Other values are not supported.
The 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 0
value can seriously affect performance of sending many short messages to the same
server.
Attributes:
GetAccess | public |
SetAccess | public |
MaxRedirects
— Number of redirects allowed
20 (default) | 0 | integer | Inf
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.
If 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
message.
Attributes:
GetAccess | public |
SetAccess | public |
ProgressMonitorFcn
— Progress monitor handler
function handle | empty
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.
Attributes:
GetAccess | public |
SetAccess | public |
Data Types: function_handle
ProxyURI
— Proxy server address
empty (default) | matlab.net.URI
| string
Proxy server address, specified as a matlab.net.URI
object or a string of the form host:port
or
//host:port
.
ProxyURI
is used only if the UseProxy
property is true. ProxyURI
overrides the proxy specified in
MATLAB Web Preferences and any proxy set in Windows system settings.
Attributes:
GetAccess | public |
SetAccess | public |
ResponseTimeout
— Seconds to wait to receive initial response
Inf
(default) | nonnegative real
Seconds to wait to receive the initial response (header) from the server after
sending the last packet of a request, specified as nonnegative real. The default value
is Inf
, meaning no timeout. If this timeout is exceeded, then
MATLAB closes the connection and throws an error.
Use ResponseTimeout
to limit the wait time when sending a
request to a server through a proxy, since ConnectTimeout
only
applies to the proxy connection time.
ResponseTimeout
is equivalent to the
Timeout
property set by weboptions
.
Attributes:
GetAccess | public |
SetAccess | public |
SavePayload
— Whether Payload saved
false
(default) | true
Whether Payload is saved, specified as true
or
false
. The payload is the raw bytes received from or sent to the
server, saved in the MessageBody.Payload
property.
In a request message, setting SavePayload
to
true
saves the payload after data conversion. In a response
message, the bytes are saved before conversion.
Use 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 SavePayload
to true
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
MessageBody.Data
instead.
If an HTTPException
occurs during message processing, then the
payload received up to the point of failure is in
HTTPException.History(end).Response.Body.Payload
.
If RequestMessage.Body
is a ContentProvider
object, then MATLAB saves the provider's converted data in
Body.Payload
.
Attributes:
GetAccess | public |
SetAccess | public |
Data Types: logical
UseProgressMonitor
— Whether to display progress
false
(default) | true
Whether to display progress, specified as true
or
false
. Set UseProgressMonitor
to
true
to report progress of a transfer using the function specified
by the ProgressMonitorFcn
property.
Attributes:
GetAccess | public |
SetAccess | public |
Data Types: logical
UseProxy
— Whether using proxy
true
(default) | false
Whether using a proxy, specified as true
or
false
.
If 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 butProxyURI
is empty and there is no proxy set in preferences.
MATLAB automatically diverts a message to a proxy when
UseProxy
is true.
Attributes:
GetAccess | public |
SetAccess | public |
Data Types: logical
VerifyServerName
— Whether server name matches certificate
true
(default) | false
Whether server name matches certificate, specified as true
or
false
.
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.
Attributes:
GetAccess | public |
SetAccess | public |
Data Types: logical
Examples
Extend Connection Timeout
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
url
.
options = matlab.net.http.HTTPOptions('ConnectTimeout',20);
response = request.send(url,options);
Version History
Introduced in R2016b
See Also
send
| MessageBody
| ProgressMonitor
| URI
| ContentProvider
| ContentConsumer
| Credentials
Topics
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)