public class IProgress extends IUnknown
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: {D7B98D2B-30E8-447E-99CB-E31BECAE6AE4}Constructor and Description |
---|
IProgress(java.lang.String wrapped,
org.virtualbox_6_1.ObjectRefManager objMgr,
org.virtualbox_6_1.jaxws.VboxPortType port) |
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.
|
IEventSource |
getEventSource() |
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 |
setTimeout(java.lang.Long value)
When non-zero, this specifies the number of milliseconds after which
the operation will automatically be canceled.
|
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.
|
getObjMgr, getRemoteWSPort, getWrapped, releaseRemote
public IProgress(java.lang.String wrapped, org.virtualbox_6_1.ObjectRefManager objMgr, org.virtualbox_6_1.jaxws.VboxPortType port)
public java.lang.String getId()
public java.lang.String getDescription()
public IUnknown getInitiator()
public java.lang.Boolean getCancelable()
public java.lang.Long getPercent()
getCompleted()
is true.public java.lang.Integer getTimeRemaining()
public java.lang.Boolean getCompleted()
public java.lang.Boolean getCanceled()
public java.lang.Integer getResultCode()
getCompleted()
is true.public IVirtualBoxErrorInfo getErrorInfo()
getCompleted()
is true andgetResultCode()
indicates a failure.public java.lang.Long getOperationCount()
public java.lang.Long getOperation()
public java.lang.String getOperationDescription()
public java.lang.Long getOperationPercent()
public java.lang.Long getOperationWeight()
public java.lang.Long getTimeout()
public void setTimeout(java.lang.Long value)
value
- Longpublic IEventSource getEventSource()
public void waitForCompletion(java.lang.Integer timeout)
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. |
public void waitForOperationCompletion(java.lang.Long operation, java.lang.Integer timeout)
waitForCompletion(Integer)
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:
VBOX_E_IPRT_ERROR | Failed to wait for operation completion. |
public void cancel()
VBOX_E_INVALID_OBJECT_STATE | Operation cannot be canceled. |
getCancelable()
is false, then this method will fail.