IMedium Interface Reference

The IMedium interface is a common interface for all objects representing virtual media such as hard disks, CD/DVD images and floppy images. More...

Inheritance diagram for IMedium:

IDVDImage IFloppyImage IHardDisk

List of all members.

Public Member Functions

void getSnapshotIds (in uuid machineId,[retval] out uuid[] snapshotIds)
 Returns an array of UUIDs of all snapshots of the given machine where this medium is attached to.
void lockRead ([retval] out MediaState state)
 Locks this medium for reading.
void unlockRead ([retval] out MediaState state)
 Cancels the read lock previously set by lockRead.
void lockWrite ([retval] out MediaState state)
 Locks this medium for writing.
void unlockWrite ([retval] out MediaState state)
 Cancels the write lock previously set by lockWrite.
void close ()
 Closes this medium.

Public Attributes

readonly attribute uuid id
 UUID of the medium.
attribute wstring description
 Optional description of the medium.
readonly attribute MediaState state
 Current media state.
attribute wstring location
 Location of the storage unit holding media data.
readonly attribute wstring name
 Name of the storage unit holding media data.
readonly attribute unsigned
long long 
size
 Physical size of the storage unit used to hold media data (in bytes).
readonly attribute wstring lastAccessError
 Text message that represents the result of the last accessibility check.
readonly attribute uuid[] machineIds
 Array of UUIDs of all machines this medium is attached to.


Detailed Description

The IMedium interface is a common interface for all objects representing virtual media such as hard disks, CD/DVD images and floppy images.

Each medium is associated with a storage unit (such as a file on the host computer or a network resource) that holds actual data. The location of the storage unit is represented by the location attribute. The value of this attribute is media type dependent.

The exact media type may be determined by querying the appropriate interface such as:

Existing media are opened using the following methods, depending on the media type:

New hard disk media are created using the IVirtualBox::createHardDisk method. CD/DVD and floppy images are created outside VirtualBox, usually by storing a copy of the real medium of the corresponding type in a regular file.

Known Media

When an existing medium gets opened for the first time, it gets automatically remembered by the given VirtualBox installation or, in other words, becomes a known medium. Known media are stored in the media registry transparently maintained by VirtualBox and stored in settings files so that this registry is preserved when VirtualBox is not running.

Newly created virtual hard disks get remembered only when the associated storage unit is actually created (see IHardDisk for more details).

All known media can be enumerated using IVirtualBox::hardDisks, IVirtualBox::DVDImages and IVirtualBox::floppyImages attributes. Individual media can be quickly found by UUID using IVirtualBox::getHardDisk and similar methods or by location using IVirtualBox::findHardDisk and similar methods.

Only known media can be attached to virtual machines.

Removing known media from the media registry is performed when the given medium is closed using the close method or when its associated storage unit is deleted (only for hard disks).

Accessibility Checks

The given medium (with the created storage unit) is considered to be accessible when its storage unit can be read. Accessible media are indicated by the MediaState_Created value of the state attribute. When 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 considered to be inaccessible which is indicated by the MediaState_Inaccessible state. The details about the reason of being inaccessible can be obtained using the lastAccessError attribute.

A new accessibility check is performed each time the state attribute is read. Please note that this check may take long time (several seconds or even minutes, depending on the storage unit location and format), and will block the calling thread until finished. For this reason, it is recommended to never read this attribute on the main UI thread to avoid making the UI unresponsive.

Note that when VirtualBox starts up (e.g. the VirtualBox object gets created for the first time), all known media are in the MediaState_Inaccessible state but the value of the lastAccessError attribute is null because no actual accessibility check is made on startup. 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.

Interface ID:
{A7FB3BFB-C180-4274-BAE4-7FBC89046E13}

Member Function Documentation

void IMedium::getSnapshotIds ( in uuid  machineId,
[retval] out uuid[]  snapshotIds 
)

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.
snapshotIds Array of snapshot UUIDs of the given machine using this medium.

void IMedium::lockRead ( [retval] out MediaState  state  ) 

Locks this medium for reading.

The read lock is shared: many clients can simultaneously lock the same media for reading unless it is already locked for writing (see 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) and that an attempt to start a virtual machine that wants to modify the medium will also fail.

When the virtual machine is started up, it locks for reading all media it uses in read-only mode. If some media cannot be locked for reading, the startup procedure will fail.

The medium locked for reading must be unlocked using the unlockRead method. Calls to lockRead can be nested and must be followed by the same number of paired unlockRead calls.

This method sets the media state to MediaState_LockedRead on success. The state prior to this call must be MediaState_Created, MediaState_Inaccessible or MediaState_LockedRead. As you can see, inaccessible media can be locked too. This is not an error; this method performs a logical lock that prevents modifications of this media through the VirtualBox API, not a physical lock of the underlying storage unit.

This method returns the current state of the medium before the operation.

Parameters:
state State of the medium after the operation.
Expected result codes:
VBOX_E_INVALID_OBJECT_STATE Invalid media state (e.g. not created, locked, inaccessible, creating, deleting).

void IMedium::unlockRead ( [retval] out MediaState  state  ) 

Cancels the read lock previously set by lockRead.

For both, success and failure, this method returns the current state of the medium after the operation.

See lockRead for more details.

Parameters:
state State of the medium after the operation.
Expected result codes:
VBOX_E_INVALID_OBJECT_STATE Medium not locked for reading.

void IMedium::lockWrite ( [retval] out MediaState  state  ) 

Locks this medium for writing.

The write lock, as opposed to 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.

When the 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) and an attempt to start a virtual machine wanting to modify or to read the medium will fail.

When the 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.

The medium locked for writing must be unlocked using the unlockWrite method. Calls to lockWrite can not be nested and must be followed by aunlockWrite call before the next lockWrite call.

This method sets the media state to MediaState_LockedWrite on success. The state prior to this call must be MediaState_Created or MediaState_Inaccessible. As you can see, inaccessible media can be locked too. This is not an error; this method performs a logical lock preventing modifications of this media through the VirtualBox API, not a physical lock of the underlying storage unit.

For both, success and failure, this method returns the current state of the medium before the operation.

Parameters:
state State of the medium after the operation.
Expected result codes:
VBOX_E_INVALID_OBJECT_STATE Invalid media state (e.g. not created, locked, inaccessible, creating, deleting).

void IMedium::unlockWrite ( [retval] out MediaState  state  ) 

Cancels the write lock previously set by lockWrite.

For both, success and failure, this method returns the current state of the medium after the operation.

See lockWrite for more details.

Parameters:
state State of the medium after the operation.
Expected result codes:
VBOX_E_INVALID_OBJECT_STATE Medium not locked for writing.

void IMedium::close (  ) 

Closes this medium.

The hard disk must not be attached to any known virtual machine and must not have any known child hard disks, otherwise the operation will fail.

When the hard disk is successfully closed, it gets removed from the list of remembered hard disks, but its storage unit is not deleted. In particular, this means that this hard disk can be later opened again using the IVirtualBox::openHardDisk call.

Note that after this method successfully returns, the given hard disk 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:
VBOX_E_INVALID_OBJECT_STATE Invalid media 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.


Member Data Documentation

readonly attribute uuid IMedium::id

UUID of the medium.

For a newly created medium, this value is a randomly generated UUID.

Note:
For media in one of MediaState_NotCreated, MediaState_Creating or MediaState_Deleting states, the value of this property is undefined and will most likely be an empty UUID.

attribute wstring IMedium::description

Optional description of the medium.

For newly created media, the value of this attribute value is null.

Media 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 when state is MediaState_Inaccessible or MediaState_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 the MediaState_LockedRead state.

readonly attribute MediaState IMedium::state

Current media state.

Inspect MediaState values for details.

Reading this attribute may take a long time because an accessibility check of the storage unit is performed each time the attribute is read. 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 -- the call will not return until a timeout interval defined by the host OS for this operation expires.

If the last known state of the medium is MediaState_Created and the accessibility check fails then the state would be set to MediaState_Inaccessible and lastAccessError may be used to get more details about the failure. If the state of the medium is MediaState_LockedRead or MediaState_LockedWrite then it remains the same, and a non-null value of lastAccessError will indicate a failed accessibility check in this case.

Note that not all media states are applicable to all media types. For example, states MediaState_NotCreated, MediaState_LockedWrite, MediaState_Creating, MediaState_Deleting are meaningless for IDVDImage and IFloppyImage media.

attribute wstring IMedium::location

Location of the storage unit holding media data.

The format of the location string is media type specific. For media types using regular files in a host's file system, the location string is the full file name.

Some media types may support changing the storage unit location by simply changing the value of this property. If this operation is not supported, the implementation will return E_NOTIMPL in attempt to set this attribute's value.

When setting a value of the location attribute which is a regular file in the host's file system, the given file name may be either relative to the VirtualBox home folder 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 media type.

readonly attribute wstring IMedium::name

Name of the storage unit holding media data.

The returned string is a short version of the location 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 the location attribute, the name attribute will not necessary be unique for a list of media of the given type and format.

readonly attribute unsigned long long IMedium::size

Physical size of the storage unit used to hold media data (in bytes).

Note:
For media whose state is MediaState_Inaccessible, the value of this property is the last known size. For MediaState_NotCreated media, the returned value is zero.

readonly attribute wstring IMedium::lastAccessError

Text message that represents the result of the last accessibility check.

Accessibility checks are performed each time the state attribute is read. A null string is returned if the last accessibility check was successful. A non-null string indicates a failure and should normally describe a reason of the failure (for example, a file read error).

readonly attribute uuid [] IMedium::machineIds

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. See getSnapshotIds for details.


Generated on Tue Apr 7 21:43:44 2009 for VirtualBox Main API by  doxygen 1.5.6