VirtualBox

source: vbox/trunk/include/VBox/VBoxHDD.h@ 18618

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

Storage/API/VBoxManage/...: add maximum size check to prevent creation of invalid images, implement fixed-size ESX variants, update VBoxManage and docs accordingly

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 63.6 KB
Line 
1/** @file
2 * VBox HDD Container API.
3 */
4
5/*
6 * Copyright (C) 2006-2008 Sun Microsystems, Inc.
7 *
8 * This file is part of VirtualBox Open Source Edition (OSE), as
9 * available from http://www.virtualbox.org. This file is free software;
10 * you can redistribute it and/or modify it under the terms of the GNU
11 * General Public License (GPL) as published by the Free Software
12 * Foundation, in version 2 as it comes in the "COPYING" file of the
13 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
14 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
15 *
16 * The contents of this file may alternatively be used under the terms
17 * of the Common Development and Distribution License Version 1.0
18 * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
19 * VirtualBox OSE distribution, in which case the provisions of the
20 * CDDL are applicable instead of those of the GPL.
21 *
22 * You may elect to license modified versions of this file under the
23 * terms and conditions of either the GPL or the CDDL or both.
24 *
25 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
26 * Clara, CA 95054 USA or visit http://www.sun.com if you need
27 * additional information or have any questions.
28 */
29
30#ifndef ___VBox_VD_h
31#define ___VBox_VD_h
32
33#include <iprt/assert.h>
34#include <iprt/string.h>
35#include <iprt/mem.h>
36#include <VBox/cdefs.h>
37#include <VBox/types.h>
38#include <VBox/err.h>
39#include <VBox/pdmifs.h>
40/** @todo remove this dependency, using PFNVMPROGRESS outside VMM is *WRONG*. */
41#include <VBox/vmapi.h>
42
43__BEGIN_DECLS
44
45#ifdef IN_RING0
46# error "There are no VBox HDD Container APIs available in Ring-0 Host Context!"
47#endif
48
49/** @defgroup grp_vd VBox HDD Container
50 * @{
51 */
52
53/** Current VMDK image version. */
54#define VMDK_IMAGE_VERSION (0x0001)
55
56/** Current VDI image major version. */
57#define VDI_IMAGE_VERSION_MAJOR (0x0001)
58/** Current VDI image minor version. */
59#define VDI_IMAGE_VERSION_MINOR (0x0001)
60/** Current VDI image version. */
61#define VDI_IMAGE_VERSION ((VDI_IMAGE_VERSION_MAJOR << 16) | VDI_IMAGE_VERSION_MINOR)
62
63/** Get VDI major version from combined version. */
64#define VDI_GET_VERSION_MAJOR(uVer) ((uVer) >> 16)
65/** Get VDI minor version from combined version. */
66#define VDI_GET_VERSION_MINOR(uVer) ((uVer) & 0xffff)
67
68/** Placeholder for specifying the last opened image. */
69#define VD_LAST_IMAGE 0xffffffffU
70
71/** @name VBox HDD container image flags
72 * @{
73 */
74/** No flags. */
75#define VD_IMAGE_FLAGS_NONE (0)
76/** Fixed image. */
77#define VD_IMAGE_FLAGS_FIXED (0x10000)
78/** Diff image. Mutually exclusive with fixed image. */
79#define VD_IMAGE_FLAGS_DIFF (0x20000)
80/** VMDK: Split image into 2GB extents. */
81#define VD_VMDK_IMAGE_FLAGS_SPLIT_2G (0x0001)
82/** VMDK: Raw disk image (giving access to a number of host partitions). */
83#define VD_VMDK_IMAGE_FLAGS_RAWDISK (0x0002)
84/** VMDK: stream optimized image, read only. */
85#define VD_VMDK_IMAGE_FLAGS_STREAM_OPTIMIZED (0x0004)
86/** VMDK: ESX variant, use in addition to other flags. */
87#define VD_VMDK_IMAGE_FLAGS_ESX (0x0008)
88/** VDI: Fill new blocks with zeroes while expanding image file. Only valid
89 * for newly created images, never set for opened existing images. */
90#define VD_VDI_IMAGE_FLAGS_ZERO_EXPAND (0x0100)
91
92/** Mask of valid image flags for VMDK. */
93#define VD_VMDK_IMAGE_FLAGS_MASK ( VD_IMAGE_FLAGS_FIXED | VD_IMAGE_FLAGS_DIFF | VD_IMAGE_FLAGS_NONE \
94 | VD_VMDK_IMAGE_FLAGS_SPLIT_2G | VD_VMDK_IMAGE_FLAGS_RAWDISK \
95 | VD_VMDK_IMAGE_FLAGS_STREAM_OPTIMIZED | VD_VMDK_IMAGE_FLAGS_ESX)
96
97/** Mask of valid image flags for VDI. */
98#define VD_VDI_IMAGE_FLAGS_MASK (VD_IMAGE_FLAGS_FIXED | VD_IMAGE_FLAGS_DIFF | VD_IMAGE_FLAGS_NONE | VD_VDI_IMAGE_FLAGS_ZERO_EXPAND)
99
100/** Mask of all valid image flags for all formats. */
101#define VD_IMAGE_FLAGS_MASK (VD_VMDK_IMAGE_FLAGS_MASK | VD_VDI_IMAGE_FLAGS_MASK)
102
103/** Default image flags. */
104#define VD_IMAGE_FLAGS_DEFAULT (VD_IMAGE_FLAGS_NONE)
105/** @} */
106
107
108/**
109 * Auxiliary type for describing partitions on raw disks.
110 */
111typedef struct VBOXHDDRAWPART
112{
113 /** Device to use for this partition. Can be the disk device if the offset
114 * field is set appropriately. If this is NULL, then this partition will
115 * not be accessible to the guest. The size of the partition must still
116 * be set correctly. */
117 const char *pszRawDevice;
118 /** Offset where the partition data starts in this device. */
119 uint64_t uPartitionStartOffset;
120 /** Offset where the partition data starts in the disk. */
121 uint64_t uPartitionStart;
122 /** Size of the partition. */
123 uint64_t cbPartition;
124 /** Size of the partitioning info to prepend. */
125 uint64_t cbPartitionData;
126 /** Offset where the partitioning info starts in the disk. */
127 uint64_t uPartitionDataStart;
128 /** Pointer to the partitioning info to prepend. */
129 const void *pvPartitionData;
130} VBOXHDDRAWPART, *PVBOXHDDRAWPART;
131
132/**
133 * Auxiliary data structure for creating raw disks.
134 */
135typedef struct VBOXHDDRAW
136{
137 /** Signature for structure. Must be 'R', 'A', 'W', '\0'. Actually a trick
138 * to make logging of the comment string produce sensible results. */
139 char szSignature[4];
140 /** Flag whether access to full disk should be given (ignoring the
141 * partition information below). */
142 bool fRawDisk;
143 /** Filename for the raw disk. Ignored for partitioned raw disks.
144 * For Linux e.g. /dev/sda, and for Windows e.g. \\.\PhysicalDisk0. */
145 const char *pszRawDisk;
146 /** Number of entries in the partitions array. */
147 unsigned cPartitions;
148 /** Pointer to the partitions array. */
149 PVBOXHDDRAWPART pPartitions;
150} VBOXHDDRAW, *PVBOXHDDRAW;
151
152/** @name VBox HDD container image open mode flags
153 * @{
154 */
155/** Try to open image in read/write exclusive access mode if possible, or in read-only elsewhere. */
156#define VD_OPEN_FLAGS_NORMAL 0
157/** Open image in read-only mode with sharing access with others. */
158#define VD_OPEN_FLAGS_READONLY RT_BIT(0)
159/** Honor zero block writes instead of ignoring them whenever possible.
160 * This is not supported by all formats. It is silently ignored in this case. */
161#define VD_OPEN_FLAGS_HONOR_ZEROES RT_BIT(1)
162/** Honor writes of the same data instead of ignoring whenever possible.
163 * This is handled generically, and is only meaningful for differential image
164 * formats. It is silently ignored otherwise. */
165#define VD_OPEN_FLAGS_HONOR_SAME RT_BIT(2)
166/** Do not perform the base/diff image check on open. This does NOT imply
167 * opening the image as readonly (would break e.g. adding UUIDs to VMDK files
168 * created by other products). Images opened with this flag should only be
169 * used for querying information, and nothing else. */
170#define VD_OPEN_FLAGS_INFO RT_BIT(3)
171/** Open image for asynchronous access.
172 * Only available if VD_CAP_ASYNC_IO is set
173 * Check with VDIsAsynchonousIoSupported wether
174 * asynchronous I/O is really supported for this file.
175 */
176#define VD_OPEN_FLAGS_ASYNC_IO RT_BIT(4)
177/** Mask of valid flags. */
178#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)
179/** @}*/
180
181
182/** @name VBox HDD container backend capability flags
183 * @{
184 */
185/** Supports UUIDs as expected by VirtualBox code. */
186#define VD_CAP_UUID RT_BIT(0)
187/** Supports creating fixed size images, allocating all space instantly. */
188#define VD_CAP_CREATE_FIXED RT_BIT(1)
189/** Supports creating dynamically growing images, allocating space on demand. */
190#define VD_CAP_CREATE_DYNAMIC RT_BIT(2)
191/** Supports creating images split in chunks of a bit less than 2GBytes. */
192#define VD_CAP_CREATE_SPLIT_2G RT_BIT(3)
193/** Supports being used as differencing image format backend. */
194#define VD_CAP_DIFF RT_BIT(4)
195/** Supports asynchronous I/O operations for at least some configurations. */
196#define VD_CAP_ASYNC RT_BIT(5)
197/** The backend operates on files. The caller needs to know to handle the
198 * location appropriately. */
199#define VD_CAP_FILE RT_BIT(6)
200/** The backend uses the config interface. The caller needs to know how to
201 * provide the mandatory configuration parts this way. */
202#define VD_CAP_CONFIG RT_BIT(7)
203/** The backend uses the network stack interface. The caller has to provide
204 * the appropriate interface. */
205#define VD_CAP_TCPNET RT_BIT(8)
206/** @}*/
207
208/**
209 * Supported interface types.
210 */
211typedef enum VDINTERFACETYPE
212{
213 /** First valid interface. */
214 VDINTERFACETYPE_FIRST = 0,
215 /** Interface to pass error message to upper layers. Per-disk. */
216 VDINTERFACETYPE_ERROR = VDINTERFACETYPE_FIRST,
217 /** Interface for asynchronous I/O operations. Per-disk. */
218 VDINTERFACETYPE_ASYNCIO,
219 /** Interface for progress notification. Per-operation. */
220 VDINTERFACETYPE_PROGRESS,
221 /** Interface for configuration information. Per-image. */
222 VDINTERFACETYPE_CONFIG,
223 /** Interface for TCP network stack. Per-disk. */
224 VDINTERFACETYPE_TCPNET,
225 /** invalid interface. */
226 VDINTERFACETYPE_INVALID
227} VDINTERFACETYPE;
228
229/**
230 * Common structure for all interfaces.
231 */
232typedef struct VDINTERFACE
233{
234 /** Human readable interface name. */
235 const char *pszInterfaceName;
236 /** The size of the struct. */
237 uint32_t cbSize;
238 /** Pointer to the next common interface structure. */
239 struct VDINTERFACE *pNext;
240 /** Interface type. */
241 VDINTERFACETYPE enmInterface;
242 /** Opaque user data which is passed on every call. */
243 void *pvUser;
244 /** Pointer to the function call table of the interface.
245 * As this is opaque this must be casted to the right interface
246 * struct defined below based on the interface type in enmInterface. */
247 void *pCallbacks;
248} VDINTERFACE;
249/** Pointer to a VDINTERFACE. */
250typedef VDINTERFACE *PVDINTERFACE;
251/** Pointer to a const VDINTERFACE. */
252typedef const VDINTERFACE *PCVDINTERFACE;
253
254/**
255 * Helper functions to handle interface lists.
256 *
257 * @note These interface lists are used consistently to pass per-disk,
258 * per-image and/or per-operation callbacks. Those three purposes are strictly
259 * separate. See the individual interface declarations for what context they
260 * apply to. The caller is responsible for ensuring that the lifetime of the
261 * interface descriptors is appropriate for the category of interface.
262 */
263
264/**
265 * Get a specific interface from a list of interfaces specified by the type.
266 *
267 * @return Pointer to the matching interface or NULL if none was found.
268 * @param pVDIfs Pointer to the VD interface list.
269 * @param enmInterface Interface to search for.
270 */
271DECLINLINE(PVDINTERFACE) VDInterfaceGet(PVDINTERFACE pVDIfs, VDINTERFACETYPE enmInterface)
272{
273 AssertMsgReturn( (enmInterface >= VDINTERFACETYPE_FIRST)
274 && (enmInterface < VDINTERFACETYPE_INVALID),
275 ("enmInterface=%u", enmInterface), NULL);
276
277 while (pVDIfs)
278 {
279 /* Sanity checks. */
280 AssertMsgBreak(pVDIfs->cbSize == sizeof(VDINTERFACE),
281 ("cbSize=%u\n", pVDIfs->cbSize));
282
283 if (pVDIfs->enmInterface == enmInterface)
284 return pVDIfs;
285 pVDIfs = pVDIfs->pNext;
286 }
287
288 /* No matching interface was found. */
289 return NULL;
290}
291
292/**
293 * Add an interface to a list of interfaces.
294 *
295 * @return VBox status code.
296 * @param pInterface Pointer to an unitialized common interface structure.
297 * @param pszName Name of the interface.
298 * @param enmInterface Type of the interface.
299 * @param pCallbacks The callback table of the interface.
300 * @param pvUser Opaque user data passed on every function call.
301 * @param ppVDIfs Pointer to the VD interface list.
302 */
303DECLINLINE(int) VDInterfaceAdd(PVDINTERFACE pInterface, const char *pszName,
304 VDINTERFACETYPE enmInterface, void *pCallbacks,
305 void *pvUser, PVDINTERFACE *ppVDIfs)
306{
307
308 /** Argument checks. */
309 AssertMsgReturn( (enmInterface >= VDINTERFACETYPE_FIRST)
310 && (enmInterface < VDINTERFACETYPE_INVALID),
311 ("enmInterface=%u", enmInterface), VERR_INVALID_PARAMETER);
312
313 AssertMsgReturn(VALID_PTR(pCallbacks),
314 ("pCallbacks=%#p", pCallbacks),
315 VERR_INVALID_PARAMETER);
316
317 AssertMsgReturn(VALID_PTR(ppVDIfs),
318 ("pInterfaceList=%#p", ppVDIfs),
319 VERR_INVALID_PARAMETER);
320
321 /* Fill out interface descriptor. */
322 pInterface->cbSize = sizeof(VDINTERFACE);
323 pInterface->pszInterfaceName = pszName;
324 pInterface->enmInterface = enmInterface;
325 pInterface->pCallbacks = pCallbacks;
326 pInterface->pvUser = pvUser;
327 pInterface->pNext = *ppVDIfs;
328
329 /* Remember the new start of the list. */
330 *ppVDIfs = pInterface;
331
332 return VINF_SUCCESS;
333}
334
335/**
336 * Interface to deliver error messages to upper layers.
337 *
338 * Per disk interface. Optional, but think twice if you want to miss the
339 * opportunity of reporting better human-readable error messages.
340 */
341typedef struct VDINTERFACEERROR
342{
343 /**
344 * Size of the error interface.
345 */
346 uint32_t cbSize;
347
348 /**
349 * Interface type.
350 */
351 VDINTERFACETYPE enmInterface;
352
353 /**
354 * Error message callback.
355 *
356 * @param pvUser The opaque data passed on container creation.
357 * @param rc The VBox error code.
358 * @param RT_SRC_POS_DECL Use RT_SRC_POS.
359 * @param pszFormat Error message format string.
360 * @param va Error message arguments.
361 */
362 DECLR3CALLBACKMEMBER(void, pfnError, (void *pvUser, int rc, RT_SRC_POS_DECL, const char *pszFormat, va_list va));
363
364} VDINTERFACEERROR, *PVDINTERFACEERROR;
365
366/**
367 * Get error interface from opaque callback table.
368 *
369 * @return Pointer to the callback table.
370 * @param pInterface Pointer to the interface descriptor.
371 */
372DECLINLINE(PVDINTERFACEERROR) VDGetInterfaceError(PVDINTERFACE pInterface)
373{
374 /* Check that the interface descriptor is a error interface. */
375 AssertMsgReturn( (pInterface->enmInterface == VDINTERFACETYPE_ERROR)
376 && (pInterface->cbSize == sizeof(VDINTERFACE)),
377 ("Not an error interface"), NULL);
378
379 PVDINTERFACEERROR pInterfaceError = (PVDINTERFACEERROR)pInterface->pCallbacks;
380
381 /* Do basic checks. */
382 AssertMsgReturn( (pInterfaceError->cbSize == sizeof(VDINTERFACEERROR))
383 && (pInterfaceError->enmInterface == VDINTERFACETYPE_ERROR),
384 ("A non error callback table attached to a error interface descriptor\n"), NULL);
385
386 return pInterfaceError;
387}
388
389/**
390 * Completion callback which is called by the interface owner
391 * to inform the backend that a task finished.
392 *
393 * @return VBox status code.
394 * @param pvUser Opaque user data which is passed on request submission.
395 */
396typedef DECLCALLBACK(int) FNVDCOMPLETED(void *pvUser);
397/** Pointer to FNVDCOMPLETED() */
398typedef FNVDCOMPLETED *PFNVDCOMPLETED;
399
400
401/**
402 * Support interface for asynchronous I/O
403 *
404 * Per-disk. Optional.
405 */
406typedef struct VDINTERFACEASYNCIO
407{
408 /**
409 * Size of the async interface.
410 */
411 uint32_t cbSize;
412
413 /**
414 * Interface type.
415 */
416 VDINTERFACETYPE enmInterface;
417
418 /**
419 * Open callback
420 *
421 * @return VBox status code.
422 * @param pvUser The opaque data passed on container creation.
423 * @param pszLocation Name of the location to open.
424 * @param fReadonly Whether to open the storage medium read only.
425 * @param ppStorage Where to store the opaque storage handle.
426 */
427 DECLR3CALLBACKMEMBER(int, pfnOpen, (void *pvUser, const char *pszLocation, bool fReadonly, void **ppStorage));
428
429 /**
430 * Close callback.
431 *
432 * @return VBox status code.
433 * @param pvUser The opaque data passed on container creation.
434 * @param pStorage The opaque storage handle to close.
435 */
436 DECLR3CALLBACKMEMBER(int, pfnClose, (void *pvUser, void *pStorage));
437
438 /**
439 * Synchronous write callback.
440 *
441 * @return VBox status code.
442 * @param pvUser The opaque data passed on container creation.
443 * @param pStorage The storage handle to use.
444 * @param uOffset The offset to start from.
445 * @param cbWrite How many bytes to write.
446 * @param pvBuf Pointer to the bits need to be written.
447 * @param pcbWritten Where to store how many bytes where actually written.
448 */
449 DECLR3CALLBACKMEMBER(int, pfnWrite, (void *pvUser, void *pStorage, uint64_t uOffset,
450 size_t cbWrite, const void *pvBuf, size_t *pcbWritten));
451
452 /**
453 * Synchronous read callback.
454 *
455 * @return VBox status code.
456 * @param pvUser The opaque data passed on container creation.
457 * @param pStorage The storage handle to use.
458 * @param uOffset The offset to start from.
459 * @param cbRead How many bytes to read.
460 * @param pvBuf Where to store the read bits.
461 * @param pcbRead Where to store how many bytes where actually read.
462 */
463 DECLR3CALLBACKMEMBER(int, pfnRead, (void *pvUser, void *pStorage, uint64_t uOffset,
464 size_t cbRead, void *pvBuf, size_t *pcbRead));
465
466 /**
467 * Flush data to the storage backend.
468 *
469 * @return VBox statis code.
470 * @param pvUser The opaque data passed on container creation.
471 * @param pStorage The storage handle to flush.
472 */
473 DECLR3CALLBACKMEMBER(int, pfnFlush, (void *pvUser, void *pStorage));
474
475 /**
476 * Prepare an asynchronous read task.
477 *
478 * @return VBox status code.
479 * @param pvUser The opqaue user data passed on container creation.
480 * @param pStorage The storage handle.
481 * @param uOffset The offset to start reading from.
482 * @param pvBuf Where to store read bits.
483 * @param cbRead How many bytes to read.
484 * @param ppTask Where to store the opaque task handle.
485 */
486 DECLR3CALLBACKMEMBER(int, pfnPrepareRead, (void *pvUser, void *pStorage, uint64_t uOffset,
487 void *pvBuf, size_t cbRead, void **ppTask));
488
489 /**
490 * Prepare an asynchronous write task.
491 *
492 * @return VBox status code.
493 * @param pvUser The opaque user data passed on conatiner creation.
494 * @param pStorage The storage handle.
495 * @param uOffset The offset to start writing to.
496 * @param pvBuf Where to read the data from.
497 * @param cbWrite How many bytes to write.
498 * @param ppTask Where to store the opaque task handle.
499 */
500 DECLR3CALLBACKMEMBER(int, pfnPrepareWrite, (void *pvUser, void *pStorage, uint64_t uOffset,
501 void *pvBuf, size_t cbWrite, void **ppTask));
502
503 /**
504 * Submit an array of tasks for processing
505 *
506 * @return VBox status code.
507 * @param pvUser The opaque user data passed on container creation.
508 * @param apTasks Array of task handles to submit.
509 * @param cTasks How many tasks to submit.
510 * @param pvUser2 User data which is passed on completion.
511 * @param pvUserCaller Opaque user data the caller of VDAsyncWrite/Read passed.
512 * @param pfnTasksCompleted Pointer to callback which is called on request completion.
513 */
514 DECLR3CALLBACKMEMBER(int, pfnTasksSubmit, (void *pvUser, void *apTasks[], unsigned cTasks, void *pvUser2,
515 void *pvUserCaller, PFNVDCOMPLETED pfnTasksCompleted));
516
517} VDINTERFACEASYNCIO, *PVDINTERFACEASYNCIO;
518
519/**
520 * Get async I/O interface from opaque callback table.
521 *
522 * @return Pointer to the callback table.
523 * @param pInterface Pointer to the interface descriptor.
524 */
525DECLINLINE(PVDINTERFACEASYNCIO) VDGetInterfaceAsyncIO(PVDINTERFACE pInterface)
526{
527 /* Check that the interface descriptor is a async I/O interface. */
528 AssertMsgReturn( (pInterface->enmInterface == VDINTERFACETYPE_ASYNCIO)
529 && (pInterface->cbSize == sizeof(VDINTERFACE)),
530 ("Not an async I/O interface"), NULL);
531
532 PVDINTERFACEASYNCIO pInterfaceAsyncIO = (PVDINTERFACEASYNCIO)pInterface->pCallbacks;
533
534 /* Do basic checks. */
535 AssertMsgReturn( (pInterfaceAsyncIO->cbSize == sizeof(VDINTERFACEASYNCIO))
536 && (pInterfaceAsyncIO->enmInterface == VDINTERFACETYPE_ASYNCIO),
537 ("A non async I/O callback table attached to a async I/O interface descriptor\n"), NULL);
538
539 return pInterfaceAsyncIO;
540}
541
542/**
543 * Progress notification interface
544 *
545 * Per-operation. Optional.
546 */
547typedef struct VDINTERFACEPROGRESS
548{
549 /**
550 * Size of the progress interface.
551 */
552 uint32_t cbSize;
553
554 /**
555 * Interface type.
556 */
557 VDINTERFACETYPE enmInterface;
558
559 /**
560 * Progress notification callbacks.
561 * @todo r=bird: Why the heck are we using PFNVMPROGRESS here?
562 */
563 PFNVMPROGRESS pfnProgress;
564} VDINTERFACEPROGRESS, *PVDINTERFACEPROGRESS;
565
566/**
567 * Get progress interface from opaque callback table.
568 *
569 * @return Pointer to the callback table.
570 * @param pInterface Pointer to the interface descriptor.
571 */
572DECLINLINE(PVDINTERFACEPROGRESS) VDGetInterfaceProgress(PVDINTERFACE pInterface)
573{
574 /* Check that the interface descriptor is a progress interface. */
575 AssertMsgReturn( (pInterface->enmInterface == VDINTERFACETYPE_PROGRESS)
576 && (pInterface->cbSize == sizeof(VDINTERFACE)),
577 ("Not a progress interface"), NULL);
578
579
580 PVDINTERFACEPROGRESS pInterfaceProgress = (PVDINTERFACEPROGRESS)pInterface->pCallbacks;
581
582 /* Do basic checks. */
583 AssertMsgReturn( (pInterfaceProgress->cbSize == sizeof(VDINTERFACEPROGRESS))
584 && (pInterfaceProgress->enmInterface == VDINTERFACETYPE_PROGRESS),
585 ("A non progress callback table attached to a progress interface descriptor\n"), NULL);
586
587 return pInterfaceProgress;
588}
589
590
591/**
592 * Configuration information interface
593 *
594 * Per-image. Optional for most backends, but mandatory for images which do
595 * not operate on files (including standard block or character devices).
596 */
597typedef struct VDINTERFACECONFIG
598{
599 /**
600 * Size of the configuration interface.
601 */
602 uint32_t cbSize;
603
604 /**
605 * Interface type.
606 */
607 VDINTERFACETYPE enmInterface;
608
609 /**
610 * Validates that the keys are within a set of valid names.
611 *
612 * @return true if all key names are found in pszzAllowed.
613 * @return false if not.
614 * @param pvUser The opaque user data associated with this interface.
615 * @param pszzValid List of valid key names separated by '\\0' and ending with
616 * a double '\\0'.
617 */
618 DECLR3CALLBACKMEMBER(bool, pfnAreKeysValid, (void *pvUser, const char *pszzValid));
619
620 /**
621 * Retrieves the length of the string value associated with a key (including
622 * the terminator, for compatibility with CFGMR3QuerySize).
623 *
624 * @return VBox status code.
625 * VERR_CFGM_VALUE_NOT_FOUND means that the key is not known.
626 * @param pvUser The opaque user data associated with this interface.
627 * @param pszName Name of the key to query.
628 * @param pcbValue Where to store the value length. Non-NULL.
629 */
630 DECLR3CALLBACKMEMBER(int, pfnQuerySize, (void *pvUser, const char *pszName, size_t *pcbValue));
631
632 /**
633 * Query the string value associated with a key.
634 *
635 * @return VBox status code.
636 * VERR_CFGM_VALUE_NOT_FOUND means that the key is not known.
637 * VERR_CFGM_NOT_ENOUGH_SPACE means that the buffer is not big enough.
638 * @param pvUser The opaque user data associated with this interface.
639 * @param pszName Name of the key to query.
640 * @param pszValue Pointer to buffer where to store value.
641 * @param cchValue Length of value buffer.
642 */
643 DECLR3CALLBACKMEMBER(int, pfnQuery, (void *pvUser, const char *pszName, char *pszValue, size_t cchValue));
644} VDINTERFACECONFIG, *PVDINTERFACECONFIG;
645
646/**
647 * Get configuration information interface from opaque callback table.
648 *
649 * @return Pointer to the callback table.
650 * @param pInterface Pointer to the interface descriptor.
651 */
652DECLINLINE(PVDINTERFACECONFIG) VDGetInterfaceConfig(PVDINTERFACE pInterface)
653{
654 /* Check that the interface descriptor is a config interface. */
655 AssertMsgReturn( (pInterface->enmInterface == VDINTERFACETYPE_CONFIG)
656 && (pInterface->cbSize == sizeof(VDINTERFACE)),
657 ("Not a config interface"), NULL);
658
659 PVDINTERFACECONFIG pInterfaceConfig = (PVDINTERFACECONFIG)pInterface->pCallbacks;
660
661 /* Do basic checks. */
662 AssertMsgReturn( (pInterfaceConfig->cbSize == sizeof(VDINTERFACECONFIG))
663 && (pInterfaceConfig->enmInterface == VDINTERFACETYPE_CONFIG),
664 ("A non config callback table attached to a config interface descriptor\n"), NULL);
665
666 return pInterfaceConfig;
667}
668
669/**
670 * Query configuration, validates that the keys are within a set of valid names.
671 *
672 * @return true if all key names are found in pszzAllowed.
673 * @return false if not.
674 * @param pCfgIf Pointer to configuration callback table.
675 * @param pvUser The opaque user data associated with this interface.
676 * @param pszzValid List of valid names separated by '\\0' and ending with
677 * a double '\\0'.
678 */
679DECLINLINE(bool) VDCFGAreKeysValid(PVDINTERFACECONFIG pCfgIf, void *pvUser,
680 const char *pszzValid)
681{
682 return pCfgIf->pfnAreKeysValid(pvUser, pszzValid);
683}
684
685/**
686 * Query configuration, unsigned 64-bit integer value with default.
687 *
688 * @return VBox status code.
689 * @param pCfgIf Pointer to configuration callback table.
690 * @param pvUser The opaque user data associated with this interface.
691 * @param pszName Name of an integer value
692 * @param pu64 Where to store the value. Set to default on failure.
693 * @param u64Def The default value.
694 */
695DECLINLINE(int) VDCFGQueryU64Def(PVDINTERFACECONFIG pCfgIf, void *pvUser,
696 const char *pszName, uint64_t *pu64,
697 uint64_t u64Def)
698{
699 char aszBuf[32];
700 int rc = pCfgIf->pfnQuery(pvUser, pszName, aszBuf, sizeof(aszBuf));
701 if (RT_SUCCESS(rc))
702 {
703 rc = RTStrToUInt64Full(aszBuf, 0, pu64);
704 }
705 else if (rc == VERR_CFGM_VALUE_NOT_FOUND)
706 {
707 rc = VINF_SUCCESS;
708 *pu64 = u64Def;
709 }
710 return rc;
711}
712
713/**
714 * Query configuration, unsigned 32-bit integer value with default.
715 *
716 * @return VBox status code.
717 * @param pCfgIf Pointer to configuration callback table.
718 * @param pvUser The opaque user data associated with this interface.
719 * @param pszName Name of an integer value
720 * @param pu32 Where to store the value. Set to default on failure.
721 * @param u32Def The default value.
722 */
723DECLINLINE(int) VDCFGQueryU32Def(PVDINTERFACECONFIG pCfgIf, void *pvUser,
724 const char *pszName, uint32_t *pu32,
725 uint32_t u32Def)
726{
727 uint64_t u64;
728 int rc = VDCFGQueryU64Def(pCfgIf, pvUser, pszName, &u64, u32Def);
729 if (RT_SUCCESS(rc))
730 {
731 if (!(u64 & UINT64_C(0xffffffff00000000)))
732 *pu32 = (uint32_t)u64;
733 else
734 rc = VERR_CFGM_INTEGER_TOO_BIG;
735 }
736 return rc;
737}
738
739/**
740 * Query configuration, bool value with default.
741 *
742 * @return VBox status code.
743 * @param pCfgIf Pointer to configuration callback table.
744 * @param pvUser The opaque user data associated with this interface.
745 * @param pszName Name of an integer value
746 * @param pf Where to store the value. Set to default on failure.
747 * @param fDef The default value.
748 */
749DECLINLINE(int) VDCFGQueryBoolDef(PVDINTERFACECONFIG pCfgIf, void *pvUser,
750 const char *pszName, bool *pf,
751 bool fDef)
752{
753 uint64_t u64;
754 int rc = VDCFGQueryU64Def(pCfgIf, pvUser, pszName, &u64, fDef);
755 if (RT_SUCCESS(rc))
756 *pf = u64 ? true : false;
757 return rc;
758}
759
760/**
761 * Query configuration, dynamically allocated (RTMemAlloc) zero terminated
762 * character value.
763 *
764 * @return VBox status code.
765 * @param pCfgIf Pointer to configuration callback table.
766 * @param pvUser The opaque user data associated with this interface.
767 * @param pszName Name of an zero terminated character value
768 * @param ppszString Where to store the string pointer. Not set on failure.
769 * Free this using RTMemFree().
770 */
771DECLINLINE(int) VDCFGQueryStringAlloc(PVDINTERFACECONFIG pCfgIf,
772 void *pvUser, const char *pszName,
773 char **ppszString)
774{
775 size_t cb;
776 int rc = pCfgIf->pfnQuerySize(pvUser, pszName, &cb);
777 if (RT_SUCCESS(rc))
778 {
779 char *pszString = (char *)RTMemAlloc(cb);
780 if (pszString)
781 {
782 rc = pCfgIf->pfnQuery(pvUser, pszName, pszString, cb);
783 if (RT_SUCCESS(rc))
784 *ppszString = pszString;
785 else
786 RTMemFree(pszString);
787 }
788 else
789 rc = VERR_NO_MEMORY;
790 }
791 return rc;
792}
793
794/**
795 * Query configuration, dynamically allocated (RTMemAlloc) zero terminated
796 * character value with default.
797 *
798 * @return VBox status code.
799 * @param pCfgIf Pointer to configuration callback table.
800 * @param pvUser The opaque user data associated with this interface.
801 * @param pszName Name of an zero terminated character value
802 * @param ppszString Where to store the string pointer. Not set on failure.
803 * Free this using RTMemFree().
804 * @param pszDef The default value.
805 */
806DECLINLINE(int) VDCFGQueryStringAllocDef(PVDINTERFACECONFIG pCfgIf,
807 void *pvUser, const char *pszName,
808 char **ppszString,
809 const char *pszDef)
810{
811 size_t cb;
812 int rc = pCfgIf->pfnQuerySize(pvUser, pszName, &cb);
813 if (rc == VERR_CFGM_VALUE_NOT_FOUND || rc == VERR_CFGM_NO_PARENT)
814 {
815 cb = strlen(pszDef) + 1;
816 rc = VINF_SUCCESS;
817 }
818 if (RT_SUCCESS(rc))
819 {
820 char *pszString = (char *)RTMemAlloc(cb);
821 if (pszString)
822 {
823 rc = pCfgIf->pfnQuery(pvUser, pszName, pszString, cb);
824 if (rc == VERR_CFGM_VALUE_NOT_FOUND || rc == VERR_CFGM_NO_PARENT)
825 {
826 memcpy(pszString, pszDef, cb);
827 rc = VINF_SUCCESS;
828 }
829 if (RT_SUCCESS(rc))
830 *ppszString = pszString;
831 else
832 RTMemFree(pszString);
833 }
834 else
835 rc = VERR_NO_MEMORY;
836 }
837 return rc;
838}
839
840/**
841 * Query configuration, dynamically allocated (RTMemAlloc) byte string value.
842 *
843 * @return VBox status code.
844 * @param pCfgIf Pointer to configuration callback table.
845 * @param pvUser The opaque user data associated with this interface.
846 * @param pszName Name of an zero terminated character value
847 * @param ppvData Where to store the byte string pointer. Not set on failure.
848 * Free this using RTMemFree().
849 * @param pcbData Where to store the byte string length.
850 */
851DECLINLINE(int) VDCFGQueryBytesAlloc(PVDINTERFACECONFIG pCfgIf,
852 void *pvUser, const char *pszName,
853 void **ppvData, size_t *pcbData)
854{
855 size_t cb;
856 int rc = pCfgIf->pfnQuerySize(pvUser, pszName, &cb);
857 if (RT_SUCCESS(rc))
858 {
859 char *pvData = (char *)RTMemAlloc(cb);
860 if (pvData)
861 {
862 rc = pCfgIf->pfnQuery(pvUser, pszName, pvData, cb);
863 if (RT_SUCCESS(rc))
864 {
865 *ppvData = pvData;
866 *pcbData = cb;
867 }
868 else
869 RTMemFree(pvData);
870 }
871 else
872 rc = VERR_NO_MEMORY;
873 }
874 return rc;
875}
876
877
878/**
879 * TCP network stack interface
880 *
881 * Per-disk. Mandatory for backends which have the VD_CAP_TCPNET bit set.
882 */
883typedef struct VDINTERFACETCPNET
884{
885 /**
886 * Size of the configuration interface.
887 */
888 uint32_t cbSize;
889
890 /**
891 * Interface type.
892 */
893 VDINTERFACETYPE enmInterface;
894
895 /**
896 * Connect as a client to a TCP port.
897 *
898 * @return iprt status code.
899 * @param pszAddress The address to connect to.
900 * @param uPort The port to connect to.
901 * @param pSock Where to store the handle to the established connect
902ion.
903 */
904 DECLR3CALLBACKMEMBER(int, pfnClientConnect, (const char *pszAddress, uint32_t uPort, PRTSOCKET pSock));
905
906 /**
907 * Close a TCP connection.
908 *
909 * @return iprt status code.
910 * @param Sock Socket descriptor.
911ion.
912 */
913 DECLR3CALLBACKMEMBER(int, pfnClientClose, (RTSOCKET Sock));
914
915 /**
916 * Socket I/O multiplexing.
917 * Checks if the socket is ready for reading.
918 *
919 * @return iprt status code.
920 * @param Sock Socket descriptor.
921 * @param cMillies Number of milliseconds to wait for the socket.
922 * Use RT_INDEFINITE_WAIT to wait for ever.
923 */
924 DECLR3CALLBACKMEMBER(int, pfnSelectOne, (RTSOCKET Sock, unsigned cMillies));
925
926 /**
927 * Receive data from a socket.
928 *
929 * @return iprt status code.
930 * @param Sock Socket descriptor.
931 * @param pvBuffer Where to put the data we read.
932 * @param cbBuffer Read buffer size.
933 * @param pcbRead Number of bytes read.
934 * If NULL the entire buffer will be filled upon successful return.
935 * If not NULL a partial read can be done successfully.
936 */
937 DECLR3CALLBACKMEMBER(int, pfnRead, (RTSOCKET Sock, void *pvBuffer, size_t cbBuffer, size_t *pcbRead));
938
939 /**
940 * Send data from a socket.
941 *
942 * @return iprt status code.
943 * @param Sock Socket descriptor.
944 * @param pvBuffer Buffer to write data to socket.
945 * @param cbBuffer How much to write.
946 * @param pcbRead Number of bytes read.
947 */
948 DECLR3CALLBACKMEMBER(int, pfnWrite, (RTSOCKET Sock, const void *pvBuffer, size_t cbBuffer));
949
950 /**
951 * Flush socket write buffers.
952 *
953 * @return iprt status code.
954 * @param Sock Socket descriptor.
955 */
956 DECLR3CALLBACKMEMBER(int, pfnFlush, (RTSOCKET Sock));
957
958} VDINTERFACETCPNET, *PVDINTERFACETCPNET;
959
960/**
961 * Get TCP network stack interface from opaque callback table.
962 *
963 * @return Pointer to the callback table.
964 * @param pInterface Pointer to the interface descriptor.
965 */
966DECLINLINE(PVDINTERFACETCPNET) VDGetInterfaceTcpNet(PVDINTERFACE pInterface)
967{
968 /* Check that the interface descriptor is a TCP network stack interface. */
969 AssertMsgReturn( (pInterface->enmInterface == VDINTERFACETYPE_TCPNET)
970 && (pInterface->cbSize == sizeof(VDINTERFACE)),
971 ("Not a TCP network stack interface"), NULL);
972
973 PVDINTERFACETCPNET pInterfaceTcpNet = (PVDINTERFACETCPNET)pInterface->pCallbacks;
974
975 /* Do basic checks. */
976 AssertMsgReturn( (pInterfaceTcpNet->cbSize == sizeof(VDINTERFACETCPNET))
977 && (pInterfaceTcpNet->enmInterface == VDINTERFACETYPE_TCPNET),
978 ("A non TCP network stack callback table attached to a TCP network stack interface descriptor\n"), NULL);
979
980 return pInterfaceTcpNet;
981}
982
983
984/** @name Configuration interface key handling flags.
985 * @{
986 */
987/** Mandatory config key. Not providing a value for this key will cause
988 * the backend to fail. */
989#define VD_CFGKEY_MANDATORY RT_BIT(0)
990/** Expert config key. Not showing it by default in the GUI is is probably
991 * a good idea, as the average user won't understand it easily. */
992#define VD_CFGKEY_EXPERT RT_BIT(1)
993/** @}*/
994
995
996/**
997 * Configuration value type for configuration information interface.
998 */
999typedef enum VDCFGVALUETYPE
1000{
1001 /** Integer value. */
1002 VDCFGVALUETYPE_INTEGER = 1,
1003 /** String value. */
1004 VDCFGVALUETYPE_STRING,
1005 /** Bytestring value. */
1006 VDCFGVALUETYPE_BYTES
1007} VDCFGVALUETYPE;
1008
1009
1010/**
1011 * Structure describing configuration keys required/supported by a backend
1012 * through the config interface.
1013 */
1014typedef struct VDCONFIGINFO
1015{
1016 /** Key name of the configuration. */
1017 const char *pszKey;
1018 /** Pointer to default value (descriptor). NULL if no useful default value
1019 * can be specified. */
1020 const char *pszDefaultValue;
1021 /** Value type for this key. */
1022 VDCFGVALUETYPE enmValueType;
1023 /** Key handling flags (a combination of VD_CFGKEY_* flags). */
1024 uint64_t uKeyFlags;
1025} VDCONFIGINFO;
1026
1027/** Pointer to structure describing configuration keys. */
1028typedef VDCONFIGINFO *PVDCONFIGINFO;
1029
1030/** Pointer to const structure describing configuration keys. */
1031typedef const VDCONFIGINFO *PCVDCONFIGINFO;
1032
1033/**
1034 * Data structure for returning a list of backend capabilities.
1035 */
1036typedef struct VDBACKENDINFO
1037{
1038 /** Name of the backend. Must be unique even with case insensitive comparison. */
1039 const char *pszBackend;
1040 /** Capabilities of the backend (a combination of the VD_CAP_* flags). */
1041 uint64_t uBackendCaps;
1042 /** Pointer to a NULL-terminated array of strings, containing the supported
1043 * file extensions. Note that some backends do not work on files, so this
1044 * pointer may just contain NULL. */
1045 const char * const *papszFileExtensions;
1046 /** Pointer to an array of structs describing each supported config key.
1047 * Terminated by a NULL config key. Note that some backends do not support
1048 * the configuration interface, so this pointer may just contain NULL.
1049 * Mandatory if the backend sets VD_CAP_CONFIG. */
1050 PCVDCONFIGINFO paConfigInfo;
1051 /** Returns a human readable hard disk location string given a
1052 * set of hard disk configuration keys. The returned string is an
1053 * equivalent of the full file path for image-based hard disks.
1054 * Mandatory for backends with no VD_CAP_FILE and NULL otherwise. */
1055 DECLR3CALLBACKMEMBER(int, pfnComposeLocation, (PVDINTERFACE pConfig, char **pszLocation));
1056 /** Returns a human readable hard disk name string given a
1057 * set of hard disk configuration keys. The returned string is an
1058 * equivalent of the file name part in the full file path for
1059 * image-based hard disks. Mandatory for backends with no
1060 * VD_CAP_FILE and NULL otherwise. */
1061 DECLR3CALLBACKMEMBER(int, pfnComposeName, (PVDINTERFACE pConfig, char **pszName));
1062} VDBACKENDINFO, *PVDBACKENDINFO;
1063
1064
1065/**
1066 * VBox HDD Container main structure.
1067 */
1068/* Forward declaration, VBOXHDD structure is visible only inside VBox HDD module. */
1069struct VBOXHDD;
1070typedef struct VBOXHDD VBOXHDD;
1071typedef VBOXHDD *PVBOXHDD;
1072
1073/**
1074 * Initializes HDD backends.
1075 *
1076 * @returns VBox status code.
1077 */
1078VBOXDDU_DECL(int) VDInit(void);
1079
1080/**
1081 * Destroys loaded HDD backends.
1082 *
1083 * @returns VBox status code.
1084 */
1085VBOXDDU_DECL(int) VDShutdown(void);
1086
1087/**
1088 * Lists all HDD backends and their capabilities in a caller-provided buffer.
1089 * Free all returned names with RTStrFree() when you no longer need them.
1090 *
1091 * @return VBox status code.
1092 * VERR_BUFFER_OVERFLOW if not enough space is passed.
1093 * @param cEntriesAlloc Number of list entries available.
1094 * @param pEntries Pointer to array for the entries.
1095 * @param pcEntriesUsed Number of entries returned.
1096 */
1097VBOXDDU_DECL(int) VDBackendInfo(unsigned cEntriesAlloc, PVDBACKENDINFO pEntries,
1098 unsigned *pcEntriesUsed);
1099
1100/**
1101 * Lists the capablities of a backend indentified by its name.
1102 * Free all returned names with RTStrFree() when you no longer need them.
1103 *
1104 * @return VBox status code.
1105 * @param pszBackend The backend name (case insensitive).
1106 * @param pEntries Pointer to an entry.
1107 */
1108VBOXDDU_DECL(int) VDBackendInfoOne(const char *pszBackend, PVDBACKENDINFO pEntry);
1109
1110/**
1111 * Allocates and initializes an empty HDD container.
1112 * No image files are opened.
1113 *
1114 * @return VBox status code.
1115 * @param pVDIfsDisk Pointer to the per-disk VD interface list.
1116 * @param ppDisk Where to store the reference to HDD container.
1117 */
1118VBOXDDU_DECL(int) VDCreate(PVDINTERFACE pVDIfsDisk, PVBOXHDD *ppDisk);
1119
1120/**
1121 * Destroys HDD container.
1122 * If container has opened image files they will be closed.
1123 *
1124 * @param pDisk Pointer to HDD container.
1125 */
1126VBOXDDU_DECL(void) VDDestroy(PVBOXHDD pDisk);
1127
1128/**
1129 * Try to get the backend name which can use this image.
1130 *
1131 * @return VBox status code.
1132 * @param pszFilename Name of the image file for which the backend is queried.
1133 * @param ppszFormat Receives pointer of the UTF-8 string which contains the format name.
1134 * The returned pointer must be freed using RTStrFree().
1135 */
1136VBOXDDU_DECL(int) VDGetFormat(const char *pszFilename, char **ppszFormat);
1137
1138/**
1139 * Opens an image file.
1140 *
1141 * The first opened image file in HDD container must have a base image type,
1142 * others (next opened images) must be differencing or undo images.
1143 * Linkage is checked for differencing image to be consistent with the previously opened image.
1144 * When another differencing image is opened and the last image was opened in read/write access
1145 * mode, then the last image is reopened in read-only with deny write sharing mode. This allows
1146 * other processes to use images in read-only mode too.
1147 *
1148 * Note that the image is opened in read-only mode if a read/write open is not possible.
1149 * Use VDIsReadOnly to check open mode.
1150 *
1151 * @return VBox status code.
1152 * @param pDisk Pointer to HDD container.
1153 * @param pszBackend Name of the image file backend to use (case insensitive).
1154 * @param pszFilename Name of the image file to open.
1155 * @param uOpenFlags Image file open mode, see VD_OPEN_FLAGS_* constants.
1156 * @param pVDIfsImage Pointer to the per-image VD interface list.
1157 */
1158VBOXDDU_DECL(int) VDOpen(PVBOXHDD pDisk, const char *pszBackend,
1159 const char *pszFilename, unsigned uOpenFlags,
1160 PVDINTERFACE pVDIfsImage);
1161
1162/**
1163 * Creates and opens a new base image file.
1164 *
1165 * @return VBox status code.
1166 * @param pDisk Pointer to HDD container.
1167 * @param pszBackend Name of the image file backend to use (case insensitive).
1168 * @param pszFilename Name of the image file to create.
1169 * @param cbSize Image size in bytes.
1170 * @param uImageFlags Flags specifying special image features.
1171 * @param pszComment Pointer to image comment. NULL is ok.
1172 * @param pPCHSGeometry Pointer to physical disk geometry <= (16383,16,63). Not NULL.
1173 * @param pLCHSGeometry Pointer to logical disk geometry <= (x,255,63). Not NULL.
1174 * @param pUuid New UUID of the image. If NULL, a new UUID is created.
1175 * @param uOpenFlags Image file open mode, see VD_OPEN_FLAGS_* constants.
1176 * @param pVDIfsImage Pointer to the per-image VD interface list.
1177 * @param pVDIfsOperation Pointer to the per-operation VD interface list.
1178 */
1179VBOXDDU_DECL(int) VDCreateBase(PVBOXHDD pDisk, const char *pszBackend,
1180 const char *pszFilename, uint64_t cbSize,
1181 unsigned uImageFlags, const char *pszComment,
1182 PCPDMMEDIAGEOMETRY pPCHSGeometry,
1183 PCPDMMEDIAGEOMETRY pLCHSGeometry,
1184 PCRTUUID pUuid, unsigned uOpenFlags,
1185 PVDINTERFACE pVDIfsImage,
1186 PVDINTERFACE pVDIfsOperation);
1187
1188/**
1189 * Creates and opens a new differencing image file in HDD container.
1190 * See comments for VDOpen function about differencing images.
1191 *
1192 * @return VBox status code.
1193 * @param pDisk Pointer to HDD container.
1194 * @param pszBackend Name of the image file backend to use (case insensitive).
1195 * @param pszFilename Name of the differencing image file to create.
1196 * @param uImageFlags Flags specifying special image features.
1197 * @param pszComment Pointer to image comment. NULL is ok.
1198 * @param pUuid New UUID of the image. If NULL, a new UUID is created.
1199 * @param pParentUuid New parent UUID of the image. If NULL, the UUID is queried automatically.
1200 * @param uOpenFlags Image file open mode, see VD_OPEN_FLAGS_* constants.
1201 * @param pVDIfsImage Pointer to the per-image VD interface list.
1202 * @param pVDIfsOperation Pointer to the per-operation VD interface list.
1203 */
1204VBOXDDU_DECL(int) VDCreateDiff(PVBOXHDD pDisk, const char *pszBackend,
1205 const char *pszFilename, unsigned uImageFlags,
1206 const char *pszComment, PCRTUUID pUuid,
1207 PCRTUUID pParentUuid, unsigned uOpenFlags,
1208 PVDINTERFACE pVDIfsImage,
1209 PVDINTERFACE pVDIfsOperation);
1210
1211/**
1212 * Merges two images (not necessarily with direct parent/child relationship).
1213 * As a side effect the source image and potentially the other images which
1214 * are also merged to the destination are deleted from both the disk and the
1215 * images in the HDD container.
1216 *
1217 * @return VBox status code.
1218 * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
1219 * @param pDisk Pointer to HDD container.
1220 * @param nImageFrom Name of the image file to merge from.
1221 * @param nImageTo Name of the image file to merge to.
1222 * @param pVDIfsOperation Pointer to the per-operation VD interface list.
1223 */
1224VBOXDDU_DECL(int) VDMerge(PVBOXHDD pDisk, unsigned nImageFrom,
1225 unsigned nImageTo, PVDINTERFACE pVDIfsOperation);
1226
1227/**
1228 * Copies an image from one HDD container to another.
1229 * The copy is opened in the target HDD container.
1230 * It is possible to convert between different image formats, because the
1231 * backend for the destination may be different from the source.
1232 * If both the source and destination reference the same HDD container,
1233 * then the image is moved (by copying/deleting or renaming) to the new location.
1234 * The source container is unchanged if the move operation fails, otherwise
1235 * the image at the new location is opened in the same way as the old one was.
1236 *
1237 * @return VBox status code.
1238 * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
1239 * @param pDiskFrom Pointer to source HDD container.
1240 * @param nImage Image number, counts from 0. 0 is always base image of container.
1241 * @param pDiskTo Pointer to destination HDD container.
1242 * @param pszBackend Name of the image file backend to use (may be NULL to use the same as the source, case insensitive).
1243 * @param pszFilename New name of the image (may be NULL if pDiskFrom == pDiskTo).
1244 * @param fMoveByRename If true, attempt to perform a move by renaming (if successful the new size is ignored).
1245 * @param cbSize New image size (0 means leave unchanged).
1246 * @param uImageFlags Flags specifying special destination image features.
1247 * @param pDstUuid New UUID of the destination image. If NULL, a new UUID is created.
1248 * This parameter is used if and only if a true copy is created.
1249 * In all rename/move cases the UUIDs are copied over.
1250 * @param pVDIfsOperation Pointer to the per-operation VD interface list.
1251 * @param pDstVDIfsImage Pointer to the per-image VD interface list, for the
1252 * destination image.
1253 * @param pDstVDIfsOperation Pointer to the per-operation VD interface list,
1254 * for the destination operation.
1255 */
1256VBOXDDU_DECL(int) VDCopy(PVBOXHDD pDiskFrom, unsigned nImage, PVBOXHDD pDiskTo,
1257 const char *pszBackend, const char *pszFilename,
1258 bool fMoveByRename, uint64_t cbSize,
1259 unsigned uImageFlags, PCRTUUID pDstUuid,
1260 PVDINTERFACE pVDIfsOperation,
1261 PVDINTERFACE pDstVDIfsImage,
1262 PVDINTERFACE pDstVDIfsOperation);
1263
1264/**
1265 * Closes the last opened image file in HDD container.
1266 * If previous image file was opened in read-only mode (that is normal) and closing image
1267 * was opened in read-write mode (the whole disk was in read-write mode) - the previous image
1268 * will be reopened in read/write mode.
1269 *
1270 * @return VBox status code.
1271 * @return VERR_VD_NOT_OPENED if no image is opened in HDD container.
1272 * @param pDisk Pointer to HDD container.
1273 * @param fDelete If true, delete the image from the host disk.
1274 */
1275VBOXDDU_DECL(int) VDClose(PVBOXHDD pDisk, bool fDelete);
1276
1277/**
1278 * Closes all opened image files in HDD container.
1279 *
1280 * @return VBox status code.
1281 * @param pDisk Pointer to HDD container.
1282 */
1283VBOXDDU_DECL(int) VDCloseAll(PVBOXHDD pDisk);
1284
1285/**
1286 * Read data from virtual HDD.
1287 *
1288 * @return VBox status code.
1289 * @return VERR_VD_NOT_OPENED if no image is opened in HDD container.
1290 * @param pDisk Pointer to HDD container.
1291 * @param uOffset Offset of first reading byte from start of disk.
1292 * Must be aligned to a sector boundary.
1293 * @param pvBuf Pointer to buffer for reading data.
1294 * @param cbRead Number of bytes to read.
1295 * Must be aligned to a sector boundary.
1296 */
1297VBOXDDU_DECL(int) VDRead(PVBOXHDD pDisk, uint64_t uOffset, void *pvBuf, size_t cbRead);
1298
1299/**
1300 * Write data to virtual HDD.
1301 *
1302 * @return VBox status code.
1303 * @return VERR_VD_NOT_OPENED if no image is opened in HDD container.
1304 * @param pDisk Pointer to HDD container.
1305 * @param uOffset Offset of first writing byte from start of disk.
1306 * Must be aligned to a sector boundary.
1307 * @param pvBuf Pointer to buffer for writing data.
1308 * @param cbWrite Number of bytes to write.
1309 * Must be aligned to a sector boundary.
1310 */
1311VBOXDDU_DECL(int) VDWrite(PVBOXHDD pDisk, uint64_t uOffset, const void *pvBuf, size_t cbWrite);
1312
1313/**
1314 * Make sure the on disk representation of a virtual HDD is up to date.
1315 *
1316 * @return VBox status code.
1317 * @return VERR_VD_NOT_OPENED if no image is opened in HDD container.
1318 * @param pDisk Pointer to HDD container.
1319 */
1320VBOXDDU_DECL(int) VDFlush(PVBOXHDD pDisk);
1321
1322/**
1323 * Get number of opened images in HDD container.
1324 *
1325 * @return Number of opened images for HDD container. 0 if no images have been opened.
1326 * @param pDisk Pointer to HDD container.
1327 */
1328VBOXDDU_DECL(unsigned) VDGetCount(PVBOXHDD pDisk);
1329
1330/**
1331 * Get read/write mode of HDD container.
1332 *
1333 * @return Virtual disk ReadOnly status.
1334 * @return true if no image is opened in HDD container.
1335 * @param pDisk Pointer to HDD container.
1336 */
1337VBOXDDU_DECL(bool) VDIsReadOnly(PVBOXHDD pDisk);
1338
1339/**
1340 * Get total capacity of an image in HDD container.
1341 *
1342 * @return Virtual disk size in bytes.
1343 * @return 0 if image with specified number was not opened.
1344 * @param pDisk Pointer to HDD container.
1345 * @param nImage Image number, counts from 0. 0 is always base image of container.
1346 */
1347VBOXDDU_DECL(uint64_t) VDGetSize(PVBOXHDD pDisk, unsigned nImage);
1348
1349/**
1350 * Get total file size of an image in HDD container.
1351 *
1352 * @return Virtual disk size in bytes.
1353 * @return 0 if image with specified number was not opened.
1354 * @param pDisk Pointer to HDD container.
1355 * @param nImage Image number, counts from 0. 0 is always base image of container.
1356 */
1357VBOXDDU_DECL(uint64_t) VDGetFileSize(PVBOXHDD pDisk, unsigned nImage);
1358
1359/**
1360 * Get virtual disk PCHS geometry of an image in HDD container.
1361 *
1362 * @return VBox status code.
1363 * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
1364 * @return VERR_VD_GEOMETRY_NOT_SET if no geometry present in the HDD container.
1365 * @param pDisk Pointer to HDD container.
1366 * @param nImage Image number, counts from 0. 0 is always base image of container.
1367 * @param pPCHSGeometry Where to store PCHS geometry. Not NULL.
1368 */
1369VBOXDDU_DECL(int) VDGetPCHSGeometry(PVBOXHDD pDisk, unsigned nImage,
1370 PPDMMEDIAGEOMETRY pPCHSGeometry);
1371
1372/**
1373 * Store virtual disk PCHS geometry of an image in HDD container.
1374 *
1375 * @return VBox status code.
1376 * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
1377 * @param pDisk Pointer to HDD container.
1378 * @param nImage Image number, counts from 0. 0 is always base image of container.
1379 * @param pPCHSGeometry Where to load PCHS geometry from. Not NULL.
1380 */
1381VBOXDDU_DECL(int) VDSetPCHSGeometry(PVBOXHDD pDisk, unsigned nImage,
1382 PCPDMMEDIAGEOMETRY pPCHSGeometry);
1383
1384/**
1385 * Get virtual disk LCHS geometry of an image in HDD container.
1386 *
1387 * @return VBox status code.
1388 * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
1389 * @return VERR_VD_GEOMETRY_NOT_SET if no geometry present in the HDD container.
1390 * @param pDisk Pointer to HDD container.
1391 * @param nImage Image number, counts from 0. 0 is always base image of container.
1392 * @param pLCHSGeometry Where to store LCHS geometry. Not NULL.
1393 */
1394VBOXDDU_DECL(int) VDGetLCHSGeometry(PVBOXHDD pDisk, unsigned nImage,
1395 PPDMMEDIAGEOMETRY pLCHSGeometry);
1396
1397/**
1398 * Store virtual disk LCHS geometry of an image in HDD container.
1399 *
1400 * @return VBox status code.
1401 * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
1402 * @param pDisk Pointer to HDD container.
1403 * @param nImage Image number, counts from 0. 0 is always base image of container.
1404 * @param pLCHSGeometry Where to load LCHS geometry from. Not NULL.
1405 */
1406VBOXDDU_DECL(int) VDSetLCHSGeometry(PVBOXHDD pDisk, unsigned nImage,
1407 PCPDMMEDIAGEOMETRY pLCHSGeometry);
1408
1409/**
1410 * Get version of image in HDD container.
1411 *
1412 * @return VBox status code.
1413 * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
1414 * @param pDisk Pointer to HDD container.
1415 * @param nImage Image number, counts from 0. 0 is always base image of container.
1416 * @param puVersion Where to store the image version.
1417 */
1418VBOXDDU_DECL(int) VDGetVersion(PVBOXHDD pDisk, unsigned nImage,
1419 unsigned *puVersion);
1420
1421/**
1422 * List the capabilities of image backend in HDD container.
1423 *
1424 * @return VBox status code.
1425 * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
1426 * @param pDisk Pointer to the HDD container.
1427 * @param nImage Image number, counts from 0. 0 is always base image of container.
1428 * @param pbackendInfo Where to store the backend information.
1429 */
1430VBOXDDU_DECL(int) VDBackendInfoSingle(PVBOXHDD pDisk, unsigned nImage,
1431 PVDBACKENDINFO pBackendInfo);
1432
1433/**
1434 * Get flags of image in HDD container.
1435 *
1436 * @return VBox status code.
1437 * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
1438 * @param pDisk Pointer to HDD container.
1439 * @param nImage Image number, counts from 0. 0 is always base image of container.
1440 * @param puImageFlags Where to store the image flags.
1441 */
1442VBOXDDU_DECL(int) VDGetImageFlags(PVBOXHDD pDisk, unsigned nImage, unsigned *puImageFlags);
1443
1444/**
1445 * Get open flags of image in HDD container.
1446 *
1447 * @return VBox status code.
1448 * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
1449 * @param pDisk Pointer to HDD container.
1450 * @param nImage Image number, counts from 0. 0 is always base image of container.
1451 * @param puOpenFlags Where to store the image open flags.
1452 */
1453VBOXDDU_DECL(int) VDGetOpenFlags(PVBOXHDD pDisk, unsigned nImage,
1454 unsigned *puOpenFlags);
1455
1456/**
1457 * Set open flags of image in HDD container.
1458 * This operation may cause file locking changes and/or files being reopened.
1459 * Note that in case of unrecoverable error all images in HDD container will be closed.
1460 *
1461 * @return VBox status code.
1462 * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
1463 * @param pDisk Pointer to HDD container.
1464 * @param nImage Image number, counts from 0. 0 is always base image of container.
1465 * @param uOpenFlags Image file open mode, see VD_OPEN_FLAGS_* constants.
1466 */
1467VBOXDDU_DECL(int) VDSetOpenFlags(PVBOXHDD pDisk, unsigned nImage,
1468 unsigned uOpenFlags);
1469
1470/**
1471 * Get base filename of image in HDD container. Some image formats use
1472 * other filenames as well, so don't use this for anything but informational
1473 * purposes.
1474 *
1475 * @return VBox status code.
1476 * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
1477 * @return VERR_BUFFER_OVERFLOW if pszFilename buffer too small to hold filename.
1478 * @param pDisk Pointer to HDD container.
1479 * @param nImage Image number, counts from 0. 0 is always base image of container.
1480 * @param pszFilename Where to store the image file name.
1481 * @param cbFilename Size of buffer pszFilename points to.
1482 */
1483VBOXDDU_DECL(int) VDGetFilename(PVBOXHDD pDisk, unsigned nImage,
1484 char *pszFilename, unsigned cbFilename);
1485
1486/**
1487 * Get the comment line of image in HDD container.
1488 *
1489 * @return VBox status code.
1490 * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
1491 * @return VERR_BUFFER_OVERFLOW if pszComment buffer too small to hold comment text.
1492 * @param pDisk Pointer to HDD container.
1493 * @param nImage Image number, counts from 0. 0 is always base image of container.
1494 * @param pszComment Where to store the comment string of image. NULL is ok.
1495 * @param cbComment The size of pszComment buffer. 0 is ok.
1496 */
1497VBOXDDU_DECL(int) VDGetComment(PVBOXHDD pDisk, unsigned nImage,
1498 char *pszComment, unsigned cbComment);
1499
1500/**
1501 * Changes the comment line of image in HDD container.
1502 *
1503 * @return VBox status code.
1504 * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
1505 * @param pDisk Pointer to HDD container.
1506 * @param nImage Image number, counts from 0. 0 is always base image of container.
1507 * @param pszComment New comment string (UTF-8). NULL is allowed to reset the comment.
1508 */
1509VBOXDDU_DECL(int) VDSetComment(PVBOXHDD pDisk, unsigned nImage,
1510 const char *pszComment);
1511
1512/**
1513 * Get UUID of image in HDD container.
1514 *
1515 * @return VBox status code.
1516 * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
1517 * @param pDisk Pointer to HDD container.
1518 * @param nImage Image number, counts from 0. 0 is always base image of container.
1519 * @param pUuid Where to store the image UUID.
1520 */
1521VBOXDDU_DECL(int) VDGetUuid(PVBOXHDD pDisk, unsigned nImage, PRTUUID pUuid);
1522
1523/**
1524 * Set the image's UUID. Should not be used by normal applications.
1525 *
1526 * @return VBox status code.
1527 * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
1528 * @param pDisk Pointer to HDD container.
1529 * @param nImage Image number, counts from 0. 0 is always base image of container.
1530 * @param pUuid New UUID of the image. If NULL, a new UUID is created.
1531 */
1532VBOXDDU_DECL(int) VDSetUuid(PVBOXHDD pDisk, unsigned nImage, PCRTUUID pUuid);
1533
1534/**
1535 * Get last modification UUID of image in HDD container.
1536 *
1537 * @return VBox status code.
1538 * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
1539 * @param pDisk Pointer to HDD container.
1540 * @param nImage Image number, counts from 0. 0 is always base image of container.
1541 * @param pUuid Where to store the image modification UUID.
1542 */
1543VBOXDDU_DECL(int) VDGetModificationUuid(PVBOXHDD pDisk, unsigned nImage,
1544 PRTUUID pUuid);
1545
1546/**
1547 * Set the image's last modification UUID. Should not be used by normal applications.
1548 *
1549 * @return VBox status code.
1550 * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
1551 * @param pDisk Pointer to HDD container.
1552 * @param nImage Image number, counts from 0. 0 is always base image of container.
1553 * @param pUuid New modification UUID of the image. If NULL, a new UUID is created.
1554 */
1555VBOXDDU_DECL(int) VDSetModificationUuid(PVBOXHDD pDisk, unsigned nImage,
1556 PCRTUUID pUuid);
1557
1558/**
1559 * Get parent UUID of image in HDD container.
1560 *
1561 * @return VBox status code.
1562 * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
1563 * @param pDisk Pointer to HDD container.
1564 * @param nImage Image number, counts from 0. 0 is always base image of the container.
1565 * @param pUuid Where to store the parent image UUID.
1566 */
1567VBOXDDU_DECL(int) VDGetParentUuid(PVBOXHDD pDisk, unsigned nImage,
1568 PRTUUID pUuid);
1569
1570/**
1571 * Set the image's parent UUID. Should not be used by normal applications.
1572 *
1573 * @return VBox status code.
1574 * @param pDisk Pointer to HDD container.
1575 * @param nImage Image number, counts from 0. 0 is always base image of container.
1576 * @param pUuid New parent UUID of the image. If NULL, a new UUID is created.
1577 */
1578VBOXDDU_DECL(int) VDSetParentUuid(PVBOXHDD pDisk, unsigned nImage,
1579 PCRTUUID pUuid);
1580
1581
1582/**
1583 * Debug helper - dumps all opened images in HDD container into the log file.
1584 *
1585 * @param pDisk Pointer to HDD container.
1586 */
1587VBOXDDU_DECL(void) VDDumpImages(PVBOXHDD pDisk);
1588
1589
1590/**
1591 * Query if asynchronous operations are supported for this disk.
1592 *
1593 * @return VBox status code.
1594 * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
1595 * @param pDisk Pointer to the HDD container.
1596 * @param nImage Image number, counts from 0. 0 is always base image of container.
1597 * @param pfAIOSupported Where to store if async IO is supported.
1598 */
1599VBOXDDU_DECL(int) VDImageIsAsyncIOSupported(PVBOXHDD pDisk, unsigned nImage, bool *pfAIOSupported);
1600
1601
1602/**
1603 * Start a asynchronous read request.
1604 *
1605 * @return VBox status code.
1606 * @param pDisk Pointer to the HDD container.
1607 * @param uOffset The offset of the virtual disk to read from.
1608 * @param cbRead How many bytes to read.
1609 * @param paSeg Pointer to an array of segments.
1610 * @param cSeg Number of segments in the array.
1611 * @param pvUser User data which is passed on completion
1612 */
1613VBOXDDU_DECL(int) VDAsyncRead(PVBOXHDD pDisk, uint64_t uOffset, size_t cbRead,
1614 PPDMDATASEG paSeg, unsigned cSeg,
1615 void *pvUser);
1616
1617
1618/**
1619 * Start a asynchronous write request.
1620 *
1621 * @return VBox status code.
1622 * @param pDisk Pointer to the HDD container.
1623 * @param uOffset The offset of the virtual disk to write to.
1624 * @param cbWrtie How many bytes to write.
1625 * @param paSeg Pointer to an array of segments.
1626 * @param cSeg Number of segments in the array.
1627 * @param pvUser User data which is passed on completion.
1628 */
1629VBOXDDU_DECL(int) VDAsyncWrite(PVBOXHDD pDisk, uint64_t uOffset, size_t cbWrite,
1630 PPDMDATASEG paSeg, unsigned cSeg,
1631 void *pvUser);
1632
1633
1634__END_DECLS
1635
1636/** @} */
1637
1638#endif
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette