Public Member Functions | Public Attributes

# IProgress Interface Reference

The IProgress interface is used to track and control asynchronous tasks within VirtualBox. More...

List of all members.

## Public Member Functions
void | setCurrentOperationProgress (in unsigned long percent)
| Internal method, not to be called externally.
void | setNextOperation (in wstring nextOperationDescription, in unsigned long nextOperationsWeight)
| Internal method, not to be called externally.
void | waitForCompletion (in long timeout)
| Waits until the task is done (including all sub-operations) with a given timeout in milliseconds; specify -1 for an indefinite wait.
void | waitForOperationCompletion (in unsigned long operation, in long timeout)
| Waits until the given operation is done with a given timeout in milliseconds; specify -1 for an indefinite wait.
void | waitForAsyncProgressCompletion (in IProgress pProgressAsync)
| Waits until the other task is completed (including all sub-operations) and forward all changes from the other progress to this progress.
void | cancel ()
| Cancels the task.
## Public Attributes
readonly attribute wstringUUID | id
| ID of the task.
readonly attribute wstring | description
| Description of the task.
readonly attribute $unknown | initiator
| Initiator of the task.
readonly attribute boolean | cancelable
| Whether the task can be interrupted.
readonly attribute unsigned long | percent
| Current progress value of the task as a whole, in percent.
readonly attribute long | timeRemaining
| Estimated remaining time until the task completes, in seconds.
readonly attribute boolean | completed
| Whether the task has been completed.
readonly attribute boolean | canceled
| Whether the task has been canceled.
readonly attribute long | resultCode
| Result code of the progress task.
readonly attribute IVirtualBoxErrorInfo | errorInfo
| Extended information about the unsuccessful result of the progress operation.
readonly attribute unsigned long | operationCount
| Number of sub-operations this task is divided into.
readonly attribute unsigned long | operation
| Number of the sub-operation being currently executed.
readonly attribute wstring | operationDescription
| Description of the sub-operation being currently executed.
readonly attribute unsigned long | operationPercent
| Progress value of the current sub-operation only, in percent.
readonly attribute unsigned long | operationWeight
| Weight value of the current sub-operation only.
attribute unsigned long | timeout
| When non-zero, this specifies the number of milliseconds after which the operation will automatically be canceled.

## Detailed Description

The IProgress interface is used to track and control asynchronous tasks within VirtualBox.

An instance of this is returned every time VirtualBox starts an asynchronous task (in other words, a separate thread) which continues to run after a method call returns. For example, IConsole::saveState, which saves the state of a running virtual machine, can take a long time to complete. To be able to display a progress bar, a user interface such as the VirtualBox graphical user interface can use the IProgress object returned by that method.

Note that IProgress is a "read-only" interface in the sense that only the VirtualBox internals behind the Main API can create and manipulate progress objects, whereas client code can only use the IProgress object to monitor a task's progress and, if cancelable is `true`, cancel the task by calling cancel.

A task represented by IProgress consists of either one or several sub-operations that run sequentially, one by one (see operation and operationCount). Every operation is identified by a number (starting from 0) and has a separate description.

You can find the individual percentage of completion of the current operation in operationPercent and the percentage of completion of the task as a whole in percent.

Similarly, you can wait for the completion of a particular operation via waitForOperationCompletion or for the completion of the whole task via waitForCompletion.

Interface ID:
  `{C20238E4-3221-4D3F-8891-81CE92D9F913}`

## Member Function Documentation

void IProgress::setCurrentOperationProgress | ( | in unsigned long | percent | ) |

Internal method, not to be called externally.

void IProgress::setNextOperation | ( | in wstring | nextOperationDescription,
|  | in unsigned long | nextOperationsWeight |
| ) |  |  |

Internal method, not to be called externally.

void IProgress::waitForCompletion | ( | in long | timeout | ) |

Waits until the task is done (including all sub-operations) with a given timeout in milliseconds; specify -1 for an indefinite wait.

Note that the VirtualBox/XPCOM/COM/native event queues of the calling thread are not processed while waiting. Neglecting event queues may have dire consequences (degrade performance, resource hogs, deadlocks, etc.), this is specially so for the main thread on platforms using XPCOM. Callers are adviced wait for short periods and service their event queues between calls, or to create a worker thread to do the waiting.

Parameters:

  | timeout | Maximum time in milliseconds to wait or -1 to wait indefinitely.

Expected result codes:

  VBOX_E_IPRT_ERROR | Failed to wait for task completion.

void IProgress::waitForOperationCompletion | ( | in unsigned long | operation,
|  | in long | timeout |
| ) |  |  |

Waits until the given operation is done with a given timeout in milliseconds; specify -1 for an indefinite wait.

See for event queue considerations.

Parameters:

  | operation | Number of the operation to wait for. Must be less than operationCount.
  | timeout | Maximum time in milliseconds to wait or -1 to wait indefinitely.

Expected result codes:

  VBOX_E_IPRT_ERROR | Failed to wait for operation completion.

void IProgress::waitForAsyncProgressCompletion | ( | in IProgress | pProgressAsync | ) |

Waits until the other task is completed (including all sub-operations) and forward all changes from the other progress to this progress.

This means sub-operation number, description, percent and so on.

You have to take care on setting up at least the same count on sub-operations in this progress object like there are in the other progress object.

If the other progress object supports cancel and this object gets any cancel request (when here enabled as well), it will be forwarded to the other progress object.

If there is an error in the other progress, this error isn't automatically transfered to this progress object. So you have to check any operation error within the other progress object, after this method returns.

Parameters:

  | pProgressAsync | The progress object of the asynchrony process.

void IProgress::cancel | ( |  | ) |

Cancels the task.

Expected result codes:

  VBOX_E_INVALID_OBJECT_STATE | Operation cannot be canceled.

Note:
  If cancelable is `false`, then this method will fail.

## Member Data Documentation

readonly attribute wstringUUID IProgress::id

ID of the task.

readonly attribute wstring IProgress::description

Description of the task.

readonly attribute $unknown IProgress::initiator

Initiator of the task.

readonly attribute boolean IProgress::cancelable

Whether the task can be interrupted.

readonly attribute unsigned long IProgress::percent

Current progress value of the task as a whole, in percent.

This value depends on how many operations are already complete. Returns 100 if completed is `true`.

readonly attribute long IProgress::timeRemaining

Estimated remaining time until the task completes, in seconds.

Returns 0 once the task has completed; returns -1 if the remaining time cannot be computed, in particular if the current progress is 0.

Even if a value is returned, the estimate will be unreliable for low progress values. It will become more reliable as the task progresses; it is not recommended to display an ETA before at least 20% of a task have completed.

readonly attribute boolean IProgress::completed

Whether the task has been completed.

readonly attribute boolean IProgress::canceled

Whether the task has been canceled.

readonly attribute long IProgress::resultCode

Result code of the progress task.

Valid only if completed is `true`.

readonly attribute IVirtualBoxErrorInfo IProgress::errorInfo

Extended information about the unsuccessful result of the progress operation.

May be `null` if no extended information is available. Valid only if completed is `true` and resultCode indicates a failure.

readonly attribute unsigned long IProgress::operationCount

Number of sub-operations this task is divided into.

Every task consists of at least one suboperation.

readonly attribute unsigned long IProgress::operation

Number of the sub-operation being currently executed.

readonly attribute wstring IProgress::operationDescription

Description of the sub-operation being currently executed.

readonly attribute unsigned long IProgress::operationPercent

Progress value of the current sub-operation only, in percent.

readonly attribute unsigned long IProgress::operationWeight

Weight value of the current sub-operation only.

attribute unsigned long IProgress::timeout

When non-zero, this specifies the number of milliseconds after which the operation will automatically be canceled.

This can only be set on cancelable objects.