org.virtualbox_4_3

Class IProgress

java.lang.Object

org.virtualbox_4_3.IUnknown

org.virtualbox_4_3.IProgress

public class IProgress
extends IUnknown

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 getCancelable()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 getOperation()and getOperationCount()). 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 getOperationPercent()and the percentage of completion of the task as a whole in getPercent(). Similarly, you can wait for the completion of a particular operation via waitForOperationCompletion(Long,Integer)or for the completion of the whole task via waitForCompletion(Integer). Interface ID: {C20238E4-3221-4D3F-8891-81CE92D9F913}

Field Summary

Fields inherited from class org.virtualbox_4_3.IUnknown

obj, port

Constructor Summary

Constructors

Constructor and Description
IProgress(java.lang.String wrapped, org.virtualbox_4_3.jaxws.VboxPortType port)

Method Summary

Methods

Modifier and Type	Method and Description
void	cancel() Cancels the task.
java.lang.Boolean	getCancelable() Whether the task can be interrupted.
java.lang.Boolean	getCanceled() Whether the task has been canceled.
java.lang.Boolean	getCompleted() Whether the task has been completed.
java.lang.String	getDescription() Description of the task.
IVirtualBoxErrorInfo	getErrorInfo() Extended information about the unsuccessful result of the progress operation.
java.lang.String	getId() ID of the task.
IUnknown	getInitiator() Initiator of the task.
java.lang.Long	getOperation() Number of the sub-operation being currently executed.
java.lang.Long	getOperationCount() Number of sub-operations this task is divided into.
java.lang.String	getOperationDescription() Description of the sub-operation being currently executed.
java.lang.Long	getOperationPercent() Progress value of the current sub-operation only, in percent.
java.lang.Long	getOperationWeight() Weight value of the current sub-operation only.
java.lang.Long	getPercent() Current progress value of the task as a whole, in percent.
java.lang.Integer	getResultCode() Result code of the progress task.
java.lang.Long	getTimeout() When non-zero, this specifies the number of milliseconds after which the operation will automatically be canceled.
java.lang.Integer	getTimeRemaining() Estimated remaining time until the task completes, in seconds.
static IProgress	queryInterface(IUnknown obj)
void	setCurrentOperationProgress(java.lang.Long percent) Internal method, not to be called externally.
void	setNextOperation(java.lang.String nextOperationDescription, java.lang.Long nextOperationsWeight) Internal method, not to be called externally.
void	setTimeout(java.lang.Long value) When non-zero, this specifies the number of milliseconds after which the operation will automatically be canceled.
void	waitForAsyncProgressCompletion(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	waitForCompletion(java.lang.Integer 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(java.lang.Long operation, java.lang.Integer timeout) Waits until the given operation is done with a given timeout in milliseconds; specify -1 for an indefinite wait.

Methods inherited from class org.virtualbox_4_3.IUnknown

getRemoteWSPort, getWrapped, releaseRemote

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

IProgress

public IProgress(java.lang.String wrapped,
         org.virtualbox_4_3.jaxws.VboxPortType port)

Method Detail

getId

public java.lang.String getId()

ID of the task.

Returns:

String

getDescription

public java.lang.String getDescription()

Description of the task.

Returns:

String

getInitiator

public IUnknown getInitiator()

Initiator of the task.

Returns:

IUnknown

getCancelable

public java.lang.Boolean getCancelable()

Whether the task can be interrupted.

Returns:

Boolean

getPercent

public java.lang.Long getPercent()

Current progress value of the task as a whole, in percent. This value depends on how many operations are already complete. Returns 100 if getCompleted()is true.

Returns:

Long

getTimeRemaining

public java.lang.Integer getTimeRemaining()

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.

Returns:

Integer

getCompleted

public java.lang.Boolean getCompleted()

Whether the task has been completed.

Returns:

Boolean

getCanceled

public java.lang.Boolean getCanceled()

Whether the task has been canceled.

Returns:

Boolean

getResultCode

public java.lang.Integer getResultCode()

Result code of the progress task. Valid only if getCompleted()is true.

Returns:

Integer

getErrorInfo

public IVirtualBoxErrorInfo getErrorInfo()

Extended information about the unsuccessful result of the progress operation. May be null if no extended information is available. Valid only if getCompleted()is true and getResultCode()indicates a failure.

Returns:

org.virtualbox_4_3.IVirtualBoxErrorInfo

getOperationCount

public java.lang.Long getOperationCount()

Number of sub-operations this task is divided into. Every task consists of at least one suboperation.

Returns:

Long

getOperation

public java.lang.Long getOperation()

Number of the sub-operation being currently executed.

Returns:

Long

getOperationDescription

public java.lang.String getOperationDescription()

Description of the sub-operation being currently executed.

Returns:

String

getOperationPercent

public java.lang.Long getOperationPercent()

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

Returns:

Long

getOperationWeight

public java.lang.Long getOperationWeight()

Weight value of the current sub-operation only.

Returns:

Long

getTimeout

public java.lang.Long getTimeout()

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.

Returns:

Long

setTimeout

public void setTimeout(java.lang.Long value)

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.

Parameters:

value - Long

queryInterface

public static IProgress queryInterface(IUnknown obj)

setCurrentOperationProgress

public void setCurrentOperationProgress(java.lang.Long percent)

Internal method, not to be called externally.

setNextOperation

public void setNextOperation(java.lang.String nextOperationDescription,
                    java.lang.Long nextOperationsWeight)

Internal method, not to be called externally.

waitForCompletion

public void waitForCompletion(java.lang.Integer 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:

@link ::VBOX_E_IPRT_ERROR VBOX_E_IPRT_ERROR	Failed to wait for task completion.

waitForOperationCompletion

public void waitForOperationCompletion(java.lang.Long operation,
                              java.lang.Integer timeout)

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

Parameters:

operation - Number of the operation to wait for. Must be less than getOperationCount().

timeout - Maximum time in milliseconds to wait or -1 to wait indefinitely. Expected result codes:

@link ::VBOX_E_IPRT_ERROR VBOX_E_IPRT_ERROR	Failed to wait for operation completion.

waitForAsyncProgressCompletion

public void waitForAsyncProgressCompletion(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.

cancel

public void cancel()

Cancels the task. Expected result codes:

@link ::VBOX_E_INVALID_OBJECT_STATE VBOX_E_INVALID_OBJECT_STATE	Operation cannot be canceled.

NOTE: If getCancelable()is false, then this method will fail.