matlab.net.http.HTTPOptions Class

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.

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

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 ConvertResponse is false, then any specified ContentConsumer is ignored and the behavior depends on whether the Content-Type specifies character data.

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:

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:

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

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

All requests go directly to the destination URI without a proxy when any of the following is true.

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