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