matlab.net.http.ProgressMonitor class

Package: matlab.net.http
Superclasses: handle

Progress monitor for HTTP message exchange

Description

Use the ProgressMonitor class to implement a progress monitor for an HTTP request message. A progress monitor listens to changes in the properties of this class to implement a display or update of your choice.

To implement a progress monitor, create a subclass of this class. Then create an HTTPOptions object, specify that subclass as the ProgressMonitorFcn property, and set the UseProgressMonitor property to true.

An HTTP request starts when you call the RequestMessage.send method. The process might involve multiple messages in both directions in the case of redirects and authentication. MATLAB^® calls the done method when all transfers have been completed.

During a transfer:

• MATLAB sets the Max, CancelFcn, and Direction properties when you call RequestMessage.send.

• MATLAB sets the Value property repeatedly as the body of the request message is sent to indicate the number of bytes transferred.

• When receipt of the ResponseMessage begins, MATLAB sets Direction to Response and again sets Value repeatedly.

• To cancel the transfer at any time, call the CancelFcn function. This action is the same as interrupting the send function in the Command Window.

You can display a graphical progress indicator or other indication of progress after Direction changes to Response. For each subsequent Value, update the indicator to the current Value. You can also use this mechanism to monitor progress programmatically.

The matlab.net.http.ProgressMonitor class is a handle class.

Creation

obj = matlab.net.http.ProgressMonitor(Name,Value) creates a progress monitor 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

Interval — Seconds to first call and maximum interval between calls

2 seconds (default) | double

Seconds to first call and maximum interval between calls, specified as double.

Interval is the amount of time in seconds after the start of transfer before the first setting of the Value property. Interval is a suggested maximum amount of time between settings of Value, regardless of progress. If the total time to transfer the data is less than Interval seconds, then Value is not set. If no data has been transferred in Interval seconds since the last setting of Value, then Value might be set again to the same value. In this way, your ProgressMonitor object can cancel a transfer (by calling CancelFcn) even if there is no progress.

The Interval value is a suggested value. There is no guarantee that MATLAB sets Value within Interval seconds if there has been no progress.

The default interval is two seconds. To specify a different value, set Interval in your constructor. The minimum interval between consecutive settings of Value when there is no progress is 0.1 seconds. However, if Value changes, it might be set more often than this interval.

After setting Value the first time, there is no delay in setting Value for subsequent messages in the same exchange.

InUse — Monitor is in use indicator (read-only)

true | false

Monitor is in use indicator, specified as true or false. MATLAB sets this property to indicate whether it is using this ProgressMonitor object during a transfer. InUse prevents you from reusing this object for more than one transfer at a time.

Data Types: logical

CancelFcn — Function to call to cancel transfer (read-only)

function handle

Function to call to cancel a transfer, specified as a function handle. MATLAB sets CancelFcn to the function your ProgressMonitor should call to cancel a transfer. Calling this function has the same effect as interrupting the transfer in the Command Window.

Max — Maximum length of the transfer (read-only)

uint64 | []

Maximum length of the transfer, specified as uint64. If the maximum length is not known, Max is []. Max is the maximum value for your displayed progress indicator.

MATLAB sets Max at the beginning of each send and receive operation to the expected number of bytes to be transferred, based on the Content-Length header field.

If the message does not contain a Content-Length field, Max is []. In this case, you cannot determine the proportion of the transfer that has been completed. You can, however, still monitor changes in the Value property.

Direction — Direction of transfer

matlab.net.http.MessageType object | empty

Direction of transfer, specified as a matlab.net.http.MessageType object. MATLAB sets Direction to indicate whether progress is monitored for a request message or a response message. If no transfer is taking place, then Direction is empty.

Value — Number of bytes transferred so far

uint64 | empty

Number of bytes transferred so far, specified as uint64. MATLAB sets Value repeatedly to the total number of bytes transferred for the current message. However, it delays setting this property the first time in an exchange until at least Interval seconds have elapsed since the start of the message.

Implement a set.Value method for this property to monitor progress of the transfer. You can also implement the ability to cancel the transfer from within the progress monitor in the set.Value method.

MATLAB might set Value to empty at the end of a given transfer, to indicate that transfer in the current direction has ended. MATLAB always sets Value to empty at the conclusion of all transfers before calling the done method.

You cannot control the frequency at which MATLAB updates the Value property. However, MATLAB might set Value at least once every Interval seconds, even if there is no progress. This behavior allows you to call the CancelFcn if a transfer is not progressing. Value might be zero if no bytes have been transferred for Interval seconds since transfer began.

Methods

Public Methods

done	Indicate all message transfers completed