The IProgress interface is used to track and control asynchronous tasks within VirtualBox. More...
Public Member Functions | |
| 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. | |
| 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. | |
| readonly attribute IEventSource | eventSource |
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, IMachine::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:
{D7B98D2B-30E8-447E-99CB-E31BECAE6AE4}
Member Function Documentation
◆ waitForCompletion()
| 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 advised 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.
◆ waitForOperationCompletion()
| 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.
◆ cancel()
| 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
◆ id
| readonly attribute wstringUUID IProgress::id |
ID of the task.
◆ description
| readonly attribute wstring IProgress::description |
Description of the task.
◆ initiator
| readonly attribute $unknown IProgress::initiator |
Initiator of the task.
◆ cancelable
| readonly attribute boolean IProgress::cancelable |
Whether the task can be interrupted.
◆ percent
| 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.
◆ timeRemaining
| 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.
◆ completed
| readonly attribute boolean IProgress::completed |
Whether the task has been completed.
◆ canceled
| readonly attribute boolean IProgress::canceled |
Whether the task has been canceled.
◆ resultCode
| readonly attribute long IProgress::resultCode |
Result code of the progress task.
Valid only if completed is true.
◆ errorInfo
| 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.
◆ operationCount
| readonly attribute unsigned long IProgress::operationCount |
Number of sub-operations this task is divided into.
Every task consists of at least one suboperation.
◆ operation
| readonly attribute unsigned long IProgress::operation |
Number of the sub-operation being currently executed.
◆ operationDescription
| readonly attribute wstring IProgress::operationDescription |
Description of the sub-operation being currently executed.
◆ operationPercent
| readonly attribute unsigned long IProgress::operationPercent |
Progress value of the current sub-operation only, in percent.
◆ operationWeight
| readonly attribute unsigned long IProgress::operationWeight |
Weight value of the current sub-operation only.
◆ timeout
| 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.
◆ eventSource
| readonly attribute IEventSource IProgress::eventSource |
