matlab.net.http.HTTPOptions Class

Namespace: matlab.net.http

Options controlling HTTP message exchange

expand all in page

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.

example

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

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, 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 the matlab.net.http.HTTPOptions.VerifyServerName property to false.

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

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

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

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 Web Settings in the Settings 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 Settings window.

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

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 Settings, if any.

  • The proxy specified in your system settings (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 settings.

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

Version History

Introduced in R2016b

See Also

| | | | | |

Topics