vd.h revision 67c733be807e2523abf07fbb3c5c4146828cfa2a
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * VBox HDD Container API.
e64031e20c39650a7bc902a3e1aba613b9415deevboxsync * Copyright (C) 2006-2013 Oracle Corporation
cf5f6bf2704d4fff443139e10bccc6a0a7fa4b85vboxsync * This file is part of VirtualBox Open Source Edition (OSE), as
cf5f6bf2704d4fff443139e10bccc6a0a7fa4b85vboxsync * available from http://www.virtualbox.org. This file is free software;
cf5f6bf2704d4fff443139e10bccc6a0a7fa4b85vboxsync * you can redistribute it and/or modify it under the terms of the GNU
cf5f6bf2704d4fff443139e10bccc6a0a7fa4b85vboxsync * General Public License (GPL) as published by the Free Software
cf5f6bf2704d4fff443139e10bccc6a0a7fa4b85vboxsync * Foundation, in version 2 as it comes in the "COPYING" file of the
cf5f6bf2704d4fff443139e10bccc6a0a7fa4b85vboxsync * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
cf5f6bf2704d4fff443139e10bccc6a0a7fa4b85vboxsync * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * The contents of this file may alternatively be used under the terms
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * of the Common Development and Distribution License Version 1.0
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * VirtualBox OSE distribution, in which case the provisions of the
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * CDDL are applicable instead of those of the GPL.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * You may elect to license modified versions of this file under the
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * terms and conditions of either the GPL or the CDDL or both.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync# error "There are no VBox HDD Container APIs available in Ring-0 Host Context!"
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync/** @defgroup grp_vd VBox HDD Container
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync/** Current VMDK image version. */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync/** Current VDI image major version. */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync/** Current VDI image minor version. */
79baed6836ae36c5f15b182292387484dcf7a752vboxsync/** Current VDI image version. */
79baed6836ae36c5f15b182292387484dcf7a752vboxsync#define VDI_IMAGE_VERSION ((VDI_IMAGE_VERSION_MAJOR << 16) | VDI_IMAGE_VERSION_MINOR)
79baed6836ae36c5f15b182292387484dcf7a752vboxsync/** Get VDI major version from combined version. */
79baed6836ae36c5f15b182292387484dcf7a752vboxsync/** Get VDI minor version from combined version. */
79baed6836ae36c5f15b182292387484dcf7a752vboxsync#define VDI_GET_VERSION_MINOR(uVer) ((uVer) & 0xffff)
79baed6836ae36c5f15b182292387484dcf7a752vboxsync/** Placeholder for specifying the last opened image. */
79baed6836ae36c5f15b182292387484dcf7a752vboxsync/** Placeholder for VDCopyEx to indicate that the image content is unknown. */
aef51041e0fe31e8ea903dd7e67fe12cef645654vboxsync/** @name VBox HDD container image flags
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync/** No flags. */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync/** Fixed image. */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync/** Diff image. Mutually exclusive with fixed image. */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync/** VMDK: Split image into 2GB extents. */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync/** VMDK: Raw disk image (giving access to a number of host partitions). */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync/** VMDK: stream optimized image, read only. */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync#define VD_VMDK_IMAGE_FLAGS_STREAM_OPTIMIZED (0x0004)
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync/** VMDK: ESX variant, use in addition to other flags. */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync/** VDI: Fill new blocks with zeroes while expanding image file. Only valid
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * for newly created images, never set for opened existing images. */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync/** Mask of valid image flags for VMDK. */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync#define VD_VMDK_IMAGE_FLAGS_MASK ( VD_IMAGE_FLAGS_FIXED | VD_IMAGE_FLAGS_DIFF | VD_IMAGE_FLAGS_NONE \
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync | VD_VMDK_IMAGE_FLAGS_SPLIT_2G | VD_VMDK_IMAGE_FLAGS_RAWDISK \
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync | VD_VMDK_IMAGE_FLAGS_STREAM_OPTIMIZED | VD_VMDK_IMAGE_FLAGS_ESX)
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync/** Mask of valid image flags for VDI. */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync#define VD_VDI_IMAGE_FLAGS_MASK (VD_IMAGE_FLAGS_FIXED | VD_IMAGE_FLAGS_DIFF | VD_IMAGE_FLAGS_NONE | VD_VDI_IMAGE_FLAGS_ZERO_EXPAND)
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync/** Mask of all valid image flags for all formats. */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync#define VD_IMAGE_FLAGS_MASK (VD_VMDK_IMAGE_FLAGS_MASK | VD_VDI_IMAGE_FLAGS_MASK)
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync/** Default image flags. */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync#define VD_IMAGE_FLAGS_DEFAULT (VD_IMAGE_FLAGS_NONE)
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync/** @name VD image repair flags
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync/** Don't repair the image but check what needs to be done. */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync/** Mask of all valid repair flags. */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync/** @name VD image VFS file flags
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync/** Destroy the VD disk container when the VFS file is released. */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync/** Mask of all valid repair flags. */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync#define VD_VFSFILE_FLAGS_MASK (VD_VFSFILE_DESTROY_ON_RELEASE)
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * Auxiliary type for describing partitions on raw disks. The entries must be
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * in ascending order (as far as uStart is concerned), and must not overlap.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * Note that this does not correspond 1:1 to partitions, it is describing the
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * general meaning of contiguous areas on the disk.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync /** Device to use for this partition/data area. Can be the disk device if
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * the offset field is set appropriately. If this is NULL, then this
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * partition will not be accessible to the guest. The size of the data area
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * must still be set correctly. */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync /** Pointer to the partitioning info. NULL means this is a regular data
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * area on disk, non-NULL denotes data which should be copied to the
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * partition data overlay. */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync /** Offset where the data starts in this device. */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync /** Offset where the data starts in the disk. */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync /** Size of the data area. */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * Auxiliary data structure for difference between GPT and MBR
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * Auxiliary data structure for creating raw disks.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsynctypedef struct VBOXHDDRAW
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync /** Signature for structure. Must be 'R', 'A', 'W', '\\0'. Actually a trick
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * to make logging of the comment string produce sensible results. */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync /** Flag whether access to full disk should be given (ignoring the
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * partition information below). */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync /** Filename for the raw disk. Ignored for partitioned raw disks.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * For Linux e.g. /dev/sda, and for Windows e.g. \\\\.\\PhysicalDisk0. */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync /** Number of entries in the partition descriptor array. */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync /** Pointer to the partition descriptor array. */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync /**partitioning type of the disk */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync/** @name VBox HDD container image open mode flags
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync/** Try to open image in read/write exclusive access mode if possible, or in read-only elsewhere. */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync/** Open image in read-only mode with sharing access with others. */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync/** Honor zero block writes instead of ignoring them whenever possible.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * This is not supported by all formats. It is silently ignored in this case. */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync/** Honor writes of the same data instead of ignoring whenever possible.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * This is handled generically, and is only meaningful for differential image
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * formats. It is silently ignored otherwise. */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync/** Do not perform the base/diff image check on open. This does NOT imply
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * opening the image as readonly (would break e.g. adding UUIDs to VMDK files
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * created by other products). Images opened with this flag should only be
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * used for querying information, and nothing else. */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync/** Open image for asynchronous access. Only available if VD_CAP_ASYNC_IO is
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * set. VDOpen fails with VERR_NOT_SUPPORTED if this operation is not supported for
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * this kind of image. */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync/** Allow sharing of the image for writable images. May be ignored if the
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * format backend doesn't support this type of concurrent access. */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync/** Ask the backend to switch to sequential accesses if possible. Opening
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * will not fail if it cannot do this, the flag will be simply ignored. */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync/** Allow the discard operation if supported. Only available if VD_CAP_DISCARD
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * is set. VDOpen fails with VERR_VD_DISCARD_NOT_SUPPORTED if discarding is not
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * supported. */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync/** Ignore all flush requests to workaround certain filesystems which are slow
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * when writing a lot of cached data to the medium.
ad27e1d5e48ca41245120c331cc88b50464813cevboxsync * Use with extreme care as a host crash can result in completely corrupted and
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * unusable images.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * Return VINF_VD_NEW_ZEROED_BLOCK for reads from unallocated blocks.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * The caller who uses the flag has to make sure that the read doesn't cross
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * a block boundary. Because the block size can differ between images reading one
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * sector at a time is the safest solution.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync#define VD_OPEN_FLAGS_INFORM_ABOUT_ZERO_BLOCKS RT_BIT(9)
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * Don't do unnecessary consistency checks when opening the image.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * Only valid when the image is opened in readonly because inconsistencies
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * can lead to corrupted images in read-write mode.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync#define VD_OPEN_FLAGS_SKIP_CONSISTENCY_CHECKS RT_BIT(10)
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync/** Mask of valid flags. */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync#define VD_OPEN_FLAGS_MASK (VD_OPEN_FLAGS_NORMAL | VD_OPEN_FLAGS_READONLY | VD_OPEN_FLAGS_HONOR_ZEROES | VD_OPEN_FLAGS_HONOR_SAME | VD_OPEN_FLAGS_INFO | VD_OPEN_FLAGS_ASYNC_IO | VD_OPEN_FLAGS_SHAREABLE | VD_OPEN_FLAGS_SEQUENTIAL | VD_OPEN_FLAGS_DISCARD | VD_OPEN_FLAGS_IGNORE_FLUSH | VD_OPEN_FLAGS_INFORM_ABOUT_ZERO_BLOCKS | VD_OPEN_FLAGS_SKIP_CONSISTENCY_CHECKS)
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * Helper functions to handle open flags.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * Translate VD_OPEN_FLAGS_* to RTFile open flags.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @return RTFile open flags.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @param uOpenFlags VD_OPEN_FLAGS_* open flags.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @param fCreate Flag that the file should be created.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsyncDECLINLINE(uint32_t) VDOpenFlagsToFileOpenFlags(unsigned uOpenFlags, bool fCreate)
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync AssertMsg(!((uOpenFlags & VD_OPEN_FLAGS_READONLY) && fCreate), ("Image can't be opened readonly while being created\n"));
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync if (RT_UNLIKELY(uOpenFlags & VD_OPEN_FLAGS_READONLY))
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync if (RT_UNLIKELY(uOpenFlags & VD_OPEN_FLAGS_SHAREABLE))
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync fOpen |= RTFILE_O_CREATE | RTFILE_O_NOT_CONTENT_INDEXED;
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync/** @name VBox HDD container backend capability flags
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync/** Supports UUIDs as expected by VirtualBox code. */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync/** Supports creating fixed size images, allocating all space instantly. */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync/** Supports creating dynamically growing images, allocating space on demand. */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync/** Supports creating images split in chunks of a bit less than 2GBytes. */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync/** Supports being used as differencing image format backend. */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync/** Supports asynchronous I/O operations for at least some configurations. */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync/** The backend operates on files. The caller needs to know to handle the
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * location appropriately. */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync/** The backend uses the config interface. The caller needs to know how to
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * provide the mandatory configuration parts this way. */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync/** The backend uses the network stack interface. The caller has to provide
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * the appropriate interface. */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync/** The backend supports VFS (virtual filesystem) functionality since it uses
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * VDINTERFACEIO exclusively for all file operations. */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync/** The backend supports the discard operation. */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync/** @name VBox HDD container type.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync /** Invalid. */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync /** HardDisk */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync /** Floppy. */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync/** @name Configuration interface key handling flags.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync/** Mandatory config key. Not providing a value for this key will cause
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * the backend to fail. */
58ab0ad45444e80bdd970ddeb468d0872dbbbb47vboxsync/** Expert config key. Not showing it by default in the GUI is is probably
11d3005e2935c925665896fa26fde09b3e656d70vboxsync * a good idea, as the average user won't understand it easily. */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * Configuration value type for configuration information interface.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync /** Integer value. */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync /** String value. */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync /** Bytestring value. */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * Structure describing configuration keys required/supported by a backend
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * through the config interface.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsynctypedef struct VDCONFIGINFO
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync /** Key name of the configuration. */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync const char *pszKey;
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync /** Pointer to default value (descriptor). NULL if no useful default value
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * can be specified. */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync /** Value type for this key. */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync /** Key handling flags (a combination of VD_CFGKEY_* flags). */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync/** Pointer to structure describing configuration keys. */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync/** Pointer to const structure describing configuration keys. */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * Structure describing a file extension.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync /** Pointer to the NULL-terminated string containing the extension. */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync /** The device type the extension supports. */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync/** Pointer to a structure describing a file extension. */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync/** Pointer to a const structure describing a file extension. */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * Data structure for returning a list of backend capabilities.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync /** Name of the backend. Must be unique even with case insensitive comparison. */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync /** Capabilities of the backend (a combination of the VD_CAP_* flags). */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync /** Pointer to a NULL-terminated array of strings, containing the supported
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * file extensions. Note that some backends do not work on files, so this
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * pointer may just contain NULL. */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync /** Pointer to an array of structs describing each supported config key.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * Terminated by a NULL config key. Note that some backends do not support
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * the configuration interface, so this pointer may just contain NULL.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * Mandatory if the backend sets VD_CAP_CONFIG. */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync /** Returns a human readable hard disk location string given a
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * set of hard disk configuration keys. The returned string is an
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * equivalent of the full file path for image-based hard disks.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * Mandatory for backends with no VD_CAP_FILE and NULL otherwise. */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync DECLR3CALLBACKMEMBER(int, pfnComposeLocation, (PVDINTERFACE pConfig, char **pszLocation));
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync /** Returns a human readable hard disk name string given a
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * set of hard disk configuration keys. The returned string is an
58ab0ad45444e80bdd970ddeb468d0872dbbbb47vboxsync * equivalent of the file name part in the full file path for
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * image-based hard disks. Mandatory for backends with no
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * VD_CAP_FILE and NULL otherwise. */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync DECLR3CALLBACKMEMBER(int, pfnComposeName, (PVDINTERFACE pConfig, char **pszName));
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * Request completion callback for the async read/write API.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsynctypedef void (FNVDASYNCTRANSFERCOMPLETE) (void *pvUser1, void *pvUser2, int rcReq);
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync/** Pointer to a transfer compelte callback. */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsynctypedef FNVDASYNCTRANSFERCOMPLETE *PFNVDASYNCTRANSFERCOMPLETE;
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * Disk geometry.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsynctypedef struct VDGEOMETRY
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync /** Number of cylinders. */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync /** Number of heads. */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync /** Number of sectors. */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync/** Pointer to disk geometry. */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync/** Pointer to constant disk geometry. */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * VBox HDD Container main structure.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync/* Forward declaration, VBOXHDD structure is visible only inside VBox HDD module. */
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * Initializes HDD backends.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @returns VBox status code.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * Destroys loaded HDD backends.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @returns VBox status code.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * Lists all HDD backends and their capabilities in a caller-provided buffer.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @return VBox status code.
befced03fd84a13590b8ce8be8c2480e9bc568c6vboxsync * VERR_BUFFER_OVERFLOW if not enough space is passed.
befced03fd84a13590b8ce8be8c2480e9bc568c6vboxsync * @param cEntriesAlloc Number of list entries available.
befced03fd84a13590b8ce8be8c2480e9bc568c6vboxsync * @param pEntries Pointer to array for the entries.
befced03fd84a13590b8ce8be8c2480e9bc568c6vboxsync * @param pcEntriesUsed Number of entries returned.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsyncVBOXDDU_DECL(int) VDBackendInfo(unsigned cEntriesAlloc, PVDBACKENDINFO pEntries,
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * Lists the capabilities of a backend identified by its name.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @return VBox status code.
befced03fd84a13590b8ce8be8c2480e9bc568c6vboxsync * @param pszBackend The backend name (case insensitive).
e6a3673a23c632af5208dcc8a37f45d7a20b0554vboxsync * @param pEntries Pointer to an entry.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsyncVBOXDDU_DECL(int) VDBackendInfoOne(const char *pszBackend, PVDBACKENDINFO pEntry);
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * Allocates and initializes an empty HDD container.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * No image files are opened.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @return VBox status code.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @param pVDIfsDisk Pointer to the per-disk VD interface list.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @param enmType Type of the image container.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @param ppDisk Where to store the reference to HDD container.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsyncVBOXDDU_DECL(int) VDCreate(PVDINTERFACE pVDIfsDisk, VDTYPE enmType, PVBOXHDD *ppDisk);
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * Destroys HDD container.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * If container has opened image files they will be closed.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @return VBox status code.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @param pDisk Pointer to HDD container.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * Try to get the backend name which can use this image.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @return VBox status code.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * VINF_SUCCESS if a plugin was found.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * ppszFormat contains the string which can be used as backend name.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * VERR_NOT_SUPPORTED if no backend was found.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @param pVDIfsDisk Pointer to the per-disk VD interface list.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @param pVDIfsImage Pointer to the per-image VD interface list.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @param pszFilename Name of the image file for which the backend is queried.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @param ppszFormat Receives pointer of the UTF-8 string which contains the format name.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * The returned pointer must be freed using RTStrFree().
16d723d9d597f4872dd4c2c960af9cbca4ed63bdvboxsync * @param penmType Where to store the type of the image.
16d723d9d597f4872dd4c2c960af9cbca4ed63bdvboxsyncVBOXDDU_DECL(int) VDGetFormat(PVDINTERFACE pVDIfsDisk, PVDINTERFACE pVDIfsImage,
16d723d9d597f4872dd4c2c960af9cbca4ed63bdvboxsync const char *pszFilename, char **ppszFormat, VDTYPE *penmType);
16d723d9d597f4872dd4c2c960af9cbca4ed63bdvboxsync * Opens an image file.
16d723d9d597f4872dd4c2c960af9cbca4ed63bdvboxsync * The first opened image file in HDD container must have a base image type,
16d723d9d597f4872dd4c2c960af9cbca4ed63bdvboxsync * others (next opened images) must be differencing or undo images.
16d723d9d597f4872dd4c2c960af9cbca4ed63bdvboxsync * Linkage is checked for differencing image to be consistent with the previously opened image.
16d723d9d597f4872dd4c2c960af9cbca4ed63bdvboxsync * When another differencing image is opened and the last image was opened in read/write access
16d723d9d597f4872dd4c2c960af9cbca4ed63bdvboxsync * mode, then the last image is reopened in read-only with deny write sharing mode. This allows
16d723d9d597f4872dd4c2c960af9cbca4ed63bdvboxsync * other processes to use images in read-only mode too.
16d723d9d597f4872dd4c2c960af9cbca4ed63bdvboxsync * Note that the image is opened in read-only mode if a read/write open is not possible.
16d723d9d597f4872dd4c2c960af9cbca4ed63bdvboxsync * Use VDIsReadOnly to check open mode.
16d723d9d597f4872dd4c2c960af9cbca4ed63bdvboxsync * @return VBox status code.
79baed6836ae36c5f15b182292387484dcf7a752vboxsync * @param pDisk Pointer to HDD container.
79baed6836ae36c5f15b182292387484dcf7a752vboxsync * @param pszBackend Name of the image file backend to use (case insensitive).
79baed6836ae36c5f15b182292387484dcf7a752vboxsync * @param pszFilename Name of the image file to open.
79baed6836ae36c5f15b182292387484dcf7a752vboxsync * @param uOpenFlags Image file open mode, see VD_OPEN_FLAGS_* constants.
79baed6836ae36c5f15b182292387484dcf7a752vboxsync * @param pVDIfsImage Pointer to the per-image VD interface list.
79baed6836ae36c5f15b182292387484dcf7a752vboxsyncVBOXDDU_DECL(int) VDOpen(PVBOXHDD pDisk, const char *pszBackend,
79baed6836ae36c5f15b182292387484dcf7a752vboxsync * Opens a cache image.
79baed6836ae36c5f15b182292387484dcf7a752vboxsync * @return VBox status code.
79baed6836ae36c5f15b182292387484dcf7a752vboxsync * @param pDisk Pointer to the HDD container which should use the cache image.
79baed6836ae36c5f15b182292387484dcf7a752vboxsync * @param pszBackend Name of the cache file backend to use (case insensitive).
79baed6836ae36c5f15b182292387484dcf7a752vboxsync * @param pszFilename Name of the cache image to open.
79baed6836ae36c5f15b182292387484dcf7a752vboxsync * @param uOpenFlags Image file open mode, see VD_OPEN_FLAGS_* constants.
79baed6836ae36c5f15b182292387484dcf7a752vboxsync * @param pVDIfsCache Pointer to the per-cache VD interface list.
79baed6836ae36c5f15b182292387484dcf7a752vboxsyncVBOXDDU_DECL(int) VDCacheOpen(PVBOXHDD pDisk, const char *pszBackend,
79baed6836ae36c5f15b182292387484dcf7a752vboxsync * Creates and opens a new base image file.
79baed6836ae36c5f15b182292387484dcf7a752vboxsync * @return VBox status code.
79baed6836ae36c5f15b182292387484dcf7a752vboxsync * @param pDisk Pointer to HDD container.
79baed6836ae36c5f15b182292387484dcf7a752vboxsync * @param pszBackend Name of the image file backend to use (case insensitive).
79baed6836ae36c5f15b182292387484dcf7a752vboxsync * @param pszFilename Name of the image file to create.
79baed6836ae36c5f15b182292387484dcf7a752vboxsync * @param cbSize Image size in bytes.
79baed6836ae36c5f15b182292387484dcf7a752vboxsync * @param uImageFlags Flags specifying special image features.
79baed6836ae36c5f15b182292387484dcf7a752vboxsync * @param pszComment Pointer to image comment. NULL is ok.
79baed6836ae36c5f15b182292387484dcf7a752vboxsync * @param pPCHSGeometry Pointer to physical disk geometry <= (16383,16,63). Not NULL.
79baed6836ae36c5f15b182292387484dcf7a752vboxsync * @param pLCHSGeometry Pointer to logical disk geometry <= (x,255,63). Not NULL.
79baed6836ae36c5f15b182292387484dcf7a752vboxsync * @param pUuid New UUID of the image. If NULL, a new UUID is created.
79baed6836ae36c5f15b182292387484dcf7a752vboxsync * @param uOpenFlags Image file open mode, see VD_OPEN_FLAGS_* constants.
79baed6836ae36c5f15b182292387484dcf7a752vboxsync * @param pVDIfsImage Pointer to the per-image VD interface list.
79baed6836ae36c5f15b182292387484dcf7a752vboxsync * @param pVDIfsOperation Pointer to the per-operation VD interface list.
79baed6836ae36c5f15b182292387484dcf7a752vboxsyncVBOXDDU_DECL(int) VDCreateBase(PVBOXHDD pDisk, const char *pszBackend,
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * Creates and opens a new differencing image file in HDD container.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * See comments for VDOpen function about differencing images.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @return VBox status code.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @param pDisk Pointer to HDD container.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @param pszBackend Name of the image file backend to use (case insensitive).
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @param pszFilename Name of the differencing image file to create.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @param uImageFlags Flags specifying special image features.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @param pszComment Pointer to image comment. NULL is ok.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @param pUuid New UUID of the image. If NULL, a new UUID is created.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @param pParentUuid New parent UUID of the image. If NULL, the UUID is queried automatically.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @param uOpenFlags Image file open mode, see VD_OPEN_FLAGS_* constants.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @param pVDIfsImage Pointer to the per-image VD interface list.
11d3005e2935c925665896fa26fde09b3e656d70vboxsync * @param pVDIfsOperation Pointer to the per-operation VD interface list.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsyncVBOXDDU_DECL(int) VDCreateDiff(PVBOXHDD pDisk, const char *pszBackend,
79baed6836ae36c5f15b182292387484dcf7a752vboxsync * Creates and opens new cache image file in HDD container.
79baed6836ae36c5f15b182292387484dcf7a752vboxsync * @return VBox status code.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @param pDisk Name of the cache file backend to use (case insensitive).
69c6eff4fcb6dc027e94a3e7908926c4e8ef5aefvboxsync * @param pszFilename Name of the differencing cache file to create.
69c6eff4fcb6dc027e94a3e7908926c4e8ef5aefvboxsync * @param cbSize Maximum size of the cache.
69c6eff4fcb6dc027e94a3e7908926c4e8ef5aefvboxsync * @param uImageFlags Flags specifying special cache features.
69c6eff4fcb6dc027e94a3e7908926c4e8ef5aefvboxsync * @param pszComment Pointer to image comment. NULL is ok.
69c6eff4fcb6dc027e94a3e7908926c4e8ef5aefvboxsync * @param pUuid New UUID of the image. If NULL, a new UUID is created.
69c6eff4fcb6dc027e94a3e7908926c4e8ef5aefvboxsync * @param uOpenFlags Image file open mode, see VD_OPEN_FLAGS_* constants.
79baed6836ae36c5f15b182292387484dcf7a752vboxsync * @param pVDIfsCache Pointer to the per-cache VD interface list.
79baed6836ae36c5f15b182292387484dcf7a752vboxsync * @param pVDIfsOperation Pointer to the per-operation VD interface list.
79baed6836ae36c5f15b182292387484dcf7a752vboxsyncVBOXDDU_DECL(int) VDCreateCache(PVBOXHDD pDisk, const char *pszBackend,
79baed6836ae36c5f15b182292387484dcf7a752vboxsync PVDINTERFACE pVDIfsCache, PVDINTERFACE pVDIfsOperation);
79baed6836ae36c5f15b182292387484dcf7a752vboxsync * Merges two images (not necessarily with direct parent/child relationship).
79baed6836ae36c5f15b182292387484dcf7a752vboxsync * As a side effect the source image and potentially the other images which
79baed6836ae36c5f15b182292387484dcf7a752vboxsync * are also merged to the destination are deleted from both the disk and the
79baed6836ae36c5f15b182292387484dcf7a752vboxsync * images in the HDD container.
79baed6836ae36c5f15b182292387484dcf7a752vboxsync * @return VBox status code.
79baed6836ae36c5f15b182292387484dcf7a752vboxsync * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
79baed6836ae36c5f15b182292387484dcf7a752vboxsync * @param pDisk Pointer to HDD container.
79baed6836ae36c5f15b182292387484dcf7a752vboxsync * @param nImageFrom Image number to merge from, counts from 0. 0 is always base image of container.
79baed6836ae36c5f15b182292387484dcf7a752vboxsync * @param nImageTo Image number to merge to, counts from 0. 0 is always base image of container.
79baed6836ae36c5f15b182292387484dcf7a752vboxsync * @param pVDIfsOperation Pointer to the per-operation VD interface list.
79baed6836ae36c5f15b182292387484dcf7a752vboxsyncVBOXDDU_DECL(int) VDMerge(PVBOXHDD pDisk, unsigned nImageFrom,
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * Copies an image from one HDD container to another - extended version.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * The copy is opened in the target HDD container.
79baed6836ae36c5f15b182292387484dcf7a752vboxsync * It is possible to convert between different image formats, because the
79baed6836ae36c5f15b182292387484dcf7a752vboxsync * backend for the destination may be different from the source.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * If both the source and destination reference the same HDD container,
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * then the image is moved (by copying/deleting or renaming) to the new location.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * The source container is unchanged if the move operation fails, otherwise
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * the image at the new location is opened in the same way as the old one was.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @note The read/write accesses across disks are not synchronized, just the
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * accesses to each disk. Once there is a use case which requires a defined
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * read/write behavior in this situation this needs to be extended.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @return VBox status code.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @param pDiskFrom Pointer to source HDD container.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @param nImage Image number, counts from 0. 0 is always base image of container.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @param pDiskTo Pointer to destination HDD container.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @param pszBackend Name of the image file backend to use (may be NULL to use the same as the source, case insensitive).
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @param pszFilename New name of the image (may be NULL to specify that the
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * copy destination is the destination container, or
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * if pDiskFrom == pDiskTo, i.e. when moving).
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @param fMoveByRename If true, attempt to perform a move by renaming (if successful the new size is ignored).
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @param cbSize New image size (0 means leave unchanged).
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @param nImageSameFrom The number of the last image in the source chain having the same content as the
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * image in the destination chain given by nImageSameTo or
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * VD_IMAGE_CONTENT_UNKNOWN to indicate that the content of both containers is unknown.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * See the notes for further information.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @param nImageSameTo The number of the last image in the destination chain having the same content as the
58461e707998a927c19da46b98748ee2b79f4190vboxsync * image in the source chain given by nImageSameFrom or
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * VD_IMAGE_CONTENT_UNKNOWN to indicate that the content of both containers is unknown.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * See the notes for further information.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @param uImageFlags Flags specifying special destination image features.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @param pDstUuid New UUID of the destination image. If NULL, a new UUID is created.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * This parameter is used if and only if a true copy is created.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * In all rename/move cases or copy to existing image cases the modification UUIDs are copied over.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @param uOpenFlags Image file open mode, see VD_OPEN_FLAGS_* constants.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * Only used if the destination image is created.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @param pVDIfsOperation Pointer to the per-operation VD interface list.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @param pDstVDIfsImage Pointer to the per-image VD interface list, for the
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * destination image.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @param pDstVDIfsOperation Pointer to the per-operation VD interface list,
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * for the destination operation.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @note Using nImageSameFrom and nImageSameTo can lead to a significant speedup
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * when copying an image but can also lead to a corrupted copy if used incorrectly.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * It is mainly useful when cloning a chain of images and it is known that
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * the virtual disk content of the two chains is exactly the same upto a certain image.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * Imagine the chain of images which consist of a base and one diff image.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * Copying the chain starts with the base image. When copying the first
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * diff image VDCopy() will read the data from the diff of the source chain
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * and probably from the base image again in case the diff doesn't has data
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * for the block. However the block will be optimized away because VDCopy()
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * reads data from the base image of the destination chain compares the to
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * and suppresses the write because the data is unchanged.
11d3005e2935c925665896fa26fde09b3e656d70vboxsync * For a lot of diff images this will be a huge waste of I/O bandwidth if
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * the diff images contain only few changes.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * Because it is known that the base image of the source and the destination chain
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * have the same content it is enough to check the diff image for changed data
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * and copy it to the destination diff image which is achieved with
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * nImageSameFrom and nImageSameTo. Setting both to 0 can suppress a lot of I/O.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsyncVBOXDDU_DECL(int) VDCopyEx(PVBOXHDD pDiskFrom, unsigned nImage, PVBOXHDD pDiskTo,
27152389a84c6dec057fba6fc21241991e079006vboxsync * Copies an image from one HDD container to another.
27152389a84c6dec057fba6fc21241991e079006vboxsync * The copy is opened in the target HDD container.
27152389a84c6dec057fba6fc21241991e079006vboxsync * It is possible to convert between different image formats, because the
27152389a84c6dec057fba6fc21241991e079006vboxsync * backend for the destination may be different from the source.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * If both the source and destination reference the same HDD container,
27152389a84c6dec057fba6fc21241991e079006vboxsync * then the image is moved (by copying/deleting or renaming) to the new location.
27152389a84c6dec057fba6fc21241991e079006vboxsync * The source container is unchanged if the move operation fails, otherwise
27152389a84c6dec057fba6fc21241991e079006vboxsync * the image at the new location is opened in the same way as the old one was.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @note The read/write accesses across disks are not synchronized, just the
27152389a84c6dec057fba6fc21241991e079006vboxsync * accesses to each disk. Once there is a use case which requires a defined
27152389a84c6dec057fba6fc21241991e079006vboxsync * read/write behavior in this situation this needs to be extended.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @return VBox status code.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param pDiskFrom Pointer to source HDD container.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param nImage Image number, counts from 0. 0 is always base image of container.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param pDiskTo Pointer to destination HDD container.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param pszBackend Name of the image file backend to use (may be NULL to use the same as the source, case insensitive).
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param pszFilename New name of the image (may be NULL to specify that the
27152389a84c6dec057fba6fc21241991e079006vboxsync * copy destination is the destination container, or
27152389a84c6dec057fba6fc21241991e079006vboxsync * if pDiskFrom == pDiskTo, i.e. when moving).
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param fMoveByRename If true, attempt to perform a move by renaming (if successful the new size is ignored).
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param cbSize New image size (0 means leave unchanged).
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param uImageFlags Flags specifying special destination image features.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param pDstUuid New UUID of the destination image. If NULL, a new UUID is created.
27152389a84c6dec057fba6fc21241991e079006vboxsync * This parameter is used if and only if a true copy is created.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * In all rename/move cases or copy to existing image cases the modification UUIDs are copied over.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param uOpenFlags Image file open mode, see VD_OPEN_FLAGS_* constants.
27152389a84c6dec057fba6fc21241991e079006vboxsync * Only used if the destination image is created.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param pVDIfsOperation Pointer to the per-operation VD interface list.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @param pDstVDIfsImage Pointer to the per-image VD interface list, for the
27152389a84c6dec057fba6fc21241991e079006vboxsync * destination image.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param pDstVDIfsOperation Pointer to the per-operation VD interface list,
27152389a84c6dec057fba6fc21241991e079006vboxsync * for the destination operation.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsyncVBOXDDU_DECL(int) VDCopy(PVBOXHDD pDiskFrom, unsigned nImage, PVBOXHDD pDiskTo,
27152389a84c6dec057fba6fc21241991e079006vboxsync * Optimizes the storage consumption of an image. Typically the unused blocks
27152389a84c6dec057fba6fc21241991e079006vboxsync * have to be wiped with zeroes to achieve a substantial reduced storage use.
27152389a84c6dec057fba6fc21241991e079006vboxsync * Another optimization done is reordering the image blocks, which can provide
27152389a84c6dec057fba6fc21241991e079006vboxsync * a significant performance boost, as reads and writes tend to use less random
27152389a84c6dec057fba6fc21241991e079006vboxsync * file offsets.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @note Compaction is treated as a single operation with regard to thread
27152389a84c6dec057fba6fc21241991e079006vboxsync * synchronization, which means that it potentially blocks other activities for
27152389a84c6dec057fba6fc21241991e079006vboxsync * a long time. The complexity of compaction would grow even more if concurrent
27152389a84c6dec057fba6fc21241991e079006vboxsync * accesses have to be handled.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @return VBox status code.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @return VERR_VD_IMAGE_READ_ONLY if image is not writable.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @return VERR_NOT_SUPPORTED if this kind of image can be compacted, but
27152389a84c6dec057fba6fc21241991e079006vboxsync * this isn't supported yet.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param pDisk Pointer to HDD container.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param nImage Image number, counts from 0. 0 is always base image of container.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param pVDIfsOperation Pointer to the per-operation VD interface list.
27152389a84c6dec057fba6fc21241991e079006vboxsyncVBOXDDU_DECL(int) VDCompact(PVBOXHDD pDisk, unsigned nImage,
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * Resizes the given disk image to the given size. It is OK if there are
27152389a84c6dec057fba6fc21241991e079006vboxsync * multiple images open in the container. In this case the last disk image
27152389a84c6dec057fba6fc21241991e079006vboxsync * will be resized.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @return VBox status
27152389a84c6dec057fba6fc21241991e079006vboxsync * @return VERR_VD_IMAGE_READ_ONLY if image is not writable.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @return VERR_NOT_SUPPORTED if this kind of image can be compacted, but
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param pDisk Pointer to the HDD container.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param cbSize New size of the image.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param pPCHSGeometry Pointer to the new physical disk geometry <= (16383,16,63). Not NULL.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param pLCHSGeometry Pointer to the new logical disk geometry <= (x,255,63). Not NULL.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param pVDIfsOperation Pointer to the per-operation VD interface list.
27152389a84c6dec057fba6fc21241991e079006vboxsyncVBOXDDU_DECL(int) VDResize(PVBOXHDD pDisk, uint64_t cbSize,
27152389a84c6dec057fba6fc21241991e079006vboxsync * Closes the last opened image file in HDD container.
27152389a84c6dec057fba6fc21241991e079006vboxsync * If previous image file was opened in read-only mode (the normal case) and
27152389a84c6dec057fba6fc21241991e079006vboxsync * the last opened image is in read-write mode then the previous image will be
27152389a84c6dec057fba6fc21241991e079006vboxsync * reopened in read/write mode.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @return VBox status code.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @return VERR_VD_NOT_OPENED if no image is opened in HDD container.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param pDisk Pointer to HDD container.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param fDelete If true, delete the image from the host disk.
27152389a84c6dec057fba6fc21241991e079006vboxsyncVBOXDDU_DECL(int) VDClose(PVBOXHDD pDisk, bool fDelete);
27152389a84c6dec057fba6fc21241991e079006vboxsync * Closes the currently opened cache image file in HDD container.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @return VBox status code.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @return VERR_VD_NOT_OPENED if no cache is opened in HDD container.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param pDisk Pointer to HDD container.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @param fDelete If true, delete the image from the host disk.
27152389a84c6dec057fba6fc21241991e079006vboxsyncVBOXDDU_DECL(int) VDCacheClose(PVBOXHDD pDisk, bool fDelete);
27152389a84c6dec057fba6fc21241991e079006vboxsync * Closes all opened image files in HDD container.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @return VBox status code.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param pDisk Pointer to HDD container.
27152389a84c6dec057fba6fc21241991e079006vboxsync * Read data from virtual HDD.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @return VBox status code.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @return VERR_VD_NOT_OPENED if no image is opened in HDD container.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param pDisk Pointer to HDD container.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param uOffset Offset of first reading byte from start of disk.
27152389a84c6dec057fba6fc21241991e079006vboxsync * Must be aligned to a sector boundary.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param pvBuffer Pointer to buffer for reading data.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @param cbBuffer Number of bytes to read.
27152389a84c6dec057fba6fc21241991e079006vboxsync * Must be aligned to a sector boundary.
27152389a84c6dec057fba6fc21241991e079006vboxsyncVBOXDDU_DECL(int) VDRead(PVBOXHDD pDisk, uint64_t uOffset, void *pvBuffer, size_t cbBuffer);
27152389a84c6dec057fba6fc21241991e079006vboxsync * Write data to virtual HDD.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @return VBox status code.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @return VERR_VD_NOT_OPENED if no image is opened in HDD container.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param pDisk Pointer to HDD container.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param uOffset Offset of first writing byte from start of disk.
27152389a84c6dec057fba6fc21241991e079006vboxsync * Must be aligned to a sector boundary.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param pvBuffer Pointer to buffer for writing data.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param cbBuffer Number of bytes to write.
27152389a84c6dec057fba6fc21241991e079006vboxsync * Must be aligned to a sector boundary.
27152389a84c6dec057fba6fc21241991e079006vboxsyncVBOXDDU_DECL(int) VDWrite(PVBOXHDD pDisk, uint64_t uOffset, const void *pvBuffer, size_t cbBuffer);
27152389a84c6dec057fba6fc21241991e079006vboxsync * Make sure the on disk representation of a virtual HDD is up to date.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @return VBox status code.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @return VERR_VD_NOT_OPENED if no image is opened in HDD container.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param pDisk Pointer to HDD container.
27152389a84c6dec057fba6fc21241991e079006vboxsync * Get number of opened images in HDD container.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @return Number of opened images for HDD container. 0 if no images have been opened.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param pDisk Pointer to HDD container.
27152389a84c6dec057fba6fc21241991e079006vboxsync * Get read/write mode of HDD container.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @return Virtual disk ReadOnly status.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @return true if no image is opened in HDD container.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param pDisk Pointer to HDD container.
27152389a84c6dec057fba6fc21241991e079006vboxsync * Get total capacity of an image in HDD container.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @return Virtual disk size in bytes.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @return 0 if image with specified number was not opened.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param pDisk Pointer to HDD container.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param nImage Image number, counts from 0. 0 is always base image of container.
27152389a84c6dec057fba6fc21241991e079006vboxsyncVBOXDDU_DECL(uint64_t) VDGetSize(PVBOXHDD pDisk, unsigned nImage);
27152389a84c6dec057fba6fc21241991e079006vboxsync * Get total file size of an image in HDD container.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @return Virtual disk size in bytes.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @return 0 if image with specified number was not opened.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param pDisk Pointer to HDD container.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param nImage Image number, counts from 0. 0 is always base image of container.
27152389a84c6dec057fba6fc21241991e079006vboxsyncVBOXDDU_DECL(uint64_t) VDGetFileSize(PVBOXHDD pDisk, unsigned nImage);
27152389a84c6dec057fba6fc21241991e079006vboxsync * Get virtual disk PCHS geometry of an image in HDD container.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @return VBox status code.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @return VERR_VD_GEOMETRY_NOT_SET if no geometry present in the HDD container.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @param pDisk Pointer to HDD container.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param nImage Image number, counts from 0. 0 is always base image of container.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @param pPCHSGeometry Where to store PCHS geometry. Not NULL.
79baed6836ae36c5f15b182292387484dcf7a752vboxsyncVBOXDDU_DECL(int) VDGetPCHSGeometry(PVBOXHDD pDisk, unsigned nImage,
27152389a84c6dec057fba6fc21241991e079006vboxsync * Store virtual disk PCHS geometry of an image in HDD container.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @return VBox status code.
79baed6836ae36c5f15b182292387484dcf7a752vboxsync * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
79baed6836ae36c5f15b182292387484dcf7a752vboxsync * @param pDisk Pointer to HDD container.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param nImage Image number, counts from 0. 0 is always base image of container.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param pPCHSGeometry Where to load PCHS geometry from. Not NULL.
27152389a84c6dec057fba6fc21241991e079006vboxsyncVBOXDDU_DECL(int) VDSetPCHSGeometry(PVBOXHDD pDisk, unsigned nImage,
27152389a84c6dec057fba6fc21241991e079006vboxsync * Get virtual disk LCHS geometry of an image in HDD container.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @return VBox status code.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @return VERR_VD_GEOMETRY_NOT_SET if no geometry present in the HDD container.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param pDisk Pointer to HDD container.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param nImage Image number, counts from 0. 0 is always base image of container.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param pLCHSGeometry Where to store LCHS geometry. Not NULL.
27152389a84c6dec057fba6fc21241991e079006vboxsyncVBOXDDU_DECL(int) VDGetLCHSGeometry(PVBOXHDD pDisk, unsigned nImage,
27152389a84c6dec057fba6fc21241991e079006vboxsync * Store virtual disk LCHS geometry of an image in HDD container.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @return VBox status code.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param pDisk Pointer to HDD container.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param nImage Image number, counts from 0. 0 is always base image of container.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @param pLCHSGeometry Where to load LCHS geometry from. Not NULL.
27152389a84c6dec057fba6fc21241991e079006vboxsyncVBOXDDU_DECL(int) VDSetLCHSGeometry(PVBOXHDD pDisk, unsigned nImage,
27152389a84c6dec057fba6fc21241991e079006vboxsync * Get version of image in HDD container.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @return VBox status code.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param pDisk Pointer to HDD container.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @param nImage Image number, counts from 0. 0 is always base image of container.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param puVersion Where to store the image version.
27152389a84c6dec057fba6fc21241991e079006vboxsyncVBOXDDU_DECL(int) VDGetVersion(PVBOXHDD pDisk, unsigned nImage,
27152389a84c6dec057fba6fc21241991e079006vboxsync * List the capabilities of image backend in HDD container.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @return VBox status code.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param pDisk Pointer to the HDD container.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @param nImage Image number, counts from 0. 0 is always base image of container.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param pbackendInfo Where to store the backend information.
27152389a84c6dec057fba6fc21241991e079006vboxsyncVBOXDDU_DECL(int) VDBackendInfoSingle(PVBOXHDD pDisk, unsigned nImage,
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * Get flags of image in HDD container.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @return VBox status code.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param pDisk Pointer to HDD container.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param nImage Image number, counts from 0. 0 is always base image of container.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @param puImageFlags Where to store the image flags.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsyncVBOXDDU_DECL(int) VDGetImageFlags(PVBOXHDD pDisk, unsigned nImage, unsigned *puImageFlags);
27152389a84c6dec057fba6fc21241991e079006vboxsync * Get open flags of image in HDD container.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @return VBox status code.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param pDisk Pointer to HDD container.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @param nImage Image number, counts from 0. 0 is always base image of container.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param puOpenFlags Where to store the image open flags.
27152389a84c6dec057fba6fc21241991e079006vboxsyncVBOXDDU_DECL(int) VDGetOpenFlags(PVBOXHDD pDisk, unsigned nImage,
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * Set open flags of image in HDD container.
27152389a84c6dec057fba6fc21241991e079006vboxsync * This operation may cause file locking changes and/or files being reopened.
79baed6836ae36c5f15b182292387484dcf7a752vboxsync * Note that in case of unrecoverable error all images in HDD container will be closed.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @return VBox status code.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
79baed6836ae36c5f15b182292387484dcf7a752vboxsync * @param pDisk Pointer to HDD container.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param nImage Image number, counts from 0. 0 is always base image of container.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param uOpenFlags Image file open mode, see VD_OPEN_FLAGS_* constants.
27152389a84c6dec057fba6fc21241991e079006vboxsyncVBOXDDU_DECL(int) VDSetOpenFlags(PVBOXHDD pDisk, unsigned nImage,
79baed6836ae36c5f15b182292387484dcf7a752vboxsync * Get base filename of image in HDD container. Some image formats use
27152389a84c6dec057fba6fc21241991e079006vboxsync * other filenames as well, so don't use this for anything but informational
27152389a84c6dec057fba6fc21241991e079006vboxsync * purposes.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @return VBox status code.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
79baed6836ae36c5f15b182292387484dcf7a752vboxsync * @return VERR_BUFFER_OVERFLOW if pszFilename buffer too small to hold filename.
79baed6836ae36c5f15b182292387484dcf7a752vboxsync * @param pDisk Pointer to HDD container.
79baed6836ae36c5f15b182292387484dcf7a752vboxsync * @param nImage Image number, counts from 0. 0 is always base image of container.
79baed6836ae36c5f15b182292387484dcf7a752vboxsync * @param pszFilename Where to store the image file name.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param cbFilename Size of buffer pszFilename points to.
27152389a84c6dec057fba6fc21241991e079006vboxsyncVBOXDDU_DECL(int) VDGetFilename(PVBOXHDD pDisk, unsigned nImage,
27152389a84c6dec057fba6fc21241991e079006vboxsync * Get the comment line of image in HDD container.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @return VBox status code.
79baed6836ae36c5f15b182292387484dcf7a752vboxsync * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @return VERR_BUFFER_OVERFLOW if pszComment buffer too small to hold comment text.
79baed6836ae36c5f15b182292387484dcf7a752vboxsync * @param pDisk Pointer to HDD container.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param nImage Image number, counts from 0. 0 is always base image of container.
79baed6836ae36c5f15b182292387484dcf7a752vboxsync * @param pszComment Where to store the comment string of image. NULL is ok.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @param cbComment The size of pszComment buffer. 0 is ok.
27152389a84c6dec057fba6fc21241991e079006vboxsyncVBOXDDU_DECL(int) VDGetComment(PVBOXHDD pDisk, unsigned nImage,
79baed6836ae36c5f15b182292387484dcf7a752vboxsync * Changes the comment line of image in HDD container.
79baed6836ae36c5f15b182292387484dcf7a752vboxsync * @return VBox status code.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @param pDisk Pointer to HDD container.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param nImage Image number, counts from 0. 0 is always base image of container.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @param pszComment New comment string (UTF-8). NULL is allowed to reset the comment.
27152389a84c6dec057fba6fc21241991e079006vboxsyncVBOXDDU_DECL(int) VDSetComment(PVBOXHDD pDisk, unsigned nImage,
895d68f6e6c15446ca98b8f6ec96ce19d7ea356fvboxsync const char *pszComment);
27152389a84c6dec057fba6fc21241991e079006vboxsync * Get UUID of image in HDD container.
895d68f6e6c15446ca98b8f6ec96ce19d7ea356fvboxsync * @return VBox status code.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @param pDisk Pointer to HDD container.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param nImage Image number, counts from 0. 0 is always base image of container.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param pUuid Where to store the image UUID.
27152389a84c6dec057fba6fc21241991e079006vboxsyncVBOXDDU_DECL(int) VDGetUuid(PVBOXHDD pDisk, unsigned nImage, PRTUUID pUuid);
27152389a84c6dec057fba6fc21241991e079006vboxsync * Set the image's UUID. Should not be used by normal applications.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @return VBox status code.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param pDisk Pointer to HDD container.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param nImage Image number, counts from 0. 0 is always base image of container.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param pUuid New UUID of the image. If NULL, a new UUID is created.
27152389a84c6dec057fba6fc21241991e079006vboxsyncVBOXDDU_DECL(int) VDSetUuid(PVBOXHDD pDisk, unsigned nImage, PCRTUUID pUuid);
27152389a84c6dec057fba6fc21241991e079006vboxsync * Get last modification UUID of image in HDD container.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @return VBox status code.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param pDisk Pointer to HDD container.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param nImage Image number, counts from 0. 0 is always base image of container.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param pUuid Where to store the image modification UUID.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsyncVBOXDDU_DECL(int) VDGetModificationUuid(PVBOXHDD pDisk, unsigned nImage,
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * Set the image's last modification UUID. Should not be used by normal applications.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @return VBox status code.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param pDisk Pointer to HDD container.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param nImage Image number, counts from 0. 0 is always base image of container.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @param pUuid New modification UUID of the image. If NULL, a new UUID is created.
27152389a84c6dec057fba6fc21241991e079006vboxsyncVBOXDDU_DECL(int) VDSetModificationUuid(PVBOXHDD pDisk, unsigned nImage,
27152389a84c6dec057fba6fc21241991e079006vboxsync * Get parent UUID of image in HDD container.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @return VBox status code.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param pDisk Pointer to HDD container.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @param nImage Image number, counts from 0. 0 is always base image of the container.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param pUuid Where to store the parent image UUID.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsyncVBOXDDU_DECL(int) VDGetParentUuid(PVBOXHDD pDisk, unsigned nImage,
27152389a84c6dec057fba6fc21241991e079006vboxsync * Set the image's parent UUID. Should not be used by normal applications.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @return VBox status code.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param pDisk Pointer to HDD container.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param nImage Image number, counts from 0. 0 is always base image of container.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param pUuid New parent UUID of the image. If NULL, a new UUID is created.
27152389a84c6dec057fba6fc21241991e079006vboxsyncVBOXDDU_DECL(int) VDSetParentUuid(PVBOXHDD pDisk, unsigned nImage,
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * Debug helper - dumps all opened images in HDD container into the log file.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @param pDisk Pointer to HDD container.
27152389a84c6dec057fba6fc21241991e079006vboxsync * Discards unused ranges given as a list.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @return VBox status code.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param pDisk Pointer to HDD container.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsync * @param paRanges The array of ranges to discard.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param cRanges Number of entries in the array.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @note In contrast to VDCompact() the ranges are always discarded even if they
27152389a84c6dec057fba6fc21241991e079006vboxsync * appear to contain data. This method is mainly used to implement TRIM support.
27152389a84c6dec057fba6fc21241991e079006vboxsyncVBOXDDU_DECL(int) VDDiscardRanges(PVBOXHDD pDisk, PCRTRANGE paRanges, unsigned cRanges);
27152389a84c6dec057fba6fc21241991e079006vboxsync * Start an asynchronous read request.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @return VBox status code.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param pDisk Pointer to the HDD container.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param uOffset The offset of the virtual disk to read from.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param cbRead How many bytes to read.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param pcSgBuf Pointer to the S/G buffer to read into.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param pfnComplete Completion callback.
895d68f6e6c15446ca98b8f6ec96ce19d7ea356fvboxsync * @param pvUser User data which is passed on completion
27152389a84c6dec057fba6fc21241991e079006vboxsyncVBOXDDU_DECL(int) VDAsyncRead(PVBOXHDD pDisk, uint64_t uOffset, size_t cbRead,
27152389a84c6dec057fba6fc21241991e079006vboxsync * Start an asynchronous write request.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @return VBox status code.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param pDisk Pointer to the HDD container.
895d68f6e6c15446ca98b8f6ec96ce19d7ea356fvboxsync * @param uOffset The offset of the virtual disk to write to.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param cbWrtie How many bytes to write.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param pcSgBuf Pointer to the S/G buffer to write from.
895d68f6e6c15446ca98b8f6ec96ce19d7ea356fvboxsync * @param pfnComplete Completion callback.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param pvUser User data which is passed on completion.
27152389a84c6dec057fba6fc21241991e079006vboxsyncVBOXDDU_DECL(int) VDAsyncWrite(PVBOXHDD pDisk, uint64_t uOffset, size_t cbWrite,
27152389a84c6dec057fba6fc21241991e079006vboxsync * Start an asynchronous flush request.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @return VBox status code.
c9a51cded51b8f691f24de730e190ef573344bfcvboxsync * @param pDisk Pointer to the HDD container.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param pfnComplete Completion callback.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param pvUser User data which is passed on completion.
27152389a84c6dec057fba6fc21241991e079006vboxsync * Start an asynchronous discard request.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @return VBox status code.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param pDisk Pointer to HDD container.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param paRanges The array of ranges to discard.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param cRanges Number of entries in the array.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param pfnComplete Completion callback.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param pvUser1 User data which is passed on completion.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param pvUser2 User data which is passed on completion.
2ca380caf80f0dacc65f8c996077e827318f1c69vboxsyncVBOXDDU_DECL(int) VDAsyncDiscardRanges(PVBOXHDD pDisk, PCRTRANGE paRanges, unsigned cRanges,
ce9015004a47e95eb75e047ba42f2d3200d2d222vboxsync * Tries to repair a corrupted image.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @return VBox status code.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @retval VERR_VD_IMAGE_REPAIR_NOT_SUPPORTED if the backend does not support repairing the image.
ce9015004a47e95eb75e047ba42f2d3200d2d222vboxsync * @retval VERR_VD_IMAGE_REPAIR_IMPOSSIBLE if the corruption is to severe to repair the image.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param pVDIfsDisk Pointer to the per-disk VD interface list.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param pVDIfsImage Pointer to the per-image VD interface list.
895d68f6e6c15446ca98b8f6ec96ce19d7ea356fvboxsync * @param pszFilename Name of the image file to repair.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param pszFormat The backend to use.
ce9015004a47e95eb75e047ba42f2d3200d2d222vboxsync * @param fFlags Combination of the VD_REPAIR_* flags.
27152389a84c6dec057fba6fc21241991e079006vboxsyncVBOXDDU_DECL(int) VDRepair(PVDINTERFACE pVDIfsDisk, PVDINTERFACE pVDIfsImage,
27152389a84c6dec057fba6fc21241991e079006vboxsync * Create a VFS file handle from the given HDD container.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @return VBox status code.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param pDisk Pointer to HDD container.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param fFlags Combination of the VD_VFSFILE_* flags.
27152389a84c6dec057fba6fc21241991e079006vboxsync * @param phVfsFile Where to stoer the handle to the VFS file on success.