VirtualBox

source: vbox/trunk/include/VBox/VBoxHDD-new.h@ 9565

Last change on this file since 9565 was 9565, checked in by vboxsync, 16 years ago

Fix incorrect check verifying disk type. Also make the API for getting the disk type return an error if the cached value is invalid.
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 29.6 KB
Line 
1/** @file
2 * VBox HDD Container API.
3 * Will replace VBoxHDD.h.
4 */
5
6/*
7 * Copyright (C) 2006-2008 Sun Microsystems, Inc.
8 *
9 * This file is part of VirtualBox Open Source Edition (OSE), as
10 * available from http://www.virtualbox.org. This file is free software;
11 * you can redistribute it and/or modify it under the terms of the GNU
12 * General Public License (GPL) as published by the Free Software
13 * Foundation, in version 2 as it comes in the "COPYING" file of the
14 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
15 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
16 *
17 * The contents of this file may alternatively be used under the terms
18 * of the Common Development and Distribution License Version 1.0
19 * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
20 * VirtualBox OSE distribution, in which case the provisions of the
21 * CDDL are applicable instead of those of the GPL.
22 *
23 * You may elect to license modified versions of this file under the
24 * terms and conditions of either the GPL or the CDDL or both.
25 *
26 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
27 * Clara, CA 95054 USA or visit http://www.sun.com if you need
28 * additional information or have any questions.
29 */
30
31#ifndef ___VBox_VD_h
32#define ___VBox_VD_h
33
34#include <VBox/cdefs.h>
35#include <VBox/types.h>
36#include <VBox/pdm.h>
37
38__BEGIN_DECLS
39
40#ifdef IN_RING0
41# error "There are no VBox HDD Container APIs available in Ring-0 Host Context!"
42#endif
43
44/** @defgroup grp_vd VBox HDD Container
45 * @{
46 */
47
48/** Current VMDK image version. */
49#define VMDK_IMAGE_VERSION (0x0001)
50
51/** Current VDI image major version. */
52#define VDI_IMAGE_VERSION_MAJOR (0x0001)
53/** Current VDI image minor version. */
54#define VDI_IMAGE_VERSION_MINOR (0x0001)
55/** Current VDI image version. */
56#define VDI_IMAGE_VERSION ((VDI_IMAGE_VERSION_MAJOR << 16) | VDI_IMAGE_VERSION_MINOR)
57
58/** Get VDI major version from combined version. */
59#define VDI_GET_VERSION_MAJOR(uVer) ((uVer) >> 16)
60/** Get VDI minor version from combined version. */
61#define VDI_GET_VERSION_MINOR(uVer) ((uVer) & 0xffff)
62
63/** Placeholder for specifying the last opened image. */
64#define VD_LAST_IMAGE 0xffffffffU
65
66/** @name VBox HDD container image types
67 * @{ */
68typedef enum VDIMAGETYPE
69{
70 /** Invalid image type. Should never be returned/passed through the API. */
71 VD_IMAGE_TYPE_INVALID = 0,
72 /** Normal dynamically growing base image file. */
73 VD_IMAGE_TYPE_NORMAL,
74 /** Preallocated base image file of a fixed size. */
75 VD_IMAGE_TYPE_FIXED,
76 /** Dynamically growing image file for undo/commit changes support. */
77 VD_IMAGE_TYPE_UNDO,
78 /** Dynamically growing image file for differencing support. */
79 VD_IMAGE_TYPE_DIFF,
80
81 /** First valid image type value. */
82 VD_IMAGE_TYPE_FIRST = VD_IMAGE_TYPE_NORMAL,
83 /** Last valid image type value. */
84 VD_IMAGE_TYPE_LAST = VD_IMAGE_TYPE_DIFF
85} VDIMAGETYPE;
86/** Pointer to VBox HDD container image type. */
87typedef VDIMAGETYPE *PVDIMAGETYPE;
88/** @} */
89
90/** @name VBox HDD container image flags
91 * @{
92 */
93/** No flags. */
94#define VD_IMAGE_FLAGS_NONE (0)
95/** VMDK: Split image into 2GB extents. */
96#define VD_VMDK_IMAGE_FLAGS_SPLIT_2G (0x0001)
97/** VMDK: Raw disk image (giving access to a number of host partitions). */
98#define VD_VMDK_IMAGE_FLAGS_RAWDISK (0x0002)
99/** VDI: Fill new blocks with zeroes while expanding image file. Only valid
100 * for newly created images, never set for opened existing images. */
101#define VD_VDI_IMAGE_FLAGS_ZERO_EXPAND (0x0100)
102
103/** Mask of valid image flags for VMDK. */
104#define VD_VMDK_IMAGE_FLAGS_MASK (VD_IMAGE_FLAGS_NONE | VD_VMDK_IMAGE_FLAGS_SPLIT_2G | VD_VMDK_IMAGE_FLAGS_RAWDISK)
105
106/** Mask of valid image flags for VDI. */
107#define VD_VDI_IMAGE_FLAGS_MASK (VD_IMAGE_FLAGS_NONE | VD_VDI_IMAGE_FLAGS_ZERO_EXPAND)
108
109/** Mask of all valid image flags for all formats. */
110#define VD_IMAGE_FLAGS_MASK (VD_VMDK_IMAGE_FLAGS_MASK | VD_VDI_IMAGE_FLAGS_MASK)
111
112/** Default image flags. */
113#define VD_IMAGE_FLAGS_DEFAULT (VD_IMAGE_FLAGS_NONE)
114/** @} */
115
116
117/**
118 * Auxiliary type for describing partitions on raw disks.
119 */
120typedef struct VBOXHDDRAWPART
121{
122 /** Device to use for this partition. Can be the disk device if the offset
123 * field is set appropriately. If this is NULL, then this partition will
124 * not be accessible to the guest. The size of the partition must still
125 * be set correctly. */
126 const char *pszRawDevice;
127 /** Offset where the partition data starts in this device. */
128 uint64_t uPartitionStartOffset;
129 /** Offset where the partition data starts in the disk. */
130 uint64_t uPartitionStart;
131 /** Size of the partition. */
132 uint64_t cbPartition;
133 /** Size of the partitioning info to prepend. */
134 uint64_t cbPartitionData;
135 /** Offset where the partitioning info starts in the disk. */
136 uint64_t uPartitionDataStart;
137 /** Pointer to the partitioning info to prepend. */
138 const void *pvPartitionData;
139} VBOXHDDRAWPART, *PVBOXHDDRAWPART;
140
141/**
142 * Auxiliary data structure for creating raw disks.
143 */
144typedef struct VBOXHDDRAW
145{
146 /** Signature for structure. Must be 'R', 'A', 'W', '\0'. Actually a trick
147 * to make logging of the comment string produce sensible results. */
148 char szSignature[4];
149 /** Flag whether access to full disk should be given (ignoring the
150 * partition information below). */
151 bool fRawDisk;
152 /** Filename for the raw disk. Ignored for partitioned raw disks.
153 * For Linux e.g. /dev/sda, and for Windows e.g. \\.\PhysicalDisk0. */
154 const char *pszRawDisk;
155 /** Number of entries in the partitions array. */
156 unsigned cPartitions;
157 /** Pointer to the partitions array. */
158 PVBOXHDDRAWPART pPartitions;
159} VBOXHDDRAW, *PVBOXHDDRAW;
160
161/** @name VBox HDD container image open mode flags
162 * @{
163 */
164/** Try to open image in read/write exclusive access mode if possible, or in read-only elsewhere. */
165#define VD_OPEN_FLAGS_NORMAL 0
166/** Open image in read-only mode with sharing access with others. */
167#define VD_OPEN_FLAGS_READONLY RT_BIT(0)
168/** Honor zero block writes instead of ignoring them whenever possible.
169 * This is not supported by all formats. It is silently ignored in this case. */
170#define VD_OPEN_FLAGS_HONOR_ZEROES RT_BIT(1)
171/** Honor writes of the same data instead of ignoring whenever possible.
172 * This is handled generically, and is only meaningful for differential image
173 * formats. It is silently ignored otherwise. */
174#define VD_OPEN_FLAGS_HONOR_SAME RT_BIT(2)
175/** Do not perform the base/diff image check on open. This internally implies
176 * opening the image as readonly. Images opened with this flag should only be
177 * used for querying information, and nothing else. */
178#define VD_OPEN_FLAGS_INFO RT_BIT(3)
179/** Mask of valid flags. */
180#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)
181/** @}*/
182
183
184/** @name VBox HDD container backend capability flags
185 * @{
186 */
187/** Supports UUIDs as expected by VirtualBox code. */
188#define VD_CAP_UUID RT_BIT(0)
189/** Supports creating fixed size images, allocating all space instantly. */
190#define VD_CAP_CREATE_FIXED RT_BIT(1)
191/** Supports creating dynamically growing images, allocating space on demand. */
192#define VD_CAP_CREATE_DYNAMIC RT_BIT(2)
193/** Supports creating images split in chunks of a bit less than 2GBytes. */
194#define VD_CAP_CREATE_SPLIT_2G RT_BIT(3)
195/** Supports being used as differencing image format backend. */
196#define VD_CAP_DIFF RT_BIT(4)
197/** @}*/
198
199
200/**
201 * Data structure for returning a list of backend capabilities.
202 */
203typedef struct VDBACKENDINFO
204{
205 /** Name of the backend. */
206 char *pszBackend;
207 /** Capabilities of the backend (a combination of the VD_CAP_* flags). */
208 uint64_t uBackendCaps;
209} VDBACKENDINFO, *PVDBACKENDINFO;
210
211
212/**
213 * Error message callback.
214 *
215 * @param pvUser The opaque data passed on container creation.
216 * @param rc The VBox error code.
217 * @param RT_SRC_POS_DECL Use RT_SRC_POS.
218 * @param pszFormat Error message format string.
219 * @param va Error message arguments.
220 */
221typedef DECLCALLBACK(void) FNVDERROR(void *pvUser, int rc, RT_SRC_POS_DECL, const char *pszFormat, va_list va);
222/** Pointer to a FNVDERROR(). */
223typedef FNVDERROR *PFNVDERROR;
224
225
226/**
227 * VBox HDD Container main structure.
228 */
229/* Forward declaration, VBOXHDD structure is visible only inside VBox HDD module. */
230struct VBOXHDD;
231typedef struct VBOXHDD VBOXHDD;
232typedef VBOXHDD *PVBOXHDD;
233
234
235/**
236 * Lists all HDD backends and their capabilities in a caller-provided buffer.
237 * Free all returned names with RTStrFree() when you no longer need them.
238 *
239 * @returns VBox status code.
240 * VERR_BUFFER_OVERFLOW if not enough space is passed.
241 * @param cEntriesAlloc Number of list entries available.
242 * @param pEntries Pointer to array for the entries.
243 * @param pcEntriesUsed Number of entries returned.
244 */
245VBOXDDU_DECL(int) VDBackendInfo(unsigned cEntriesAlloc, PVDBACKENDINFO pEntries,
246 unsigned *pcEntriesUsed);
247
248
249/**
250 * Allocates and initializes an empty HDD container.
251 * No image files are opened.
252 *
253 * @returns VBox status code.
254 * @param pfnError Callback for setting extended error information.
255 * @param pvErrorUser Opaque parameter for pfnError.
256 * @param ppDisk Where to store the reference to HDD container.
257 */
258VBOXDDU_DECL(int) VDCreate(PFNVDERROR pfnError, void *pvErrorUser,
259 PVBOXHDD *ppDisk);
260
261/**
262 * Destroys HDD container.
263 * If container has opened image files they will be closed.
264 *
265 * @param pDisk Pointer to HDD container.
266 */
267VBOXDDU_DECL(void) VDDestroy(PVBOXHDD pDisk);
268
269/**
270 * Try to get the backend name which can use this image.
271 *
272 * @returns VBox status code.
273 * @param pszFilename Name of the image file for which the backend is queried.
274 * @param ppszFormat Receives pointer of the UTF-8 string which contains the format name.
275 * The returned pointer must be freed using RTStrFree().
276 */
277VBOXDDU_DECL(int) VDGetFormat(const char *pszFilename, char **ppszFormat);
278
279/**
280 * Opens an image file.
281 *
282 * The first opened image file in HDD container must have a base image type,
283 * others (next opened images) must be differencing or undo images.
284 * Linkage is checked for differencing image to be consistent with the previously opened image.
285 * When another differencing image is opened and the last image was opened in read/write access
286 * mode, then the last image is reopened in read-only with deny write sharing mode. This allows
287 * other processes to use images in read-only mode too.
288 *
289 * Note that the image is opened in read-only mode if a read/write open is not possible.
290 * Use VDIsReadOnly to check open mode.
291 *
292 * @returns VBox status code.
293 * @param pDisk Pointer to HDD container.
294 * @param pszBackend Name of the image file backend to use.
295 * @param pszFilename Name of the image file to open.
296 * @param uOpenFlags Image file open mode, see VD_OPEN_FLAGS_* constants.
297 */
298VBOXDDU_DECL(int) VDOpen(PVBOXHDD pDisk, const char *pszBackend,
299 const char *pszFilename, unsigned uOpenFlags);
300
301/**
302 * Creates and opens a new base image file.
303 *
304 * @returns VBox status code.
305 * @param pDisk Pointer to HDD container.
306 * @param pszBackend Name of the image file backend to use.
307 * @param pszFilename Name of the image file to create.
308 * @param enmType Image type, only base image types are acceptable.
309 * @param cbSize Image size in bytes.
310 * @param uImageFlags Flags specifying special image features.
311 * @param pszComment Pointer to image comment. NULL is ok.
312 * @param pPCHSGeometry Pointer to physical disk geometry <= (16383,16,63). Not NULL.
313 * @param pLCHSGeometry Pointer to logical disk geometry <= (1024,255,63). Not NULL.
314 * @param uOpenFlags Image file open mode, see VD_OPEN_FLAGS_* constants.
315 * @param pfnProgress Progress callback. Optional. NULL if not to be used.
316 * @param pvUser User argument for the progress callback.
317 */
318VBOXDDU_DECL(int) VDCreateBase(PVBOXHDD pDisk, const char *pszBackend,
319 const char *pszFilename, VDIMAGETYPE enmType,
320 uint64_t cbSize, unsigned uImageFlags,
321 const char *pszComment,
322 PCPDMMEDIAGEOMETRY pPCHSGeometry,
323 PCPDMMEDIAGEOMETRY pLCHSGeometry,
324 unsigned uOpenFlags, PFNVMPROGRESS pfnProgress,
325 void *pvUser);
326
327/**
328 * Creates and opens a new differencing image file in HDD container.
329 * See comments for VDOpen function about differencing images.
330 *
331 * @returns VBox status code.
332 * @param pDisk Pointer to HDD container.
333 * @param pszBackend Name of the image file backend to use.
334 * @param pszFilename Name of the differencing image file to create.
335 * @param uImageFlags Flags specifying special image features.
336 * @param pszComment Pointer to image comment. NULL is ok.
337 * @param uOpenFlags Image file open mode, see VD_OPEN_FLAGS_* constants.
338 * @param pfnProgress Progress callback. Optional. NULL if not to be used.
339 * @param pvUser User argument for the progress callback.
340 */
341VBOXDDU_DECL(int) VDCreateDiff(PVBOXHDD pDisk, const char *pszBackend,
342 const char *pszFilename, unsigned uImageFlags,
343 const char *pszComment, unsigned uOpenFlags,
344 PFNVMPROGRESS pfnProgress, void *pvUser);
345
346/**
347 * Merges two images (not necessarily with direct parent/child relationship).
348 * As a side effect the source image and potentially the other images which
349 * are also merged to the destination are deleted from both the disk and the
350 * images in the HDD container.
351 *
352 * @returns VBox status code.
353 * @returns VERR_VDI_IMAGE_NOT_FOUND if image with specified number was not opened.
354 * @param pDisk Pointer to HDD container.
355 * @param nImageFrom Name of the image file to merge from.
356 * @param nImageTo Name of the image file to merge to.
357 * @param pfnProgress Progress callback. Optional. NULL if not to be used.
358 * @param pvUser User argument for the progress callback.
359 */
360VBOXDDU_DECL(int) VDMerge(PVBOXHDD pDisk, unsigned nImageFrom,
361 unsigned nImageTo, PFNVMPROGRESS pfnProgress,
362 void *pvUser);
363
364/**
365 * Copies an image from one HDD container to another.
366 * The copy is opened in the target HDD container.
367 * It is possible to convert between different image formats, because the
368 * backend for the destination may be different from the source.
369 * If both the source and destination reference the same HDD container,
370 * then the image is moved (by copying/deleting or renaming) to the new location.
371 * The source container is unchanged if the move operation fails, otherwise
372 * the image at the new location is opened in the same way as the old one was.
373 *
374 * @returns VBox status code.
375 * @returns VERR_VDI_IMAGE_NOT_FOUND if image with specified number was not opened.
376 * @param pDiskFrom Pointer to source HDD container.
377 * @param nImage Image number, counts from 0. 0 is always base image of container.
378 * @param pDiskTo Pointer to destination HDD container.
379 * @param pszBackend Name of the image file backend to use (may be NULL to use the same as the source).
380 * @param pszFilename New name of the image (may be NULL if pDiskFrom == pDiskTo).
381 * @param fMoveByRename If true, attempt to perform a move by renaming (if successful the new size is ignored).
382 * @param cbSize New image size (0 means leave unchanged).
383 * @param pfnProgress Progress callback. Optional. NULL if not to be used.
384 * @param pvUser User argument for the progress callback.
385 */
386VBOXDDU_DECL(int) VDCopy(PVBOXHDD pDiskFrom, unsigned nImage, PVBOXHDD pDiskTo,
387 const char *pszBackend, const char *pszFilename,
388 bool fMoveByRename, uint64_t cbSize,
389 PFNVMPROGRESS pfnProgress, void *pvUser);
390
391/**
392 * Closes the last opened image file in HDD container.
393 * If previous image file was opened in read-only mode (that is normal) and closing image
394 * was opened in read-write mode (the whole disk was in read-write mode) - the previous image
395 * will be reopened in read/write mode.
396 *
397 * @returns VBox status code.
398 * @returns VERR_VDI_NOT_OPENED if no image is opened in HDD container.
399 * @param pDisk Pointer to HDD container.
400 * @param fDelete If true, delete the image from the host disk.
401 */
402VBOXDDU_DECL(int) VDClose(PVBOXHDD pDisk, bool fDelete);
403
404/**
405 * Closes all opened image files in HDD container.
406 *
407 * @returns VBox status code.
408 * @param pDisk Pointer to HDD container.
409 */
410VBOXDDU_DECL(int) VDCloseAll(PVBOXHDD pDisk);
411
412/**
413 * Read data from virtual HDD.
414 *
415 * @returns VBox status code.
416 * @returns VERR_VDI_NOT_OPENED if no image is opened in HDD container.
417 * @param pDisk Pointer to HDD container.
418 * @param uOffset Offset of first reading byte from start of disk.
419 * @param pvBuf Pointer to buffer for reading data.
420 * @param cbRead Number of bytes to read.
421 */
422VBOXDDU_DECL(int) VDRead(PVBOXHDD pDisk, uint64_t uOffset, void *pvBuf, size_t cbRead);
423
424/**
425 * Write data to virtual HDD.
426 *
427 * @returns VBox status code.
428 * @returns VERR_VDI_NOT_OPENED if no image is opened in HDD container.
429 * @param pDisk Pointer to HDD container.
430 * @param uOffset Offset of first writing byte from start of disk.
431 * @param pvBuf Pointer to buffer for writing data.
432 * @param cbWrite Number of bytes to write.
433 */
434VBOXDDU_DECL(int) VDWrite(PVBOXHDD pDisk, uint64_t uOffset, const void *pvBuf, size_t cbWrite);
435
436/**
437 * Make sure the on disk representation of a virtual HDD is up to date.
438 *
439 * @returns VBox status code.
440 * @returns VERR_VDI_NOT_OPENED if no image is opened in HDD container.
441 * @param pDisk Pointer to HDD container.
442 */
443VBOXDDU_DECL(int) VDFlush(PVBOXHDD pDisk);
444
445/**
446 * Get number of opened images in HDD container.
447 *
448 * @returns Number of opened images for HDD container. 0 if no images have been opened.
449 * @param pDisk Pointer to HDD container.
450 */
451VBOXDDU_DECL(unsigned) VDGetCount(PVBOXHDD pDisk);
452
453/**
454 * Get read/write mode of HDD container.
455 *
456 * @returns Virtual disk ReadOnly status.
457 * @returns true if no image is opened in HDD container.
458 * @param pDisk Pointer to HDD container.
459 */
460VBOXDDU_DECL(bool) VDIsReadOnly(PVBOXHDD pDisk);
461
462/**
463 * Get total capacity of an image in HDD container.
464 *
465 * @returns Virtual disk size in bytes.
466 * @returns 0 if image with specified number was not opened.
467 * @param pDisk Pointer to HDD container.
468 * @param nImage Image number, counts from 0. 0 is always base image of container.
469 */
470VBOXDDU_DECL(uint64_t) VDGetSize(PVBOXHDD pDisk, unsigned nImage);
471
472/**
473 * Get total file size of an image in HDD container.
474 *
475 * @returns Virtual disk size in bytes.
476 * @returns 0 if image with specified number was not opened.
477 * @param pDisk Pointer to HDD container.
478 * @param nImage Image number, counts from 0. 0 is always base image of container.
479 */
480VBOXDDU_DECL(uint64_t) VDGetFileSize(PVBOXHDD pDisk, unsigned nImage);
481
482/**
483 * Get virtual disk PCHS geometry of an image in HDD container.
484 *
485 * @returns VBox status code.
486 * @returns VERR_VDI_IMAGE_NOT_FOUND if image with specified number was not opened.
487 * @returns VERR_VDI_GEOMETRY_NOT_SET if no geometry present in the HDD container.
488 * @param pDisk Pointer to HDD container.
489 * @param nImage Image number, counts from 0. 0 is always base image of container.
490 * @param pPCHSGeometry Where to store PCHS geometry. Not NULL.
491 */
492VBOXDDU_DECL(int) VDGetPCHSGeometry(PVBOXHDD pDisk, unsigned nImage,
493 PPDMMEDIAGEOMETRY pPCHSGeometry);
494
495/**
496 * Store virtual disk PCHS geometry of an image in HDD container.
497 *
498 * @returns VBox status code.
499 * @returns VERR_VDI_IMAGE_NOT_FOUND if image with specified number was not opened.
500 * @param pDisk Pointer to HDD container.
501 * @param nImage Image number, counts from 0. 0 is always base image of container.
502 * @param pPCHSGeometry Where to load PCHS geometry from. Not NULL.
503 */
504VBOXDDU_DECL(int) VDSetPCHSGeometry(PVBOXHDD pDisk, unsigned nImage,
505 PCPDMMEDIAGEOMETRY pPCHSGeometry);
506
507/**
508 * Get virtual disk LCHS geometry of an image in HDD container.
509 *
510 * @returns VBox status code.
511 * @returns VERR_VDI_IMAGE_NOT_FOUND if image with specified number was not opened.
512 * @returns VERR_VDI_GEOMETRY_NOT_SET if no geometry present in the HDD container.
513 * @param pDisk Pointer to HDD container.
514 * @param nImage Image number, counts from 0. 0 is always base image of container.
515 * @param pLCHSGeometry Where to store LCHS geometry. Not NULL.
516 */
517VBOXDDU_DECL(int) VDGetLCHSGeometry(PVBOXHDD pDisk, unsigned nImage,
518 PPDMMEDIAGEOMETRY pLCHSGeometry);
519
520/**
521 * Store virtual disk LCHS geometry of an image in HDD container.
522 *
523 * @returns VBox status code.
524 * @returns VERR_VDI_IMAGE_NOT_FOUND if image with specified number was not opened.
525 * @param pDisk Pointer to HDD container.
526 * @param nImage Image number, counts from 0. 0 is always base image of container.
527 * @param pLCHSGeometry Where to load LCHS geometry from. Not NULL.
528 */
529VBOXDDU_DECL(int) VDSetLCHSGeometry(PVBOXHDD pDisk, unsigned nImage,
530 PCPDMMEDIAGEOMETRY pLCHSGeometry);
531
532/**
533 * Get version of image in HDD container.
534 *
535 * @returns VBox status code.
536 * @returns VERR_VDI_IMAGE_NOT_FOUND if image with specified number was not opened.
537 * @param pDisk Pointer to HDD container.
538 * @param nImage Image number, counts from 0. 0 is always base image of container.
539 * @param puVersion Where to store the image version.
540 */
541VBOXDDU_DECL(int) VDGetVersion(PVBOXHDD pDisk, unsigned nImage,
542 unsigned *puVersion);
543
544/**
545 * Get type of image in HDD container.
546 *
547 * @returns VBox status code.
548 * @returns VERR_VDI_IMAGE_NOT_FOUND if image with specified number was not opened.
549 * @param pDisk Pointer to HDD container.
550 * @param nImage Image number, counts from 0. 0 is always base image of container.
551 * @param penmType Where to store the image type.
552 */
553VBOXDDU_DECL(int) VDGetImageType(PVBOXHDD pDisk, unsigned nImage,
554 PVDIMAGETYPE penmType);
555
556/**
557 * Get flags of image in HDD container.
558 *
559 * @returns VBox status code.
560 * @returns VERR_VDI_IMAGE_NOT_FOUND if image with specified number was not opened.
561 * @param pDisk Pointer to HDD container.
562 * @param nImage Image number, counts from 0. 0 is always base image of container.
563 * @param puImageFlags Where to store the image flags.
564 */
565VBOXDDU_DECL(int) VDGetImageFlags(PVBOXHDD pDisk, unsigned nImage, unsigned *puImageFlags);
566
567/**
568 * Get open flags of image in HDD container.
569 *
570 * @returns VBox status code.
571 * @returns VERR_VDI_IMAGE_NOT_FOUND if image with specified number was not opened.
572 * @param pDisk Pointer to HDD container.
573 * @param nImage Image number, counts from 0. 0 is always base image of container.
574 * @param puOpenFlags Where to store the image open flags.
575 */
576VBOXDDU_DECL(int) VDGetOpenFlags(PVBOXHDD pDisk, unsigned nImage,
577 unsigned *puOpenFlags);
578
579/**
580 * Set open flags of image in HDD container.
581 * This operation may cause file locking changes and/or files being reopened.
582 * Note that in case of unrecoverable error all images in HDD container will be closed.
583 *
584 * @returns VBox status code.
585 * @returns VERR_VDI_IMAGE_NOT_FOUND if image with specified number was not opened.
586 * @param pDisk Pointer to HDD container.
587 * @param nImage Image number, counts from 0. 0 is always base image of container.
588 * @param uOpenFlags Image file open mode, see VD_OPEN_FLAGS_* constants.
589 */
590VBOXDDU_DECL(int) VDSetOpenFlags(PVBOXHDD pDisk, unsigned nImage,
591 unsigned uOpenFlags);
592
593/**
594 * Get base filename of image in HDD container. Some image formats use
595 * other filenames as well, so don't use this for anything but informational
596 * purposes.
597 *
598 * @returns VBox status code.
599 * @returns VERR_VDI_IMAGE_NOT_FOUND if image with specified number was not opened.
600 * @returns VERR_BUFFER_OVERFLOW if pszFilename buffer too small to hold filename.
601 * @param pDisk Pointer to HDD container.
602 * @param nImage Image number, counts from 0. 0 is always base image of container.
603 * @param pszFilename Where to store the image file name.
604 * @param cbFilename Size of buffer pszFilename points to.
605 */
606VBOXDDU_DECL(int) VDGetFilename(PVBOXHDD pDisk, unsigned nImage,
607 char *pszFilename, unsigned cbFilename);
608
609/**
610 * Get the comment line of image in HDD container.
611 *
612 * @returns VBox status code.
613 * @returns VERR_VDI_IMAGE_NOT_FOUND if image with specified number was not opened.
614 * @returns VERR_BUFFER_OVERFLOW if pszComment buffer too small to hold comment text.
615 * @param pDisk Pointer to HDD container.
616 * @param nImage Image number, counts from 0. 0 is always base image of container.
617 * @param pszComment Where to store the comment string of image. NULL is ok.
618 * @param cbComment The size of pszComment buffer. 0 is ok.
619 */
620VBOXDDU_DECL(int) VDGetComment(PVBOXHDD pDisk, unsigned nImage,
621 char *pszComment, unsigned cbComment);
622
623/**
624 * Changes the comment line of image in HDD container.
625 *
626 * @returns VBox status code.
627 * @returns VERR_VDI_IMAGE_NOT_FOUND if image with specified number was not opened.
628 * @param pDisk Pointer to HDD container.
629 * @param nImage Image number, counts from 0. 0 is always base image of container.
630 * @param pszComment New comment string (UTF-8). NULL is allowed to reset the comment.
631 */
632VBOXDDU_DECL(int) VDSetComment(PVBOXHDD pDisk, unsigned nImage,
633 const char *pszComment);
634
635/**
636 * Get UUID of image in HDD container.
637 *
638 * @returns VBox status code.
639 * @returns VERR_VDI_IMAGE_NOT_FOUND if image with specified number was not opened.
640 * @param pDisk Pointer to HDD container.
641 * @param nImage Image number, counts from 0. 0 is always base image of container.
642 * @param pUuid Where to store the image UUID.
643 */
644VBOXDDU_DECL(int) VDGetUuid(PVBOXHDD pDisk, unsigned nImage, PRTUUID pUuid);
645
646/**
647 * Set the image's UUID. Should not be used by normal applications.
648 *
649 * @returns VBox status code.
650 * @returns VERR_VDI_IMAGE_NOT_FOUND if image with specified number was not opened.
651 * @param pDisk Pointer to HDD container.
652 * @param nImage Image number, counts from 0. 0 is always base image of container.
653 * @param pUuid New UUID of the image. If NULL, a new UUID is created.
654 */
655VBOXDDU_DECL(int) VDSetUuid(PVBOXHDD pDisk, unsigned nImage, PCRTUUID pUuid);
656
657/**
658 * Get last modification UUID of image in HDD container.
659 *
660 * @returns VBox status code.
661 * @returns VERR_VDI_IMAGE_NOT_FOUND if image with specified number was not opened.
662 * @param pDisk Pointer to HDD container.
663 * @param nImage Image number, counts from 0. 0 is always base image of container.
664 * @param pUuid Where to store the image modification UUID.
665 */
666VBOXDDU_DECL(int) VDGetModificationUuid(PVBOXHDD pDisk, unsigned nImage,
667 PRTUUID pUuid);
668
669/**
670 * Set the image's last modification UUID. Should not be used by normal applications.
671 *
672 * @returns VBox status code.
673 * @returns VERR_VDI_IMAGE_NOT_FOUND if image with specified number was not opened.
674 * @param pDisk Pointer to HDD container.
675 * @param nImage Image number, counts from 0. 0 is always base image of container.
676 * @param pUuid New modification UUID of the image. If NULL, a new UUID is created.
677 */
678VBOXDDU_DECL(int) VDSetModificationUuid(PVBOXHDD pDisk, unsigned nImage,
679 PCRTUUID pUuid);
680
681/**
682 * Get parent UUID of image in HDD container.
683 *
684 * @returns VBox status code.
685 * @returns VERR_VDI_IMAGE_NOT_FOUND if image with specified number was not opened.
686 * @param pDisk Pointer to HDD container.
687 * @param nImage Image number, counts from 0. 0 is always base image of the container.
688 * @param pUuid Where to store the parent image UUID.
689 */
690VBOXDDU_DECL(int) VDGetParentUuid(PVBOXHDD pDisk, unsigned nImage,
691 PRTUUID pUuid);
692
693/**
694 * Set the image's parent UUID. Should not be used by normal applications.
695 *
696 * @returns VBox status code.
697 * @param pDisk Pointer to HDD container.
698 * @param nImage Image number, counts from 0. 0 is always base image of container.
699 * @param pUuid New parent UUID of the image. If NULL, a new UUID is created.
700 */
701VBOXDDU_DECL(int) VDSetParentUuid(PVBOXHDD pDisk, unsigned nImage,
702 PCRTUUID pUuid);
703
704
705/**
706 * Debug helper - dumps all opened images in HDD container into the log file.
707 *
708 * @param pDisk Pointer to HDD container.
709 */
710VBOXDDU_DECL(void) VDDumpImages(PVBOXHDD pDisk);
711
712__END_DECLS
713
714/** @} */
715
716#endif
Note: See TracBrowser for help on using the repository browser.

© 2023 Oracle
Contact – Privacy policy – Terms of Use