Index: /trunk/src/VBox/Main/idl/VirtualBox.xidl =================================================================== --- /trunk/src/VBox/Main/idl/VirtualBox.xidl (revision 35917) +++ /trunk/src/VBox/Main/idl/VirtualBox.xidl (revision 35918) @@ -1871,16 +1871,4 @@ The format of the location string is storage format specific. See and IMedium for more details. - - 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 are attached to a machine. Machines created with VirtualBox 4.0 - or later can have their own media registry. As a result, a medium attached - to such a machine will be remembered in that machine's XML settings file. - Media attached to older machines will continue to be added to the global - registry. @@ -3421,5 +3409,5 @@ - Delete all snapshots, detach all media and return hard disks for closing, but not removeable media. + Delete all snapshots, detach all media and return hard disks for closing, but not removable media. @@ -4396,5 +4384,5 @@ This method is intended for managing storage devices in general while a machine is powered off. It can be used to attach and detach fixed - and removeable media. The following kind of media can be attached + and removable media. The following kind of media can be attached to a machine: @@ -4409,5 +4397,5 @@ in the and arrays to indicate a host drive. - For removeable devices, you can also use + For removable devices, you can also use to change the media while the machine is running. @@ -5252,8 +5240,6 @@
  • With "DetachAllReturnNone", the call will succeed even if the machine is in "Saved" state or if it has snapshots or media attached. All media attached to the current machine - state or in snapshots will be detached. For machines created with VirtualBox 4.0 or - later, media which are registered in this machine's media registry which are still - attached to another machine besides this machine will be moved a another machine's - registry. No medium objects will be returned; all of the machine's media will remain open.
    • + state or in snapshots will be detached. No medium objects will be returned; + all of the machine's media will remain open.
  • With "DetachAllReturnHardDisksOnly", the call will behave like with "DetachAllReturnNone", except that all the hard disk medium objects which were detached from the machine will @@ -5261,5 +5247,5 @@ API for closing and deletion.
  • With "Full", the call will behave like with "DetachAllReturnHardDisksOnly", except - that all media will be returned in the array, including removeable media like DVDs and + that all media will be returned in the array, including removable media like DVDs and floppies. This might be useful if the user wants to inspect in detail which media were attached to the machine. Be careful when passing the media array to @@ -5267,4 +5253,9 @@ + A typical implementation will use "DetachAllReturnHardDisksOnly" and then pass the + resulting IMedium array to . This way, the machine is completely + deleted with all its saved states and hard disk images, but images for removable + drives (such as ISO and RAW files) will remain on disk. + This API does not verify whether the media files returned in the array are still attached to other machines (i.e. shared between several machines). If such a shared @@ -5272,15 +5263,19 @@ and the image will be silently skipped. - A typical implementation will use "DetachAllReturnHardDisksOnly" and then pass the - resulting IMedia array to . This way, the machine is completely - deleted with all its saved states and hard disk images, but images for removeable - drives (such as ISO and RAW files) will remain on disk. - - The call will fail if the machine is currently locked (see ). - It implicitly calls to save all current machine settings - before unregistering it. + This API may, however, move media from this machine's media registry to other media + registries (see for details on media registries). For machines + created with VirtualBox 4.0 or later, if media from this machine's media registry + are also attached to another machine (shared attachments), each such medium will be + moved to another machine's registry. This is because without this machine's media + registry, the other machine cannot find its media any more and would become inaccessible. + + This API implicitly calls to save all current machine settings + before unregistering it. It may also silently call saveSettings() on other machines + if media are moved to other machines' media registries. After successful method invocation, the event is fired. + + The call will fail if the machine is currently locked (see ). @@ -8953,6 +8948,8 @@ > - Virtual medium type. - IMedium + Virtual medium type. For each , this defines how the medium is + attached to a virtual machine (see ) and what happens + when a snapshot (see ) is taken of a virtual machine which has + the medium attached. At the moment DVD and floppy media are always of type "writethrough". @@ -9057,224 +9054,9 @@ hard disk or floppy or DVD image. - For removeable media (DVDs or floppies), there are two additional + For removable media (DVDs or floppies), there are two additional options. For one, the IMedium instance can be @c null to represent an empty drive with no media inserted (see ); secondly, the medium can be one of the pseudo-media for host drives listed in or . - - - - Medium object associated with this attachment; it - can be @c null for removable devices. - - - - Name of the storage controller of this attachment; this - refers to one of the controllers in - by name. - - - - Port number of this attachment. - See for the meaning of this value for the different controller types. - - - - - Device slot number of this attachment. - See for the meaning of this value for the different controller types. - - - - - Device type of this attachment. - - - - Pass I/O requests through to a device on the host. - - - - The bandwidth group this medium attachment is assigned to. - - - - - - - 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 (see ), 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: - -
      -
    • contains an array of - storage controllers (IDE, SATA, SCSI, SAS or a floppy controller; - these are instances of ).
      • -
    • contains an array of - medium attachments (instances of ), - 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.
      • -
    • Each IMedium in turn points to a storage unit (such as a file - on the host computer or a network resource) that holds actual - data. This location is represented by the - attribute.
      • -
    - - Existing media are opened using ; - new hard disk media can be created with the VirtualBox API using the - method. - - CD/DVD and floppy images (ISO and RAW files) are usually created outside - VirtualBox, e.g. by storing a copy of the real medium of the corresponding - type in a regular file. - - Only for CD/DVDs and floppies, an IMedium instance can also represent a host - drive; in that case the attribute contains the UUID of - one of the drives in or . - -

    Known media

    - - When an existing medium is opened and attached to a virtual machine, it - is automatically added to a media registry. If the medium has first - been attached to a machine which was created by VirtualBox 4.0 or later, - it is added to that machine's media registry (in the machine XML settings - file; this way all information about a machine's media attachments is - contained in a single file). For older media attachments (i.e. if the - medium was first attached to a machine which was created with a VirtualBox - version before 4.0), media continue to be registered in the global - VirtualBox settings file, for backwards compatibility. - - See for more information. - - All known media can be enumerated using - , - and - attributes. Individual media can be - quickly found using the method. - - 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 method or when its - associated storage unit is deleted. - -

    Accessibility checks

    - - VirtualBox defers media accessibility checks until the - 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 the - attribute is an empty string because no actual accessibility check has - been made yet. - - After calling , a medium is considered - accessible if its storage unit can be read. In that case, the - 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 considered inaccessible, which is indicated by the - "Inaccessible" state. The exact reason why the medium is inaccessible can be - obtained by reading the attribute. - -

    Medium types

    - - There are four types of medium behavior (see ): - "normal", "immutable", "writethrough" and "shareable", represented by the - attribute. The type of the medium defines how the - medium is attached to a virtual machine and what happens when a - snapshot of the virtual machine with the - attached medium is taken. At the moment DVD and floppy media are always - of type "writethrough". - - All media can be also divided in two groups: base media and - differencing media. 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 a parent. The differencing medium is said to be - linked to that 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 the - attribute: base media do not have parents they would - depend on, so the value of this attribute is always @c 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 the 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. - -

    Creating hard disks

    - - New base hard disks are created using - . Existing hard disks are - opened using . Differencing hard - disks are usually implicitly created by VirtualBox when needed but may - also be created explicitly using . - - After the hard disk is successfully created (including the storage unit) - or opened, it becomes a known hard disk (remembered in the internal media - registry). Known hard disks can be attached to a virtual machine, accessed - through or enumerated using the - array (only for base hard disks). - - The following methods, besides , - automatically remove the hard disk from the media registry: -
      -
      • -
      • -
    - - If the storage unit of the hard disk is a regular file in the host's - file system then the rules stated in the description of the - attribute apply when setting its value. - -

    Automatic composition of the file name part

    - - Another extension to the 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 in state, - e.g. before the storage unit is created, and works as follows. You set the - value of the 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.

    Attaching Hard Disks

    @@ -9282,6 +9064,6 @@ Hard disks are attached to virtual machines using the method and detached using the - method. Depending on their - , hard disks are attached either + method. Depending on a medium's + type (see ), hard disks are attached either directly or indirectly. @@ -9306,5 +9088,5 @@ dependent children or being part of the snapshot makes it impossible to modify hard disk contents without breaking the integrity of the - dependent party. The attribute allows to + dependent party. The attribute allows to quickly determine the kind of the attachment for the given hard disk. Note that if a normal base hard disk is to be indirectly @@ -9364,5 +9146,5 @@ (for example, as a result of virtual machine execution). If these hard disks are no more necessary, the caller can always delete them explicitly - using after they are actually de-associated + using after they are actually de-associated from this machine by the call. @@ -9436,4 +9218,201 @@ without losing the contents of the differencing hard disk actually attached to the machine in place of it. + +     + + + Medium object associated with this attachment; it + can be @c null for removable devices. + + + + Name of the storage controller of this attachment; this + refers to one of the controllers in + by name. + + + + Port number of this attachment. + See for the meaning of this value for the different controller types. + + + + + Device slot number of this attachment. + See for the meaning of this value for the different controller types. + + + + + Device type of this attachment. + + + + Pass I/O requests through to a device on the host. + + + + The bandwidth group this medium attachment is assigned to. + + +     + + + + 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: + +
      +
    • contains an array of + storage controllers (IDE, SATA, SCSI, SAS or a floppy controller; + these are instances of ).
      • +
    • contains an array of + medium attachments (instances of + created by ), + 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.
      • +
    • Each IMedium in turn points to a storage unit (such as a file + on the host computer or a network resource) that holds actual + data. This location is represented by the + attribute.
      • +
    + + Existing media are opened using ; + new hard disk media can be created with the VirtualBox API using the + method. Differencing hard + disks (see below) are usually implicitly created by VirtualBox as + needed, but may also be created explicitly using . + 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 the attribute contains the UUID of + one of the drives in or . + +

    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 accessed through . + They also appear in the global + , + and + 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 are + attached to a machine using . For + backwards compatibility, which registry a medium is added to depends on which + VirtualBox version created a machine: + +
      +
    • If the medium has first been attached to a machine which was created by + VirtualBox 4.0 or later, it is added to that machine's media registry in + the machine XML settings file. This way all information about a machine's + media attachments is contained in a single file and can be transported + easily.
      • +
    • For older media attachments (i.e. if the medium was first attached to a + machine which was created with a VirtualBox version before 4.0), media + continue to be registered in the global VirtualBox settings file, for + backwards compatibility.
      • +
    + + See for more information. + + Media are removed from media registries by the , + and methods. + +

    Accessibility checks

    + + VirtualBox defers media accessibility checks until the + 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 the + attribute is an empty string because no actual accessibility check has + been made yet. + + After calling , a medium is considered + accessible if its storage unit can be read. In that case, the + 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 considered inaccessible, which is indicated by the + "Inaccessible" state. The exact reason why the medium is inaccessible can be + obtained by reading the attribute. + +

    Medium types

    + + There are five types of medium behavior which are stored in the + attribute (see ) and + which define the medium's behavior with attachments and snapshots. + + All media can be also divided in two groups: base media and + differencing media. 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 a parent. The differencing medium is said to be + linked to that 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 the + attribute: base media do not have parents they would + depend on, so the value of this attribute is always @c 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 the 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 the 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 in state, + e.g. before the storage unit is created, and works as follows. You set the + value of the 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.