matlab.net.http.HTTPOptions - Options controlling HTTP message exchange - MATLAB (original) (raw)

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 asName1,Value1,...,NameN,ValueN. Unspecified properties are set to their default values.

example

Properties

expand all

Authenticate — Whether Credentials used for authentication

true (default) | false

Whether Credentials are used for authentication, specified astrue 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:

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 byCertificateFilename.
  • Disable certificate validation by settingCertificateFilename 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 amatlab.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:

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, thenConnectTimeout throws an error. To disable timeouts, setConnectTimeout 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:

ConvertResponse — How to process raw payload from server

true (default) | false

How to process raw payload received from a server in aResponseMessage, specified as true orfalse.

If ConvertResponse is true, then

• If a ContentConsumer is specified, then the uint8 payload is passed to the ContentConsumer 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 theData property for conversion rules. If the conversion is successful, thenData contains the converted data andPayload is empty.

If ConvertResponse is false, then any specifiedContentConsumer 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 raw uint8 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:

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:

DecodeResponse — Whether to decode compressed data

true (default) | false

Whether to decode compressed data, specified as true orfalse. 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 valueidentity 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 theConvertResponse property.

Do not set this value to false for compressed responses if you are using aContentConsumer 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:

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 defaultmatlab.net.http.Credentials object. Use a defaultCredentials 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 theAuthenticate property is true. You must specify at least oneCredentials object for authentication to take place. If you setCredentials 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 sameHTTPOptions 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 theProxyURI property of thisHTTPOptions object or clear the Use a proxy with authentication option in the Preferences window.

Attributes:

KeepAliveTimeout — Seconds to keep server connection open

Inf (default) | 0

Seconds to keep a server connection open after the initial connect, specified as0 or Inf. Use this property to enable multiple successive messages to be sent over the same connection. AnInf 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:

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 toInf to allow unlimited redirections.

If MaxRedirects is nonzero, then cookies received from the server in each redirect response are copied into the redirected message. AfterMaxRedirects, the response message contains the next redirect message.

Attributes:

ProgressMonitorFcn — Progress monitor handler

function handle | empty

Progress monitor handler, specified as a function handle to a matlab.net.http.ProgressMonitor object. IfUseProgressMonitor is true, then MATLAB calls the ProgressMonitor function to report the progress of a transfer. If UseProgressMonitor is false orProgressMonitorFcn is empty, then no progress is reported.

Attributes:

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:

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 theTimeout property set by weboptions.

Attributes:

SavePayload — Whether Payload saved

false (default) | true

Whether Payload is saved, specified as true orfalse. 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 totrue 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 theConvertResponse property to false and readMessageBody.Data instead.

If an HTTPException occurs during message processing, then the payload received up to the point of failure is inHTTPException.History(end).Response.Body.Payload.

If RequestMessage.Body is a ContentProvider object, then MATLAB saves the provider's converted data inBody.Payload.

Attributes:

Data Types: logical

UseProgressMonitor — Whether to display progress

false (default) | true

Whether to display progress, specified as true orfalse. Set UseProgressMonitor totrue to report progress of a transfer using the function specified by the ProgressMonitorFcn property.

Attributes:

Data Types: logical

UseProxy — Whether using proxy

true (default) | false

Whether using a proxy, specified as true orfalse.

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 but ProxyURI is empty and there is no proxy set in preferences.

MATLAB automatically diverts a message to a proxy whenUseProxy is true.

Attributes:

Data Types: logical

VerifyServerName — Whether server name matches certificate

true (default) | false

Whether server name matches certificate, specified as true orfalse.

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:

Data Types: logical

Examples

collapse all

Extend Connection Timeout

Increase connection time out to 20 seconds.

Change the default timeout option for the request message specified in the variablerequest sent to the server specified in the variableurl.

options = matlab.net.http.HTTPOptions('ConnectTimeout',20); response = request.send(url,options);

Version History

Introduced in R2016b