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

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.