matlab.net.http.HTTPOptions class

Package: 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.

example

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

expand all

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. MATLAB supports Basic and Digest authentication only.

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

File name of root certificates, specified as a string scalar 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 'default', then system certificates are used.

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.

If you need additional certificates, add them to the system certificates. 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.

If 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.

Set CertificateFilename to empty ('') only if you cannot establish a connection due to a missing or expired certificate.

Attributes:

GetAccess
public
SetAccess
public

Data Types: char | string

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 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

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 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 the Data property for conversion rules. If the conversion is successful, then Data contains the converted data and Payload 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 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:

GetAccess
public
SetAccess
public

Data Types: logical

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 matlab.net.http.HTTPException History property to obtain any partial data.

Attributes:

GetAccess
public
SetAccess
public

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

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 MATLAB Web Preferences Panel, 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 panel.

Attributes:

GetAccess
public
SetAccess
public

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

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

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

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

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.

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

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

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

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 but ProxyURI 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

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

collapse all

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);

Introduced in R2016b