VirtualBox Main API

Public Member Functions | Public Attributes | List of all members
IProgress Interface Reference

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

Inheritance diagram for IProgress:

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