The IProgress interface is used to track and control asynchronous tasks within VirtualBox. More...
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 | 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. | |
attribute unsigned long | timeout |
When non-zero, this specifies the number of milliseconds after which the operation will automatically be canceled. |
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.
{856AA038-853F-42E2-ACF7-6E7B02DBE294}
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.
timeout | Maximum time in milliseconds to wait or -1 to wait indefinitely. |
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.
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. |
VBOX_E_IPRT_ERROR | Failed to wait for operation completion. |
void IProgress::cancel | ( | ) |
Cancels the task.
VBOX_E_INVALID_OBJECT_STATE | Operation cannot be canceled. |
false
, then this method will fail. 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.
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.