[1] | 1 | /** @file
|
---|
[1942] | 2 | * VBox HDD Container API.
|
---|
[1] | 3 | */
|
---|
| 4 |
|
---|
| 5 | /*
|
---|
[66192] | 6 | * Copyright (C) 2006-2017 Oracle Corporation
|
---|
[1] | 7 | *
|
---|
| 8 | * This file is part of VirtualBox Open Source Edition (OSE), as
|
---|
| 9 | * available from http://www.virtualbox.org. This file is free software;
|
---|
| 10 | * you can redistribute it and/or modify it under the terms of the GNU
|
---|
[5999] | 11 | * General Public License (GPL) as published by the Free Software
|
---|
| 12 | * Foundation, in version 2 as it comes in the "COPYING" file of the
|
---|
| 13 | * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
|
---|
| 14 | * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
|
---|
| 15 | *
|
---|
| 16 | * The contents of this file may alternatively be used under the terms
|
---|
| 17 | * of the Common Development and Distribution License Version 1.0
|
---|
| 18 | * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
|
---|
| 19 | * VirtualBox OSE distribution, in which case the provisions of the
|
---|
| 20 | * CDDL are applicable instead of those of the GPL.
|
---|
| 21 | *
|
---|
| 22 | * You may elect to license modified versions of this file under the
|
---|
| 23 | * terms and conditions of either the GPL or the CDDL or both.
|
---|
[1] | 24 | */
|
---|
| 25 |
|
---|
[3632] | 26 | #ifndef ___VBox_VD_h
|
---|
| 27 | #define ___VBox_VD_h
|
---|
[1] | 28 |
|
---|
[11046] | 29 | #include <iprt/assert.h>
|
---|
| 30 | #include <iprt/string.h>
|
---|
| 31 | #include <iprt/mem.h>
|
---|
[32536] | 32 | #include <iprt/file.h>
|
---|
[26916] | 33 | #include <iprt/net.h>
|
---|
[28065] | 34 | #include <iprt/sg.h>
|
---|
[41576] | 35 | #include <iprt/vfs.h>
|
---|
[1] | 36 | #include <VBox/cdefs.h>
|
---|
| 37 | #include <VBox/types.h>
|
---|
[11046] | 38 | #include <VBox/err.h>
|
---|
[66192] | 39 | #include <VBox/vdmedia.h>
|
---|
[38469] | 40 | #include <VBox/vd-ifs.h>
|
---|
[1] | 41 |
|
---|
[20374] | 42 | RT_C_DECLS_BEGIN
|
---|
[1] | 43 |
|
---|
| 44 | #ifdef IN_RING0
|
---|
[1942] | 45 | # error "There are no VBox HDD Container APIs available in Ring-0 Host Context!"
|
---|
[1] | 46 | #endif
|
---|
| 47 |
|
---|
[66264] | 48 | /** @defgroup grp_vd Virtual Disk Container
|
---|
[1] | 49 | * @{
|
---|
| 50 | */
|
---|
| 51 |
|
---|
[1942] | 52 | /** Current VMDK image version. */
|
---|
| 53 | #define VMDK_IMAGE_VERSION (0x0001)
|
---|
[1] | 54 |
|
---|
[1942] | 55 | /** Current VDI image major version. */
|
---|
| 56 | #define VDI_IMAGE_VERSION_MAJOR (0x0001)
|
---|
| 57 | /** Current VDI image minor version. */
|
---|
| 58 | #define VDI_IMAGE_VERSION_MINOR (0x0001)
|
---|
| 59 | /** Current VDI image version. */
|
---|
| 60 | #define VDI_IMAGE_VERSION ((VDI_IMAGE_VERSION_MAJOR << 16) | VDI_IMAGE_VERSION_MINOR)
|
---|
| 61 |
|
---|
| 62 | /** Get VDI major version from combined version. */
|
---|
| 63 | #define VDI_GET_VERSION_MAJOR(uVer) ((uVer) >> 16)
|
---|
| 64 | /** Get VDI minor version from combined version. */
|
---|
| 65 | #define VDI_GET_VERSION_MINOR(uVer) ((uVer) & 0xffff)
|
---|
| 66 |
|
---|
[6291] | 67 | /** Placeholder for specifying the last opened image. */
|
---|
| 68 | #define VD_LAST_IMAGE 0xffffffffU
|
---|
| 69 |
|
---|
[38203] | 70 | /** Placeholder for VDCopyEx to indicate that the image content is unknown. */
|
---|
| 71 | #define VD_IMAGE_CONTENT_UNKNOWN 0xffffffffU
|
---|
| 72 |
|
---|
[1942] | 73 | /** @name VBox HDD container image flags
|
---|
[52830] | 74 | * Same values as MediumVariant API enum.
|
---|
[1901] | 75 | * @{
|
---|
| 76 | */
|
---|
[1] | 77 | /** No flags. */
|
---|
[16827] | 78 | #define VD_IMAGE_FLAGS_NONE (0)
|
---|
[17970] | 79 | /** Fixed image. */
|
---|
| 80 | #define VD_IMAGE_FLAGS_FIXED (0x10000)
|
---|
| 81 | /** Diff image. Mutually exclusive with fixed image. */
|
---|
| 82 | #define VD_IMAGE_FLAGS_DIFF (0x20000)
|
---|
[1942] | 83 | /** VMDK: Split image into 2GB extents. */
|
---|
[16827] | 84 | #define VD_VMDK_IMAGE_FLAGS_SPLIT_2G (0x0001)
|
---|
[2650] | 85 | /** VMDK: Raw disk image (giving access to a number of host partitions). */
|
---|
[16827] | 86 | #define VD_VMDK_IMAGE_FLAGS_RAWDISK (0x0002)
|
---|
| 87 | /** VMDK: stream optimized image, read only. */
|
---|
| 88 | #define VD_VMDK_IMAGE_FLAGS_STREAM_OPTIMIZED (0x0004)
|
---|
[18566] | 89 | /** VMDK: ESX variant, use in addition to other flags. */
|
---|
| 90 | #define VD_VMDK_IMAGE_FLAGS_ESX (0x0008)
|
---|
[2741] | 91 | /** VDI: Fill new blocks with zeroes while expanding image file. Only valid
|
---|
| 92 | * for newly created images, never set for opened existing images. */
|
---|
[16827] | 93 | #define VD_VDI_IMAGE_FLAGS_ZERO_EXPAND (0x0100)
|
---|
[1] | 94 |
|
---|
[1942] | 95 | /** Mask of valid image flags for VMDK. */
|
---|
[18566] | 96 | #define VD_VMDK_IMAGE_FLAGS_MASK ( VD_IMAGE_FLAGS_FIXED | VD_IMAGE_FLAGS_DIFF | VD_IMAGE_FLAGS_NONE \
|
---|
| 97 | | VD_VMDK_IMAGE_FLAGS_SPLIT_2G | VD_VMDK_IMAGE_FLAGS_RAWDISK \
|
---|
| 98 | | VD_VMDK_IMAGE_FLAGS_STREAM_OPTIMIZED | VD_VMDK_IMAGE_FLAGS_ESX)
|
---|
[1] | 99 |
|
---|
[1942] | 100 | /** Mask of valid image flags for VDI. */
|
---|
[17970] | 101 | #define VD_VDI_IMAGE_FLAGS_MASK (VD_IMAGE_FLAGS_FIXED | VD_IMAGE_FLAGS_DIFF | VD_IMAGE_FLAGS_NONE | VD_VDI_IMAGE_FLAGS_ZERO_EXPAND)
|
---|
[1942] | 102 |
|
---|
[6291] | 103 | /** Mask of all valid image flags for all formats. */
|
---|
| 104 | #define VD_IMAGE_FLAGS_MASK (VD_VMDK_IMAGE_FLAGS_MASK | VD_VDI_IMAGE_FLAGS_MASK)
|
---|
| 105 |
|
---|
[1942] | 106 | /** Default image flags. */
|
---|
[2118] | 107 | #define VD_IMAGE_FLAGS_DEFAULT (VD_IMAGE_FLAGS_NONE)
|
---|
[1] | 108 | /** @} */
|
---|
| 109 |
|
---|
[39519] | 110 | /** @name VD image repair flags
|
---|
| 111 | * @{
|
---|
| 112 | */
|
---|
| 113 | /** Don't repair the image but check what needs to be done. */
|
---|
| 114 | #define VD_REPAIR_DRY_RUN RT_BIT_32(0)
|
---|
[2662] | 115 |
|
---|
[39519] | 116 | /** Mask of all valid repair flags. */
|
---|
| 117 | #define VD_REPAIR_FLAGS_MASK (VD_REPAIR_DRY_RUN)
|
---|
| 118 | /** @} */
|
---|
| 119 |
|
---|
[41576] | 120 | /** @name VD image VFS file flags
|
---|
| 121 | * @{
|
---|
| 122 | */
|
---|
| 123 | /** Destroy the VD disk container when the VFS file is released. */
|
---|
| 124 | #define VD_VFSFILE_DESTROY_ON_RELEASE RT_BIT_32(0)
|
---|
| 125 |
|
---|
| 126 | /** Mask of all valid repair flags. */
|
---|
| 127 | #define VD_VFSFILE_FLAGS_MASK (VD_VFSFILE_DESTROY_ON_RELEASE)
|
---|
| 128 | /** @} */
|
---|
| 129 |
|
---|
[57064] | 130 | /** @name VBox raw disk or partition flags
|
---|
| 131 | * @{
|
---|
| 132 | */
|
---|
| 133 | /** No special treatment. */
|
---|
[66250] | 134 | #define VDISKRAW_NORMAL 0
|
---|
[57064] | 135 | /** Whether this is a raw disk (where the partition information is ignored) or
|
---|
| 136 | * not. Valid only in the raw disk descriptor. */
|
---|
[66250] | 137 | #define VDISKRAW_DISK RT_BIT(0)
|
---|
[57064] | 138 | /** Open the corresponding raw disk or partition for reading only, no matter
|
---|
| 139 | * how the image is created or opened. */
|
---|
[66250] | 140 | #define VDISKRAW_READONLY RT_BIT(1)
|
---|
[57064] | 141 | /** @} */
|
---|
| 142 |
|
---|
[2662] | 143 | /**
|
---|
[29649] | 144 | * Auxiliary type for describing partitions on raw disks. The entries must be
|
---|
| 145 | * in ascending order (as far as uStart is concerned), and must not overlap.
|
---|
| 146 | * Note that this does not correspond 1:1 to partitions, it is describing the
|
---|
| 147 | * general meaning of contiguous areas on the disk.
|
---|
[2662] | 148 | */
|
---|
[66250] | 149 | typedef struct VDISKRAWPARTDESC
|
---|
[2662] | 150 | {
|
---|
[29649] | 151 | /** Device to use for this partition/data area. Can be the disk device if
|
---|
| 152 | * the offset field is set appropriately. If this is NULL, then this
|
---|
| 153 | * partition will not be accessible to the guest. The size of the data area
|
---|
| 154 | * must still be set correctly. */
|
---|
[2662] | 155 | const char *pszRawDevice;
|
---|
[29649] | 156 | /** Pointer to the partitioning info. NULL means this is a regular data
|
---|
| 157 | * area on disk, non-NULL denotes data which should be copied to the
|
---|
| 158 | * partition data overlay. */
|
---|
[2662] | 159 | const void *pvPartitionData;
|
---|
[29649] | 160 | /** Offset where the data starts in this device. */
|
---|
| 161 | uint64_t uStartOffset;
|
---|
| 162 | /** Offset where the data starts in the disk. */
|
---|
| 163 | uint64_t uStart;
|
---|
| 164 | /** Size of the data area. */
|
---|
| 165 | uint64_t cbData;
|
---|
[66250] | 166 | /** Flags for special treatment, see VDISKRAW_FLAGS_*. */
|
---|
[57064] | 167 | uint32_t uFlags;
|
---|
[66250] | 168 | } VDISKRAWPARTDESC, *PVDISKRAWPARTDESC;
|
---|
[2662] | 169 |
|
---|
| 170 | /**
|
---|
[43861] | 171 | * Auxiliary data structure for difference between GPT and MBR
|
---|
| 172 | * disks.
|
---|
[42859] | 173 | */
|
---|
[66250] | 174 | typedef enum VDISKPARTTYPE
|
---|
[42859] | 175 | {
|
---|
| 176 | MBR,
|
---|
| 177 | GPT
|
---|
[66250] | 178 | } VDISKPARTTYPE;
|
---|
[42859] | 179 |
|
---|
| 180 | /**
|
---|
[2662] | 181 | * Auxiliary data structure for creating raw disks.
|
---|
| 182 | */
|
---|
[66250] | 183 | typedef struct VDISKRAW
|
---|
[2662] | 184 | {
|
---|
[25647] | 185 | /** Signature for structure. Must be 'R', 'A', 'W', '\\0'. Actually a trick
|
---|
[6291] | 186 | * to make logging of the comment string produce sensible results. */
|
---|
| 187 | char szSignature[4];
|
---|
[66250] | 188 | /** Flags for special treatment, see VDISKRAW_FLAGS_*. */
|
---|
[2662] | 189 | /** Flag whether access to full disk should be given (ignoring the
|
---|
| 190 | * partition information below). */
|
---|
[57064] | 191 | uint32_t uFlags;
|
---|
[2662] | 192 | /** Filename for the raw disk. Ignored for partitioned raw disks.
|
---|
[58106] | 193 | * For Linux e.g. /dev/sda, and for Windows e.g. //./PhysicalDisk0. */
|
---|
[2662] | 194 | const char *pszRawDisk;
|
---|
[29649] | 195 | /** Number of entries in the partition descriptor array. */
|
---|
| 196 | unsigned cPartDescs;
|
---|
| 197 | /** Pointer to the partition descriptor array. */
|
---|
[66250] | 198 | PVDISKRAWPARTDESC pPartDescs;
|
---|
[48878] | 199 | /** Partitioning type of the disk */
|
---|
[66250] | 200 | VDISKPARTTYPE uPartitioningType;
|
---|
| 201 | } VDISKRAW, *PVDISKRAW;
|
---|
[2662] | 202 |
|
---|
[42859] | 203 |
|
---|
[1942] | 204 | /** @name VBox HDD container image open mode flags
|
---|
[1] | 205 | * @{
|
---|
| 206 | */
|
---|
| 207 | /** Try to open image in read/write exclusive access mode if possible, or in read-only elsewhere. */
|
---|
[2591] | 208 | #define VD_OPEN_FLAGS_NORMAL 0
|
---|
[1] | 209 | /** Open image in read-only mode with sharing access with others. */
|
---|
[2591] | 210 | #define VD_OPEN_FLAGS_READONLY RT_BIT(0)
|
---|
[2118] | 211 | /** Honor zero block writes instead of ignoring them whenever possible.
|
---|
| 212 | * This is not supported by all formats. It is silently ignored in this case. */
|
---|
[2591] | 213 | #define VD_OPEN_FLAGS_HONOR_ZEROES RT_BIT(1)
|
---|
| 214 | /** Honor writes of the same data instead of ignoring whenever possible.
|
---|
| 215 | * This is handled generically, and is only meaningful for differential image
|
---|
| 216 | * formats. It is silently ignored otherwise. */
|
---|
| 217 | #define VD_OPEN_FLAGS_HONOR_SAME RT_BIT(2)
|
---|
[9599] | 218 | /** Do not perform the base/diff image check on open. This does NOT imply
|
---|
| 219 | * opening the image as readonly (would break e.g. adding UUIDs to VMDK files
|
---|
| 220 | * created by other products). Images opened with this flag should only be
|
---|
[2833] | 221 | * used for querying information, and nothing else. */
|
---|
| 222 | #define VD_OPEN_FLAGS_INFO RT_BIT(3)
|
---|
[32536] | 223 | /** Open image for asynchronous access. Only available if VD_CAP_ASYNC_IO is
|
---|
[36633] | 224 | * set. VDOpen fails with VERR_NOT_SUPPORTED if this operation is not supported for
|
---|
| 225 | * this kind of image. */
|
---|
[10715] | 226 | #define VD_OPEN_FLAGS_ASYNC_IO RT_BIT(4)
|
---|
[31180] | 227 | /** Allow sharing of the image for writable images. May be ignored if the
|
---|
| 228 | * format backend doesn't support this type of concurrent access. */
|
---|
| 229 | #define VD_OPEN_FLAGS_SHAREABLE RT_BIT(5)
|
---|
[33182] | 230 | /** Ask the backend to switch to sequential accesses if possible. Opening
|
---|
| 231 | * will not fail if it cannot do this, the flag will be simply ignored. */
|
---|
| 232 | #define VD_OPEN_FLAGS_SEQUENTIAL RT_BIT(6)
|
---|
[38621] | 233 | /** Allow the discard operation if supported. Only available if VD_CAP_DISCARD
|
---|
| 234 | * is set. VDOpen fails with VERR_VD_DISCARD_NOT_SUPPORTED if discarding is not
|
---|
| 235 | * supported. */
|
---|
| 236 | #define VD_OPEN_FLAGS_DISCARD RT_BIT(7)
|
---|
[39798] | 237 | /** Ignore all flush requests to workaround certain filesystems which are slow
|
---|
| 238 | * when writing a lot of cached data to the medium.
|
---|
| 239 | * Use with extreme care as a host crash can result in completely corrupted and
|
---|
| 240 | * unusable images.
|
---|
| 241 | */
|
---|
| 242 | #define VD_OPEN_FLAGS_IGNORE_FLUSH RT_BIT(8)
|
---|
[42039] | 243 | /**
|
---|
| 244 | * Return VINF_VD_NEW_ZEROED_BLOCK for reads from unallocated blocks.
|
---|
| 245 | * The caller who uses the flag has to make sure that the read doesn't cross
|
---|
| 246 | * a block boundary. Because the block size can differ between images reading one
|
---|
| 247 | * sector at a time is the safest solution.
|
---|
| 248 | */
|
---|
| 249 | #define VD_OPEN_FLAGS_INFORM_ABOUT_ZERO_BLOCKS RT_BIT(9)
|
---|
[43861] | 250 | /**
|
---|
| 251 | * Don't do unnecessary consistency checks when opening the image.
|
---|
| 252 | * Only valid when the image is opened in readonly because inconsistencies
|
---|
| 253 | * can lead to corrupted images in read-write mode.
|
---|
| 254 | */
|
---|
| 255 | #define VD_OPEN_FLAGS_SKIP_CONSISTENCY_CHECKS RT_BIT(10)
|
---|
[1] | 256 | /** Mask of valid flags. */
|
---|
[43861] | 257 | #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)
|
---|
[1] | 258 | /** @}*/
|
---|
| 259 |
|
---|
[54340] | 260 | /** @name VBox HDD container filter flags
|
---|
| 261 | * @{
|
---|
| 262 | */
|
---|
| 263 | /** The filter is applied during writes. */
|
---|
| 264 | #define VD_FILTER_FLAGS_WRITE RT_BIT(0)
|
---|
| 265 | /** The filter is applied during reads. */
|
---|
| 266 | #define VD_FILTER_FLAGS_READ RT_BIT(1)
|
---|
[54835] | 267 | /** Open the filter in info mode. */
|
---|
| 268 | #define VD_FILTER_FLAGS_INFO RT_BIT(2)
|
---|
[54340] | 269 | /** Default set of filter flags. */
|
---|
| 270 | #define VD_FILTER_FLAGS_DEFAULT (VD_FILTER_FLAGS_WRITE | VD_FILTER_FLAGS_READ)
|
---|
| 271 | /** Mask of valid flags. */
|
---|
[54835] | 272 | #define VD_FILTER_FLAGS_MASK (VD_FILTER_FLAGS_WRITE | VD_FILTER_FLAGS_READ | VD_FILTER_FLAGS_INFO)
|
---|
[54340] | 273 | /** @} */
|
---|
| 274 |
|
---|
[32536] | 275 | /**
|
---|
| 276 | * Helper functions to handle open flags.
|
---|
| 277 | */
|
---|
[7781] | 278 |
|
---|
[32536] | 279 | /**
|
---|
| 280 | * Translate VD_OPEN_FLAGS_* to RTFile open flags.
|
---|
| 281 | *
|
---|
| 282 | * @return RTFile open flags.
|
---|
[55956] | 283 | * @param fOpenFlags VD_OPEN_FLAGS_* open flags.
|
---|
[32536] | 284 | * @param fCreate Flag that the file should be created.
|
---|
| 285 | */
|
---|
[55956] | 286 | DECLINLINE(uint32_t) VDOpenFlagsToFileOpenFlags(unsigned fOpenFlags, bool fCreate)
|
---|
[32536] | 287 | {
|
---|
[68670] | 288 | uint32_t fOpen;
|
---|
[55956] | 289 | AssertMsg(!(fOpenFlags & VD_OPEN_FLAGS_READONLY) || !fCreate, ("Image can't be opened readonly while being created\n"));
|
---|
[32536] | 290 |
|
---|
[55956] | 291 | if (fOpenFlags & VD_OPEN_FLAGS_READONLY)
|
---|
| 292 | fOpen = RTFILE_O_READ | RTFILE_O_DENY_NONE;
|
---|
[32536] | 293 | else
|
---|
| 294 | {
|
---|
[55956] | 295 | fOpen = RTFILE_O_READWRITE;
|
---|
[32536] | 296 |
|
---|
[55956] | 297 | if (fOpenFlags & VD_OPEN_FLAGS_SHAREABLE)
|
---|
[32536] | 298 | fOpen |= RTFILE_O_DENY_NONE;
|
---|
| 299 | else
|
---|
| 300 | fOpen |= RTFILE_O_DENY_WRITE;
|
---|
| 301 | }
|
---|
| 302 |
|
---|
[55956] | 303 | if (!fCreate)
|
---|
| 304 | fOpen |= RTFILE_O_OPEN;
|
---|
| 305 | else
|
---|
[32536] | 306 | fOpen |= RTFILE_O_CREATE | RTFILE_O_NOT_CONTENT_INDEXED;
|
---|
| 307 |
|
---|
| 308 | return fOpen;
|
---|
| 309 | }
|
---|
| 310 |
|
---|
| 311 |
|
---|
[7781] | 312 | /** @name VBox HDD container backend capability flags
|
---|
| 313 | * @{
|
---|
| 314 | */
|
---|
| 315 | /** Supports UUIDs as expected by VirtualBox code. */
|
---|
| 316 | #define VD_CAP_UUID RT_BIT(0)
|
---|
| 317 | /** Supports creating fixed size images, allocating all space instantly. */
|
---|
| 318 | #define VD_CAP_CREATE_FIXED RT_BIT(1)
|
---|
| 319 | /** Supports creating dynamically growing images, allocating space on demand. */
|
---|
| 320 | #define VD_CAP_CREATE_DYNAMIC RT_BIT(2)
|
---|
| 321 | /** Supports creating images split in chunks of a bit less than 2GBytes. */
|
---|
| 322 | #define VD_CAP_CREATE_SPLIT_2G RT_BIT(3)
|
---|
| 323 | /** Supports being used as differencing image format backend. */
|
---|
| 324 | #define VD_CAP_DIFF RT_BIT(4)
|
---|
[10715] | 325 | /** Supports asynchronous I/O operations for at least some configurations. */
|
---|
| 326 | #define VD_CAP_ASYNC RT_BIT(5)
|
---|
[10467] | 327 | /** The backend operates on files. The caller needs to know to handle the
|
---|
| 328 | * location appropriately. */
|
---|
| 329 | #define VD_CAP_FILE RT_BIT(6)
|
---|
[11484] | 330 | /** The backend uses the config interface. The caller needs to know how to
|
---|
| 331 | * provide the mandatory configuration parts this way. */
|
---|
| 332 | #define VD_CAP_CONFIG RT_BIT(7)
|
---|
[14526] | 333 | /** The backend uses the network stack interface. The caller has to provide
|
---|
| 334 | * the appropriate interface. */
|
---|
| 335 | #define VD_CAP_TCPNET RT_BIT(8)
|
---|
[32536] | 336 | /** The backend supports VFS (virtual filesystem) functionality since it uses
|
---|
| 337 | * VDINTERFACEIO exclusively for all file operations. */
|
---|
| 338 | #define VD_CAP_VFS RT_BIT(9)
|
---|
[38621] | 339 | /** The backend supports the discard operation. */
|
---|
| 340 | #define VD_CAP_DISCARD RT_BIT(10)
|
---|
[60608] | 341 | /** This is a frequently used backend. */
|
---|
| 342 | #define VD_CAP_PREFERRED RT_BIT(11)
|
---|
[7781] | 343 | /** @}*/
|
---|
| 344 |
|
---|
[11484] | 345 | /** @name Configuration interface key handling flags.
|
---|
| 346 | * @{
|
---|
| 347 | */
|
---|
| 348 | /** Mandatory config key. Not providing a value for this key will cause
|
---|
| 349 | * the backend to fail. */
|
---|
| 350 | #define VD_CFGKEY_MANDATORY RT_BIT(0)
|
---|
| 351 | /** Expert config key. Not showing it by default in the GUI is is probably
|
---|
| 352 | * a good idea, as the average user won't understand it easily. */
|
---|
| 353 | #define VD_CFGKEY_EXPERT RT_BIT(1)
|
---|
| 354 | /** @}*/
|
---|
| 355 |
|
---|
[14780] | 356 |
|
---|
[11046] | 357 | /**
|
---|
[14780] | 358 | * Configuration value type for configuration information interface.
|
---|
| 359 | */
|
---|
| 360 | typedef enum VDCFGVALUETYPE
|
---|
| 361 | {
|
---|
| 362 | /** Integer value. */
|
---|
| 363 | VDCFGVALUETYPE_INTEGER = 1,
|
---|
| 364 | /** String value. */
|
---|
| 365 | VDCFGVALUETYPE_STRING,
|
---|
| 366 | /** Bytestring value. */
|
---|
| 367 | VDCFGVALUETYPE_BYTES
|
---|
| 368 | } VDCFGVALUETYPE;
|
---|
| 369 |
|
---|
| 370 |
|
---|
| 371 | /**
|
---|
[11484] | 372 | * Structure describing configuration keys required/supported by a backend
|
---|
| 373 | * through the config interface.
|
---|
| 374 | */
|
---|
| 375 | typedef struct VDCONFIGINFO
|
---|
| 376 | {
|
---|
| 377 | /** Key name of the configuration. */
|
---|
| 378 | const char *pszKey;
|
---|
| 379 | /** Pointer to default value (descriptor). NULL if no useful default value
|
---|
| 380 | * can be specified. */
|
---|
[14780] | 381 | const char *pszDefaultValue;
|
---|
[11484] | 382 | /** Value type for this key. */
|
---|
| 383 | VDCFGVALUETYPE enmValueType;
|
---|
| 384 | /** Key handling flags (a combination of VD_CFGKEY_* flags). */
|
---|
| 385 | uint64_t uKeyFlags;
|
---|
| 386 | } VDCONFIGINFO;
|
---|
| 387 |
|
---|
| 388 | /** Pointer to structure describing configuration keys. */
|
---|
| 389 | typedef VDCONFIGINFO *PVDCONFIGINFO;
|
---|
| 390 |
|
---|
| 391 | /** Pointer to const structure describing configuration keys. */
|
---|
| 392 | typedef const VDCONFIGINFO *PCVDCONFIGINFO;
|
---|
| 393 |
|
---|
| 394 | /**
|
---|
[33524] | 395 | * Structure describing a file extension.
|
---|
| 396 | */
|
---|
| 397 | typedef struct VDFILEEXTENSION
|
---|
| 398 | {
|
---|
| 399 | /** Pointer to the NULL-terminated string containing the extension. */
|
---|
| 400 | const char *pszExtension;
|
---|
| 401 | /** The device type the extension supports. */
|
---|
| 402 | VDTYPE enmType;
|
---|
| 403 | } VDFILEEXTENSION;
|
---|
| 404 |
|
---|
| 405 | /** Pointer to a structure describing a file extension. */
|
---|
| 406 | typedef VDFILEEXTENSION *PVDFILEEXTENSION;
|
---|
| 407 |
|
---|
| 408 | /** Pointer to a const structure describing a file extension. */
|
---|
| 409 | typedef const VDFILEEXTENSION *PCVDFILEEXTENSION;
|
---|
| 410 |
|
---|
| 411 | /**
|
---|
[11484] | 412 | * Data structure for returning a list of backend capabilities.
|
---|
| 413 | */
|
---|
| 414 | typedef struct VDBACKENDINFO
|
---|
| 415 | {
|
---|
[15366] | 416 | /** Name of the backend. Must be unique even with case insensitive comparison. */
|
---|
[14852] | 417 | const char *pszBackend;
|
---|
[11484] | 418 | /** Capabilities of the backend (a combination of the VD_CAP_* flags). */
|
---|
| 419 | uint64_t uBackendCaps;
|
---|
| 420 | /** Pointer to a NULL-terminated array of strings, containing the supported
|
---|
| 421 | * file extensions. Note that some backends do not work on files, so this
|
---|
| 422 | * pointer may just contain NULL. */
|
---|
[33524] | 423 | PCVDFILEEXTENSION paFileExtensions;
|
---|
[11484] | 424 | /** Pointer to an array of structs describing each supported config key.
|
---|
| 425 | * Terminated by a NULL config key. Note that some backends do not support
|
---|
| 426 | * the configuration interface, so this pointer may just contain NULL.
|
---|
| 427 | * Mandatory if the backend sets VD_CAP_CONFIG. */
|
---|
| 428 | PCVDCONFIGINFO paConfigInfo;
|
---|
[14967] | 429 | /** Returns a human readable hard disk location string given a
|
---|
| 430 | * set of hard disk configuration keys. The returned string is an
|
---|
| 431 | * equivalent of the full file path for image-based hard disks.
|
---|
| 432 | * Mandatory for backends with no VD_CAP_FILE and NULL otherwise. */
|
---|
| 433 | DECLR3CALLBACKMEMBER(int, pfnComposeLocation, (PVDINTERFACE pConfig, char **pszLocation));
|
---|
| 434 | /** Returns a human readable hard disk name string given a
|
---|
| 435 | * set of hard disk configuration keys. The returned string is an
|
---|
| 436 | * equivalent of the file name part in the full file path for
|
---|
| 437 | * image-based hard disks. Mandatory for backends with no
|
---|
| 438 | * VD_CAP_FILE and NULL otherwise. */
|
---|
| 439 | DECLR3CALLBACKMEMBER(int, pfnComposeName, (PVDINTERFACE pConfig, char **pszName));
|
---|
[11484] | 440 | } VDBACKENDINFO, *PVDBACKENDINFO;
|
---|
| 441 |
|
---|
[51886] | 442 | /**
|
---|
| 443 | * Data structure for returning a list of filter capabilities.
|
---|
| 444 | */
|
---|
| 445 | typedef struct VDFILTERINFO
|
---|
| 446 | {
|
---|
| 447 | /** Name of the filter. Must be unique even with case insensitive comparison. */
|
---|
| 448 | const char *pszFilter;
|
---|
| 449 | /** Pointer to an array of structs describing each supported config key.
|
---|
| 450 | * Terminated by a NULL config key. Note that some filters do not support
|
---|
| 451 | * the configuration interface, so this pointer may just contain NULL. */
|
---|
| 452 | PCVDCONFIGINFO paConfigInfo;
|
---|
| 453 | } VDFILTERINFO, *PVDFILTERINFO;
|
---|
[28620] | 454 |
|
---|
[51886] | 455 |
|
---|
[27808] | 456 | /**
|
---|
[32536] | 457 | * Request completion callback for the async read/write API.
|
---|
| 458 | */
|
---|
[59294] | 459 | typedef DECLCALLBACK(void) FNVDASYNCTRANSFERCOMPLETE (void *pvUser1, void *pvUser2, int rcReq);
|
---|
[32536] | 460 | /** Pointer to a transfer compelte callback. */
|
---|
| 461 | typedef FNVDASYNCTRANSFERCOMPLETE *PFNVDASYNCTRANSFERCOMPLETE;
|
---|
| 462 |
|
---|
| 463 | /**
|
---|
[66250] | 464 | * VD Container main structure.
|
---|
[1] | 465 | */
|
---|
[66250] | 466 | /* Forward declaration, VDISK structure is visible only inside VD module. */
|
---|
| 467 | struct VDISK;
|
---|
| 468 | typedef struct VDISK VDISK;
|
---|
| 469 | typedef VDISK *PVDISK;
|
---|
[1] | 470 |
|
---|
[14852] | 471 | /**
|
---|
| 472 | * Initializes HDD backends.
|
---|
| 473 | *
|
---|
| 474 | * @returns VBox status code.
|
---|
| 475 | */
|
---|
[16962] | 476 | VBOXDDU_DECL(int) VDInit(void);
|
---|
[7781] | 477 |
|
---|
[1] | 478 | /**
|
---|
[14852] | 479 | * Destroys loaded HDD backends.
|
---|
| 480 | *
|
---|
| 481 | * @returns VBox status code.
|
---|
| 482 | */
|
---|
[16962] | 483 | VBOXDDU_DECL(int) VDShutdown(void);
|
---|
[14852] | 484 |
|
---|
| 485 | /**
|
---|
[51751] | 486 | * Loads a single plugin given by filename.
|
---|
| 487 | *
|
---|
| 488 | * @returns VBox status code.
|
---|
| 489 | * @param pszFilename The plugin filename to load.
|
---|
| 490 | */
|
---|
| 491 | VBOXDDU_DECL(int) VDPluginLoadFromFilename(const char *pszFilename);
|
---|
| 492 |
|
---|
| 493 | /**
|
---|
| 494 | * Load all plugins from a given path.
|
---|
| 495 | *
|
---|
| 496 | * @returns VBox statuse code.
|
---|
| 497 | * @param pszPath The path to load plugins from.
|
---|
| 498 | */
|
---|
| 499 | VBOXDDU_DECL(int) VDPluginLoadFromPath(const char *pszPath);
|
---|
| 500 |
|
---|
| 501 | /**
|
---|
[52585] | 502 | * Unloads a single plugin given by filename.
|
---|
| 503 | *
|
---|
| 504 | * @returns VBox status code.
|
---|
| 505 | * @param pszFilename The plugin filename to unload.
|
---|
| 506 | */
|
---|
| 507 | VBOXDDU_DECL(int) VDPluginUnloadFromFilename(const char *pszFilename);
|
---|
| 508 |
|
---|
| 509 | /**
|
---|
| 510 | * Unload all plugins from a given path.
|
---|
| 511 | *
|
---|
| 512 | * @returns VBox statuse code.
|
---|
| 513 | * @param pszPath The path to unload plugins from.
|
---|
| 514 | */
|
---|
| 515 | VBOXDDU_DECL(int) VDPluginUnloadFromPath(const char *pszPath);
|
---|
| 516 |
|
---|
| 517 | /**
|
---|
[7781] | 518 | * Lists all HDD backends and their capabilities in a caller-provided buffer.
|
---|
| 519 | *
|
---|
[11046] | 520 | * @return VBox status code.
|
---|
[7781] | 521 | * VERR_BUFFER_OVERFLOW if not enough space is passed.
|
---|
| 522 | * @param cEntriesAlloc Number of list entries available.
|
---|
| 523 | * @param pEntries Pointer to array for the entries.
|
---|
| 524 | * @param pcEntriesUsed Number of entries returned.
|
---|
| 525 | */
|
---|
| 526 | VBOXDDU_DECL(int) VDBackendInfo(unsigned cEntriesAlloc, PVDBACKENDINFO pEntries,
|
---|
[34217] | 527 | unsigned *pcEntriesUsed);
|
---|
[7781] | 528 |
|
---|
[10715] | 529 | /**
|
---|
[33540] | 530 | * Lists the capabilities of a backend identified by its name.
|
---|
[10715] | 531 | *
|
---|
[11046] | 532 | * @return VBox status code.
|
---|
[15366] | 533 | * @param pszBackend The backend name (case insensitive).
|
---|
[58106] | 534 | * @param pEntry Pointer to an entry.
|
---|
[10715] | 535 | */
|
---|
| 536 | VBOXDDU_DECL(int) VDBackendInfoOne(const char *pszBackend, PVDBACKENDINFO pEntry);
|
---|
[7781] | 537 |
|
---|
| 538 | /**
|
---|
[51886] | 539 | * Lists all filters and their capabilities in a caller-provided buffer.
|
---|
| 540 | *
|
---|
| 541 | * @return VBox status code.
|
---|
| 542 | * VERR_BUFFER_OVERFLOW if not enough space is passed.
|
---|
| 543 | * @param cEntriesAlloc Number of list entries available.
|
---|
| 544 | * @param pEntries Pointer to array for the entries.
|
---|
| 545 | * @param pcEntriesUsed Number of entries returned.
|
---|
| 546 | */
|
---|
| 547 | VBOXDDU_DECL(int) VDFilterInfo(unsigned cEntriesAlloc, PVDFILTERINFO pEntries,
|
---|
| 548 | unsigned *pcEntriesUsed);
|
---|
| 549 |
|
---|
| 550 | /**
|
---|
| 551 | * Lists the capabilities of a filter identified by its name.
|
---|
| 552 | *
|
---|
| 553 | * @return VBox status code.
|
---|
| 554 | * @param pszFilter The filter name (case insensitive).
|
---|
[58106] | 555 | * @param pEntry Pointer to an entry.
|
---|
[51886] | 556 | */
|
---|
| 557 | VBOXDDU_DECL(int) VDFilterInfoOne(const char *pszFilter, PVDFILTERINFO pEntry);
|
---|
| 558 |
|
---|
| 559 | /**
|
---|
[6291] | 560 | * Allocates and initializes an empty HDD container.
|
---|
[1942] | 561 | * No image files are opened.
|
---|
[1] | 562 | *
|
---|
[11046] | 563 | * @return VBox status code.
|
---|
[11444] | 564 | * @param pVDIfsDisk Pointer to the per-disk VD interface list.
|
---|
[33524] | 565 | * @param enmType Type of the image container.
|
---|
[6291] | 566 | * @param ppDisk Where to store the reference to HDD container.
|
---|
[1] | 567 | */
|
---|
[66250] | 568 | VBOXDDU_DECL(int) VDCreate(PVDINTERFACE pVDIfsDisk, VDTYPE enmType, PVDISK *ppDisk);
|
---|
[1] | 569 |
|
---|
| 570 | /**
|
---|
[6291] | 571 | * Destroys HDD container.
|
---|
[1942] | 572 | * If container has opened image files they will be closed.
|
---|
[1] | 573 | *
|
---|
[40258] | 574 | * @return VBox status code.
|
---|
[6291] | 575 | * @param pDisk Pointer to HDD container.
|
---|
[1] | 576 | */
|
---|
[66250] | 577 | VBOXDDU_DECL(int) VDDestroy(PVDISK pDisk);
|
---|
[1] | 578 |
|
---|
| 579 | /**
|
---|
[6291] | 580 | * Try to get the backend name which can use this image.
|
---|
[5103] | 581 | *
|
---|
[11046] | 582 | * @return VBox status code.
|
---|
[32536] | 583 | * VINF_SUCCESS if a plugin was found.
|
---|
| 584 | * ppszFormat contains the string which can be used as backend name.
|
---|
| 585 | * VERR_NOT_SUPPORTED if no backend was found.
|
---|
[22983] | 586 | * @param pVDIfsDisk Pointer to the per-disk VD interface list.
|
---|
[32536] | 587 | * @param pVDIfsImage Pointer to the per-image VD interface list.
|
---|
[5103] | 588 | * @param pszFilename Name of the image file for which the backend is queried.
|
---|
[5121] | 589 | * @param ppszFormat Receives pointer of the UTF-8 string which contains the format name.
|
---|
| 590 | * The returned pointer must be freed using RTStrFree().
|
---|
[33524] | 591 | * @param penmType Where to store the type of the image.
|
---|
[5103] | 592 | */
|
---|
[32536] | 593 | VBOXDDU_DECL(int) VDGetFormat(PVDINTERFACE pVDIfsDisk, PVDINTERFACE pVDIfsImage,
|
---|
[34217] | 594 | const char *pszFilename, char **ppszFormat, VDTYPE *penmType);
|
---|
[5103] | 595 |
|
---|
| 596 | /**
|
---|
[1942] | 597 | * Opens an image file.
|
---|
[1] | 598 | *
|
---|
[6291] | 599 | * The first opened image file in HDD container must have a base image type,
|
---|
[1942] | 600 | * others (next opened images) must be differencing or undo images.
|
---|
| 601 | * Linkage is checked for differencing image to be consistent with the previously opened image.
|
---|
| 602 | * When another differencing image is opened and the last image was opened in read/write access
|
---|
| 603 | * mode, then the last image is reopened in read-only with deny write sharing mode. This allows
|
---|
| 604 | * other processes to use images in read-only mode too.
|
---|
[1] | 605 | *
|
---|
[1942] | 606 | * Note that the image is opened in read-only mode if a read/write open is not possible.
|
---|
[2118] | 607 | * Use VDIsReadOnly to check open mode.
|
---|
[1942] | 608 | *
|
---|
[11046] | 609 | * @return VBox status code.
|
---|
[6291] | 610 | * @param pDisk Pointer to HDD container.
|
---|
[15366] | 611 | * @param pszBackend Name of the image file backend to use (case insensitive).
|
---|
[1942] | 612 | * @param pszFilename Name of the image file to open.
|
---|
[2118] | 613 | * @param uOpenFlags Image file open mode, see VD_OPEN_FLAGS_* constants.
|
---|
[11444] | 614 | * @param pVDIfsImage Pointer to the per-image VD interface list.
|
---|
[1] | 615 | */
|
---|
[66250] | 616 | VBOXDDU_DECL(int) VDOpen(PVDISK pDisk, const char *pszBackend,
|
---|
[34217] | 617 | const char *pszFilename, unsigned uOpenFlags,
|
---|
| 618 | PVDINTERFACE pVDIfsImage);
|
---|
[1] | 619 |
|
---|
| 620 | /**
|
---|
[32370] | 621 | * Opens a cache image.
|
---|
| 622 | *
|
---|
| 623 | * @return VBox status code.
|
---|
| 624 | * @param pDisk Pointer to the HDD container which should use the cache image.
|
---|
| 625 | * @param pszBackend Name of the cache file backend to use (case insensitive).
|
---|
| 626 | * @param pszFilename Name of the cache image to open.
|
---|
| 627 | * @param uOpenFlags Image file open mode, see VD_OPEN_FLAGS_* constants.
|
---|
| 628 | * @param pVDIfsCache Pointer to the per-cache VD interface list.
|
---|
| 629 | */
|
---|
[66250] | 630 | VBOXDDU_DECL(int) VDCacheOpen(PVDISK pDisk, const char *pszBackend,
|
---|
[34217] | 631 | const char *pszFilename, unsigned uOpenFlags,
|
---|
| 632 | PVDINTERFACE pVDIfsCache);
|
---|
[32370] | 633 |
|
---|
| 634 | /**
|
---|
[50991] | 635 | * Adds a filter to the disk.
|
---|
| 636 | *
|
---|
| 637 | * @returns VBox status code.
|
---|
| 638 | * @param pDisk Pointer to the HDD container which should use the filter.
|
---|
| 639 | * @param pszFilter Name of the filter backend to use (case insensitive).
|
---|
[54340] | 640 | * @param fFlags Flags which apply to the filter, combination of VD_FILTER_FLAGS_*
|
---|
| 641 | * defines.
|
---|
[50991] | 642 | * @param pVDIfsFilter Pointer to the per-filter VD interface list.
|
---|
| 643 | */
|
---|
[66250] | 644 | VBOXDDU_DECL(int) VDFilterAdd(PVDISK pDisk, const char *pszFilter, uint32_t fFlags,
|
---|
[50991] | 645 | PVDINTERFACE pVDIfsFilter);
|
---|
| 646 |
|
---|
| 647 | /**
|
---|
[1942] | 648 | * Creates and opens a new base image file.
|
---|
[1] | 649 | *
|
---|
[11046] | 650 | * @return VBox status code.
|
---|
[6291] | 651 | * @param pDisk Pointer to HDD container.
|
---|
[15366] | 652 | * @param pszBackend Name of the image file backend to use (case insensitive).
|
---|
[1942] | 653 | * @param pszFilename Name of the image file to create.
|
---|
| 654 | * @param cbSize Image size in bytes.
|
---|
| 655 | * @param uImageFlags Flags specifying special image features.
|
---|
| 656 | * @param pszComment Pointer to image comment. NULL is ok.
|
---|
[6291] | 657 | * @param pPCHSGeometry Pointer to physical disk geometry <= (16383,16,63). Not NULL.
|
---|
[18558] | 658 | * @param pLCHSGeometry Pointer to logical disk geometry <= (x,255,63). Not NULL.
|
---|
[11353] | 659 | * @param pUuid New UUID of the image. If NULL, a new UUID is created.
|
---|
[2118] | 660 | * @param uOpenFlags Image file open mode, see VD_OPEN_FLAGS_* constants.
|
---|
[11444] | 661 | * @param pVDIfsImage Pointer to the per-image VD interface list.
|
---|
| 662 | * @param pVDIfsOperation Pointer to the per-operation VD interface list.
|
---|
[1] | 663 | */
|
---|
[66250] | 664 | VBOXDDU_DECL(int) VDCreateBase(PVDISK pDisk, const char *pszBackend,
|
---|
[34217] | 665 | const char *pszFilename, uint64_t cbSize,
|
---|
| 666 | unsigned uImageFlags, const char *pszComment,
|
---|
| 667 | PCVDGEOMETRY pPCHSGeometry,
|
---|
| 668 | PCVDGEOMETRY pLCHSGeometry,
|
---|
| 669 | PCRTUUID pUuid, unsigned uOpenFlags,
|
---|
| 670 | PVDINTERFACE pVDIfsImage,
|
---|
| 671 | PVDINTERFACE pVDIfsOperation);
|
---|
[1] | 672 |
|
---|
| 673 | /**
|
---|
[1942] | 674 | * Creates and opens a new differencing image file in HDD container.
|
---|
[2118] | 675 | * See comments for VDOpen function about differencing images.
|
---|
[1] | 676 | *
|
---|
[11046] | 677 | * @return VBox status code.
|
---|
[6291] | 678 | * @param pDisk Pointer to HDD container.
|
---|
[15366] | 679 | * @param pszBackend Name of the image file backend to use (case insensitive).
|
---|
[1942] | 680 | * @param pszFilename Name of the differencing image file to create.
|
---|
| 681 | * @param uImageFlags Flags specifying special image features.
|
---|
| 682 | * @param pszComment Pointer to image comment. NULL is ok.
|
---|
[11353] | 683 | * @param pUuid New UUID of the image. If NULL, a new UUID is created.
|
---|
[15591] | 684 | * @param pParentUuid New parent UUID of the image. If NULL, the UUID is queried automatically.
|
---|
[2118] | 685 | * @param uOpenFlags Image file open mode, see VD_OPEN_FLAGS_* constants.
|
---|
[11444] | 686 | * @param pVDIfsImage Pointer to the per-image VD interface list.
|
---|
| 687 | * @param pVDIfsOperation Pointer to the per-operation VD interface list.
|
---|
[1] | 688 | */
|
---|
[66250] | 689 | VBOXDDU_DECL(int) VDCreateDiff(PVDISK pDisk, const char *pszBackend,
|
---|
[34217] | 690 | const char *pszFilename, unsigned uImageFlags,
|
---|
| 691 | const char *pszComment, PCRTUUID pUuid,
|
---|
| 692 | PCRTUUID pParentUuid, unsigned uOpenFlags,
|
---|
| 693 | PVDINTERFACE pVDIfsImage,
|
---|
| 694 | PVDINTERFACE pVDIfsOperation);
|
---|
[1] | 695 |
|
---|
| 696 | /**
|
---|
[32370] | 697 | * Creates and opens new cache image file in HDD container.
|
---|
| 698 | *
|
---|
| 699 | * @return VBox status code.
|
---|
| 700 | * @param pDisk Name of the cache file backend to use (case insensitive).
|
---|
[58106] | 701 | * @param pszBackend Name of the image file backend to use (case insensitive).
|
---|
[32370] | 702 | * @param pszFilename Name of the differencing cache file to create.
|
---|
| 703 | * @param cbSize Maximum size of the cache.
|
---|
| 704 | * @param uImageFlags Flags specifying special cache features.
|
---|
| 705 | * @param pszComment Pointer to image comment. NULL is ok.
|
---|
| 706 | * @param pUuid New UUID of the image. If NULL, a new UUID is created.
|
---|
| 707 | * @param uOpenFlags Image file open mode, see VD_OPEN_FLAGS_* constants.
|
---|
| 708 | * @param pVDIfsCache Pointer to the per-cache VD interface list.
|
---|
| 709 | * @param pVDIfsOperation Pointer to the per-operation VD interface list.
|
---|
| 710 | */
|
---|
[66250] | 711 | VBOXDDU_DECL(int) VDCreateCache(PVDISK pDisk, const char *pszBackend,
|
---|
[34217] | 712 | const char *pszFilename, uint64_t cbSize,
|
---|
| 713 | unsigned uImageFlags, const char *pszComment,
|
---|
| 714 | PCRTUUID pUuid, unsigned uOpenFlags,
|
---|
| 715 | PVDINTERFACE pVDIfsCache, PVDINTERFACE pVDIfsOperation);
|
---|
[32370] | 716 |
|
---|
| 717 | /**
|
---|
[6291] | 718 | * Merges two images (not necessarily with direct parent/child relationship).
|
---|
| 719 | * As a side effect the source image and potentially the other images which
|
---|
| 720 | * are also merged to the destination are deleted from both the disk and the
|
---|
| 721 | * images in the HDD container.
|
---|
[1] | 722 | *
|
---|
[11046] | 723 | * @return VBox status code.
|
---|
[15366] | 724 | * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
|
---|
[6291] | 725 | * @param pDisk Pointer to HDD container.
|
---|
[19034] | 726 | * @param nImageFrom Image number to merge from, counts from 0. 0 is always base image of container.
|
---|
| 727 | * @param nImageTo Image number to merge to, counts from 0. 0 is always base image of container.
|
---|
[11444] | 728 | * @param pVDIfsOperation Pointer to the per-operation VD interface list.
|
---|
[1] | 729 | */
|
---|
[66250] | 730 | VBOXDDU_DECL(int) VDMerge(PVDISK pDisk, unsigned nImageFrom,
|
---|
[34217] | 731 | unsigned nImageTo, PVDINTERFACE pVDIfsOperation);
|
---|
[1] | 732 |
|
---|
| 733 | /**
|
---|
[38203] | 734 | * Copies an image from one HDD container to another - extended version.
|
---|
| 735 | *
|
---|
[58106] | 736 | * The copy is opened in the target HDD container. It is possible to convert
|
---|
| 737 | * between different image formats, because the backend for the destination may
|
---|
| 738 | * be different from the source. If both the source and destination reference
|
---|
| 739 | * the same HDD container, then the image is moved (by copying/deleting or
|
---|
| 740 | * renaming) to the new location. The source container is unchanged if the move
|
---|
| 741 | * operation fails, otherwise the image at the new location is opened in the
|
---|
| 742 | * same way as the old one was.
|
---|
| 743 | *
|
---|
[38203] | 744 | * @note The read/write accesses across disks are not synchronized, just the
|
---|
| 745 | * accesses to each disk. Once there is a use case which requires a defined
|
---|
| 746 | * read/write behavior in this situation this needs to be extended.
|
---|
| 747 | *
|
---|
| 748 | * @return VBox status code.
|
---|
| 749 | * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
|
---|
[58106] | 750 | *
|
---|
[38203] | 751 | * @param pDiskFrom Pointer to source HDD container.
|
---|
[58106] | 752 | * @param nImage Image number, counts from 0. 0 is always base image
|
---|
| 753 | * of container.
|
---|
[38203] | 754 | * @param pDiskTo Pointer to destination HDD container.
|
---|
[58106] | 755 | * @param pszBackend Name of the image file backend to use (may be NULL
|
---|
| 756 | * to use the same as the source, case insensitive).
|
---|
| 757 | * @param pszFilename New name of the image (may be NULL to specify that
|
---|
| 758 | * the copy destination is the destination container,
|
---|
| 759 | * or if pDiskFrom == pDiskTo, i.e. when moving).
|
---|
| 760 | * @param fMoveByRename If true, attempt to perform a move by renaming (if
|
---|
| 761 | * successful the new size is ignored).
|
---|
[38203] | 762 | * @param cbSize New image size (0 means leave unchanged).
|
---|
[58106] | 763 | * @param nImageFromSame The number of the last image in the source chain
|
---|
| 764 | * having the same content as the image in the
|
---|
| 765 | * destination chain given by nImageToSame or
|
---|
| 766 | * VD_IMAGE_CONTENT_UNKNOWN to indicate that the
|
---|
| 767 | * content of both containers is unknown. See the
|
---|
| 768 | * notes for further information.
|
---|
| 769 | * @param nImageToSame The number of the last image in the destination
|
---|
| 770 | * chain having the same content as the image in the
|
---|
| 771 | * source chain given by nImageFromSame or
|
---|
| 772 | * VD_IMAGE_CONTENT_UNKNOWN to indicate that the
|
---|
| 773 | * content of both containers is unknown. See the notes
|
---|
| 774 | * for further information.
|
---|
[38203] | 775 | * @param uImageFlags Flags specifying special destination image features.
|
---|
[58106] | 776 | * @param pDstUuid New UUID of the destination image. If NULL, a new
|
---|
| 777 | * UUID is created. This parameter is used if and only
|
---|
| 778 | * if a true copy is created. In all rename/move cases
|
---|
| 779 | * or copy to existing image cases the modification
|
---|
| 780 | * UUIDs are copied over.
|
---|
[38203] | 781 | * @param uOpenFlags Image file open mode, see VD_OPEN_FLAGS_* constants.
|
---|
| 782 | * Only used if the destination image is created.
|
---|
| 783 | * @param pVDIfsOperation Pointer to the per-operation VD interface list.
|
---|
| 784 | * @param pDstVDIfsImage Pointer to the per-image VD interface list, for the
|
---|
| 785 | * destination image.
|
---|
[58106] | 786 | * @param pDstVDIfsOperation Pointer to the per-operation VD interface list,
|
---|
[38203] | 787 | * for the destination operation.
|
---|
| 788 | *
|
---|
[58106] | 789 | * @note Using nImageFromSame and nImageToSame can lead to a significant speedup
|
---|
| 790 | * when copying an image but can also lead to a corrupted copy if used
|
---|
| 791 | * incorrectly. It is mainly useful when cloning a chain of images and it
|
---|
| 792 | * is known that the virtual disk content of the two chains is exactly the
|
---|
| 793 | * same upto a certain image. Example:
|
---|
| 794 | * Imagine the chain of images which consist of a base and one diff
|
---|
| 795 | * image. Copying the chain starts with the base image. When copying
|
---|
| 796 | * the first diff image VDCopy() will read the data from the diff of
|
---|
| 797 | * the source chain and probably from the base image again in case the
|
---|
| 798 | * diff doesn't has data for the block. However the block will be
|
---|
| 799 | * optimized away because VDCopy() reads data from the base image of
|
---|
| 800 | * the destination chain compares the to and suppresses the write
|
---|
| 801 | * because the data is unchanged. For a lot of diff images this will be
|
---|
| 802 | * a huge waste of I/O bandwidth if the diff images contain only few
|
---|
| 803 | * changes. Because it is known that the base image of the source and
|
---|
| 804 | * the destination chain have the same content it is enough to check
|
---|
| 805 | * the diff image for changed data and copy it to the destination diff
|
---|
| 806 | * image which is achieved with nImageFromSame and nImageToSame.
|
---|
| 807 | * Setting both to 0 can suppress a lot of I/O.
|
---|
[38203] | 808 | */
|
---|
[66250] | 809 | VBOXDDU_DECL(int) VDCopyEx(PVDISK pDiskFrom, unsigned nImage, PVDISK pDiskTo,
|
---|
[38203] | 810 | const char *pszBackend, const char *pszFilename,
|
---|
| 811 | bool fMoveByRename, uint64_t cbSize,
|
---|
| 812 | unsigned nImageFromSame, unsigned nImageToSame,
|
---|
| 813 | unsigned uImageFlags, PCRTUUID pDstUuid,
|
---|
| 814 | unsigned uOpenFlags, PVDINTERFACE pVDIfsOperation,
|
---|
| 815 | PVDINTERFACE pDstVDIfsImage,
|
---|
| 816 | PVDINTERFACE pDstVDIfsOperation);
|
---|
| 817 |
|
---|
| 818 | /**
|
---|
[6291] | 819 | * Copies an image from one HDD container to another.
|
---|
| 820 | * The copy is opened in the target HDD container.
|
---|
[1942] | 821 | * It is possible to convert between different image formats, because the
|
---|
[7277] | 822 | * backend for the destination may be different from the source.
|
---|
[6291] | 823 | * If both the source and destination reference the same HDD container,
|
---|
| 824 | * then the image is moved (by copying/deleting or renaming) to the new location.
|
---|
[2118] | 825 | * The source container is unchanged if the move operation fails, otherwise
|
---|
| 826 | * the image at the new location is opened in the same way as the old one was.
|
---|
[1] | 827 | *
|
---|
[27232] | 828 | * @note The read/write accesses across disks are not synchronized, just the
|
---|
| 829 | * accesses to each disk. Once there is a use case which requires a defined
|
---|
| 830 | * read/write behavior in this situation this needs to be extended.
|
---|
| 831 | *
|
---|
[11046] | 832 | * @return VBox status code.
|
---|
[15366] | 833 | * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
|
---|
[6291] | 834 | * @param pDiskFrom Pointer to source HDD container.
|
---|
[1942] | 835 | * @param nImage Image number, counts from 0. 0 is always base image of container.
|
---|
[6291] | 836 | * @param pDiskTo Pointer to destination HDD container.
|
---|
[15366] | 837 | * @param pszBackend Name of the image file backend to use (may be NULL to use the same as the source, case insensitive).
|
---|
[21025] | 838 | * @param pszFilename New name of the image (may be NULL to specify that the
|
---|
| 839 | * copy destination is the destination container, or
|
---|
| 840 | * if pDiskFrom == pDiskTo, i.e. when moving).
|
---|
[6291] | 841 | * @param fMoveByRename If true, attempt to perform a move by renaming (if successful the new size is ignored).
|
---|
| 842 | * @param cbSize New image size (0 means leave unchanged).
|
---|
[17836] | 843 | * @param uImageFlags Flags specifying special destination image features.
|
---|
[15529] | 844 | * @param pDstUuid New UUID of the destination image. If NULL, a new UUID is created.
|
---|
| 845 | * This parameter is used if and only if a true copy is created.
|
---|
[21025] | 846 | * In all rename/move cases or copy to existing image cases the modification UUIDs are copied over.
|
---|
[33082] | 847 | * @param uOpenFlags Image file open mode, see VD_OPEN_FLAGS_* constants.
|
---|
| 848 | * Only used if the destination image is created.
|
---|
[11444] | 849 | * @param pVDIfsOperation Pointer to the per-operation VD interface list.
|
---|
| 850 | * @param pDstVDIfsImage Pointer to the per-image VD interface list, for the
|
---|
| 851 | * destination image.
|
---|
| 852 | * @param pDstVDIfsOperation Pointer to the per-operation VD interface list,
|
---|
| 853 | * for the destination operation.
|
---|
[1] | 854 | */
|
---|
[66250] | 855 | VBOXDDU_DECL(int) VDCopy(PVDISK pDiskFrom, unsigned nImage, PVDISK pDiskTo,
|
---|
[34217] | 856 | const char *pszBackend, const char *pszFilename,
|
---|
| 857 | bool fMoveByRename, uint64_t cbSize,
|
---|
| 858 | unsigned uImageFlags, PCRTUUID pDstUuid,
|
---|
| 859 | unsigned uOpenFlags, PVDINTERFACE pVDIfsOperation,
|
---|
| 860 | PVDINTERFACE pDstVDIfsImage,
|
---|
| 861 | PVDINTERFACE pDstVDIfsOperation);
|
---|
[1] | 862 |
|
---|
| 863 | /**
|
---|
[19034] | 864 | * Optimizes the storage consumption of an image. Typically the unused blocks
|
---|
| 865 | * have to be wiped with zeroes to achieve a substantial reduced storage use.
|
---|
| 866 | * Another optimization done is reordering the image blocks, which can provide
|
---|
| 867 | * a significant performance boost, as reads and writes tend to use less random
|
---|
| 868 | * file offsets.
|
---|
| 869 | *
|
---|
[27232] | 870 | * @note Compaction is treated as a single operation with regard to thread
|
---|
| 871 | * synchronization, which means that it potentially blocks other activities for
|
---|
| 872 | * a long time. The complexity of compaction would grow even more if concurrent
|
---|
| 873 | * accesses have to be handled.
|
---|
| 874 | *
|
---|
[19034] | 875 | * @return VBox status code.
|
---|
| 876 | * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
|
---|
| 877 | * @return VERR_VD_IMAGE_READ_ONLY if image is not writable.
|
---|
| 878 | * @return VERR_NOT_SUPPORTED if this kind of image can be compacted, but
|
---|
| 879 | * this isn't supported yet.
|
---|
| 880 | * @param pDisk Pointer to HDD container.
|
---|
| 881 | * @param nImage Image number, counts from 0. 0 is always base image of container.
|
---|
| 882 | * @param pVDIfsOperation Pointer to the per-operation VD interface list.
|
---|
| 883 | */
|
---|
[66250] | 884 | VBOXDDU_DECL(int) VDCompact(PVDISK pDisk, unsigned nImage, PVDINTERFACE pVDIfsOperation);
|
---|
[19034] | 885 |
|
---|
| 886 | /**
|
---|
[44408] | 887 | * Resizes the given disk image to the given size. It is OK if there are
|
---|
| 888 | * multiple images open in the container. In this case the last disk image
|
---|
| 889 | * will be resized.
|
---|
[31776] | 890 | *
|
---|
[32431] | 891 | * @return VBox status
|
---|
[31776] | 892 | * @return VERR_VD_IMAGE_READ_ONLY if image is not writable.
|
---|
[54624] | 893 | * @return VERR_NOT_SUPPORTED if this kind of image can't be compacted.
|
---|
[31776] | 894 | *
|
---|
| 895 | * @param pDisk Pointer to the HDD container.
|
---|
| 896 | * @param cbSize New size of the image.
|
---|
| 897 | * @param pPCHSGeometry Pointer to the new physical disk geometry <= (16383,16,63). Not NULL.
|
---|
| 898 | * @param pLCHSGeometry Pointer to the new logical disk geometry <= (x,255,63). Not NULL.
|
---|
| 899 | * @param pVDIfsOperation Pointer to the per-operation VD interface list.
|
---|
| 900 | */
|
---|
[66250] | 901 | VBOXDDU_DECL(int) VDResize(PVDISK pDisk, uint64_t cbSize,
|
---|
[34217] | 902 | PCVDGEOMETRY pPCHSGeometry,
|
---|
| 903 | PCVDGEOMETRY pLCHSGeometry,
|
---|
| 904 | PVDINTERFACE pVDIfsOperation);
|
---|
[31776] | 905 |
|
---|
| 906 | /**
|
---|
[54624] | 907 | * Prepares the given disk for use by the added filters. This applies to all
|
---|
| 908 | * opened images in the chain which might be opened read/write temporary.
|
---|
| 909 | *
|
---|
| 910 | * @return VBox status code.
|
---|
| 911 | *
|
---|
| 912 | * @param pDisk Pointer to the HDD container.
|
---|
| 913 | * @param pVDIfsOperation Pointer to the per-operation VD interface list.
|
---|
| 914 | */
|
---|
[66250] | 915 | VBOXDDU_DECL(int) VDPrepareWithFilters(PVDISK pDisk, PVDINTERFACE pVDIfsOperation);
|
---|
[54624] | 916 |
|
---|
| 917 | /**
|
---|
[6291] | 918 | * Closes the last opened image file in HDD container.
|
---|
[27232] | 919 | * If previous image file was opened in read-only mode (the normal case) and
|
---|
| 920 | * the last opened image is in read-write mode then the previous image will be
|
---|
| 921 | * reopened in read/write mode.
|
---|
[1] | 922 | *
|
---|
[11046] | 923 | * @return VBox status code.
|
---|
[15366] | 924 | * @return VERR_VD_NOT_OPENED if no image is opened in HDD container.
|
---|
[6291] | 925 | * @param pDisk Pointer to HDD container.
|
---|
[1942] | 926 | * @param fDelete If true, delete the image from the host disk.
|
---|
[1] | 927 | */
|
---|
[66250] | 928 | VBOXDDU_DECL(int) VDClose(PVDISK pDisk, bool fDelete);
|
---|
[1] | 929 |
|
---|
| 930 | /**
|
---|
[54340] | 931 | * Removes the last added filter in the HDD container from the specified chain.
|
---|
[50991] | 932 | *
|
---|
| 933 | * @return VBox status code.
|
---|
| 934 | * @retval VERR_VD_NOT_OPENED if no filter is present for the disk.
|
---|
| 935 | * @param pDisk Pointer to HDD container.
|
---|
[54340] | 936 | * @param fFlags Combination of VD_FILTER_FLAGS_* defines.
|
---|
[50991] | 937 | */
|
---|
[66250] | 938 | VBOXDDU_DECL(int) VDFilterRemove(PVDISK pDisk, uint32_t fFlags);
|
---|
[50991] | 939 |
|
---|
| 940 | /**
|
---|
[32370] | 941 | * Closes the currently opened cache image file in HDD container.
|
---|
| 942 | *
|
---|
| 943 | * @return VBox status code.
|
---|
| 944 | * @return VERR_VD_NOT_OPENED if no cache is opened in HDD container.
|
---|
| 945 | * @param pDisk Pointer to HDD container.
|
---|
| 946 | * @param fDelete If true, delete the image from the host disk.
|
---|
| 947 | */
|
---|
[66250] | 948 | VBOXDDU_DECL(int) VDCacheClose(PVDISK pDisk, bool fDelete);
|
---|
[32370] | 949 |
|
---|
| 950 | /**
|
---|
[1942] | 951 | * Closes all opened image files in HDD container.
|
---|
[1] | 952 | *
|
---|
[11046] | 953 | * @return VBox status code.
|
---|
[6291] | 954 | * @param pDisk Pointer to HDD container.
|
---|
[1] | 955 | */
|
---|
[66250] | 956 | VBOXDDU_DECL(int) VDCloseAll(PVDISK pDisk);
|
---|
[1] | 957 |
|
---|
| 958 | /**
|
---|
[50991] | 959 | * Removes all filters of the given HDD container.
|
---|
| 960 | *
|
---|
| 961 | * @return VBox status code.
|
---|
| 962 | * @param pDisk Pointer to HDD container.
|
---|
| 963 | */
|
---|
[66250] | 964 | VBOXDDU_DECL(int) VDFilterRemoveAll(PVDISK pDisk);
|
---|
[50991] | 965 |
|
---|
| 966 | /**
|
---|
[1942] | 967 | * Read data from virtual HDD.
|
---|
[1] | 968 | *
|
---|
[11046] | 969 | * @return VBox status code.
|
---|
[64272] | 970 | * @retval VERR_VD_NOT_OPENED if no image is opened in HDD container.
|
---|
[6291] | 971 | * @param pDisk Pointer to HDD container.
|
---|
[64272] | 972 | * @param uOffset Offset of first reading byte from start of disk.
|
---|
[13734] | 973 | * Must be aligned to a sector boundary.
|
---|
[64272] | 974 | * @param pvBuf Pointer to buffer for reading data.
|
---|
| 975 | * @param cbRead Number of bytes to read.
|
---|
[13734] | 976 | * Must be aligned to a sector boundary.
|
---|
[1] | 977 | */
|
---|
[66250] | 978 | VBOXDDU_DECL(int) VDRead(PVDISK pDisk, uint64_t uOffset, void *pvBuf, size_t cbRead);
|
---|
[1] | 979 |
|
---|
| 980 | /**
|
---|
[1942] | 981 | * Write data to virtual HDD.
|
---|
[1] | 982 | *
|
---|
[11046] | 983 | * @return VBox status code.
|
---|
[64272] | 984 | * @retval VERR_VD_NOT_OPENED if no image is opened in HDD container.
|
---|
[6291] | 985 | * @param pDisk Pointer to HDD container.
|
---|
[64272] | 986 | * @param uOffset Offset of first writing byte from start of disk.
|
---|
[13734] | 987 | * Must be aligned to a sector boundary.
|
---|
[64272] | 988 | * @param pvBuf Pointer to buffer for writing data.
|
---|
| 989 | * @param cbWrite Number of bytes to write.
|
---|
[13734] | 990 | * Must be aligned to a sector boundary.
|
---|
[1] | 991 | */
|
---|
[66250] | 992 | VBOXDDU_DECL(int) VDWrite(PVDISK pDisk, uint64_t uOffset, const void *pvBuf, size_t cbWrite);
|
---|
[1] | 993 |
|
---|
| 994 | /**
|
---|
[1949] | 995 | * Make sure the on disk representation of a virtual HDD is up to date.
|
---|
| 996 | *
|
---|
[11046] | 997 | * @return VBox status code.
|
---|
[64272] | 998 | * @retval VERR_VD_NOT_OPENED if no image is opened in HDD container.
|
---|
[6291] | 999 | * @param pDisk Pointer to HDD container.
|
---|
[1949] | 1000 | */
|
---|
[66250] | 1001 | VBOXDDU_DECL(int) VDFlush(PVDISK pDisk);
|
---|
[1949] | 1002 |
|
---|
| 1003 | /**
|
---|
[1942] | 1004 | * Get number of opened images in HDD container.
|
---|
[1] | 1005 | *
|
---|
[11046] | 1006 | * @return Number of opened images for HDD container. 0 if no images have been opened.
|
---|
[6291] | 1007 | * @param pDisk Pointer to HDD container.
|
---|
[1] | 1008 | */
|
---|
[66250] | 1009 | VBOXDDU_DECL(unsigned) VDGetCount(PVDISK pDisk);
|
---|
[1] | 1010 |
|
---|
| 1011 | /**
|
---|
[6291] | 1012 | * Get read/write mode of HDD container.
|
---|
[1] | 1013 | *
|
---|
[11046] | 1014 | * @return Virtual disk ReadOnly status.
|
---|
| 1015 | * @return true if no image is opened in HDD container.
|
---|
[6291] | 1016 | * @param pDisk Pointer to HDD container.
|
---|
[1] | 1017 | */
|
---|
[66250] | 1018 | VBOXDDU_DECL(bool) VDIsReadOnly(PVDISK pDisk);
|
---|
[1] | 1019 |
|
---|
| 1020 | /**
|
---|
[48743] | 1021 | * Get sector size of an image in HDD container.
|
---|
| 1022 | *
|
---|
| 1023 | * @return Virtual disk sector size in bytes.
|
---|
| 1024 | * @return 0 if image with specified number was not opened.
|
---|
| 1025 | * @param pDisk Pointer to HDD container.
|
---|
| 1026 | * @param nImage Image number, counts from 0. 0 is always base image of container.
|
---|
| 1027 | */
|
---|
[66250] | 1028 | VBOXDDU_DECL(uint32_t) VDGetSectorSize(PVDISK pDisk, unsigned nImage);
|
---|
[48743] | 1029 |
|
---|
| 1030 | /**
|
---|
[6291] | 1031 | * Get total capacity of an image in HDD container.
|
---|
[1] | 1032 | *
|
---|
[11046] | 1033 | * @return Virtual disk size in bytes.
|
---|
| 1034 | * @return 0 if image with specified number was not opened.
|
---|
[6291] | 1035 | * @param pDisk Pointer to HDD container.
|
---|
| 1036 | * @param nImage Image number, counts from 0. 0 is always base image of container.
|
---|
[1] | 1037 | */
|
---|
[66250] | 1038 | VBOXDDU_DECL(uint64_t) VDGetSize(PVDISK pDisk, unsigned nImage);
|
---|
[1] | 1039 |
|
---|
| 1040 | /**
|
---|
[6291] | 1041 | * Get total file size of an image in HDD container.
|
---|
[1] | 1042 | *
|
---|
[11046] | 1043 | * @return Virtual disk size in bytes.
|
---|
| 1044 | * @return 0 if image with specified number was not opened.
|
---|
[6291] | 1045 | * @param pDisk Pointer to HDD container.
|
---|
| 1046 | * @param nImage Image number, counts from 0. 0 is always base image of container.
|
---|
| 1047 | */
|
---|
[66250] | 1048 | VBOXDDU_DECL(uint64_t) VDGetFileSize(PVDISK pDisk, unsigned nImage);
|
---|
[6291] | 1049 |
|
---|
| 1050 | /**
|
---|
| 1051 | * Get virtual disk PCHS geometry of an image in HDD container.
|
---|
| 1052 | *
|
---|
[11046] | 1053 | * @return VBox status code.
|
---|
[15366] | 1054 | * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
|
---|
| 1055 | * @return VERR_VD_GEOMETRY_NOT_SET if no geometry present in the HDD container.
|
---|
[6291] | 1056 | * @param pDisk Pointer to HDD container.
|
---|
| 1057 | * @param nImage Image number, counts from 0. 0 is always base image of container.
|
---|
| 1058 | * @param pPCHSGeometry Where to store PCHS geometry. Not NULL.
|
---|
[1] | 1059 | */
|
---|
[66250] | 1060 | VBOXDDU_DECL(int) VDGetPCHSGeometry(PVDISK pDisk, unsigned nImage, PVDGEOMETRY pPCHSGeometry);
|
---|
[1] | 1061 |
|
---|
| 1062 | /**
|
---|
[6291] | 1063 | * Store virtual disk PCHS geometry of an image in HDD container.
|
---|
[1] | 1064 | *
|
---|
[11046] | 1065 | * @return VBox status code.
|
---|
[15366] | 1066 | * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
|
---|
[6291] | 1067 | * @param pDisk Pointer to HDD container.
|
---|
| 1068 | * @param nImage Image number, counts from 0. 0 is always base image of container.
|
---|
| 1069 | * @param pPCHSGeometry Where to load PCHS geometry from. Not NULL.
|
---|
[1] | 1070 | */
|
---|
[66250] | 1071 | VBOXDDU_DECL(int) VDSetPCHSGeometry(PVDISK pDisk, unsigned nImage, PCVDGEOMETRY pPCHSGeometry);
|
---|
[1] | 1072 |
|
---|
| 1073 | /**
|
---|
[6291] | 1074 | * Get virtual disk LCHS geometry of an image in HDD container.
|
---|
[1] | 1075 | *
|
---|
[11046] | 1076 | * @return VBox status code.
|
---|
[15366] | 1077 | * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
|
---|
| 1078 | * @return VERR_VD_GEOMETRY_NOT_SET if no geometry present in the HDD container.
|
---|
[6291] | 1079 | * @param pDisk Pointer to HDD container.
|
---|
| 1080 | * @param nImage Image number, counts from 0. 0 is always base image of container.
|
---|
| 1081 | * @param pLCHSGeometry Where to store LCHS geometry. Not NULL.
|
---|
[1] | 1082 | */
|
---|
[66250] | 1083 | VBOXDDU_DECL(int) VDGetLCHSGeometry(PVDISK pDisk, unsigned nImage, PVDGEOMETRY pLCHSGeometry);
|
---|
[1] | 1084 |
|
---|
| 1085 | /**
|
---|
[6291] | 1086 | * Store virtual disk LCHS geometry of an image in HDD container.
|
---|
[1] | 1087 | *
|
---|
[11046] | 1088 | * @return VBox status code.
|
---|
[15366] | 1089 | * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
|
---|
[6291] | 1090 | * @param pDisk Pointer to HDD container.
|
---|
| 1091 | * @param nImage Image number, counts from 0. 0 is always base image of container.
|
---|
| 1092 | * @param pLCHSGeometry Where to load LCHS geometry from. Not NULL.
|
---|
[1] | 1093 | */
|
---|
[66250] | 1094 | VBOXDDU_DECL(int) VDSetLCHSGeometry(PVDISK pDisk, unsigned nImage, PCVDGEOMETRY pLCHSGeometry);
|
---|
[1] | 1095 |
|
---|
| 1096 | /**
|
---|
[66110] | 1097 | * Queries the available regions of an image in the given VD container.
|
---|
| 1098 | *
|
---|
| 1099 | * @return VBox status code.
|
---|
| 1100 | * @retval VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
|
---|
| 1101 | * @retval VERR_NOT_SUPPORTED if the image backend doesn't support region lists.
|
---|
| 1102 | * @param pDisk Pointer to HDD container.
|
---|
| 1103 | * @param nImage Image number, counts from 0. 0 is always base image of container.
|
---|
| 1104 | * @param fFlags Combination of VD_REGION_LIST_F_* flags.
|
---|
| 1105 | * @param ppRegionList Where to store the pointer to the region list on success, must be freed
|
---|
| 1106 | * with VDRegionListFree().
|
---|
| 1107 | */
|
---|
[66250] | 1108 | VBOXDDU_DECL(int) VDQueryRegions(PVDISK pDisk, unsigned nImage, uint32_t fFlags,
|
---|
[66110] | 1109 | PPVDREGIONLIST ppRegionList);
|
---|
| 1110 |
|
---|
| 1111 | /**
|
---|
| 1112 | * Frees a region list previously queried with VDQueryRegions().
|
---|
| 1113 | *
|
---|
| 1114 | * @return nothing.
|
---|
| 1115 | * @param pRegionList The region list to free.
|
---|
| 1116 | */
|
---|
| 1117 | VBOXDDU_DECL(void) VDRegionListFree(PVDREGIONLIST pRegionList);
|
---|
| 1118 |
|
---|
| 1119 | /**
|
---|
[2118] | 1120 | * Get version of image in HDD container.
|
---|
[1] | 1121 | *
|
---|
[11046] | 1122 | * @return VBox status code.
|
---|
[15366] | 1123 | * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
|
---|
[6291] | 1124 | * @param pDisk Pointer to HDD container.
|
---|
[1] | 1125 | * @param nImage Image number, counts from 0. 0 is always base image of container.
|
---|
| 1126 | * @param puVersion Where to store the image version.
|
---|
| 1127 | */
|
---|
[66250] | 1128 | VBOXDDU_DECL(int) VDGetVersion(PVDISK pDisk, unsigned nImage, unsigned *puVersion);
|
---|
[1] | 1129 |
|
---|
| 1130 | /**
|
---|
[10715] | 1131 | * List the capabilities of image backend in HDD container.
|
---|
| 1132 | *
|
---|
[11046] | 1133 | * @return VBox status code.
|
---|
[15366] | 1134 | * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
|
---|
[10715] | 1135 | * @param pDisk Pointer to the HDD container.
|
---|
| 1136 | * @param nImage Image number, counts from 0. 0 is always base image of container.
|
---|
[58106] | 1137 | * @param pBackendInfo Where to store the backend information.
|
---|
[10715] | 1138 | */
|
---|
[66250] | 1139 | VBOXDDU_DECL(int) VDBackendInfoSingle(PVDISK pDisk, unsigned nImage, PVDBACKENDINFO pBackendInfo);
|
---|
[10715] | 1140 |
|
---|
| 1141 | /**
|
---|
[2118] | 1142 | * Get flags of image in HDD container.
|
---|
[1] | 1143 | *
|
---|
[11046] | 1144 | * @return VBox status code.
|
---|
[15366] | 1145 | * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
|
---|
[6291] | 1146 | * @param pDisk Pointer to HDD container.
|
---|
[1] | 1147 | * @param nImage Image number, counts from 0. 0 is always base image of container.
|
---|
[1942] | 1148 | * @param puImageFlags Where to store the image flags.
|
---|
[1] | 1149 | */
|
---|
[66250] | 1150 | VBOXDDU_DECL(int) VDGetImageFlags(PVDISK pDisk, unsigned nImage, unsigned *puImageFlags);
|
---|
[1] | 1151 |
|
---|
| 1152 | /**
|
---|
[6291] | 1153 | * Get open flags of image in HDD container.
|
---|
[1949] | 1154 | *
|
---|
[11046] | 1155 | * @return VBox status code.
|
---|
[15366] | 1156 | * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
|
---|
[6291] | 1157 | * @param pDisk Pointer to HDD container.
|
---|
| 1158 | * @param nImage Image number, counts from 0. 0 is always base image of container.
|
---|
[1949] | 1159 | * @param puOpenFlags Where to store the image open flags.
|
---|
| 1160 | */
|
---|
[66250] | 1161 | VBOXDDU_DECL(int) VDGetOpenFlags(PVDISK pDisk, unsigned nImage, unsigned *puOpenFlags);
|
---|
[1949] | 1162 |
|
---|
| 1163 | /**
|
---|
[6291] | 1164 | * Set open flags of image in HDD container.
|
---|
[1949] | 1165 | * This operation may cause file locking changes and/or files being reopened.
|
---|
| 1166 | * Note that in case of unrecoverable error all images in HDD container will be closed.
|
---|
| 1167 | *
|
---|
[11046] | 1168 | * @return VBox status code.
|
---|
[15366] | 1169 | * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
|
---|
[6291] | 1170 | * @param pDisk Pointer to HDD container.
|
---|
| 1171 | * @param nImage Image number, counts from 0. 0 is always base image of container.
|
---|
[2118] | 1172 | * @param uOpenFlags Image file open mode, see VD_OPEN_FLAGS_* constants.
|
---|
[1949] | 1173 | */
|
---|
[66250] | 1174 | VBOXDDU_DECL(int) VDSetOpenFlags(PVDISK pDisk, unsigned nImage, unsigned uOpenFlags);
|
---|
[1949] | 1175 |
|
---|
| 1176 | /**
|
---|
[2118] | 1177 | * Get base filename of image in HDD container. Some image formats use
|
---|
[6291] | 1178 | * other filenames as well, so don't use this for anything but informational
|
---|
[1942] | 1179 | * purposes.
|
---|
[1] | 1180 | *
|
---|
[11046] | 1181 | * @return VBox status code.
|
---|
[15366] | 1182 | * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
|
---|
[11046] | 1183 | * @return VERR_BUFFER_OVERFLOW if pszFilename buffer too small to hold filename.
|
---|
[6291] | 1184 | * @param pDisk Pointer to HDD container.
|
---|
[1] | 1185 | * @param nImage Image number, counts from 0. 0 is always base image of container.
|
---|
| 1186 | * @param pszFilename Where to store the image file name.
|
---|
| 1187 | * @param cbFilename Size of buffer pszFilename points to.
|
---|
| 1188 | */
|
---|
[66250] | 1189 | VBOXDDU_DECL(int) VDGetFilename(PVDISK pDisk, unsigned nImage, char *pszFilename, unsigned cbFilename);
|
---|
[1] | 1190 |
|
---|
| 1191 | /**
|
---|
[2118] | 1192 | * Get the comment line of image in HDD container.
|
---|
[1] | 1193 | *
|
---|
[11046] | 1194 | * @return VBox status code.
|
---|
[15366] | 1195 | * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
|
---|
[11046] | 1196 | * @return VERR_BUFFER_OVERFLOW if pszComment buffer too small to hold comment text.
|
---|
[6291] | 1197 | * @param pDisk Pointer to HDD container.
|
---|
[1] | 1198 | * @param nImage Image number, counts from 0. 0 is always base image of container.
|
---|
| 1199 | * @param pszComment Where to store the comment string of image. NULL is ok.
|
---|
| 1200 | * @param cbComment The size of pszComment buffer. 0 is ok.
|
---|
| 1201 | */
|
---|
[66250] | 1202 | VBOXDDU_DECL(int) VDGetComment(PVDISK pDisk, unsigned nImage, char *pszComment, unsigned cbComment);
|
---|
[1] | 1203 |
|
---|
| 1204 | /**
|
---|
[2118] | 1205 | * Changes the comment line of image in HDD container.
|
---|
[1] | 1206 | *
|
---|
[11046] | 1207 | * @return VBox status code.
|
---|
[15366] | 1208 | * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
|
---|
[6291] | 1209 | * @param pDisk Pointer to HDD container.
|
---|
[1] | 1210 | * @param nImage Image number, counts from 0. 0 is always base image of container.
|
---|
[1942] | 1211 | * @param pszComment New comment string (UTF-8). NULL is allowed to reset the comment.
|
---|
| 1212 | */
|
---|
[66250] | 1213 | VBOXDDU_DECL(int) VDSetComment(PVDISK pDisk, unsigned nImage, const char *pszComment);
|
---|
[1942] | 1214 |
|
---|
| 1215 | /**
|
---|
[2118] | 1216 | * Get UUID of image in HDD container.
|
---|
[1942] | 1217 | *
|
---|
[11046] | 1218 | * @return VBox status code.
|
---|
[15366] | 1219 | * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
|
---|
[6291] | 1220 | * @param pDisk Pointer to HDD container.
|
---|
[1942] | 1221 | * @param nImage Image number, counts from 0. 0 is always base image of container.
|
---|
[2358] | 1222 | * @param pUuid Where to store the image UUID.
|
---|
[1] | 1223 | */
|
---|
[66250] | 1224 | VBOXDDU_DECL(int) VDGetUuid(PVDISK pDisk, unsigned nImage, PRTUUID pUuid);
|
---|
[1] | 1225 |
|
---|
| 1226 | /**
|
---|
[2118] | 1227 | * Set the image's UUID. Should not be used by normal applications.
|
---|
[1] | 1228 | *
|
---|
[11046] | 1229 | * @return VBox status code.
|
---|
[15366] | 1230 | * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
|
---|
[6291] | 1231 | * @param pDisk Pointer to HDD container.
|
---|
[1] | 1232 | * @param nImage Image number, counts from 0. 0 is always base image of container.
|
---|
[6291] | 1233 | * @param pUuid New UUID of the image. If NULL, a new UUID is created.
|
---|
[1942] | 1234 | */
|
---|
[66250] | 1235 | VBOXDDU_DECL(int) VDSetUuid(PVDISK pDisk, unsigned nImage, PCRTUUID pUuid);
|
---|
[1942] | 1236 |
|
---|
| 1237 | /**
|
---|
[2118] | 1238 | * Get last modification UUID of image in HDD container.
|
---|
[1942] | 1239 | *
|
---|
[11046] | 1240 | * @return VBox status code.
|
---|
[15366] | 1241 | * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
|
---|
[6291] | 1242 | * @param pDisk Pointer to HDD container.
|
---|
[1942] | 1243 | * @param nImage Image number, counts from 0. 0 is always base image of container.
|
---|
[2358] | 1244 | * @param pUuid Where to store the image modification UUID.
|
---|
[1] | 1245 | */
|
---|
[66250] | 1246 | VBOXDDU_DECL(int) VDGetModificationUuid(PVDISK pDisk, unsigned nImage, PRTUUID pUuid);
|
---|
[1] | 1247 |
|
---|
| 1248 | /**
|
---|
[2118] | 1249 | * Set the image's last modification UUID. Should not be used by normal applications.
|
---|
[1] | 1250 | *
|
---|
[11046] | 1251 | * @return VBox status code.
|
---|
[15366] | 1252 | * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
|
---|
[6291] | 1253 | * @param pDisk Pointer to HDD container.
|
---|
[1942] | 1254 | * @param nImage Image number, counts from 0. 0 is always base image of container.
|
---|
[6291] | 1255 | * @param pUuid New modification UUID of the image. If NULL, a new UUID is created.
|
---|
[1] | 1256 | */
|
---|
[66250] | 1257 | VBOXDDU_DECL(int) VDSetModificationUuid(PVDISK pDisk, unsigned nImage, PCRTUUID pUuid);
|
---|
[1] | 1258 |
|
---|
| 1259 | /**
|
---|
[2118] | 1260 | * Get parent UUID of image in HDD container.
|
---|
[1] | 1261 | *
|
---|
[11046] | 1262 | * @return VBox status code.
|
---|
[15366] | 1263 | * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
|
---|
[6291] | 1264 | * @param pDisk Pointer to HDD container.
|
---|
[1942] | 1265 | * @param nImage Image number, counts from 0. 0 is always base image of the container.
|
---|
[2358] | 1266 | * @param pUuid Where to store the parent image UUID.
|
---|
[1] | 1267 | */
|
---|
[66250] | 1268 | VBOXDDU_DECL(int) VDGetParentUuid(PVDISK pDisk, unsigned nImage, PRTUUID pUuid);
|
---|
[1] | 1269 |
|
---|
| 1270 | /**
|
---|
[1942] | 1271 | * Set the image's parent UUID. Should not be used by normal applications.
|
---|
[1] | 1272 | *
|
---|
[11046] | 1273 | * @return VBox status code.
|
---|
[6291] | 1274 | * @param pDisk Pointer to HDD container.
|
---|
[1942] | 1275 | * @param nImage Image number, counts from 0. 0 is always base image of container.
|
---|
[6291] | 1276 | * @param pUuid New parent UUID of the image. If NULL, a new UUID is created.
|
---|
[1] | 1277 | */
|
---|
[66250] | 1278 | VBOXDDU_DECL(int) VDSetParentUuid(PVDISK pDisk, unsigned nImage, PCRTUUID pUuid);
|
---|
[1] | 1279 |
|
---|
| 1280 |
|
---|
| 1281 | /**
|
---|
[1942] | 1282 | * Debug helper - dumps all opened images in HDD container into the log file.
|
---|
[1] | 1283 | *
|
---|
[6291] | 1284 | * @param pDisk Pointer to HDD container.
|
---|
[1] | 1285 | */
|
---|
[66250] | 1286 | VBOXDDU_DECL(void) VDDumpImages(PVDISK pDisk);
|
---|
[1] | 1287 |
|
---|
[10715] | 1288 |
|
---|
| 1289 | /**
|
---|
[38621] | 1290 | * Discards unused ranges given as a list.
|
---|
| 1291 | *
|
---|
| 1292 | * @return VBox status code.
|
---|
| 1293 | * @param pDisk Pointer to HDD container.
|
---|
| 1294 | * @param paRanges The array of ranges to discard.
|
---|
| 1295 | * @param cRanges Number of entries in the array.
|
---|
| 1296 | *
|
---|
| 1297 | * @note In contrast to VDCompact() the ranges are always discarded even if they
|
---|
| 1298 | * appear to contain data. This method is mainly used to implement TRIM support.
|
---|
| 1299 | */
|
---|
[66250] | 1300 | VBOXDDU_DECL(int) VDDiscardRanges(PVDISK pDisk, PCRTRANGE paRanges, unsigned cRanges);
|
---|
[38621] | 1301 |
|
---|
| 1302 |
|
---|
| 1303 | /**
|
---|
[36573] | 1304 | * Start an asynchronous read request.
|
---|
[10715] | 1305 | *
|
---|
[11046] | 1306 | * @return VBox status code.
|
---|
[10715] | 1307 | * @param pDisk Pointer to the HDD container.
|
---|
[58106] | 1308 | * @param off The offset of the virtual disk to read from.
|
---|
[10715] | 1309 | * @param cbRead How many bytes to read.
|
---|
[34217] | 1310 | * @param pcSgBuf Pointer to the S/G buffer to read into.
|
---|
[27808] | 1311 | * @param pfnComplete Completion callback.
|
---|
[58106] | 1312 | * @param pvUser1 User data which is passed on completion.
|
---|
| 1313 | * @param pvUser2 User data which is passed on completion.
|
---|
[10715] | 1314 | */
|
---|
[66250] | 1315 | VBOXDDU_DECL(int) VDAsyncRead(PVDISK pDisk, uint64_t off, size_t cbRead,
|
---|
[34217] | 1316 | PCRTSGBUF pcSgBuf,
|
---|
| 1317 | PFNVDASYNCTRANSFERCOMPLETE pfnComplete,
|
---|
| 1318 | void *pvUser1, void *pvUser2);
|
---|
[10715] | 1319 |
|
---|
| 1320 |
|
---|
| 1321 | /**
|
---|
[36573] | 1322 | * Start an asynchronous write request.
|
---|
[10715] | 1323 | *
|
---|
[11046] | 1324 | * @return VBox status code.
|
---|
[10715] | 1325 | * @param pDisk Pointer to the HDD container.
|
---|
[58106] | 1326 | * @param off The offset of the virtual disk to write to.
|
---|
| 1327 | * @param cbWrite How many bytes to write.
|
---|
[34217] | 1328 | * @param pcSgBuf Pointer to the S/G buffer to write from.
|
---|
[27808] | 1329 | * @param pfnComplete Completion callback.
|
---|
[58106] | 1330 | * @param pvUser1 User data which is passed on completion.
|
---|
| 1331 | * @param pvUser2 User data which is passed on completion.
|
---|
[10715] | 1332 | */
|
---|
[66250] | 1333 | VBOXDDU_DECL(int) VDAsyncWrite(PVDISK pDisk, uint64_t off, size_t cbWrite,
|
---|
[34217] | 1334 | PCRTSGBUF pcSgBuf,
|
---|
| 1335 | PFNVDASYNCTRANSFERCOMPLETE pfnComplete,
|
---|
| 1336 | void *pvUser1, void *pvUser2);
|
---|
[10715] | 1337 |
|
---|
| 1338 |
|
---|
[28383] | 1339 | /**
|
---|
[36573] | 1340 | * Start an asynchronous flush request.
|
---|
[28383] | 1341 | *
|
---|
| 1342 | * @return VBox status code.
|
---|
| 1343 | * @param pDisk Pointer to the HDD container.
|
---|
| 1344 | * @param pfnComplete Completion callback.
|
---|
[58106] | 1345 | * @param pvUser1 User data which is passed on completion.
|
---|
| 1346 | * @param pvUser2 User data which is passed on completion.
|
---|
[28383] | 1347 | */
|
---|
[66250] | 1348 | VBOXDDU_DECL(int) VDAsyncFlush(PVDISK pDisk,
|
---|
[34217] | 1349 | PFNVDASYNCTRANSFERCOMPLETE pfnComplete,
|
---|
| 1350 | void *pvUser1, void *pvUser2);
|
---|
[38876] | 1351 |
|
---|
| 1352 | /**
|
---|
| 1353 | * Start an asynchronous discard request.
|
---|
| 1354 | *
|
---|
| 1355 | * @return VBox status code.
|
---|
| 1356 | * @param pDisk Pointer to HDD container.
|
---|
| 1357 | * @param paRanges The array of ranges to discard.
|
---|
| 1358 | * @param cRanges Number of entries in the array.
|
---|
| 1359 | * @param pfnComplete Completion callback.
|
---|
| 1360 | * @param pvUser1 User data which is passed on completion.
|
---|
| 1361 | * @param pvUser2 User data which is passed on completion.
|
---|
| 1362 | */
|
---|
[66250] | 1363 | VBOXDDU_DECL(int) VDAsyncDiscardRanges(PVDISK pDisk, PCRTRANGE paRanges, unsigned cRanges,
|
---|
[38876] | 1364 | PFNVDASYNCTRANSFERCOMPLETE pfnComplete,
|
---|
[58106] | 1365 | void *pvUser1, void *pvUser2);
|
---|
[38876] | 1366 |
|
---|
[39519] | 1367 | /**
|
---|
| 1368 | * Tries to repair a corrupted image.
|
---|
| 1369 | *
|
---|
| 1370 | * @return VBox status code.
|
---|
| 1371 | * @retval VERR_VD_IMAGE_REPAIR_NOT_SUPPORTED if the backend does not support repairing the image.
|
---|
| 1372 | * @retval VERR_VD_IMAGE_REPAIR_IMPOSSIBLE if the corruption is to severe to repair the image.
|
---|
| 1373 | * @param pVDIfsDisk Pointer to the per-disk VD interface list.
|
---|
| 1374 | * @param pVDIfsImage Pointer to the per-image VD interface list.
|
---|
| 1375 | * @param pszFilename Name of the image file to repair.
|
---|
[58106] | 1376 | * @param pszBackend The backend to use.
|
---|
[39519] | 1377 | * @param fFlags Combination of the VD_REPAIR_* flags.
|
---|
| 1378 | */
|
---|
| 1379 | VBOXDDU_DECL(int) VDRepair(PVDINTERFACE pVDIfsDisk, PVDINTERFACE pVDIfsImage,
|
---|
[58106] | 1380 | const char *pszFilename, const char *pszBackend, uint32_t fFlags);
|
---|
[39519] | 1381 |
|
---|
[41576] | 1382 | /**
|
---|
| 1383 | * Create a VFS file handle from the given HDD container.
|
---|
| 1384 | *
|
---|
| 1385 | * @return VBox status code.
|
---|
| 1386 | * @param pDisk Pointer to HDD container.
|
---|
| 1387 | * @param fFlags Combination of the VD_VFSFILE_* flags.
|
---|
[47345] | 1388 | * @param phVfsFile Where to store the handle to the VFS file on
|
---|
| 1389 | * success.
|
---|
[41576] | 1390 | */
|
---|
[66250] | 1391 | VBOXDDU_DECL(int) VDCreateVfsFileFromDisk(PVDISK pDisk, uint32_t fFlags,
|
---|
[41576] | 1392 | PRTVFSFILE phVfsFile);
|
---|
| 1393 |
|
---|
[66346] | 1394 | /** @defgroup grp_vd_ioiter I/O iterator
|
---|
| 1395 | * @{
|
---|
| 1396 | */
|
---|
| 1397 |
|
---|
| 1398 | /** Read metadata coming before each main data block addressed in the segment. */
|
---|
| 1399 | #define VD_IOITER_SEG_F_PRE_METADATA RT_BIT_32(0)
|
---|
| 1400 | /** Read the main user data of each addressed block in the segment. */
|
---|
| 1401 | #define VD_IOITER_SEG_F_MAIN_DATA RT_BIT_32(1)
|
---|
| 1402 | /** Read metadata coming after each main data block addressed in the segment. */
|
---|
| 1403 | #define VD_IOITER_SEG_F_POST_METADATA RT_BIT_32(2)
|
---|
| 1404 | /** Read checksum data of each data block addressed in the segment. */
|
---|
| 1405 | #define VD_IOITER_SEG_F_CHKSUM RT_BIT_32(3)
|
---|
| 1406 | /** Read all available data for each addressed block in the segment. */
|
---|
| 1407 | #define VD_IOITER_SEG_F_AVAILABLE RT_BIT_32(4)
|
---|
| 1408 |
|
---|
| 1409 | /** The offset and size members in the segments use byte granularity instead of a
|
---|
| 1410 | * block address and number of blocks respectively. */
|
---|
| 1411 | #define VDIOITER_F_BYTE_OFFSET_AND_SIZE RT_BIT_32(0)
|
---|
| 1412 |
|
---|
| 1413 | /**
|
---|
| 1414 | * VD I/O iterator segment.
|
---|
| 1415 | */
|
---|
| 1416 | typedef struct VDIOITERSEG
|
---|
| 1417 | {
|
---|
| 1418 | /** Start offset for this segment. */
|
---|
| 1419 | uint64_t offStartSeg;
|
---|
| 1420 | /** Size of the segment (bytes or blocks). */
|
---|
| 1421 | uint64_t cSizeSeg;
|
---|
| 1422 | /** Flags for this segment, see VD_IOITER_SEG_F_*. */
|
---|
| 1423 | uint32_t fFlags;
|
---|
| 1424 | } VDIOITERSEG;
|
---|
| 1425 | /** Pointer to a I/O iterator segment. */
|
---|
| 1426 | typedef VDIOITERSEG *PVDIOITERSEG;
|
---|
| 1427 | /** Pointer to a constant I/O iterator segment. */
|
---|
| 1428 | typedef VDIOITERSEG *PCVDIOITERSEG;
|
---|
| 1429 |
|
---|
| 1430 | /** I/O iterator handle. */
|
---|
| 1431 | typedef struct VDIOITERINT *VDIOITER;
|
---|
| 1432 | /** Pointer to a I/O iterator handle. */
|
---|
| 1433 | typedef VDIOITER *PVDIOITER;
|
---|
| 1434 |
|
---|
| 1435 | /**
|
---|
| 1436 | * Create a new I/O iterator.
|
---|
| 1437 | *
|
---|
| 1438 | * @returns VBox status code.
|
---|
| 1439 | * @param pDisk The disk to create the iterator for.
|
---|
| 1440 | * @param phVdIoIter Where to store the handle to the I/O iterator on success.
|
---|
| 1441 | * @param paIoIterSegs The segments for the iterator, can be destroyed after the call.
|
---|
| 1442 | * @param cIoIterSegs Number of segments.
|
---|
| 1443 | * @param fFlags Flags for the iterator, see VDIOITER_F_*
|
---|
| 1444 | */
|
---|
| 1445 | VBOXDDU_DECL(int) VDIoIterCreate(PVDISK pDisk, PVDIOITER phVdIoIter, PCVDIOITERSEG paIoIterSegs,
|
---|
| 1446 | uint32_t cIoIterSegs, uint32_t fFlags);
|
---|
| 1447 |
|
---|
| 1448 | /**
|
---|
| 1449 | * Retains the reference count of the given I/O iterator.
|
---|
| 1450 | *
|
---|
| 1451 | * @returns New reference count.
|
---|
| 1452 | * @param hVdIoIter The I/O iterator handle.
|
---|
| 1453 | */
|
---|
| 1454 | VBOXDDU_DECL(uint32_t) VDIoIterRetain(VDIOITER hVdIoIter);
|
---|
| 1455 |
|
---|
| 1456 | /**
|
---|
| 1457 | * Releases the reference count of the given I/O iterator.
|
---|
| 1458 | *
|
---|
| 1459 | * @returns New reference count, on 0 the iterator is destroyed.
|
---|
| 1460 | * @param hVdIoIter The I/O iterator handle.
|
---|
| 1461 | */
|
---|
| 1462 | VBOXDDU_DECL(uint32_t) VDIoIterRelease(VDIOITER hVdIoIter);
|
---|
| 1463 |
|
---|
| 1464 | /**
|
---|
| 1465 | * Returns the number of segments in the given I/O iterator.
|
---|
| 1466 | *
|
---|
| 1467 | * @returns Number of segments.
|
---|
| 1468 | * @param hVdIoIter The I/O iterator handle.
|
---|
| 1469 | */
|
---|
| 1470 | VBOXDDU_DECL(uint32_t) VDIoIterGetSegmentCount(VDIOITER hVdIoIter);
|
---|
| 1471 |
|
---|
| 1472 | /**
|
---|
| 1473 | * Returns the flags of the given I/O iterator.
|
---|
| 1474 | *
|
---|
| 1475 | * @returns Flags.
|
---|
| 1476 | * @param hVdIoIter The I/O iterator handle.
|
---|
| 1477 | */
|
---|
| 1478 | VBOXDDU_DECL(uint32_t) VDIoIterGetFlags(VDIOITER hVdIoIter);
|
---|
| 1479 |
|
---|
| 1480 | /**
|
---|
| 1481 | * Queries the properties of the given segment for the given I/O iterator.
|
---|
| 1482 | *
|
---|
| 1483 | * @returns VBox status code.
|
---|
| 1484 | * @param hVdIoIter The I/O iterator handle.
|
---|
| 1485 | * @param idx The segment index to query.
|
---|
| 1486 | * @param pSegment Where to store the segment properties on success.
|
---|
| 1487 | */
|
---|
| 1488 | VBOXDDU_DECL(int) VDIoIterQuerySegment(VDIOITER hVdIoIter, uint32_t idx, PVDIOITERSEG pSegment);
|
---|
| 1489 |
|
---|
| 1490 | /** @} */
|
---|
| 1491 |
|
---|
| 1492 |
|
---|
| 1493 | /** @defgroup grp_vd_io_buf I/O buffer management API.
|
---|
| 1494 | * @{
|
---|
| 1495 | */
|
---|
| 1496 |
|
---|
| 1497 | /** VD I/O buffer manager handle. */
|
---|
| 1498 | typedef struct VDIOBUFMGRINT *VDIOBUFMGR;
|
---|
| 1499 | /** Pointer to VD I/O buffer manager handle. */
|
---|
| 1500 | typedef VDIOBUFMGR *PVDIOBUFMGR;
|
---|
| 1501 |
|
---|
| 1502 | /** VD I/O buffer handle. */
|
---|
| 1503 | typedef struct VDIOBUFINT *VDIOBUF;
|
---|
| 1504 | /** Pointer to a VD I/O buffer handle. */
|
---|
| 1505 | typedef VDIOBUF *PVDIOBUF;
|
---|
| 1506 |
|
---|
| 1507 | /** Default I/O buffer manager flags. */
|
---|
| 1508 | #define VD_IOBUFMGR_F_DEFAULT (0)
|
---|
| 1509 | /** I/O buffer memory needs to be non pageable (for example because it contains sensitive data
|
---|
| 1510 | * which shouldn't end up in swap unencrypted). */
|
---|
| 1511 | #define VD_IOBUFMGR_F_REQUIRE_NOT_PAGABLE RT_BIT(0)
|
---|
| 1512 |
|
---|
| 1513 | /** Pointer to VD I/O buffer callbacks. */
|
---|
| 1514 | typedef struct VDIOBUFCALLBACKS *PVDIOBUFCALLBACKS;
|
---|
| 1515 | /** Pointer to const VD I/O buffer callbacks. */
|
---|
[68670] | 1516 | typedef const struct VDIOBUFCALLBACKS *PCVDIOBUFCALLBACKS;
|
---|
[66346] | 1517 |
|
---|
| 1518 | /**
|
---|
| 1519 | * VD I/O buffer callbacks.
|
---|
| 1520 | */
|
---|
| 1521 | typedef struct VDIOBUFCALLBACKS
|
---|
| 1522 | {
|
---|
| 1523 | /**
|
---|
| 1524 | * Copy data from the memory buffer of the caller to the callees memory buffer for the given request.
|
---|
| 1525 | *
|
---|
| 1526 | * @returns VBox status code.
|
---|
| 1527 | * @retval VERR_PDM_MEDIAEX_IOBUF_OVERFLOW if there is not enough room to store the data.
|
---|
| 1528 | * @param pInterface Pointer to the interface structure containing the called function pointer.
|
---|
| 1529 | * @param hIoBuf The I/O request handle.
|
---|
| 1530 | * @param pvIoBufAlloc The allocator specific memory for this request.
|
---|
| 1531 | * @param offDst The destination offset from the start to write the data to.
|
---|
| 1532 | * @param pSgBuf The S/G buffer to read the data from.
|
---|
| 1533 | * @param cbCopy How many bytes to copy.
|
---|
| 1534 | */
|
---|
| 1535 | DECLR3CALLBACKMEMBER(int, pfnIoBufCopyFromBuf, (PVDIOBUFCALLBACKS pInterface, VDIOBUF hIoBuf,
|
---|
| 1536 | void *pvIoBufAlloc, uint32_t offDst, PRTSGBUF pSgBuf,
|
---|
| 1537 | size_t cbCopy));
|
---|
| 1538 |
|
---|
| 1539 | /**
|
---|
| 1540 | * Copy data to the memory buffer of the caller from the callees memory buffer for the given request.
|
---|
| 1541 | *
|
---|
| 1542 | * @returns VBox status code.
|
---|
| 1543 | * @retval VERR_PDM_MEDIAEX_IOBUF_UNDERRUN if there is not enough data to copy from the buffer.
|
---|
| 1544 | * @param pInterface Pointer to the interface structure containing the called function pointer.
|
---|
| 1545 | * @param hIoBuf The I/O request handle.
|
---|
| 1546 | * @param pvIoBufAlloc The allocator specific memory for this request.
|
---|
| 1547 | * @param offSrc The offset from the start of the buffer to read the data from.
|
---|
| 1548 | * @param pSgBuf The S/G buffer to write the data to.
|
---|
| 1549 | * @param cbCopy How many bytes to copy.
|
---|
| 1550 | */
|
---|
| 1551 | DECLR3CALLBACKMEMBER(int, pfnIoBufCopyToBuf, (PVDIOBUFCALLBACKS pInterface, VDIOBUF hIoBuf,
|
---|
| 1552 | void *pvIoBufAlloc, uint32_t offSrc, PRTSGBUF pSgBuf,
|
---|
| 1553 | size_t cbCopy));
|
---|
| 1554 |
|
---|
| 1555 | /**
|
---|
| 1556 | * Queries a pointer to the memory buffer for the request from the drive/device above.
|
---|
| 1557 | *
|
---|
| 1558 | * @returns VBox status code.
|
---|
| 1559 | * @retval VERR_NOT_SUPPORTED if this is not supported for this request.
|
---|
| 1560 | * @param pInterface Pointer to the interface structure containing the called function pointer.
|
---|
| 1561 | * @param hIoBuf The I/O request handle.
|
---|
| 1562 | * @param pvIoBufAlloc The allocator specific memory for this request.
|
---|
| 1563 | * @param offBuf The offset from the start of the buffer to get the buffer address.
|
---|
| 1564 | * @param cbBuf The number of bytes requested.
|
---|
| 1565 | * @param ppvBuf Where to store the pointer to the guest buffer on success.
|
---|
| 1566 | * @param pcbBuf Where to store the size of the buffer on success.
|
---|
| 1567 | *
|
---|
| 1568 | * @note This is an optional feature of the entity implementing this interface to avoid overhead
|
---|
| 1569 | * by copying the data between buffers. If NULL it is not supported at all and the caller
|
---|
| 1570 | * has to resort to VDIOBUFCALLBACKS::pfnIoBufCopyToBuf and VDIOBUFCALLBACKS::pfnIoBufCopyFromBuf.
|
---|
| 1571 | * The same holds when VERR_NOT_SUPPORTED is returned.
|
---|
| 1572 | *
|
---|
| 1573 | * On the upside the caller of this interface might not call this method at all and just
|
---|
| 1574 | * use the before mentioned methods to copy the data between the buffers.
|
---|
| 1575 | */
|
---|
| 1576 | DECLR3CALLBACKMEMBER(int, pfnIoBufQueryBuf, (PVDIOBUFCALLBACKS pInterface, VDIOBUF hIoBuf,
|
---|
| 1577 | void *pvIoBufAlloc, uint32_t offBuf, size_t cbBuf,
|
---|
| 1578 | void **ppvBuf, size_t *pcbBuf));
|
---|
| 1579 |
|
---|
| 1580 | } VDIOBUFCALLBACKS;
|
---|
| 1581 |
|
---|
| 1582 | /**
|
---|
| 1583 | * Creates a new I/O buffer manager.
|
---|
| 1584 | *
|
---|
| 1585 | * @returns VBox status code.
|
---|
| 1586 | * @param phIoBufMgr Where to store the handle to the I/O buffer manager on success.
|
---|
| 1587 | * @param cbMax The maximum amount of I/O memory to allow. Trying to allocate more than
|
---|
| 1588 | * this will lead to out of memory errors. 0 for "unlimited" size (only restriction
|
---|
| 1589 | * is the available memory on the host).
|
---|
| 1590 | * @param fFlags Combination of VD_IOBUFMGR_F_*.
|
---|
| 1591 | * @param pIoBufClbks Memory copy callbacks between source and target memory regions, optional.
|
---|
| 1592 | * When NULL all I/O buffers must be allocated with a valid S/G buffer laying out the
|
---|
| 1593 | * memory.
|
---|
| 1594 | * @param cbIoBufAlloc How much to allocate extra in the I/O buffer for private use.
|
---|
| 1595 | */
|
---|
| 1596 | VBOXDDU_DECL(int) VDIoBufMgrCreate(PVDIOBUFMGR phIoBufMgr, size_t cbMax, uint32_t fFlags,
|
---|
| 1597 | PVDIOBUFCALLBACKS pIoBufClbks, size_t cbIoBufAlloc);
|
---|
| 1598 |
|
---|
| 1599 | /**
|
---|
| 1600 | * Destroys the given I/O buffer manager.
|
---|
| 1601 | *
|
---|
| 1602 | * @returns VBox status code.
|
---|
| 1603 | * @retval VERR_INVALID_STATE if there are still buffers allocated by the given manager.
|
---|
| 1604 | * @param hIoBufMgr The I/O buffer manager.
|
---|
| 1605 | */
|
---|
| 1606 | VBOXDDU_DECL(int) VDIoBufMgrDestroy(VDIOBUFMGR hIoBufMgr);
|
---|
| 1607 |
|
---|
| 1608 | /**-
|
---|
| 1609 | * Allocate a new I/O buffer.
|
---|
| 1610 | *
|
---|
| 1611 | * @returns VBox status code.
|
---|
| 1612 | * @param hIoBufMgr The I/O buffer manager to use.
|
---|
| 1613 | * @param phIoBuf Where to store the I/O buffer handle on success.
|
---|
| 1614 | * @param ppvIoBufAlloc Where to store the pointe to the private party on success.
|
---|
| 1615 | * @param pSgBuf The S/G buffer to use, optional. If NULL the I/O buffer callbacks
|
---|
| 1616 | * supplied when creating the owning manager are used to transfer the
|
---|
| 1617 | * data.
|
---|
| 1618 | * @param cbBuf Size of the buffer in bytes.
|
---|
| 1619 | */
|
---|
| 1620 | VBOXDDU_DECL(int) VDIoBufMgrAllocBuf(VDIOBUFMGR hIoBufMgr, PVDIOBUF phIoBuf, void **ppvIoBufAlloc,
|
---|
| 1621 | PCRTSGBUF pSgBuf, size_t cbBuf);
|
---|
| 1622 |
|
---|
| 1623 | /**
|
---|
| 1624 | * Retains the I/O buffer reference count.
|
---|
| 1625 | *
|
---|
| 1626 | * @returns New reference count.
|
---|
| 1627 | * @param hIoBuf The I/O buffer handle.
|
---|
| 1628 | */
|
---|
| 1629 | VBOXDDU_DECL(uint32_t) VDIoBufRetain(VDIOBUF hIoBuf);
|
---|
| 1630 |
|
---|
| 1631 | /**
|
---|
| 1632 | * Releases the given I/O buffer reference.
|
---|
| 1633 | *
|
---|
| 1634 | * @returns New reference count, on 0 the I/O buffer is destroyed.
|
---|
| 1635 | * @param hIoBuf The I/O buffer handle.
|
---|
| 1636 | */
|
---|
| 1637 | VBOXDDU_DECL(uint32_t) VDIoBufRelease(VDIOBUF hIoBuf);
|
---|
| 1638 |
|
---|
| 1639 | /** @} */
|
---|
| 1640 |
|
---|
| 1641 |
|
---|
[66264] | 1642 | /** @defgroup grp_vd_ioqueue I/O queues
|
---|
| 1643 | * @{
|
---|
| 1644 | */
|
---|
| 1645 |
|
---|
| 1646 | /** VD I/O queue handle. */
|
---|
| 1647 | typedef struct VDIOQUEUEINT *VDIOQUEUE;
|
---|
| 1648 | /** Pointer to an VD I/O queue handle. */
|
---|
| 1649 | typedef VDIOQUEUE *PVDIOQUEUE;
|
---|
| 1650 |
|
---|
| 1651 | /** VD I/O queue request handle. */
|
---|
| 1652 | typedef struct VDIOREQINT *VDIOREQ;
|
---|
| 1653 | /** Pointer to an VD I/O queue request handle. */
|
---|
| 1654 | typedef VDIOREQ *PVDIOREQ;
|
---|
| 1655 |
|
---|
| 1656 | /** A I/O request ID. */
|
---|
| 1657 | typedef uint64_t VDIOREQID;
|
---|
| 1658 |
|
---|
| 1659 | /**
|
---|
[66346] | 1660 | * I/O request type.
|
---|
| 1661 | */
|
---|
| 1662 | typedef enum VDIOREQTYPE
|
---|
| 1663 | {
|
---|
| 1664 | /** Invalid request type. */
|
---|
| 1665 | VDIOREQTYPE_INVALID = 0,
|
---|
| 1666 | /** Read request. */
|
---|
| 1667 | VDIOREQTYPE_READ,
|
---|
| 1668 | /** Write request. */
|
---|
| 1669 | VDIOREQTYPE_WRITE,
|
---|
| 1670 | /** Flush request. */
|
---|
| 1671 | VDIOREQTYPE_FLUSH,
|
---|
| 1672 | /** Discard request. */
|
---|
| 1673 | VDIOREQTYPE_DISCARD,
|
---|
| 1674 | /** 32bit hack. */
|
---|
| 1675 | VDIOREQTYPE_32BIT_HACK = 0x7fffffff
|
---|
| 1676 | } VDIOREQTYPE;
|
---|
| 1677 | /** Pointer to a request type. */
|
---|
| 1678 | typedef VDIOREQTYPE *PVDIOREQTYPE;
|
---|
| 1679 |
|
---|
| 1680 | /**
|
---|
[66264] | 1681 | * I/O queue request completion callback.
|
---|
| 1682 | *
|
---|
| 1683 | * @returns nothing.
|
---|
| 1684 | * @param hVdIoQueue The VD I/O queue handle.
|
---|
| 1685 | * @param pDisk The disk the queue is attached to.
|
---|
| 1686 | * @param hVdIoReq The VD I/O request which completed.
|
---|
| 1687 | * @param pvVdIoReq Pointer to the allocator specific memory for this request.
|
---|
| 1688 | * @param rcReq The completion status code.
|
---|
| 1689 | */
|
---|
| 1690 | typedef DECLCALLBACK(void) FNVDIOQUEUEREQCOMPLETE(VDIOQUEUE hVdIoQueue, PVDISK pDisk,
|
---|
| 1691 | VDIOREQ hVdIoReq, void *pvVdIoReq,
|
---|
| 1692 | int rcReq);
|
---|
| 1693 | /** Pointer to a VD I/O queue request completion callback. */
|
---|
| 1694 | typedef FNVDIOQUEUEREQCOMPLETE *PFNVDIOQUEUEREQCOMPLETE;
|
---|
| 1695 |
|
---|
| 1696 |
|
---|
| 1697 | /**
|
---|
| 1698 | * Creates a new I/O queue.
|
---|
| 1699 | *
|
---|
| 1700 | * @returns VBox status code.
|
---|
| 1701 | * @param phVdIoQueue Where to store the handle to the I/O queue on success.
|
---|
| 1702 | * @param pfnIoReqComplete The completion handle to call when a request on the specified queue completes.
|
---|
| 1703 | * @param cbIoReqAlloc The extra amount of memory to allocate and associate with allocated requests
|
---|
| 1704 | * for use by the caller.
|
---|
| 1705 | * @param iPriority The priority of the queue from 0..UINT32_MAX. The lower the number the higher
|
---|
| 1706 | * the priority of the queue.
|
---|
| 1707 | */
|
---|
| 1708 | VBOXDDU_DECL(int) VDIoQueueCreate(PVDIOQUEUE phVdIoQueue, PFNVDIOQUEUEREQCOMPLETE pfnIoReqComplete,
|
---|
| 1709 | size_t cbIoReqAlloc, uint32_t iPriority);
|
---|
| 1710 |
|
---|
| 1711 | /**
|
---|
| 1712 | * Destroys the given I/O queue.
|
---|
| 1713 | *
|
---|
| 1714 | * @returns VBox status code.
|
---|
| 1715 | * @param hVdIoQueue The I/O queue handle.
|
---|
| 1716 | */
|
---|
| 1717 | VBOXDDU_DECL(int) VDIoQueueDestroy(VDIOQUEUE hVdIoQueue);
|
---|
| 1718 |
|
---|
| 1719 | /**
|
---|
| 1720 | * Attaches the given I/O queue to the given virtual disk container.
|
---|
| 1721 | *
|
---|
| 1722 | * @returns VBox status code.
|
---|
| 1723 | * @param pDisk The disk container handle.
|
---|
| 1724 | * @param hVdIoQueue The I/O queue to attach.
|
---|
| 1725 | */
|
---|
| 1726 | VBOXDDU_DECL(int) VDIoQueueAttach(PVDISK pDisk, VDIOQUEUE hVdIoQueue);
|
---|
| 1727 |
|
---|
| 1728 | /**
|
---|
| 1729 | * Detaches the given I/O queue from the currently attached disk container.
|
---|
| 1730 | *
|
---|
| 1731 | * @returns VBox status code.
|
---|
| 1732 | * @param hVdIoQueue The I/O queue.
|
---|
| 1733 | * @param fPurge Flag whether to cancel all active requests on this queue
|
---|
| 1734 | * before detaching.
|
---|
| 1735 | */
|
---|
| 1736 | VBOXDDU_DECL(int) VDIoQueueDetach(VDIOQUEUE hVdIoQueue, bool fPurge);
|
---|
| 1737 |
|
---|
| 1738 | /**
|
---|
| 1739 | * Purges all requests on the given queue.
|
---|
| 1740 | *
|
---|
| 1741 | * @returns VBox status code.
|
---|
| 1742 | * @param hVdIoQueue The I/O queue.
|
---|
| 1743 | */
|
---|
| 1744 | VBOXDDU_DECL(int) VDIoQueuePurge(VDIOQUEUE hVdIoQueue);
|
---|
| 1745 |
|
---|
| 1746 | /**
|
---|
| 1747 | * Allocates a new request from the given queue.
|
---|
| 1748 | *
|
---|
| 1749 | * @returns VBox status code.
|
---|
| 1750 | * @param hVdIoQueue The I/O queue.
|
---|
| 1751 | * @param phVdIoReq Where to store the handle of the request on success.
|
---|
| 1752 | * @param ppvVdIoReq Where to store the pointer to the allocator usable memory on success.
|
---|
| 1753 | * @param uIoReqId The request ID to assign to the request for canceling.
|
---|
| 1754 | */
|
---|
| 1755 | VBOXDDU_DECL(int) VDIoQueueReqAlloc(VDIOQUEUE hVdIoQueue, PVDIOREQ phVdIoReq,
|
---|
| 1756 | void **ppvVdIoReq, VDIOREQID uIoReqId);
|
---|
| 1757 |
|
---|
| 1758 | /**
|
---|
| 1759 | * Frees a given non active request.
|
---|
| 1760 | *
|
---|
| 1761 | * @returns VBox status code.
|
---|
| 1762 | * @param hVdIoReq The I/O request to free.
|
---|
| 1763 | */
|
---|
| 1764 | VBOXDDU_DECL(int) VDIoQueueReqFree(VDIOREQ hVdIoReq);
|
---|
| 1765 |
|
---|
| 1766 | /**
|
---|
| 1767 | * Cancels an active request by the given request ID.
|
---|
| 1768 | *
|
---|
| 1769 | * @returns VBox status code.
|
---|
| 1770 | * @param hVdIoQueue The I/O queue to cancel the request on.
|
---|
| 1771 | * @param uIoReqId The request ID.
|
---|
| 1772 | */
|
---|
| 1773 | VBOXDDU_DECL(int) VDIoQueueReqCancelById(VDIOQUEUE hVdIoQueue, VDIOREQID uIoReqId);
|
---|
| 1774 |
|
---|
| 1775 | /**
|
---|
| 1776 | * Cancels an active request by the given handle.
|
---|
| 1777 | *
|
---|
| 1778 | * @returns VBox status code.
|
---|
| 1779 | * @param hVdIoReq The I/O request handle to cancel.
|
---|
| 1780 | */
|
---|
| 1781 | VBOXDDU_DECL(int) VDIoQueueReqCancelByHandle(VDIOREQ hVdIoReq);
|
---|
| 1782 |
|
---|
| 1783 | /**
|
---|
[66346] | 1784 | * Submit a new request to the queue the request was allocated from.
|
---|
[66264] | 1785 | *
|
---|
| 1786 | * @returns VBox status code.
|
---|
[66346] | 1787 | * @param hVdIoReq The I/O request handle to submit.
|
---|
| 1788 | * @param enmType The type of the request.
|
---|
| 1789 | * @param hVdIoIter The iterator to use, NULL for flush requests.
|
---|
| 1790 | * @param hVdIoBuf The I/O buffer handle to use, NULL for flush and discard requests.
|
---|
[66264] | 1791 | */
|
---|
[66346] | 1792 | VBOXDDU_DECL(int) VDIoQueueReqSubmit(VDIOREQ hVdIoReq, VDIOREQTYPE enmType,
|
---|
| 1793 | VDIOITER hVdIoIter, VDIOBUF hVdIoBuf);
|
---|
[66264] | 1794 |
|
---|
| 1795 | /** @} */
|
---|
| 1796 |
|
---|
| 1797 |
|
---|
[20374] | 1798 | RT_C_DECLS_END
|
---|
[1] | 1799 |
|
---|
| 1800 | /** @} */
|
---|
| 1801 |
|
---|
| 1802 | #endif
|
---|
[58111] | 1803 |
|
---|