org.virtualbox_5_1
Class IProgress

java.lang.Object
  extended by org.virtualbox_5_1.IUnknown
      extended by org.virtualbox_5_1.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,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, ifgetCancelable()is true, cancel the task by callingcancel(). A task represented by IProgress consists of either one or several sub-operations that run sequentially, one by one (seegetOperation()andgetOperationCount()). 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 ingetOperationPercent()and the percentage of completion of the task as a whole ingetPercent(). Similarly, you can wait for the completion of a particular operation viawaitForOperationCompletion(Long,Integer)or for the completion of the whole task viawaitForCompletion(Integer). Interface ID: {77FAF1C0-489D-B123-274C-5A95E77AB286}


Field Summary
 
Fields inherited from class org.virtualbox_5_1.IUnknown
obj, objMgr, port
 
Constructor Summary
IProgress(java.lang.String wrapped, org.virtualbox_5_1.ObjectRefManager objMgr, org.virtualbox_5_1.jaxws.VboxPortType port)
           
 
Method Summary
 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_5_1.IUnknown
getObjMgr, 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_5_1.ObjectRefManager objMgr,
                 org.virtualbox_5_1.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 ifgetCompleted()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 ifgetCompleted()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 ifgetCompleted()is true andgetResultCode()indicates a failure.

Returns:
org.virtualbox_5_1.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_ERRORFailed 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. SeewaitForCompletion(Integer)

Parameters:
operation - Number of the operation to wait for. Must be less thangetOperationCount().
timeout - Maximum time in milliseconds to wait or -1 to wait indefinitely. Expected result codes:
@link ::VBOX_E_IPRT_ERROR VBOX_E_IPRT_ERRORFailed 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_STATEOperation cannot be canceled.
NOTE: IfgetCancelable()is false, then this method will fail.