Documentation

This is machine translation

Translated by Microsoft
Mouseover text to see original. Click the button below to return to the English verison of the page.

Note: This page has been translated by MathWorks. Please click here
To view all translated materals including this page, select Japan from the country navigator on the bottom of this page.

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.

Construction

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.

Data Types: logical

Seconds to wait for initial server connection, specified as an integer. 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 before throwing an error. This timeout does not limit how long it takes to receive a complete response.

Whether to convert to MATLAB type, specified as true or false.

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 MessageBody.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 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 decoding failed.

  • The DecodeResponse property is false.

Data Types: logical

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 message 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 data 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.

Data Types: logical

Authentication credentials, specified as a vector of matlab.net.http.Credentials objects. Credentials are 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 Credentials vector or same HTTPOptions object for each request. Credentials contains cached information that speeds up subsequent authentications.

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.

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.

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.

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.

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.

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.

Data Types: logical

Whether using a proxy, specified as true or false.

If UseProxy is true, then MATLAB selects the first one of the following 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 are 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.

Data Types: logical

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 'default', then CertificateFilename is set to the MATLAB certificate file at:

fullfile(matlabroot,'sys','certificates','ca','rootcerts.pem')

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.

To add certificates to rootcerts.pem, copy 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 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.

Data Types: char | string

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's 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.

Examples

expand all

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

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

Introduced in R2016b

Was this topic helpful?