|
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.virtualbox_7_0.IUnknown
org.virtualbox_7_0.IMedium
public class IMedium
The IMedium interface represents virtual storage for a machine's hard disks, CD/DVD or floppy drives. It will typically represent a disk image on the host, for example a VDI or VMDK file representing a virtual hard disk, or an ISO or RAW file representing virtual removable media, but can also point to a network location (e.g. for iSCSI targets). Instances of IMedium are connected to virtual machines by way of medium attachments, which link the storage medium to a particular device slot of a storage controller of the virtual machine. In the VirtualBox API, virtual storage is therefore always represented by the following chain of object links:
IMachine.getStorageControllers()
contains an array of
storage controllers (IDE, SATA, SCSI, SAS or a floppy controller;
these are instances ofIStorageController
).IMachine.getMediumAttachments()
contains an array of
medium attachments (instances ofIMediumAttachment
created byIMachine.attachDevice(String,Integer,Integer,org.virtualbox_7_0.DeviceType,org.virtualbox_7_0.IMedium)
),
each containing a storage controller from the above array, a
port/device specification, and an instance of IMedium representing
the medium storage (image file).
For removable media, the storage medium is optional; a medium
attachment with no medium represents a CD/DVD or floppy drive
with no medium inserted. By contrast, hard disk attachments
will always have an IMedium object attached.getLocation()
attribute.IVirtualBox.openMedium(String,org.virtualbox_7_0.DeviceType,org.virtualbox_7_0.AccessMode,Boolean)
;
new hard disk media can be created with the VirtualBox API using theIVirtualBox.createMedium(String,String,org.virtualbox_7_0.AccessMode,org.virtualbox_7_0.DeviceType)
method. Differencing hard
disks (see below) are usually implicitly created by VirtualBox as
needed, but may also be created explicitly usingcreateDiffStorage(org.virtualbox_7_0.IMedium,List)
.
VirtualBox cannot create CD/DVD or floppy images (ISO and RAW files); these
should be created with external tools and then opened from within VirtualBox.
Only for CD/DVDs and floppies, an IMedium instance can also represent a host
drive. In that case thegetId()
attribute contains the UUID of
one of the drives inIHost.getDVDDrives()
orIHost.getFloppyDrives()
.IVirtualBox.openMedium(String,org.virtualbox_7_0.DeviceType,org.virtualbox_7_0.AccessMode,Boolean)
.
They also appear in the globalIVirtualBox.getHardDisks()
,IVirtualBox.getDVDImages()
andIVirtualBox.getFloppyImages()
arrays.
Prior to VirtualBox 4.0, opening a medium added it to a global media registry
in the VirtualBox.xml file, which was shared between all machines and made
transporting machines and their media from one host to another difficult.
Starting with VirtualBox 4.0, media are only added to a registry when they areattachedto a machine usingIMachine.attachDevice(String,Integer,Integer,org.virtualbox_7_0.DeviceType,org.virtualbox_7_0.IMedium)
. For
backwards compatibility, which registry a medium is added to depends on which
VirtualBox version created a machine:IVirtualBox.openMedium(String,org.virtualbox_7_0.DeviceType,org.virtualbox_7_0.AccessMode,Boolean)
for more information.
Media are removed from media registries by theclose()
,deleteStorage()
andmergeTo(org.virtualbox_7_0.IMedium)
methods.refreshState()
method is called explicitly on a medium. This is done to make the VirtualBox object
ready for serving requests as fast as possible and let the end-user
application decide if it needs to check media accessibility right away or not.
As a result, when VirtualBox starts up (e.g. the VirtualBox
object gets created for the first time), all known media are in the
"Inaccessible" state, but the value of thegetLastAccessError()
attribute is an empty string because no actual accessibility check has
been made yet.
After callingrefreshState()
, a medium is consideredaccessibleif its storage unit can be read. In that case, thegetState()
attribute has a value of "Created". If the storage
unit cannot be read (for example, because it is located on a disconnected
network resource, or was accidentally deleted outside VirtualBox),
the medium is consideredinaccessible, which is indicated by the
"Inaccessible" state. The exact reason why the medium is inaccessible can be
obtained by reading thegetLastAccessError()
attribute.getType()
attribute (seeMediumType
) and
which define the medium's behavior with attachments and snapshots.
All media can be also divided in two groups:basemedia anddifferencingmedia. A base medium contains all sectors of the
medium data in its own storage and therefore can be used independently.
In contrast, a differencing medium is a "delta" to some other medium and
contains only those sectors which differ from that other medium, which is
then called aparent. The differencing medium is said to belinked tothat parent. The parent may be itself a differencing
medium, thus forming a chain of linked media. The last element in that
chain must always be a base medium. Note that several differencing
media may be linked to the same parent medium.
Differencing media can be distinguished from base media by querying thegetParent()
attribute: base media do not have parents they would
depend on, so the value of this attribute is always null for them.
Using this attribute, it is possible to walk up the medium tree (from the
child medium to its parent). It is also possible to walk down the tree
using thegetChildren()
attribute.
Note that the type of all differencing media is "normal"; all other
values are meaningless for them. Base media may be of any type.getLocation()
attribute is that
there is a possibility to cause VirtualBox to compose a unique value for
the file name part of the location using the UUID of the hard disk. This
applies only to hard disks inMediumState.NotCreated
state,
e.g. before the storage unit is created, and works as follows. You set the
value of thegetLocation()
attribute to a location
specification which only contains the path specification but not the file
name part and ends with either a forward slash or a backslash character.
In response, VirtualBox will generate a new UUID for the hard disk and
compose the file name using the following pattern:<path>/{<uuid>}.<ext>where
<path>
is the supplied path specification,<uuid>
is the newly generated UUID and<ext>
is the default extension for the storage format of this hard disk. After
that, you may call any of the methods that create a new hard disk storage
unit and they will use the generated UUID and file name.
Interface ID: {AD47AD09-787B-44AB-B343-A082A3F2DFB1}
Field Summary |
---|
Fields inherited from class org.virtualbox_7_0.IUnknown |
---|
obj, objMgr, port |
Constructor Summary | |
---|---|
IMedium(java.lang.String wrapped,
org.virtualbox_7_0.ObjectRefManager objMgr,
org.virtualbox_7_0.jaxws.VboxPortType port)
|
Method Summary | |
---|---|
IProgress |
changeEncryption(java.lang.String currentPassword,
java.lang.String cipher,
java.lang.String newPassword,
java.lang.String newPasswordId)
Starts encryption of this medium. |
void |
checkEncryptionPassword(java.lang.String password)
Checks whether the supplied password is correct for the medium. |
IProgress |
cloneTo(IMedium target,
java.util.List<MediumVariant> variant,
IMedium parent)
Starts creating a clone of this medium in the format and at the location defined by the target argument. |
IProgress |
cloneToBase(IMedium target,
java.util.List<MediumVariant> variant)
Starts creating a clone of this medium in the format and at the location defined by the target argument. |
void |
close()
Closes this medium. |
IProgress |
compact()
Starts compacting of this medium. |
IProgress |
createBaseStorage(java.lang.Long logicalSize,
java.util.List<MediumVariant> variant)
Starts creating a hard disk storage unit (fixed/dynamic, according to the variant flags) in the background. |
IProgress |
createDiffStorage(IMedium target,
java.util.List<MediumVariant> variant)
Starts creating an empty differencing storage unit based on this medium in the format and at the location defined by the target argument. |
IProgress |
deleteStorage()
Starts deleting the storage unit of this medium. |
java.util.List<MediumType> |
getAllowedTypes()
Returns which medium types can selected for this medium. |
java.lang.Boolean |
getAutoReset()
Whether this differencing medium will be automatically reset each time a virtual machine it is attached to is powered up. |
IMedium |
getBase()
Base medium of this medium. |
java.util.List<IMedium> |
getChildren()
Children of this medium (all differencing media directly based on this medium). |
java.lang.String |
getDescription()
Optional description of the medium. |
DeviceType |
getDeviceType()
Kind of device (DVD/Floppy/HardDisk) which is applicable to this medium. |
java.lang.String |
getEncryptionSettings(Holder<java.lang.String> cipher)
Returns the encryption settings for this medium. |
java.lang.String |
getFormat()
Storage format of this medium. |
java.lang.Boolean |
getHostDrive()
True if this corresponds to a drive on the host. |
java.lang.String |
getId()
UUID of the medium. |
java.lang.String |
getLastAccessError()
Text message that represents the result of the last accessibility check performed by refreshState() . |
java.lang.String |
getLocation()
Location of the storage unit holding medium data. |
java.lang.Long |
getLogicalSize()
Logical size of this medium (in bytes), as reported to the guest OS running inside the virtual machine this medium is attached to. |
java.util.List<java.lang.String> |
getMachineIds()
Array of UUIDs of all machines this medium is attached to. |
IMediumFormat |
getMediumFormat()
Storage medium format object corresponding to this medium. |
java.lang.String |
getName()
Name of the storage unit holding medium data. |
IMedium |
getParent()
Parent of this medium (the medium this medium is directly based on). |
java.util.List<java.lang.String> |
getProperties(java.lang.String names,
Holder<java.util.List<java.lang.String>> returnNames)
Returns values for a group of properties in one call. |
java.lang.String |
getProperty(java.lang.String name)
Returns the value of the custom medium property with the given name. |
java.lang.Boolean |
getReadOnly()
Returns true if this medium is read-only and false otherwise. |
java.lang.Long |
getSize()
Physical size of the storage unit used to hold medium data (in bytes). |
java.util.List<java.lang.String> |
getSnapshotIds(java.lang.String machineId)
Returns an array of UUIDs of all snapshots of the given machine where this medium is attached to. |
MediumState |
getState()
Returns the current medium state, which is the last state set by the accessibility check performed by refreshState() . |
MediumType |
getType()
Type (role) of this medium. |
java.util.List<MediumVariant> |
getVariant()
Returns the storage format variant information for this medium as an array of the flags described at MediumVariant . |
IToken |
lockRead()
Locks this medium for reading. |
IToken |
lockWrite()
Locks this medium for writing. |
IProgress |
mergeTo(IMedium target)
Starts merging the contents of this medium and all intermediate differencing media in the chain to the given target medium. |
IProgress |
moveTo(java.lang.String location)
Changes the location of this medium. |
IMediumIO |
openForIO(java.lang.Boolean writable,
java.lang.String password)
Open the medium for I/O. |
static IMedium |
queryInterface(IUnknown obj)
|
MediumState |
refreshState()
If the current medium state (see MediumState ) is one of
"Created", "Inaccessible" or "LockedRead", then this performs an
accessibility check on the medium and sets the value of thegetState() attribute accordingly; that value is also returned for convenience. |
IProgress |
reset()
Starts erasing the contents of this differencing medium. |
IProgress |
resize(java.lang.Long logicalSize)
Starts resizing this medium. |
IProgress |
resizeAndCloneTo(IMedium target,
java.lang.Long logicalSize,
java.util.List<MediumVariant> variant,
IMedium parent)
This is a helper function that combines the functionality of cloneTo(org.virtualbox_7_0.IMedium,List,org.virtualbox_7_0.IMedium) andresize(Long) . |
void |
setAutoReset(java.lang.Boolean value)
Whether this differencing medium will be automatically reset each time a virtual machine it is attached to is powered up. |
void |
setDescription(java.lang.String value)
Optional description of the medium. |
void |
setIds(java.lang.Boolean setImageId,
java.lang.String imageId,
java.lang.Boolean setParentId,
java.lang.String parentId)
Changes the UUID and parent UUID for a hard disk medium. |
void |
setLocation(java.lang.String value)
Location of the storage unit holding medium data. |
void |
setProperties(java.util.List<java.lang.String> names,
java.util.List<java.lang.String> values)
Sets values for a group of properties in one call. |
void |
setProperty(java.lang.String name,
java.lang.String value)
Sets the value of the custom medium property with the given name. |
void |
setType(MediumType value)
Type (role) of this medium. |
Methods inherited from class org.virtualbox_7_0.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 |
---|
public IMedium(java.lang.String wrapped, org.virtualbox_7_0.ObjectRefManager objMgr, org.virtualbox_7_0.jaxws.VboxPortType port)
Method Detail |
---|
public java.lang.String getId()
public java.lang.String getDescription()
getState()
isMediumState.Inaccessible
orMediumState.LockedWrite
because the value of this attribute is
stored within the storage unit itself. Also note that changing the
attribute value is not possible in such case, as well as when the
medium is theMediumState.LockedRead
state.
public void setDescription(java.lang.String value)
getState()
isMediumState.Inaccessible
orMediumState.LockedWrite
because the value of this attribute is
stored within the storage unit itself. Also note that changing the
attribute value is not possible in such case, as well as when the
medium is theMediumState.LockedRead
state.
value
- Stringpublic MediumState getState()
refreshState()
.
If that method has not yet been called on the medium, the state
is "Inaccessible"; as opposed to truly inaccessible media, the
value ofgetLastAccessError()
will be an empty string in
that case.
NOTE: As of version 3.1, this no longer performs an accessibility check
automatically; callrefreshState()
for that.
public java.util.List<MediumVariant> getVariant()
MediumVariant
.
BeforerefreshState()
is called this method returns
an undefined value.
public java.lang.String getLocation()
public void setLocation(java.lang.String value)
value
- Stringpublic java.lang.String getName()
getLocation()
attribute that is suitable for representing the medium in situations
where the full location specification is too long (such as lists
and comboboxes in GUI frontends). This string is also used by frontends
to sort the media list alphabetically when needed.
For example, for locations that are regular files in the host's file
system, the value of this attribute is just the file name (+ extension),
without the path specification.
Note that as opposed to thegetLocation()
attribute, the name
attribute will not necessary be unique for a list of media of the
given type and format.
public DeviceType getDeviceType()
public java.lang.Boolean getHostDrive()
public java.lang.Long getSize()
getState()
isMediumState.Inaccessible
, the value of this property is the
last known size. ForMediumState.NotCreated
media,
the returned value is zero.
public java.lang.String getFormat()
ISystemProperties.getMediumFormats()
.
public IMediumFormat getMediumFormat()
public MediumType getType()
MediumType.Writethrough
.MediumType.Normal
and cannot be changed.MediumType.Normal
, except for DVD and floppy media,
which have a type ofMediumType.Writethrough
.
public void setType(MediumType value)
MediumType.Writethrough
.MediumType.Normal
and cannot be changed.MediumType.Normal
, except for DVD and floppy media,
which have a type ofMediumType.Writethrough
.
value
- org.virtualbox_7_0.MediumTypepublic java.util.List<MediumType> getAllowedTypes()
E_NOTIMPL
- This attribute is not implemented at the moment.
public IMedium getParent()
public java.util.List<IMedium> getChildren()
public IMedium getBase()
public java.lang.Boolean getReadOnly()
MediumType.Immutable
media
are always read-only while allMediumType.Writethrough
media are
always not.
NOTE: The read-only condition represented by this attribute is related to
the medium type and usage, not to the currentgetState()
and not to the read-only
state of the storage unit.
public java.lang.Long getLogicalSize()
getState()
isMediumState.Inaccessible
, the value of this property is the
last known logical size. ForMediumState.NotCreated
media, the returned value is zero.
public java.lang.Boolean getAutoReset()
MediumType
).
Seereset()
for more information about resetting
differencing media.
VBOX_E_NOT_SUPPORTED
- This is not a differencing medium (when changing the attribute
value).
public void setAutoReset(java.lang.Boolean value)
MediumType
).
Seereset()
for more information about resetting
differencing media.
VBOX_E_NOT_SUPPORTED
- This is not a differencing medium (when changing the attribute
value).
value
- Booleanpublic java.lang.String getLastAccessError()
refreshState()
.
An empty string is returned if the last accessibility check
was successful or has not yet been called. As a result, ifgetState()
is "Inaccessible" and this attribute is empty,
thenrefreshState()
has yet to be called; this is the
default value of media after VirtualBox initialization.
A non-empty string indicates a failure and should normally describe
a reason of the failure (for example, a file read error).
public java.util.List<java.lang.String> getMachineIds()
getSnapshotIds(String)
for
details.
public static IMedium queryInterface(IUnknown obj)
public void setIds(java.lang.Boolean setImageId, java.lang.String imageId, java.lang.Boolean setParentId, java.lang.String parentId)
setImageId
- Select whether a new image UUID is set or not.imageId
- New UUID for the image. If an empty string is passed, then a new
UUID is automatically created, provided that setImageId is true.
Specifying a zero UUID is not allowed.setParentId
- Select whether a new parent UUID is set or not.parentId
- New parent UUID for the image. If an empty string is passed, then a
new UUID is automatically created, provided setParentId is
true. A zero UUID is valid.public MediumState refreshState()
MediumState
) is one of
"Created", "Inaccessible" or "LockedRead", then this performs an
accessibility check on the medium and sets the value of thegetState()
attribute accordingly; that value is also returned for convenience.
For all other state values, this does not perform a refresh but returns
the state only.
The refresh, if performed, may take a long time (several seconds or even
minutes, depending on the storage unit location and format) because it performs an
accessibility check of the storage unit. This check may cause a significant
delay if the storage unit of the given medium is, for example, a file located
on a network share which is not currently accessible due to connectivity
problems. In that case, the call will not return until a timeout
interval defined by the host OS for this operation expires. For this reason,
it is recommended to never read this attribute on the main UI thread to avoid
making the UI unresponsive.
If the last known state of the medium is "Created" and the accessibility
check fails, then the state would be set to "Inaccessible", andgetLastAccessError()
may be used to get more details about the
failure. If the state of the medium is "LockedRead", then it remains the
same, and a non-empty value ofgetLastAccessError()
will
indicate a failed accessibility check in this case.
Note that not all medium states are applicable to all medium types.
public java.util.List<java.lang.String> getSnapshotIds(java.lang.String machineId)
machineId
- UUID of the machine to query.
public IToken lockRead()
lockWrite()
) in which case an error is returned.
When the medium is locked for reading, it cannot be modified
from within VirtualBox. This means that any method that changes
the properties of this medium or contents of the storage unit
will return an error (unless explicitly stated otherwise). That
includes an attempt to start a virtual machine that wants to
write to the medium.
When the virtual machine is started up, it locks for reading all
media it uses in read-only mode. If some medium cannot be locked
for reading, the startup procedure will fail.
A medium is typically locked for reading while it is used by a running
virtual machine but has a depending differencing image that receives
the actual write operations. This way one base medium can have
multiple child differencing images which can be written to
simultaneously. Read-only media such as DVD and floppy images are
also locked for reading only (so they can be in use by multiple
machines simultaneously).
A medium is also locked for reading when it is the source of a
write operation such ascloneTo(org.virtualbox_7_0.IMedium,List,org.virtualbox_7_0.IMedium)
ormergeTo(org.virtualbox_7_0.IMedium)
.
The medium locked for reading must be unlocked by abandoning the
returned token object, seeIToken
. Calls tolockRead()
can be nested and the lock is actually released
when all callers have abandoned the token.
This method sets the medium state (seegetState()
) to
"LockedRead" on success. The medium's previous state must be
one of "Created", "Inaccessible" or "LockedRead".
Locking an inaccessible medium is not an error; this method performs
a logical lock that prevents modifications of this medium through
the VirtualBox API, not a physical file-system lock of the underlying
storage unit.
This method returns the current state of the mediumbeforethe operation.
VBOX_E_INVALID_OBJECT_STATE
- Invalid medium state (e.g. not created, locked, inaccessible,
creating, deleting).
public IToken lockWrite()
lockRead()
, is
exclusive: there may be only one client holding a write lock,
and there may be no read locks while the write lock is held.
As a result, read-locking fails if a write lock is held, and
write-locking fails if either a read or another write lock is held.
When a medium is locked for writing, it cannot be modified
from within VirtualBox, and it is not guaranteed that the values
of its properties are up-to-date. Any method that changes the
properties of this medium or contents of the storage unit will
return an error (unless explicitly stated otherwise).
When a virtual machine is started up, it locks for writing all
media it uses to write data to. If any medium could not be locked
for writing, the startup procedure will fail. If a medium has
differencing images, then while the machine is running, only
the last ("leaf") differencing image is locked for writing,
whereas its parents are locked for reading only.
A medium is also locked for writing when it is the target of a
write operation such ascloneTo(org.virtualbox_7_0.IMedium,List,org.virtualbox_7_0.IMedium)
ormergeTo(org.virtualbox_7_0.IMedium)
.
The medium locked for writing must be unlocked by abandoning the
returned token object, seeIToken
. Write lockscannotbe nested.
This method sets the medium state (seegetState()
) to
"LockedWrite" on success. The medium's previous state must be
either "Created" or "Inaccessible".
Locking an inaccessible medium is not an error; this method performs
a logical lock that prevents modifications of this medium through
the VirtualBox API, not a physical file-system lock of the underlying
storage unit.
VBOX_E_INVALID_OBJECT_STATE
- Invalid medium state (e.g. not created, locked, inaccessible,
creating, deleting).
public void close()
IVirtualBox.openMedium(String,org.virtualbox_7_0.DeviceType,org.virtualbox_7_0.AccessMode,Boolean)
call.
Note that after this method successfully returns, the given medium
object becomes uninitialized. This means that any attempt
to call any of its methods or attributes will fail with the"Object not ready" (E_ACCESSDENIED)
error.
VBOX_E_INVALID_OBJECT_STATE
- Invalid medium state (other than not created, created or
inaccessible).VBOX_E_OBJECT_IN_USE
- Medium attached to virtual machine.VBOX_E_FILE_ERROR
- Settings file not accessible.VBOX_E_XML_ERROR
- Could not parse the settings file.
public java.lang.String getProperty(java.lang.String name)
IMediumFormat.describeProperties(Holder,Holder,Holder,Holder,Holder)
.
VBOX_E_OBJECT_NOT_FOUND
- Requested property does not exist (not supported by the format).E_INVALIDARG
- name is null or empty.
name
- Name of the property to get.
public void setProperty(java.lang.String name, java.lang.String value)
IMediumFormat.describeProperties(Holder,Holder,Holder,Holder,Holder)
.
VBOX_E_OBJECT_NOT_FOUND
- Requested property does not exist (not supported by the format).E_INVALIDARG
- name is null or empty.
name
- Name of the property to set.value
- Property value to set.
NOTE: Setting the property value to null or an empty string is
equivalent to deleting the existing value. A default value (if it is
defined for this property) will be used by the format backend in this
case.public java.util.List<java.lang.String> getProperties(java.lang.String names, Holder<java.util.List<java.lang.String>> returnNames)
IMediumFormat.describeProperties(Holder,Holder,Holder,Holder,Holder)
.
The method returns two arrays, the array of property names corresponding
to the names argument and the current values of these properties.
Both arrays have the same number of elements with each element at the
given index in the first array corresponds to an element at the same
index in the second array.
For properties that do not have assigned values, an empty string is
returned at the appropriate index in the returnValues array.
names
- Names of properties to get.returnNames
- Names of returned properties.
public void setProperties(java.util.List<java.lang.String> names, java.util.List<java.lang.String> values)
setProperty(String,String)
is preferred if you
need to set several properties at once since it is more efficient.
The list of all properties supported by the given medium format can
be obtained withIMediumFormat.describeProperties(Holder,Holder,Holder,Holder,Holder)
.
Setting the property value to null or an empty string is equivalent
to deleting the existing value. A default value (if it is defined for
this property) will be used by the format backend in this case.
names
- Names of properties to set.values
- Values of properties to set.public IProgress createBaseStorage(java.lang.Long logicalSize, java.util.List<MediumVariant> variant)
deleteStorage()
, otherwise the operation will fail.
Before the operation starts, the medium is placed inMediumState.Creating
state. If the create operation
fails, the medium will be placed back inMediumState.NotCreated
state.
After the returned progress object reports that the operation has
successfully completed, the medium state will be set toMediumState.Created
, the medium will be remembered by this
VirtualBox installation and may be attached to virtual machines.
VBOX_E_NOT_SUPPORTED
- The variant of storage creation operation is not supported. SeeIMediumFormat.getCapabilities()
.
logicalSize
- Maximum logical size of the medium in bytes.variant
- Exact image variant which should be created (as a combination ofMediumVariant
flags).
public IProgress deleteStorage()
MediumState.Created
.
Before the operation starts, the medium is placed inMediumState.Deleting
state and gets removed from the list
of remembered hard disks (media registry). If the delete operation
fails, the medium will be remembered again and placed back toMediumState.Created
state.
After the returned progress object reports that the operation is
complete, the medium state will be set toMediumState.NotCreated
and you will be able to use one of
the storage creation methods to create it again.
VBOX_E_OBJECT_IN_USE
- Medium is attached to a virtual machine.VBOX_E_NOT_SUPPORTED
- Storage deletion is not allowed because neither of storage creation
operations are supported. SeeIMediumFormat.getCapabilities()
.
getState()
value
to answer this question.close()
public IProgress createDiffStorage(IMedium target, java.util.List<MediumVariant> variant)
MediumState.NotCreated
state (i.e. must not have an existing storage unit). Upon successful
completion, this operation will set the type of the target medium toMediumType.Normal
and create a storage unit necessary to
represent the differencing medium data in the given format (according
to the storage format of the target object).
After the returned progress object reports that the operation is
successfully complete, the target medium gets remembered by this
VirtualBox installation and may be attached to virtual machines.
VBOX_E_OBJECT_IN_USE
- Medium not in NotCreated state.
target
- Target medium.variant
- Exact image variant which should be created (as a combination ofMediumVariant
flags).
MediumState.LockedRead
state for the duration of this operation.public IProgress mergeTo(IMedium target)
Base <- Diff_1 <- Diff_2Here, calling this method on the
Base
medium object withDiff_2
as an argument will be a forward merge; calling it onDiff_2
withBase
as an argument will be a backward
merge. Note that in both cases the contents of the resulting medium
will be the same, the only difference is the medium object that takes
the result of the merge operation. In case of the forward merge in the
above example, the result will be written toDiff_2
; in case of
the backward merge, the result will be written toBase
. In
other words, the result of the operation is always stored in the target
medium.
Upon successful operation completion, the storage units of all media in
the chain between this (source) medium and the target medium, including
the source medium itself, will be automatically deleted and the
relevant medium objects (including this medium) will become
uninitialized. This means that any attempt to call any of
their methods or attributes will fail with the"Object not ready" (E_ACCESSDENIED)
error. Applied to the above
example, the forward merge ofBase
toDiff_2
will
delete and uninitialize bothBase
andDiff_1
media.
Note thatDiff_2
in this case will become a base medium
itself since it will no longer be based on any other medium.
Considering the above, all of the following conditions must be met in
order for the merge operation to succeed:MediumType.Immutable
medium.MediumState.LockedRead
orMediumState.LockedWrite
state.
target
- Target medium.
MediumState.Deleting
state and the target medium will be
placed toMediumState.LockedWrite
state and for the
duration of this operation.public IProgress cloneTo(IMedium target, java.util.List<MediumVariant> variant, IMedium parent)
MediumState.NotCreated
state (i.e. must not have an existing storage unit) or inMediumState.Created
state (i.e. created and not locked, and
big enough to hold the data or else the copy will be partial). Upon
successful completion, the cloned medium will contain exactly the
same sector data as the medium being cloned, except that in the
first case a new UUID for the clone will be randomly generated, and in
the second case the UUID will remain unchanged.
The parent argument defines which medium will be the parent
of the clone. Passing a null reference indicates that the clone will
be a base image, i.e. completely independent. It is possible to specify
an arbitrary medium for this parameter, including the parent of the
medium which is being cloned. Even cloning to a child of the source
medium is possible. Note that when cloning to an existing image, the
parent argument is ignored.
After the returned progress object reports that the operation is
successfully complete, the target medium gets remembered by this
VirtualBox installation and may be attached to virtual machines.
E_NOTIMPL
- The specified cloning variant is not supported at the moment.
target
- Target medium.variant
- Exact image variant which should be created (as a combination ofMediumVariant
flags).parent
- Parent of the cloned medium.
MediumState.LockedRead
state for the duration of this operation.public IProgress cloneToBase(IMedium target, java.util.List<MediumVariant> variant)
MediumState.NotCreated
state (i.e. must not have an existing storage unit) or inMediumState.Created
state (i.e. created and not locked, and
big enough to hold the data or else the copy will be partial). Upon
successful completion, the cloned medium will contain exactly the
same sector data as the medium being cloned, except that in the
first case a new UUID for the clone will be randomly generated, and in
the second case the UUID will remain unchanged.
The parent argument defines which medium will be the parent
of the clone. In this case the clone will be a base image, i.e.
completely independent. It is possible to specify an arbitrary
medium for this parameter, including the parent of the
medium which is being cloned. Even cloning to a child of the source
medium is possible. Note that when cloning to an existing image, the
parent argument is ignored.
After the returned progress object reports that the operation is
successfully complete, the target medium gets remembered by this
VirtualBox installation and may be attached to virtual machines.
E_NOTIMPL
- The specified cloning variant is not supported at the moment.
target
- Target medium.variant
- MediumVariant
flags).
MediumState.LockedRead
state for the duration of this operation.public IProgress moveTo(java.lang.String location)
IVirtualBox.getHomeFolder()
or absolute. Note that if the given location
specification does not contain the file extension part then a proper
default extension will be automatically appended by the implementation
depending on the medium type.
E_NOTIMPL
- The operation is not implemented yet.VBOX_E_NOT_SUPPORTED
- Medium format does not support changing the location.
location
- New location.
public IProgress compact()
MediumState.LockedWrite
state and all its parent media (if any) will be placed toMediumState.LockedRead
state for the duration of this
operation.
Please note that the results can be either returned straight away,
or later as the result of the background operation via the object
returned via the progress parameter.
VBOX_E_NOT_SUPPORTED
- Medium format does not support compacting (but potentially
needs it).
public IProgress resize(java.lang.Long logicalSize)
MediumState.LockedWrite
state for the duration of this operation.
Please note that the results can be either returned straight away,
or later as the result of the background operation via the object
returned via the progress parameter.
VBOX_E_NOT_SUPPORTED
- Medium format does not support resizing.
logicalSize
- New nominal capacity of the medium in bytes.
public IProgress reset()
getAutoReset()
attribute is true.
The medium will be write-locked for the duration of this operation (seelockWrite()
).
VBOX_E_NOT_SUPPORTED
- This is not a differencing medium.VBOX_E_INVALID_OBJECT_STATE
- Medium is not inMediumState.Created
orMediumState.Inaccessible
state.
public IProgress changeEncryption(java.lang.String currentPassword, java.lang.String cipher, java.lang.String newPassword, java.lang.String newPasswordId)
MediumState.LockedWrite
state.
Please note that the results can be either returned straight away,
or later as the result of the background operation via the object
returned via the progress parameter.
VBOX_E_NOT_SUPPORTED
- Encryption is not supported for this medium because it is attached to more than one VM
or has children.
currentPassword
- The current password the medium is protected with. Use an empty string to indicate
that the medium isn't encrypted.cipher
- The cipher to use for encryption. An empty string indicates no encryption for the
result.newPassword
- The new password the medium should be protected with. An empty password and password ID
will result in the medium being encrypted with the current password.newPasswordId
- The ID of the new password when unlocking the medium.
public java.lang.String getEncryptionSettings(Holder<java.lang.String> cipher)
VBOX_E_NOT_SUPPORTED
- Encryption is not configured for this medium.
cipher
- The cipher used for encryption.
public void checkEncryptionPassword(java.lang.String password)
VBOX_E_NOT_SUPPORTED
- Encryption is not configured for this medium.VBOX_E_PASSWORD_INCORRECT
- The given password is incorrect.
password
- The password to check.public IMediumIO openForIO(java.lang.Boolean writable, java.lang.String password)
writable
- Set this to open the medium for both reading and writing. When
not set the medium is opened readonly.password
- Password for accessing an encrypted medium. Must be empty if not encrypted.
public IProgress resizeAndCloneTo(IMedium target, java.lang.Long logicalSize, java.util.List<MediumVariant> variant, IMedium parent)
cloneTo(org.virtualbox_7_0.IMedium,List,org.virtualbox_7_0.IMedium)
andresize(Long)
. The target medium will take the
contents of the calling medium.
E_NOTIMPL
- The specified cloning variant is not supported at the moment.
target
- Target medium.logicalSize
- New nominal capacity of the medium in bytes.variant
- Exact image variant which should be created (as a combination ofMediumVariant
flags).parent
- Parent of the cloned medium.
|
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |