org.virtualbox_5_0
Class IMedium

java.lang.Object
  extended by org.virtualbox_5_0.IUnknown
      extended by org.virtualbox_5_0.IMedium

public class IMedium
extends IUnknown

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:

Existing media are opened usingIVirtualBox.openMedium(String,org.virtualbox_5_0.DeviceType,org.virtualbox_5_0.AccessMode,Boolean); new hard disk media can be created with the VirtualBox API using theIVirtualBox.createMedium(String,String,org.virtualbox_5_0.AccessMode,org.virtualbox_5_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_5_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().

Media registries

When a medium has been opened or created using one of the aforementioned APIs, it becomes "known" to VirtualBox. Known media can be attached to virtual machines and re-found throughIVirtualBox.openMedium(String,org.virtualbox_5_0.DeviceType,org.virtualbox_5_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_5_0.DeviceType,org.virtualbox_5_0.IMedium). For backwards compatibility, which registry a medium is added to depends on which VirtualBox version created a machine:SeeIVirtualBox.openMedium(String,org.virtualbox_5_0.DeviceType,org.virtualbox_5_0.AccessMode,Boolean)for more information. Media are removed from media registries by theclose(),deleteStorage()andmergeTo(org.virtualbox_5_0.IMedium)methods.

Accessibility checks

VirtualBox defers media accessibility checks until therefreshState()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.

Medium types

There are five types of medium behavior which are stored in thegetType()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.

Automatic composition of the file name part

Another extension to thegetLocation()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.NotCreatedstate, 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: {4AFE423B-43E0-E9D0-82E8-CEB307940DDA}


Field Summary
 
Fields inherited from class org.virtualbox_5_0.IUnknown
obj, port
 
Constructor Summary
IMedium(java.lang.String wrapped, org.virtualbox_5_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 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 byrefreshState().
 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 byrefreshState().
 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 atMediumVariant.
 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.
static IMedium queryInterface(IUnknown obj)
           
 MediumState refreshState()
          If the current medium state (seeMediumState) 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.
 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.
 IProgress setLocation(java.lang.String location)
          Changes the location of this medium.
 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_5_0.IUnknown
getRemoteWSPort, getWrapped, releaseRemote
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

IMedium

public IMedium(java.lang.String wrapped,
               org.virtualbox_5_0.jaxws.VboxPortType port)
Method Detail

getId

public java.lang.String getId()
UUID of the medium. For a newly created medium, this value is a randomly generated UUID. NOTE: For media in one of MediumState_NotCreated, MediumState_Creating or MediumState_Deleting states, the value of this property is undefined and will most likely be an empty UUID.

Returns:
String

getDescription

public java.lang.String getDescription()
Optional description of the medium. For a newly created medium the value of this attribute is an empty string. Medium types that don't support this attribute will return E_NOTIMPL in attempt to get or set this attribute's value. NOTE: For some storage types, reading this attribute may return an outdated (last known) value whengetState()isMediumState.InaccessibleorMediumState.LockedWritebecause 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.LockedReadstate.

Returns:
String

setDescription

public void setDescription(java.lang.String value)
Optional description of the medium. For a newly created medium the value of this attribute is an empty string. Medium types that don't support this attribute will return E_NOTIMPL in attempt to get or set this attribute's value. NOTE: For some storage types, reading this attribute may return an outdated (last known) value whengetState()isMediumState.InaccessibleorMediumState.LockedWritebecause 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.LockedReadstate.

Parameters:
value - String

getState

public MediumState getState()
Returns the current medium state, which is the last state set by the accessibility check performed byrefreshState(). 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.

Returns:
org.virtualbox_5_0.MediumState

getVariant

public java.util.List<MediumVariant> getVariant()
Returns the storage format variant information for this medium as an array of the flags described atMediumVariant. BeforerefreshState()is called this method returns an undefined value.

Returns:
List<org.virtualbox_5_0.MediumVariant>

getLocation

public java.lang.String getLocation()
Location of the storage unit holding medium data. The format of the location string is medium type specific. For medium types using regular files in a host's file system, the location string is the full file name.

Returns:
String

getName

public java.lang.String getName()
Name of the storage unit holding medium data. The returned string is a short version of thegetLocation()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.

Returns:
String

getDeviceType

public DeviceType getDeviceType()
Kind of device (DVD/Floppy/HardDisk) which is applicable to this medium.

Returns:
org.virtualbox_5_0.DeviceType

getHostDrive

public java.lang.Boolean getHostDrive()
True if this corresponds to a drive on the host.

Returns:
Boolean

getSize

public java.lang.Long getSize()
Physical size of the storage unit used to hold medium data (in bytes). NOTE: For media whosegetState()isMediumState.Inaccessible, the value of this property is the last known size. ForMediumState.NotCreatedmedia, the returned value is zero.

Returns:
Long

getFormat

public java.lang.String getFormat()
Storage format of this medium. The value of this attribute is a string that specifies a backend used to store medium data. The storage format is defined when you create a new medium or automatically detected when you open an existing medium, and cannot be changed later. The list of all storage formats supported by this VirtualBox installation can be obtained usingISystemProperties.getMediumFormats().

Returns:
String

getMediumFormat

public IMediumFormat getMediumFormat()
Storage medium format object corresponding to this medium. The value of this attribute is a reference to the medium format object that specifies the backend properties used to store medium data. The storage format is defined when you create a new medium or automatically detected when you open an existing medium, and cannot be changed later. NOTE: null is returned if there is no associated medium format object. This can e.g. happen for medium objects representing host drives and other special medium objects.

Returns:
org.virtualbox_5_0.IMediumFormat

getType

public MediumType getType()
Type (role) of this medium. The following constraints apply when changing the value of this attribute:The type of a newly created or opened medium is set toMediumType.Normal, except for DVD and floppy media, which have a type ofMediumType.Writethrough.

Returns:
org.virtualbox_5_0.MediumType

setType

public void setType(MediumType value)
Type (role) of this medium. The following constraints apply when changing the value of this attribute:The type of a newly created or opened medium is set toMediumType.Normal, except for DVD and floppy media, which have a type ofMediumType.Writethrough.

Parameters:
value - org.virtualbox_5_0.MediumType

getAllowedTypes

public java.util.List<MediumType> getAllowedTypes()
Returns which medium types can selected for this medium. Expected result codes:
E_NOTIMPLThis attribute is not implemented at the moment.

Returns:
List<org.virtualbox_5_0.MediumType>

getParent

public IMedium getParent()
Parent of this medium (the medium this medium is directly based on). Only differencing media have parents. For base (non-differencing) media, null is returned.

Returns:
org.virtualbox_5_0.IMedium

getChildren

public java.util.List<IMedium> getChildren()
Children of this medium (all differencing media directly based on this medium). A null array is returned if this medium does not have any children.

Returns:
List<org.virtualbox_5_0.IMedium>

getBase

public IMedium getBase()
Base medium of this medium. If this is a differencing medium, its base medium is the medium the given medium branch starts from. For all other types of media, this property returns the medium object itself (i.e. the same object this property is read on).

Returns:
org.virtualbox_5_0.IMedium

getReadOnly

public java.lang.Boolean getReadOnly()
Returns true if this medium is read-only and false otherwise. A medium is considered to be read-only when its contents cannot be modified without breaking the integrity of other parties that depend on this medium such as its child media or snapshots of virtual machines where this medium is attached to these machines. If there are no children and no such snapshots then there is no dependency and the medium is not read-only. The value of this attribute can be used to determine the kind of the attachment that will take place when attaching this medium to a virtual machine. If the value is false then the medium will be attached directly. If the value is true then the medium will be attached indirectly by creating a new differencing child medium for that. See the interface description for more information. Note that allMediumType.Immutablemedia are always read-only while allMediumType.Writethroughmedia 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.

Returns:
Boolean

getLogicalSize

public 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. The logical size is defined when the medium is created and cannot be changed later. NOTE: For media whose state isgetState()isMediumState.Inaccessible, the value of this property is the last known logical size. ForMediumState.NotCreatedmedia, the returned value is zero.

Returns:
Long

getAutoReset

public java.lang.Boolean getAutoReset()
Whether this differencing medium will be automatically reset each time a virtual machine it is attached to is powered up. This attribute is automatically set to true for the last differencing image of an "immutable" medium (seeMediumType). Seereset()for more information about resetting differencing media. Expected result codes:
@link ::VBOX_E_NOT_SUPPORTED VBOX_E_NOT_SUPPORTEDThis is not a differencing medium (when changing the attribute value).
NOTE: Reading this property on a base (non-differencing) medium will always false. Changing the value of this property in this case is not supported.

Returns:
Boolean

setAutoReset

public 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. This attribute is automatically set to true for the last differencing image of an "immutable" medium (seeMediumType). Seereset()for more information about resetting differencing media. Expected result codes:
@link ::VBOX_E_NOT_SUPPORTED VBOX_E_NOT_SUPPORTEDThis is not a differencing medium (when changing the attribute value).
NOTE: Reading this property on a base (non-differencing) medium will always false. Changing the value of this property in this case is not supported.

Parameters:
value - Boolean

getLastAccessError

public java.lang.String getLastAccessError()
Text message that represents the result of the last accessibility check performed byrefreshState(). 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).

Returns:
String

getMachineIds

public java.util.List<java.lang.String> getMachineIds()
Array of UUIDs of all machines this medium is attached to. A null array is returned if this medium is not attached to any machine or to any machine's snapshot. NOTE: The returned array will include a machine even if this medium is not attached to that machine in the current state but attached to it in one of the machine's snapshots. SeegetSnapshotIds(String)for details.

Returns:
List<String>

queryInterface

public static IMedium queryInterface(IUnknown obj)

setIds

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

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

refreshState

public MediumState refreshState()
If the current medium state (seeMediumState) 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.

Returns:
New medium state.

getSnapshotIds

public 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. If the medium is attached to the machine in the current state, then the first element in the array will always be the ID of the queried machine (i.e. the value equal to the machineId argument), followed by snapshot IDs (if any). If the medium is not attached to the machine in the current state, then the array will contain only snapshot IDs. The returned array may be null if this medium is not attached to the given machine at all, neither in the current state nor in one of the snapshots.

Parameters:
machineId - UUID of the machine to query.
Returns:
Array of snapshot UUIDs of the given machine using this medium.

lockRead

public IToken lockRead()
Locks this medium for reading. A read lock is shared: many clients can simultaneously lock the same medium for reading unless it is already locked for writing (seelockWrite()) 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 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_5_0.IMedium,List,org.virtualbox_5_0.IMedium)ormergeTo(org.virtualbox_5_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.

Returns:
Token object, when this is released (reference count reaches 0) then the lock count is decreased. The lock is released when the lock count reaches 0. Expected result codes:
@link ::VBOX_E_INVALID_OBJECT_STATE VBOX_E_INVALID_OBJECT_STATEInvalid medium state (e.g. not created, locked, inaccessible, creating, deleting).

lockWrite

public IToken lockWrite()
Locks this medium for writing. A write lock, as opposed tolockRead(), 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_5_0.IMedium,List,org.virtualbox_5_0.IMedium)ormergeTo(org.virtualbox_5_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.

Returns:
Token object, when this is released (reference count reaches 0) then the lock is released. Expected result codes:
@link ::VBOX_E_INVALID_OBJECT_STATE VBOX_E_INVALID_OBJECT_STATEInvalid medium state (e.g. not created, locked, inaccessible, creating, deleting).

close

public void close()
Closes this medium. The medium must not be attached to any known virtual machine and must not have any known child media, otherwise the operation will fail. When the medium is successfully closed, it is removed from the list of registered media, but its storage unit is not deleted. In particular, this means that this medium can later be opened again using theIVirtualBox.openMedium(String,org.virtualbox_5_0.DeviceType,org.virtualbox_5_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. Expected result codes:
@link ::VBOX_E_INVALID_OBJECT_STATE VBOX_E_INVALID_OBJECT_STATEInvalid medium state (other than not created, created or inaccessible).
@link ::VBOX_E_OBJECT_IN_USE VBOX_E_OBJECT_IN_USEMedium attached to virtual machine.
@link ::VBOX_E_FILE_ERROR VBOX_E_FILE_ERRORSettings file not accessible.
@link ::VBOX_E_XML_ERROR VBOX_E_XML_ERRORCould not parse the settings file.


getProperty

public java.lang.String getProperty(java.lang.String name)
Returns the value of the custom medium property with the given name. The list of all properties supported by the given medium format can be obtained withIMediumFormat.describeProperties(Holder,Holder,Holder,Holder,Holder).

Parameters:
name - Name of the property to get.
Returns:
Current property value. Expected result codes:
@link ::VBOX_E_OBJECT_NOT_FOUND VBOX_E_OBJECT_NOT_FOUNDRequested property does not exist (not supported by the format).
E_INVALIDARGname is null or empty.
NOTE: If this method returns an empty string in value, the requested property is supported but currently not assigned any value.

setProperty

public void setProperty(java.lang.String name,
                        java.lang.String value)
Sets the value of the custom medium property with the given name. The list of all properties supported by the given medium format can be obtained withIMediumFormat.describeProperties(Holder,Holder,Holder,Holder,Holder).

Parameters:
name - Name of the property to set.
value - Property value to set. Expected result codes:
@link ::VBOX_E_OBJECT_NOT_FOUND VBOX_E_OBJECT_NOT_FOUNDRequested property does not exist (not supported by the format).
E_INVALIDARGname is null or empty.
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.

getProperties

public 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. The names of the properties to get are specified using the names argument which is a list of comma-separated property names or an empty string if all properties are to be returned.The list of all properties supported by the given medium format can be obtained withIMediumFormat.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.

Parameters:
names - Names of properties to get.
returnNames - Names of returned properties.
Returns:
Values of returned properties. NOTE: Currently the value of this argument is ignored and the method always returns all existing properties.

setProperties

public 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. The names of the properties to set are passed in the names array along with the new values for them in the values array. Both arrays have the same number of elements with each element at the given index in the first array corresponding to an element at the same index in the second array. If there is at least one property name in names that is not valid, the method will fail before changing the values of any other properties from the names array. Using this method oversetProperty(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.

Parameters:
names - Names of properties to set.
values - Values of properties to set.

createBaseStorage

public 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 in the background. The previous storage unit created for this object, if any, must first be deleted usingdeleteStorage(), otherwise the operation will fail. Before the operation starts, the medium is placed inMediumState.Creatingstate. If the create operation fails, the medium will be placed back inMediumState.NotCreatedstate. 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.

Parameters:
logicalSize - Maximum logical size of the medium in bytes.
variant - Exact image variant which should be created (as a combination ofMediumVariantflags).
Returns:
Progress object to track the operation completion. Expected result codes:
@link ::VBOX_E_NOT_SUPPORTED VBOX_E_NOT_SUPPORTEDThe variant of storage creation operation is not supported. SeeIMediumFormat.getCapabilities().

deleteStorage

public IProgress deleteStorage()
Starts deleting the storage unit of this medium. The medium must not be attached to any known virtual machine and must not have any known child media, otherwise the operation will fail. It will also fail if there is no storage unit to delete or if deletion is already in progress, or if the medium is being in use (locked for read or for write) or inaccessible. Therefore, the only valid state for this operation to succeed isMediumState.Created. Before the operation starts, the medium is placed inMediumState.Deletingstate 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.Createdstate. After the returned progress object reports that the operation is complete, the medium state will be set toMediumState.NotCreatedand you will be able to use one of the storage creation methods to create it again.

Returns:
Progress object to track the operation completion. Expected result codes:
@link ::VBOX_E_OBJECT_IN_USE VBOX_E_OBJECT_IN_USEMedium is attached to a virtual machine.
@link ::VBOX_E_NOT_SUPPORTED VBOX_E_NOT_SUPPORTEDStorage deletion is not allowed because neither of storage creation operations are supported. SeeIMediumFormat.getCapabilities().
NOTE: If the deletion operation fails, it is not guaranteed that the storage unit still exists. You may check thegetState()value to answer this question.
See Also:
close()

createDiffStorage

public 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. The target medium must be inMediumState.NotCreatedstate (i.e. must not have an existing storage unit). Upon successful completion, this operation will set the type of the target medium toMediumType.Normaland 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.

Parameters:
target - Target medium.
variant - Exact image variant which should be created (as a combination ofMediumVariantflags).
Returns:
Progress object to track the operation completion. Expected result codes:
@link ::VBOX_E_OBJECT_IN_USE VBOX_E_OBJECT_IN_USEMedium not in NotCreated state.
NOTE: The medium will be set toMediumState.LockedReadstate for the duration of this operation.

mergeTo

public IProgress mergeTo(IMedium target)
Starts merging the contents of this medium and all intermediate differencing media in the chain to the given target medium. The target medium must be either a descendant of this medium or its ancestor (otherwise this method will immediately return a failure). It follows that there are two logical directions of the merge operation: from ancestor to descendant (forward merge) and from descendant to ancestor (backward merge). Let us consider the following medium chain:
Base <- Diff_1 <- Diff_2
Here, calling this method on theBasemedium object withDiff_2as an argument will be a forward merge; calling it onDiff_2withBaseas 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 ofBasetoDiff_2will delete and uninitialize bothBaseandDiff_1media. Note thatDiff_2in 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:

Parameters:
target - Target medium.
Returns:
Progress object to track the operation completion. NOTE: This (source) medium and all intermediates will be placed toMediumState.Deletingstate and the target medium will be placed toMediumState.LockedWritestate and for the duration of this operation.

cloneTo

public 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. The target medium must be either inMediumState.NotCreatedstate (i.e. must not have an existing storage unit) or inMediumState.Createdstate (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.

Parameters:
target - Target medium.
variant - Exact image variant which should be created (as a combination ofMediumVariantflags).
parent - Parent of the cloned medium.
Returns:
Progress object to track the operation completion. Expected result codes:
E_NOTIMPLThe specified cloning variant is not supported at the moment.
NOTE: This medium will be placed toMediumState.LockedReadstate for the duration of this operation.

cloneToBase

public 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. The target medium must be either inMediumState.NotCreatedstate (i.e. must not have an existing storage unit) or inMediumState.Createdstate (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.

Parameters:
target - Target medium.
variant - MediumVariantflags).
Returns:
Progress object to track the operation completion. Expected result codes:
E_NOTIMPLThe specified cloning variant is not supported at the moment.
NOTE: This medium will be placed toMediumState.LockedReadstate for the duration of this operation.

setLocation

public IProgress setLocation(java.lang.String location)
Changes the location of this medium. Some medium types may support changing the storage unit location by simply changing the value of the associated property. In this case the operation is performed immediately, and progress is returning a null reference. Otherwise on success there is a progress object returned, which signals progress and completion of the operation. This distinction is necessary because for some formats the operation is very fast, while for others it can be very slow (moving the image file by copying all data), and in the former case it'd be a waste of resources to create a progress object which will immediately signal completion. When setting a location for a medium which corresponds to a/several regular file(s) in the host's file system, the given file name may be either relative to theIVirtualBox.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.

Parameters:
location - New location.
Returns:
Progress object to track the operation completion. Expected result codes:
E_NOTIMPLThe operation is not implemented yet.
@link ::VBOX_E_NOT_SUPPORTED VBOX_E_NOT_SUPPORTEDMedium format does not support changing the location.

compact

public IProgress compact()
Starts compacting of this medium. This means that the medium is transformed into a possibly more compact storage representation. This potentially creates temporary images, which can require a substantial amount of additional disk space. This medium will be placed toMediumState.LockedWritestate and all its parent media (if any) will be placed toMediumState.LockedReadstate 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.

Returns:
Progress object to track the operation completion. Expected result codes:
@link ::VBOX_E_NOT_SUPPORTED VBOX_E_NOT_SUPPORTEDMedium format does not support compacting (but potentially needs it).

resize

public IProgress resize(java.lang.Long logicalSize)
Starts resizing this medium. This means that the nominal size of the medium is set to the new value. Both increasing and decreasing the size is possible, and there are no safety checks, since VirtualBox does not make any assumptions about the medium contents. Resizing usually needs additional disk space, and possibly also some temporary disk space. Note that resize does not create a full temporary copy of the medium, so the additional disk space requirement is usually much lower than using the clone operation. This medium will be placed toMediumState.LockedWritestate 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.

Parameters:
logicalSize - New nominal capacity of the medium in bytes.
Returns:
Progress object to track the operation completion. Expected result codes:
@link ::VBOX_E_NOT_SUPPORTED VBOX_E_NOT_SUPPORTEDMedium format does not support resizing.

reset

public IProgress reset()
Starts erasing the contents of this differencing medium. This operation will reset the differencing medium to its initial state when it does not contain any sector data and any read operation is redirected to its parent medium. This automatically gets called during VM power-up for every medium whosegetAutoReset()attribute is true. The medium will be write-locked for the duration of this operation (seelockWrite()).

Returns:
Progress object to track the operation completion. Expected result codes:
@link ::VBOX_E_NOT_SUPPORTED VBOX_E_NOT_SUPPORTEDThis is not a differencing medium.
@link ::VBOX_E_INVALID_OBJECT_STATE VBOX_E_INVALID_OBJECT_STATEMedium is not inMediumState.CreatedorMediumState.Inaccessiblestate.

changeEncryption

public IProgress changeEncryption(java.lang.String currentPassword,
                                  java.lang.String cipher,
                                  java.lang.String newPassword,
                                  java.lang.String newPasswordId)
Starts encryption of this medium. This means that the stored data in the medium is encrypted. This medium will be placed toMediumState.LockedWritestate. 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.

Parameters:
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.
Returns:
Progress object to track the operation completion. Expected result codes:
@link ::VBOX_E_NOT_SUPPORTED VBOX_E_NOT_SUPPORTEDEncryption is not supported for this medium because it is attached to more than one VM or has children.

getEncryptionSettings

public java.lang.String getEncryptionSettings(Holder<java.lang.String> cipher)
Returns the encryption settings for this medium.

Parameters:
cipher - The cipher used for encryption.
Returns:
The ID of the password when unlocking the medium. Expected result codes:
@link ::VBOX_E_NOT_SUPPORTED VBOX_E_NOT_SUPPORTEDEncryption is not configured for this medium.

checkEncryptionPassword

public void checkEncryptionPassword(java.lang.String password)
Checks whether the supplied password is correct for the medium.

Parameters:
password - The password to check. Expected result codes:
@link ::VBOX_E_NOT_SUPPORTED VBOX_E_NOT_SUPPORTEDEncryption is not configured for this medium.
@link ::VBOX_E_PASSWORD_INCORRECT VBOX_E_PASSWORD_INCORRECTThe given password is incorrect.