VirtualBox

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

Last change on this file since 32507 was 32431, checked in by vboxsync, 14 years ago

scm cleanup

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 98.8 KB
Line 
1/** @file
2 * VBox HDD Container API.
3 */
4
5/*
6 * Copyright (C) 2006-2010 Oracle Corporation
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
26#ifndef ___VBox_VD_h
27#define ___VBox_VD_h
28
29#include <iprt/assert.h>
30#include <iprt/string.h>
31#include <iprt/mem.h>
32#include <iprt/net.h>
33#include <iprt/sg.h>
34#include <VBox/cdefs.h>
35#include <VBox/types.h>
36#include <VBox/err.h>
37#include <VBox/pdmifs.h>
38
39RT_C_DECLS_BEGIN
40
41#ifdef IN_RING0
42# error "There are no VBox HDD Container APIs available in Ring-0 Host Context!"
43#endif
44
45/** @defgroup grp_vd VBox HDD Container
46 * @{
47 */
48
49/** Current VMDK image version. */
50#define VMDK_IMAGE_VERSION (0x0001)
51
52/** Current VDI image major version. */
53#define VDI_IMAGE_VERSION_MAJOR (0x0001)
54/** Current VDI image minor version. */
55#define VDI_IMAGE_VERSION_MINOR (0x0001)
56/** Current VDI image version. */
57#define VDI_IMAGE_VERSION ((VDI_IMAGE_VERSION_MAJOR << 16) | VDI_IMAGE_VERSION_MINOR)
58
59/** Get VDI major version from combined version. */
60#define VDI_GET_VERSION_MAJOR(uVer) ((uVer) >> 16)
61/** Get VDI minor version from combined version. */
62#define VDI_GET_VERSION_MINOR(uVer) ((uVer) & 0xffff)
63
64/** Placeholder for specifying the last opened image. */
65#define VD_LAST_IMAGE 0xffffffffU
66
67/** @name VBox HDD container image flags
68 * @{
69 */
70/** No flags. */
71#define VD_IMAGE_FLAGS_NONE (0)
72/** Fixed image. */
73#define VD_IMAGE_FLAGS_FIXED (0x10000)
74/** Diff image. Mutually exclusive with fixed image. */
75#define VD_IMAGE_FLAGS_DIFF (0x20000)
76/** VMDK: Split image into 2GB extents. */
77#define VD_VMDK_IMAGE_FLAGS_SPLIT_2G (0x0001)
78/** VMDK: Raw disk image (giving access to a number of host partitions). */
79#define VD_VMDK_IMAGE_FLAGS_RAWDISK (0x0002)
80/** VMDK: stream optimized image, read only. */
81#define VD_VMDK_IMAGE_FLAGS_STREAM_OPTIMIZED (0x0004)
82/** VMDK: ESX variant, use in addition to other flags. */
83#define VD_VMDK_IMAGE_FLAGS_ESX (0x0008)
84/** VDI: Fill new blocks with zeroes while expanding image file. Only valid
85 * for newly created images, never set for opened existing images. */
86#define VD_VDI_IMAGE_FLAGS_ZERO_EXPAND (0x0100)
87
88/** Mask of valid image flags for VMDK. */
89#define VD_VMDK_IMAGE_FLAGS_MASK ( VD_IMAGE_FLAGS_FIXED | VD_IMAGE_FLAGS_DIFF | VD_IMAGE_FLAGS_NONE \
90 | VD_VMDK_IMAGE_FLAGS_SPLIT_2G | VD_VMDK_IMAGE_FLAGS_RAWDISK \
91 | VD_VMDK_IMAGE_FLAGS_STREAM_OPTIMIZED | VD_VMDK_IMAGE_FLAGS_ESX)
92
93/** Mask of valid image flags for VDI. */
94#define VD_VDI_IMAGE_FLAGS_MASK (VD_IMAGE_FLAGS_FIXED | VD_IMAGE_FLAGS_DIFF | VD_IMAGE_FLAGS_NONE | VD_VDI_IMAGE_FLAGS_ZERO_EXPAND)
95
96/** Mask of all valid image flags for all formats. */
97#define VD_IMAGE_FLAGS_MASK (VD_VMDK_IMAGE_FLAGS_MASK | VD_VDI_IMAGE_FLAGS_MASK)
98
99/** Default image flags. */
100#define VD_IMAGE_FLAGS_DEFAULT (VD_IMAGE_FLAGS_NONE)
101/** @} */
102
103
104/**
105 * Auxiliary type for describing partitions on raw disks. The entries must be
106 * in ascending order (as far as uStart is concerned), and must not overlap.
107 * Note that this does not correspond 1:1 to partitions, it is describing the
108 * general meaning of contiguous areas on the disk.
109 */
110typedef struct VBOXHDDRAWPARTDESC
111{
112 /** Device to use for this partition/data area. Can be the disk device if
113 * the offset field is set appropriately. If this is NULL, then this
114 * partition will not be accessible to the guest. The size of the data area
115 * must still be set correctly. */
116 const char *pszRawDevice;
117 /** Pointer to the partitioning info. NULL means this is a regular data
118 * area on disk, non-NULL denotes data which should be copied to the
119 * partition data overlay. */
120 const void *pvPartitionData;
121 /** Offset where the data starts in this device. */
122 uint64_t uStartOffset;
123 /** Offset where the data starts in the disk. */
124 uint64_t uStart;
125 /** Size of the data area. */
126 uint64_t cbData;
127} VBOXHDDRAWPARTDESC, *PVBOXHDDRAWPARTDESC;
128
129/**
130 * Auxiliary data structure for creating raw disks.
131 */
132typedef struct VBOXHDDRAW
133{
134 /** Signature for structure. Must be 'R', 'A', 'W', '\\0'. Actually a trick
135 * to make logging of the comment string produce sensible results. */
136 char szSignature[4];
137 /** Flag whether access to full disk should be given (ignoring the
138 * partition information below). */
139 bool fRawDisk;
140 /** Filename for the raw disk. Ignored for partitioned raw disks.
141 * For Linux e.g. /dev/sda, and for Windows e.g. \\\\.\\PhysicalDisk0. */
142 const char *pszRawDisk;
143 /** Number of entries in the partition descriptor array. */
144 unsigned cPartDescs;
145 /** Pointer to the partition descriptor array. */
146 PVBOXHDDRAWPARTDESC pPartDescs;
147} VBOXHDDRAW, *PVBOXHDDRAW;
148
149/** @name VBox HDD container image open mode flags
150 * @{
151 */
152/** Try to open image in read/write exclusive access mode if possible, or in read-only elsewhere. */
153#define VD_OPEN_FLAGS_NORMAL 0
154/** Open image in read-only mode with sharing access with others. */
155#define VD_OPEN_FLAGS_READONLY RT_BIT(0)
156/** Honor zero block writes instead of ignoring them whenever possible.
157 * This is not supported by all formats. It is silently ignored in this case. */
158#define VD_OPEN_FLAGS_HONOR_ZEROES RT_BIT(1)
159/** Honor writes of the same data instead of ignoring whenever possible.
160 * This is handled generically, and is only meaningful for differential image
161 * formats. It is silently ignored otherwise. */
162#define VD_OPEN_FLAGS_HONOR_SAME RT_BIT(2)
163/** Do not perform the base/diff image check on open. This does NOT imply
164 * opening the image as readonly (would break e.g. adding UUIDs to VMDK files
165 * created by other products). Images opened with this flag should only be
166 * used for querying information, and nothing else. */
167#define VD_OPEN_FLAGS_INFO RT_BIT(3)
168/** Open image for asynchronous access.
169 * Only available if VD_CAP_ASYNC_IO is set
170 * Check with VDIsAsynchonousIoSupported wether
171 * asynchronous I/O is really supported for this file. */
172#define VD_OPEN_FLAGS_ASYNC_IO RT_BIT(4)
173/** Allow sharing of the image for writable images. May be ignored if the
174 * format backend doesn't support this type of concurrent access. */
175#define VD_OPEN_FLAGS_SHAREABLE RT_BIT(5)
176/** Mask of valid flags. */
177#define VD_OPEN_FLAGS_MASK (VD_OPEN_FLAGS_NORMAL | VD_OPEN_FLAGS_READONLY | VD_OPEN_FLAGS_HONOR_ZEROES | VD_OPEN_FLAGS_HONOR_SAME | VD_OPEN_FLAGS_INFO | VD_OPEN_FLAGS_ASYNC_IO | VD_OPEN_FLAGS_SHAREABLE)
178/** @}*/
179
180
181/** @name VBox HDD container backend capability flags
182 * @{
183 */
184/** Supports UUIDs as expected by VirtualBox code. */
185#define VD_CAP_UUID RT_BIT(0)
186/** Supports creating fixed size images, allocating all space instantly. */
187#define VD_CAP_CREATE_FIXED RT_BIT(1)
188/** Supports creating dynamically growing images, allocating space on demand. */
189#define VD_CAP_CREATE_DYNAMIC RT_BIT(2)
190/** Supports creating images split in chunks of a bit less than 2GBytes. */
191#define VD_CAP_CREATE_SPLIT_2G RT_BIT(3)
192/** Supports being used as differencing image format backend. */
193#define VD_CAP_DIFF RT_BIT(4)
194/** Supports asynchronous I/O operations for at least some configurations. */
195#define VD_CAP_ASYNC RT_BIT(5)
196/** The backend operates on files. The caller needs to know to handle the
197 * location appropriately. */
198#define VD_CAP_FILE RT_BIT(6)
199/** The backend uses the config interface. The caller needs to know how to
200 * provide the mandatory configuration parts this way. */
201#define VD_CAP_CONFIG RT_BIT(7)
202/** The backend uses the network stack interface. The caller has to provide
203 * the appropriate interface. */
204#define VD_CAP_TCPNET RT_BIT(8)
205/** @}*/
206
207/**
208 * Supported interface types.
209 */
210typedef enum VDINTERFACETYPE
211{
212 /** First valid interface. */
213 VDINTERFACETYPE_FIRST = 0,
214 /** Interface to pass error message to upper layers. Per-disk. */
215 VDINTERFACETYPE_ERROR = VDINTERFACETYPE_FIRST,
216 /** Interface for asynchronous I/O operations. Per-disk. */
217 VDINTERFACETYPE_ASYNCIO,
218 /** Interface for progress notification. Per-operation. */
219 VDINTERFACETYPE_PROGRESS,
220 /** Interface for configuration information. Per-image. */
221 VDINTERFACETYPE_CONFIG,
222 /** Interface for TCP network stack. Per-disk. */
223 VDINTERFACETYPE_TCPNET,
224 /** Interface for getting parent image state. Per-operation. */
225 VDINTERFACETYPE_PARENTSTATE,
226 /** Interface for synchronizing accesses from several threads. Per-disk. */
227 VDINTERFACETYPE_THREADSYNC,
228 /** Interface for I/O between the generic VBoxHDD code and the backend. Per-image. */
229 VDINTERFACETYPE_IO,
230 /** invalid interface. */
231 VDINTERFACETYPE_INVALID
232} VDINTERFACETYPE;
233
234/**
235 * Common structure for all interfaces.
236 */
237typedef struct VDINTERFACE
238{
239 /** Human readable interface name. */
240 const char *pszInterfaceName;
241 /** The size of the struct. */
242 uint32_t cbSize;
243 /** Pointer to the next common interface structure. */
244 struct VDINTERFACE *pNext;
245 /** Interface type. */
246 VDINTERFACETYPE enmInterface;
247 /** Opaque user data which is passed on every call. */
248 void *pvUser;
249 /** Pointer to the function call table of the interface.
250 * As this is opaque this must be casted to the right interface
251 * struct defined below based on the interface type in enmInterface. */
252 void *pCallbacks;
253} VDINTERFACE;
254/** Pointer to a VDINTERFACE. */
255typedef VDINTERFACE *PVDINTERFACE;
256/** Pointer to a const VDINTERFACE. */
257typedef const VDINTERFACE *PCVDINTERFACE;
258
259/**
260 * Helper functions to handle interface lists.
261 *
262 * @note These interface lists are used consistently to pass per-disk,
263 * per-image and/or per-operation callbacks. Those three purposes are strictly
264 * separate. See the individual interface declarations for what context they
265 * apply to. The caller is responsible for ensuring that the lifetime of the
266 * interface descriptors is appropriate for the category of interface.
267 */
268
269/**
270 * Get a specific interface from a list of interfaces specified by the type.
271 *
272 * @return Pointer to the matching interface or NULL if none was found.
273 * @param pVDIfs Pointer to the VD interface list.
274 * @param enmInterface Interface to search for.
275 */
276DECLINLINE(PVDINTERFACE) VDInterfaceGet(PVDINTERFACE pVDIfs, VDINTERFACETYPE enmInterface)
277{
278 AssertMsgReturn( enmInterface >= VDINTERFACETYPE_FIRST
279 && enmInterface < VDINTERFACETYPE_INVALID,
280 ("enmInterface=%u", enmInterface), NULL);
281
282 while (pVDIfs)
283 {
284 /* Sanity checks. */
285 AssertMsgBreak(pVDIfs->cbSize == sizeof(VDINTERFACE),
286 ("cbSize=%u\n", pVDIfs->cbSize));
287
288 if (pVDIfs->enmInterface == enmInterface)
289 return pVDIfs;
290 pVDIfs = pVDIfs->pNext;
291 }
292
293 /* No matching interface was found. */
294 return NULL;
295}
296
297/**
298 * Add an interface to a list of interfaces.
299 *
300 * @return VBox status code.
301 * @param pInterface Pointer to an unitialized common interface structure.
302 * @param pszName Name of the interface.
303 * @param enmInterface Type of the interface.
304 * @param pCallbacks The callback table of the interface.
305 * @param pvUser Opaque user data passed on every function call.
306 * @param ppVDIfs Pointer to the VD interface list.
307 */
308DECLINLINE(int) VDInterfaceAdd(PVDINTERFACE pInterface, const char *pszName,
309 VDINTERFACETYPE enmInterface, void *pCallbacks,
310 void *pvUser, PVDINTERFACE *ppVDIfs)
311{
312 /* Argument checks. */
313 AssertMsgReturn( enmInterface >= VDINTERFACETYPE_FIRST
314 && enmInterface < VDINTERFACETYPE_INVALID,
315 ("enmInterface=%u", enmInterface), VERR_INVALID_PARAMETER);
316
317 AssertMsgReturn(VALID_PTR(pCallbacks),
318 ("pCallbacks=%#p", pCallbacks),
319 VERR_INVALID_PARAMETER);
320
321 AssertMsgReturn(VALID_PTR(ppVDIfs),
322 ("pInterfaceList=%#p", ppVDIfs),
323 VERR_INVALID_PARAMETER);
324
325 /* Fill out interface descriptor. */
326 pInterface->cbSize = sizeof(VDINTERFACE);
327 pInterface->pszInterfaceName = pszName;
328 pInterface->enmInterface = enmInterface;
329 pInterface->pCallbacks = pCallbacks;
330 pInterface->pvUser = pvUser;
331 pInterface->pNext = *ppVDIfs;
332
333 /* Remember the new start of the list. */
334 *ppVDIfs = pInterface;
335
336 return VINF_SUCCESS;
337}
338
339/**
340 * Removes an interface from a list of interfaces.
341 *
342 * @return VBox status code
343 * @param pInterface Pointer to an initialized common interface structure to remove.
344 * @param ppVDIfs Pointer to the VD interface list to remove from.
345 */
346DECLINLINE(int) VDInterfaceRemove(PVDINTERFACE pInterface, PVDINTERFACE *ppVDIfs)
347{
348 int rc = VERR_NOT_FOUND;
349
350 /* Argument checks. */
351 AssertMsgReturn(VALID_PTR(pInterface),
352 ("pInterface=%#p", pInterface),
353 VERR_INVALID_PARAMETER);
354
355 AssertMsgReturn(VALID_PTR(ppVDIfs),
356 ("pInterfaceList=%#p", ppVDIfs),
357 VERR_INVALID_PARAMETER);
358
359 if (*ppVDIfs)
360 {
361 PVDINTERFACE pPrev = NULL;
362 PVDINTERFACE pCurr = *ppVDIfs;
363
364 while ( pCurr
365 && (pCurr != pInterface))
366 {
367 pPrev = pCurr;
368 pCurr = pCurr->pNext;
369 }
370
371 /* First interface */
372 if (!pPrev)
373 {
374 *ppVDIfs = pCurr->pNext;
375 rc = VINF_SUCCESS;
376 }
377 else if (pCurr)
378 {
379 pPrev = pCurr->pNext;
380 rc = VINF_SUCCESS;
381 }
382 }
383
384 return rc;
385}
386
387/**
388 * Interface to deliver error messages (and also informational messages)
389 * to upper layers.
390 *
391 * Per disk interface. Optional, but think twice if you want to miss the
392 * opportunity of reporting better human-readable error messages.
393 */
394typedef struct VDINTERFACEERROR
395{
396 /**
397 * Size of the error interface.
398 */
399 uint32_t cbSize;
400
401 /**
402 * Interface type.
403 */
404 VDINTERFACETYPE enmInterface;
405
406 /**
407 * Error message callback. Must be able to accept special IPRT format
408 * strings.
409 *
410 * @param pvUser The opaque data passed on container creation.
411 * @param rc The VBox error code.
412 * @param RT_SRC_POS_DECL Use RT_SRC_POS.
413 * @param pszFormat Error message format string.
414 * @param va Error message arguments.
415 */
416 DECLR3CALLBACKMEMBER(void, pfnError, (void *pvUser, int rc, RT_SRC_POS_DECL, const char *pszFormat, va_list va));
417
418 /**
419 * Informational message callback. May be NULL. Used e.g. in
420 * VDDumpImages(). Must be able to accept special IPRT format strings.
421 *
422 * @return VBox status code.
423 * @param pvUser The opaque data passed on container creation.
424 * @param pszFormat Error message format string.
425 * @param ... Error message arguments.
426 */
427 DECLR3CALLBACKMEMBER(int, pfnMessage, (void *pvUser, const char *pszFormat, ...));
428
429} VDINTERFACEERROR, *PVDINTERFACEERROR;
430
431/**
432 * Get error interface from opaque callback table.
433 *
434 * @return Pointer to the callback table.
435 * @param pInterface Pointer to the interface descriptor.
436 */
437DECLINLINE(PVDINTERFACEERROR) VDGetInterfaceError(PVDINTERFACE pInterface)
438{
439 PVDINTERFACEERROR pInterfaceError;
440
441 /* Check that the interface descriptor is a error interface. */
442 AssertMsgReturn( pInterface->enmInterface == VDINTERFACETYPE_ERROR
443 && pInterface->cbSize == sizeof(VDINTERFACE),
444 ("Not an error interface"), NULL);
445
446 pInterfaceError = (PVDINTERFACEERROR)pInterface->pCallbacks;
447
448 /* Do basic checks. */
449 AssertMsgReturn( pInterfaceError->cbSize == sizeof(VDINTERFACEERROR)
450 && pInterfaceError->enmInterface == VDINTERFACETYPE_ERROR,
451 ("A non error callback table attached to a error interface descriptor\n"), NULL);
452
453 return pInterfaceError;
454}
455
456/**
457 * Completion callback which is called by the interface owner
458 * to inform the backend that a task finished.
459 *
460 * @return VBox status code.
461 * @param pvUser Opaque user data which is passed on request submission.
462 * @param rcReq Status code of the completed request.
463 */
464typedef DECLCALLBACK(int) FNVDCOMPLETED(void *pvUser, int rcReq);
465/** Pointer to FNVDCOMPLETED() */
466typedef FNVDCOMPLETED *PFNVDCOMPLETED;
467
468/** Open the storage readonly. */
469#define VD_INTERFACEASYNCIO_OPEN_FLAGS_READONLY RT_BIT(0)
470/** Create the storage backend if it doesn't exist. */
471#define VD_INTERFACEASYNCIO_OPEN_FLAGS_CREATE RT_BIT(1)
472/** Don't write lock the opened file. */
473#define VD_INTERFACEASYNCIO_OPEN_FLAGS_DONT_LOCK RT_BIT(2)
474
475/**
476 * Support interface for asynchronous I/O
477 *
478 * Per-disk. Optional.
479 */
480typedef struct VDINTERFACEASYNCIO
481{
482 /**
483 * Size of the async interface.
484 */
485 uint32_t cbSize;
486
487 /**
488 * Interface type.
489 */
490 VDINTERFACETYPE enmInterface;
491
492 /**
493 * Open callback
494 *
495 * @return VBox status code.
496 * @param pvUser The opaque data passed on container creation.
497 * @param pszLocation Name of the location to open.
498 * @param uOpenFlags Flags for opening the backend.
499 * See VD_INTERFACEASYNCIO_OPEN_FLAGS_* #defines
500 * @param pfnCompleted The callback which is called whenever a task
501 * completed. The backend has to pass the user data
502 * of the request initiator (ie the one who calls
503 * VDAsyncRead or VDAsyncWrite) in pvCompletion
504 * if this is NULL.
505 * @param pVDIfsDisk Pointer to the per-disk VD interface list.
506 * @param ppStorage Where to store the opaque storage handle.
507 */
508 DECLR3CALLBACKMEMBER(int, pfnOpen, (void *pvUser, const char *pszLocation,
509 unsigned uOpenFlags,
510 PFNVDCOMPLETED pfnCompleted,
511 PVDINTERFACE pVDIfsDisk,
512 void **ppStorage));
513
514 /**
515 * Close callback.
516 *
517 * @return VBox status code.
518 * @param pvUser The opaque data passed on container creation.
519 * @param pStorage The opaque storage handle to close.
520 */
521 DECLR3CALLBACKMEMBER(int, pfnClose, (void *pvUser, void *pStorage));
522
523 /**
524 * Returns the size of the opened storage backend.
525 *
526 * @return VBox status code.
527 * @param pvUser The opaque data passed on container creation.
528 * @param pStorage The opaque storage handle to close.
529 * @param pcbSize Where to store the size of the storage backend.
530 */
531 DECLR3CALLBACKMEMBER(int, pfnGetSize, (void *pvUser, void *pStorage, uint64_t *pcbSize));
532
533 /**
534 * Sets the size of the opened storage backend if possible.
535 *
536 * @return VBox status code.
537 * @retval VERR_NOT_SUPPORTED if the backend does not support this operation.
538 * @param pvUser The opaque data passed on container creation.
539 * @param pStorage The opaque storage handle to close.
540 * @param cbSize The new size of the image.
541 */
542 DECLR3CALLBACKMEMBER(int, pfnSetSize, (void *pvUser, void *pStorage, uint64_t cbSize));
543
544 /**
545 * Synchronous write callback.
546 *
547 * @return VBox status code.
548 * @param pvUser The opaque data passed on container creation.
549 * @param pStorage The storage handle to use.
550 * @param uOffset The offset to start from.
551 * @param cbWrite How many bytes to write.
552 * @param pvBuf Pointer to the bits need to be written.
553 * @param pcbWritten Where to store how many bytes where actually written.
554 */
555 DECLR3CALLBACKMEMBER(int, pfnWriteSync, (void *pvUser, void *pStorage, uint64_t uOffset,
556 size_t cbWrite, const void *pvBuf, size_t *pcbWritten));
557
558 /**
559 * Synchronous read callback.
560 *
561 * @return VBox status code.
562 * @param pvUser The opaque data passed on container creation.
563 * @param pStorage The storage handle to use.
564 * @param uOffset The offset to start from.
565 * @param cbRead How many bytes to read.
566 * @param pvBuf Where to store the read bits.
567 * @param pcbRead Where to store how many bytes where actually read.
568 */
569 DECLR3CALLBACKMEMBER(int, pfnReadSync, (void *pvUser, void *pStorage, uint64_t uOffset,
570 size_t cbRead, void *pvBuf, size_t *pcbRead));
571
572 /**
573 * Flush data to the storage backend.
574 *
575 * @return VBox statis code.
576 * @param pvUser The opaque data passed on container creation.
577 * @param pStorage The storage handle to flush.
578 */
579 DECLR3CALLBACKMEMBER(int, pfnFlushSync, (void *pvUser, void *pStorage));
580
581 /**
582 * Initiate a asynchronous read request.
583 *
584 * @return VBox status code.
585 * @param pvUser The opqaue user data passed on container creation.
586 * @param pStorage The storage handle.
587 * @param uOffset The offset to start reading from.
588 * @param paSegments Scatter gather list to store the data in.
589 * @param cSegments Number of segments in the list.
590 * @param cbRead How many bytes to read.
591 * @param pvCompletion The opaque user data which is returned upon completion.
592 * @param ppTask Where to store the opaque task handle.
593 */
594 DECLR3CALLBACKMEMBER(int, pfnReadAsync, (void *pvUser, void *pStorage, uint64_t uOffset,
595 PCRTSGSEG paSegments, size_t cSegments,
596 size_t cbRead, void *pvCompletion,
597 void **ppTask));
598
599 /**
600 * Initiate a asynchronous write request.
601 *
602 * @return VBox status code.
603 * @param pvUser The opaque user data passed on conatiner creation.
604 * @param pStorage The storage handle.
605 * @param uOffset The offset to start writing to.
606 * @param paSegments Scatter gather list of the data to write
607 * @param cSegments Number of segments in the list.
608 * @param cbWrite How many bytes to write.
609 * @param pvCompletion The opaque user data which is returned upon completion.
610 * @param ppTask Where to store the opaque task handle.
611 */
612 DECLR3CALLBACKMEMBER(int, pfnWriteAsync, (void *pvUser, void *pStorage, uint64_t uOffset,
613 PCRTSGSEG paSegments, size_t cSegments,
614 size_t cbWrite, void *pvCompletion,
615 void **ppTask));
616
617 /**
618 * Initiates a async flush request.
619 *
620 * @return VBox statis code.
621 * @param pvUser The opaque data passed on container creation.
622 * @param pStorage The storage handle to flush.
623 * @param pvCompletion The opaque user data which is returned upon completion.
624 * @param ppTask Where to store the opaque task handle.
625 */
626 DECLR3CALLBACKMEMBER(int, pfnFlushAsync, (void *pvUser, void *pStorage,
627 void *pvCompletion, void **ppTask));
628
629} VDINTERFACEASYNCIO, *PVDINTERFACEASYNCIO;
630
631/**
632 * Get async I/O interface from opaque callback table.
633 *
634 * @return Pointer to the callback table.
635 * @param pInterface Pointer to the interface descriptor.
636 */
637DECLINLINE(PVDINTERFACEASYNCIO) VDGetInterfaceAsyncIO(PVDINTERFACE pInterface)
638{
639 PVDINTERFACEASYNCIO pInterfaceAsyncIO;
640
641 /* Check that the interface descriptor is a async I/O interface. */
642 AssertMsgReturn( (pInterface->enmInterface == VDINTERFACETYPE_ASYNCIO)
643 && (pInterface->cbSize == sizeof(VDINTERFACE)),
644 ("Not an async I/O interface"), NULL);
645
646 pInterfaceAsyncIO = (PVDINTERFACEASYNCIO)pInterface->pCallbacks;
647
648 /* Do basic checks. */
649 AssertMsgReturn( (pInterfaceAsyncIO->cbSize == sizeof(VDINTERFACEASYNCIO))
650 && (pInterfaceAsyncIO->enmInterface == VDINTERFACETYPE_ASYNCIO),
651 ("A non async I/O callback table attached to a async I/O interface descriptor\n"), NULL);
652
653 return pInterfaceAsyncIO;
654}
655
656/**
657 * Callback which provides progress information about a currently running
658 * lengthy operation.
659 *
660 * @return VBox status code.
661 * @param pvUser The opaque user data associated with this interface.
662 * @param uPercent Completion percentage.
663 */
664typedef DECLCALLBACK(int) FNVDPROGRESS(void *pvUser, unsigned uPercentage);
665/** Pointer to FNVDPROGRESS() */
666typedef FNVDPROGRESS *PFNVDPROGRESS;
667
668/**
669 * Progress notification interface
670 *
671 * Per-operation. Optional.
672 */
673typedef struct VDINTERFACEPROGRESS
674{
675 /**
676 * Size of the progress interface.
677 */
678 uint32_t cbSize;
679
680 /**
681 * Interface type.
682 */
683 VDINTERFACETYPE enmInterface;
684
685 /**
686 * Progress notification callbacks.
687 */
688 PFNVDPROGRESS pfnProgress;
689
690} VDINTERFACEPROGRESS, *PVDINTERFACEPROGRESS;
691
692/**
693 * Get progress interface from opaque callback table.
694 *
695 * @return Pointer to the callback table.
696 * @param pInterface Pointer to the interface descriptor.
697 */
698DECLINLINE(PVDINTERFACEPROGRESS) VDGetInterfaceProgress(PVDINTERFACE pInterface)
699{
700 PVDINTERFACEPROGRESS pInterfaceProgress;
701
702 /* Check that the interface descriptor is a progress interface. */
703 AssertMsgReturn( (pInterface->enmInterface == VDINTERFACETYPE_PROGRESS)
704 && (pInterface->cbSize == sizeof(VDINTERFACE)),
705 ("Not a progress interface"), NULL);
706
707
708 pInterfaceProgress = (PVDINTERFACEPROGRESS)pInterface->pCallbacks;
709
710 /* Do basic checks. */
711 AssertMsgReturn( (pInterfaceProgress->cbSize == sizeof(VDINTERFACEPROGRESS))
712 && (pInterfaceProgress->enmInterface == VDINTERFACETYPE_PROGRESS),
713 ("A non progress callback table attached to a progress interface descriptor\n"), NULL);
714
715 return pInterfaceProgress;
716}
717
718
719/**
720 * Configuration information interface
721 *
722 * Per-image. Optional for most backends, but mandatory for images which do
723 * not operate on files (including standard block or character devices).
724 */
725typedef struct VDINTERFACECONFIG
726{
727 /**
728 * Size of the configuration interface.
729 */
730 uint32_t cbSize;
731
732 /**
733 * Interface type.
734 */
735 VDINTERFACETYPE enmInterface;
736
737 /**
738 * Validates that the keys are within a set of valid names.
739 *
740 * @return true if all key names are found in pszzAllowed.
741 * @return false if not.
742 * @param pvUser The opaque user data associated with this interface.
743 * @param pszzValid List of valid key names separated by '\\0' and ending with
744 * a double '\\0'.
745 */
746 DECLR3CALLBACKMEMBER(bool, pfnAreKeysValid, (void *pvUser, const char *pszzValid));
747
748 /**
749 * Retrieves the length of the string value associated with a key (including
750 * the terminator, for compatibility with CFGMR3QuerySize).
751 *
752 * @return VBox status code.
753 * VERR_CFGM_VALUE_NOT_FOUND means that the key is not known.
754 * @param pvUser The opaque user data associated with this interface.
755 * @param pszName Name of the key to query.
756 * @param pcbValue Where to store the value length. Non-NULL.
757 */
758 DECLR3CALLBACKMEMBER(int, pfnQuerySize, (void *pvUser, const char *pszName, size_t *pcbValue));
759
760 /**
761 * Query the string value associated with a key.
762 *
763 * @return VBox status code.
764 * VERR_CFGM_VALUE_NOT_FOUND means that the key is not known.
765 * VERR_CFGM_NOT_ENOUGH_SPACE means that the buffer is not big enough.
766 * @param pvUser The opaque user data associated with this interface.
767 * @param pszName Name of the key to query.
768 * @param pszValue Pointer to buffer where to store value.
769 * @param cchValue Length of value buffer.
770 */
771 DECLR3CALLBACKMEMBER(int, pfnQuery, (void *pvUser, const char *pszName, char *pszValue, size_t cchValue));
772
773} VDINTERFACECONFIG, *PVDINTERFACECONFIG;
774
775/**
776 * Get configuration information interface from opaque callback table.
777 *
778 * @return Pointer to the callback table.
779 * @param pInterface Pointer to the interface descriptor.
780 */
781DECLINLINE(PVDINTERFACECONFIG) VDGetInterfaceConfig(PVDINTERFACE pInterface)
782{
783 PVDINTERFACECONFIG pInterfaceConfig;
784
785 /* Check that the interface descriptor is a config interface. */
786 AssertMsgReturn( (pInterface->enmInterface == VDINTERFACETYPE_CONFIG)
787 && (pInterface->cbSize == sizeof(VDINTERFACE)),
788 ("Not a config interface"), NULL);
789
790 pInterfaceConfig = (PVDINTERFACECONFIG)pInterface->pCallbacks;
791
792 /* Do basic checks. */
793 AssertMsgReturn( (pInterfaceConfig->cbSize == sizeof(VDINTERFACECONFIG))
794 && (pInterfaceConfig->enmInterface == VDINTERFACETYPE_CONFIG),
795 ("A non config callback table attached to a config interface descriptor\n"), NULL);
796
797 return pInterfaceConfig;
798}
799
800/**
801 * Query configuration, validates that the keys are within a set of valid names.
802 *
803 * @return true if all key names are found in pszzAllowed.
804 * @return false if not.
805 * @param pCfgIf Pointer to configuration callback table.
806 * @param pvUser The opaque user data associated with this interface.
807 * @param pszzValid List of valid names separated by '\\0' and ending with
808 * a double '\\0'.
809 */
810DECLINLINE(bool) VDCFGAreKeysValid(PVDINTERFACECONFIG pCfgIf, void *pvUser,
811 const char *pszzValid)
812{
813 return pCfgIf->pfnAreKeysValid(pvUser, pszzValid);
814}
815
816/**
817 * Query configuration, unsigned 64-bit integer value with default.
818 *
819 * @return VBox status code.
820 * @param pCfgIf Pointer to configuration callback table.
821 * @param pvUser The opaque user data associated with this interface.
822 * @param pszName Name of an integer value
823 * @param pu64 Where to store the value. Set to default on failure.
824 * @param u64Def The default value.
825 */
826DECLINLINE(int) VDCFGQueryU64Def(PVDINTERFACECONFIG pCfgIf, void *pvUser,
827 const char *pszName, uint64_t *pu64,
828 uint64_t u64Def)
829{
830 char aszBuf[32];
831 int rc = pCfgIf->pfnQuery(pvUser, pszName, aszBuf, sizeof(aszBuf));
832 if (RT_SUCCESS(rc))
833 {
834 rc = RTStrToUInt64Full(aszBuf, 0, pu64);
835 }
836 else if (rc == VERR_CFGM_VALUE_NOT_FOUND)
837 {
838 rc = VINF_SUCCESS;
839 *pu64 = u64Def;
840 }
841 return rc;
842}
843
844/**
845 * Query configuration, unsigned 32-bit integer value with default.
846 *
847 * @return VBox status code.
848 * @param pCfgIf Pointer to configuration callback table.
849 * @param pvUser The opaque user data associated with this interface.
850 * @param pszName Name of an integer value
851 * @param pu32 Where to store the value. Set to default on failure.
852 * @param u32Def The default value.
853 */
854DECLINLINE(int) VDCFGQueryU32Def(PVDINTERFACECONFIG pCfgIf, void *pvUser,
855 const char *pszName, uint32_t *pu32,
856 uint32_t u32Def)
857{
858 uint64_t u64;
859 int rc = VDCFGQueryU64Def(pCfgIf, pvUser, pszName, &u64, u32Def);
860 if (RT_SUCCESS(rc))
861 {
862 if (!(u64 & UINT64_C(0xffffffff00000000)))
863 *pu32 = (uint32_t)u64;
864 else
865 rc = VERR_CFGM_INTEGER_TOO_BIG;
866 }
867 return rc;
868}
869
870/**
871 * Query configuration, bool value with default.
872 *
873 * @return VBox status code.
874 * @param pCfgIf Pointer to configuration callback table.
875 * @param pvUser The opaque user data associated with this interface.
876 * @param pszName Name of an integer value
877 * @param pf Where to store the value. Set to default on failure.
878 * @param fDef The default value.
879 */
880DECLINLINE(int) VDCFGQueryBoolDef(PVDINTERFACECONFIG pCfgIf, void *pvUser,
881 const char *pszName, bool *pf,
882 bool fDef)
883{
884 uint64_t u64;
885 int rc = VDCFGQueryU64Def(pCfgIf, pvUser, pszName, &u64, fDef);
886 if (RT_SUCCESS(rc))
887 *pf = u64 ? true : false;
888 return rc;
889}
890
891/**
892 * Query configuration, dynamically allocated (RTMemAlloc) zero terminated
893 * character value.
894 *
895 * @return VBox status code.
896 * @param pCfgIf Pointer to configuration callback table.
897 * @param pvUser The opaque user data associated with this interface.
898 * @param pszName Name of an zero terminated character value
899 * @param ppszString Where to store the string pointer. Not set on failure.
900 * Free this using RTMemFree().
901 */
902DECLINLINE(int) VDCFGQueryStringAlloc(PVDINTERFACECONFIG pCfgIf,
903 void *pvUser, const char *pszName,
904 char **ppszString)
905{
906 size_t cb;
907 int rc = pCfgIf->pfnQuerySize(pvUser, pszName, &cb);
908 if (RT_SUCCESS(rc))
909 {
910 char *pszString = (char *)RTMemAlloc(cb);
911 if (pszString)
912 {
913 rc = pCfgIf->pfnQuery(pvUser, pszName, pszString, cb);
914 if (RT_SUCCESS(rc))
915 *ppszString = pszString;
916 else
917 RTMemFree(pszString);
918 }
919 else
920 rc = VERR_NO_MEMORY;
921 }
922 return rc;
923}
924
925/**
926 * Query configuration, dynamically allocated (RTMemAlloc) zero terminated
927 * character value with default.
928 *
929 * @return VBox status code.
930 * @param pCfgIf Pointer to configuration callback table.
931 * @param pvUser The opaque user data associated with this interface.
932 * @param pszName Name of an zero terminated character value
933 * @param ppszString Where to store the string pointer. Not set on failure.
934 * Free this using RTMemFree().
935 * @param pszDef The default value.
936 */
937DECLINLINE(int) VDCFGQueryStringAllocDef(PVDINTERFACECONFIG pCfgIf,
938 void *pvUser, const char *pszName,
939 char **ppszString,
940 const char *pszDef)
941{
942 size_t cb;
943 int rc = pCfgIf->pfnQuerySize(pvUser, pszName, &cb);
944 if (rc == VERR_CFGM_VALUE_NOT_FOUND || rc == VERR_CFGM_NO_PARENT)
945 {
946 cb = strlen(pszDef) + 1;
947 rc = VINF_SUCCESS;
948 }
949 if (RT_SUCCESS(rc))
950 {
951 char *pszString = (char *)RTMemAlloc(cb);
952 if (pszString)
953 {
954 rc = pCfgIf->pfnQuery(pvUser, pszName, pszString, cb);
955 if (rc == VERR_CFGM_VALUE_NOT_FOUND || rc == VERR_CFGM_NO_PARENT)
956 {
957 memcpy(pszString, pszDef, cb);
958 rc = VINF_SUCCESS;
959 }
960 if (RT_SUCCESS(rc))
961 *ppszString = pszString;
962 else
963 RTMemFree(pszString);
964 }
965 else
966 rc = VERR_NO_MEMORY;
967 }
968 return rc;
969}
970
971/**
972 * Query configuration, dynamically allocated (RTMemAlloc) byte string value.
973 *
974 * @return VBox status code.
975 * @param pCfgIf Pointer to configuration callback table.
976 * @param pvUser The opaque user data associated with this interface.
977 * @param pszName Name of an zero terminated character value
978 * @param ppvData Where to store the byte string pointer. Not set on failure.
979 * Free this using RTMemFree().
980 * @param pcbData Where to store the byte string length.
981 */
982DECLINLINE(int) VDCFGQueryBytesAlloc(PVDINTERFACECONFIG pCfgIf,
983 void *pvUser, const char *pszName,
984 void **ppvData, size_t *pcbData)
985{
986 size_t cb;
987 int rc = pCfgIf->pfnQuerySize(pvUser, pszName, &cb);
988 if (RT_SUCCESS(rc))
989 {
990 char *pbData;
991 Assert(cb);
992
993 pbData = (char *)RTMemAlloc(cb);
994 if (pbData)
995 {
996 rc = pCfgIf->pfnQuery(pvUser, pszName, pbData, cb);
997 if (RT_SUCCESS(rc))
998 {
999 *ppvData = pbData;
1000 *pcbData = cb - 1; /* Exclude terminator of the queried string. */
1001 }
1002 else
1003 RTMemFree(pbData);
1004 }
1005 else
1006 rc = VERR_NO_MEMORY;
1007 }
1008 return rc;
1009}
1010
1011/** Forward declaration of a VD socket. */
1012typedef struct VDSOCKETINT *VDSOCKET;
1013/** Pointer to a VD socket. */
1014typedef VDSOCKET *PVDSOCKET;
1015/** Nil socket handle. */
1016#define NIL_VDSOCKET ((VDSOCKET)0)
1017
1018/** Connect flag to indicate that the backend wants to use the extended
1019 * socket I/O multiplexing call. This might not be supported on all configurations
1020 * (internal networking and iSCSI)
1021 * and the backend needs to take appropriate action.
1022 */
1023#define VD_INTERFACETCPNET_CONNECT_EXTENDED_SELECT RT_BIT_32(0)
1024
1025/** @name Select events
1026 * @{ */
1027/** Readable without blocking. */
1028#define VD_INTERFACETCPNET_EVT_READ RT_BIT_32(0)
1029/** Writable without blocking. */
1030#define VD_INTERFACETCPNET_EVT_WRITE RT_BIT_32(1)
1031/** Error condition, hangup, exception or similar. */
1032#define VD_INTERFACETCPNET_EVT_ERROR RT_BIT_32(2)
1033/** Hint for the select that getting interrupted while waiting is more likely.
1034 * The interface implementation can optimize the waiting strategy based on this.
1035 * It is assumed that it is more likely to get one of the above socket events
1036 * instead of being interrupted if the flag is not set. */
1037#define VD_INTERFACETCPNET_HINT_INTERRUPT RT_BIT_32(3)
1038/** Mask of the valid bits. */
1039#define VD_INTERFACETCPNET_EVT_VALID_MASK UINT32_C(0x0000000f)
1040/** @} */
1041
1042/**
1043 * TCP network stack interface
1044 *
1045 * Per-disk. Mandatory for backends which have the VD_CAP_TCPNET bit set.
1046 */
1047typedef struct VDINTERFACETCPNET
1048{
1049 /**
1050 * Size of the configuration interface.
1051 */
1052 uint32_t cbSize;
1053
1054 /**
1055 * Interface type.
1056 */
1057 VDINTERFACETYPE enmInterface;
1058
1059 /**
1060 * Creates a socket. The socket is not connected if this succeeds.
1061 *
1062 * @return iprt status code.
1063 * @retval VERR_NOT_SUPPORTED if the combination of flags is not supported.
1064 * @param fFlags Combination of the VD_INTERFACETCPNET_CONNECT_* #defines.
1065 * @param pSock Where to store the handle.
1066 */
1067 DECLR3CALLBACKMEMBER(int, pfnSocketCreate, (uint32_t fFlags, PVDSOCKET pSock));
1068
1069 /**
1070 * Destroys the socket.
1071 *
1072 * @return iprt status code.
1073 * @param Sock Socket descriptor.
1074 */
1075 DECLR3CALLBACKMEMBER(int, pfnSocketDestroy, (VDSOCKET Sock));
1076
1077 /**
1078 * Connect as a client to a TCP port.
1079 *
1080 * @return iprt status code.
1081 * @param Sock Socket descriptor.
1082 * @param pszAddress The address to connect to.
1083 * @param uPort The port to connect to.
1084 */
1085 DECLR3CALLBACKMEMBER(int, pfnClientConnect, (VDSOCKET Sock, const char *pszAddress, uint32_t uPort));
1086
1087 /**
1088 * Close a TCP connection.
1089 *
1090 * @return iprt status code.
1091 * @param Sock Socket descriptor.
1092 */
1093 DECLR3CALLBACKMEMBER(int, pfnClientClose, (VDSOCKET Sock));
1094
1095 /**
1096 * Returns whether the socket is currently connected to the client.
1097 *
1098 * @returns true if the socket is connected.
1099 * false otherwise.
1100 * @param Sock Socket descriptor.
1101 */
1102 DECLR3CALLBACKMEMBER(bool, pfnIsClientConnected, (VDSOCKET Sock));
1103
1104 /**
1105 * Socket I/O multiplexing.
1106 * Checks if the socket is ready for reading.
1107 *
1108 * @return iprt status code.
1109 * @param Sock Socket descriptor.
1110 * @param cMillies Number of milliseconds to wait for the socket.
1111 * Use RT_INDEFINITE_WAIT to wait for ever.
1112 */
1113 DECLR3CALLBACKMEMBER(int, pfnSelectOne, (VDSOCKET Sock, RTMSINTERVAL cMillies));
1114
1115 /**
1116 * Receive data from a socket.
1117 *
1118 * @return iprt status code.
1119 * @param Sock Socket descriptor.
1120 * @param pvBuffer Where to put the data we read.
1121 * @param cbBuffer Read buffer size.
1122 * @param pcbRead Number of bytes read.
1123 * If NULL the entire buffer will be filled upon successful return.
1124 * If not NULL a partial read can be done successfully.
1125 */
1126 DECLR3CALLBACKMEMBER(int, pfnRead, (VDSOCKET Sock, void *pvBuffer, size_t cbBuffer, size_t *pcbRead));
1127
1128 /**
1129 * Send data to a socket.
1130 *
1131 * @return iprt status code.
1132 * @param Sock Socket descriptor.
1133 * @param pvBuffer Buffer to write data to socket.
1134 * @param cbBuffer How much to write.
1135 */
1136 DECLR3CALLBACKMEMBER(int, pfnWrite, (VDSOCKET Sock, const void *pvBuffer, size_t cbBuffer));
1137
1138 /**
1139 * Send data from scatter/gather buffer to a socket.
1140 *
1141 * @return iprt status code.
1142 * @param Sock Socket descriptor.
1143 * @param pSgBuf Scatter/gather buffer to write data to socket.
1144 */
1145 DECLR3CALLBACKMEMBER(int, pfnSgWrite, (VDSOCKET Sock, PCRTSGBUF pSgBuf));
1146
1147 /**
1148 * Receive data from a socket - not blocking.
1149 *
1150 * @return iprt status code.
1151 * @param Sock Socket descriptor.
1152 * @param pvBuffer Where to put the data we read.
1153 * @param cbBuffer Read buffer size.
1154 * @param pcbRead Number of bytes read.
1155 */
1156 DECLR3CALLBACKMEMBER(int, pfnReadNB, (VDSOCKET Sock, void *pvBuffer, size_t cbBuffer, size_t *pcbRead));
1157
1158 /**
1159 * Send data to a socket - not blocking.
1160 *
1161 * @return iprt status code.
1162 * @param Sock Socket descriptor.
1163 * @param pvBuffer Buffer to write data to socket.
1164 * @param cbBuffer How much to write.
1165 * @param pcbWritten Number of bytes written.
1166 */
1167 DECLR3CALLBACKMEMBER(int, pfnWriteNB, (VDSOCKET Sock, const void *pvBuffer, size_t cbBuffer, size_t *pcbWritten));
1168
1169 /**
1170 * Send data from scatter/gather buffer to a socket - not blocking.
1171 *
1172 * @return iprt status code.
1173 * @param Sock Socket descriptor.
1174 * @param pSgBuf Scatter/gather buffer to write data to socket.
1175 * @param pcbWritten Number of bytes written.
1176 */
1177 DECLR3CALLBACKMEMBER(int, pfnSgWriteNB, (VDSOCKET Sock, PRTSGBUF pSgBuf, size_t *pcbWritten));
1178
1179 /**
1180 * Flush socket write buffers.
1181 *
1182 * @return iprt status code.
1183 * @param Sock Socket descriptor.
1184 */
1185 DECLR3CALLBACKMEMBER(int, pfnFlush, (VDSOCKET Sock));
1186
1187 /**
1188 * Enables or disables delaying sends to coalesce packets.
1189 *
1190 * @return iprt status code.
1191 * @param Sock Socket descriptor.
1192 * @param fEnable When set to true enables coalescing.
1193 */
1194 DECLR3CALLBACKMEMBER(int, pfnSetSendCoalescing, (VDSOCKET Sock, bool fEnable));
1195
1196 /**
1197 * Gets the address of the local side.
1198 *
1199 * @return iprt status code.
1200 * @param Sock Socket descriptor.
1201 * @param pAddr Where to store the local address on success.
1202 */
1203 DECLR3CALLBACKMEMBER(int, pfnGetLocalAddress, (VDSOCKET Sock, PRTNETADDR pAddr));
1204
1205 /**
1206 * Gets the address of the other party.
1207 *
1208 * @return iprt status code.
1209 * @param Sock Socket descriptor.
1210 * @param pAddr Where to store the peer address on success.
1211 */
1212 DECLR3CALLBACKMEMBER(int, pfnGetPeerAddress, (VDSOCKET Sock, PRTNETADDR pAddr));
1213
1214 /**
1215 * Socket I/O multiplexing - extended version which can be woken up.
1216 * Checks if the socket is ready for reading or writing.
1217 *
1218 * @return iprt status code.
1219 * @retval VERR_INTERRUPTED if the thread was woken up by a pfnPoke call.
1220 * @param Sock Socket descriptor.
1221 * @param fEvents Mask of events to wait for.
1222 * @param pfEvents Where to store the received events.
1223 * @param cMillies Number of milliseconds to wait for the socket.
1224 * Use RT_INDEFINITE_WAIT to wait for ever.
1225 */
1226 DECLR3CALLBACKMEMBER(int, pfnSelectOneEx, (VDSOCKET Sock, uint32_t fEvents,
1227 uint32_t *pfEvents, RTMSINTERVAL cMillies));
1228
1229 /**
1230 * Wakes up the thread waiting in pfnSelectOneEx.
1231 *
1232 * @return iprt status code.
1233 * @param Sock Socket descriptor.
1234 */
1235 DECLR3CALLBACKMEMBER(int, pfnPoke, (VDSOCKET Sock));
1236
1237} VDINTERFACETCPNET, *PVDINTERFACETCPNET;
1238
1239/**
1240 * Get TCP network stack interface from opaque callback table.
1241 *
1242 * @return Pointer to the callback table.
1243 * @param pInterface Pointer to the interface descriptor.
1244 */
1245DECLINLINE(PVDINTERFACETCPNET) VDGetInterfaceTcpNet(PVDINTERFACE pInterface)
1246{
1247 PVDINTERFACETCPNET pInterfaceTcpNet;
1248
1249 /* Check that the interface descriptor is a TCP network stack interface. */
1250 AssertMsgReturn( (pInterface->enmInterface == VDINTERFACETYPE_TCPNET)
1251 && (pInterface->cbSize == sizeof(VDINTERFACE)),
1252 ("Not a TCP network stack interface"), NULL);
1253
1254 pInterfaceTcpNet = (PVDINTERFACETCPNET)pInterface->pCallbacks;
1255
1256 /* Do basic checks. */
1257 AssertMsgReturn( (pInterfaceTcpNet->cbSize == sizeof(VDINTERFACETCPNET))
1258 && (pInterfaceTcpNet->enmInterface == VDINTERFACETYPE_TCPNET),
1259 ("A non TCP network stack callback table attached to a TCP network stack interface descriptor\n"), NULL);
1260
1261 return pInterfaceTcpNet;
1262}
1263
1264/**
1265 * Interface to get the parent state.
1266 *
1267 * Per operation interface. Optional, present only if there is a parent, and
1268 * used only internally for compacting.
1269 */
1270typedef struct VDINTERFACEPARENTSTATE
1271{
1272 /**
1273 * Size of the parent state interface.
1274 */
1275 uint32_t cbSize;
1276
1277 /**
1278 * Interface type.
1279 */
1280 VDINTERFACETYPE enmInterface;
1281
1282 /**
1283 * Read data callback.
1284 *
1285 * @return VBox status code.
1286 * @return VERR_VD_NOT_OPENED if no image is opened in HDD container.
1287 * @param pvUser The opaque data passed for the operation.
1288 * @param uOffset Offset of first reading byte from start of disk.
1289 * Must be aligned to a sector boundary.
1290 * @param pvBuf Pointer to buffer for reading data.
1291 * @param cbRead Number of bytes to read.
1292 * Must be aligned to a sector boundary.
1293 */
1294 DECLR3CALLBACKMEMBER(int, pfnParentRead, (void *pvUser, uint64_t uOffset, void *pvBuf, size_t cbRead));
1295
1296} VDINTERFACEPARENTSTATE, *PVDINTERFACEPARENTSTATE;
1297
1298
1299/**
1300 * Get parent state interface from opaque callback table.
1301 *
1302 * @return Pointer to the callback table.
1303 * @param pInterface Pointer to the interface descriptor.
1304 */
1305DECLINLINE(PVDINTERFACEPARENTSTATE) VDGetInterfaceParentState(PVDINTERFACE pInterface)
1306{
1307 PVDINTERFACEPARENTSTATE pInterfaceParentState;
1308
1309 /* Check that the interface descriptor is a parent state interface. */
1310 AssertMsgReturn( (pInterface->enmInterface == VDINTERFACETYPE_PARENTSTATE)
1311 && (pInterface->cbSize == sizeof(VDINTERFACE)),
1312 ("Not a parent state interface"), NULL);
1313
1314 pInterfaceParentState = (PVDINTERFACEPARENTSTATE)pInterface->pCallbacks;
1315
1316 /* Do basic checks. */
1317 AssertMsgReturn( (pInterfaceParentState->cbSize == sizeof(VDINTERFACEPARENTSTATE))
1318 && (pInterfaceParentState->enmInterface == VDINTERFACETYPE_PARENTSTATE),
1319 ("A non parent state callback table attached to a parent state interface descriptor\n"), NULL);
1320
1321 return pInterfaceParentState;
1322}
1323
1324/**
1325 * Interface to synchronize concurrent accesses by several threads.
1326 *
1327 * @note The scope of this interface is to manage concurrent accesses after
1328 * the HDD container has been created, and they must stop before destroying the
1329 * container. Opening or closing images is covered by the synchronization, but
1330 * that does not mean it is safe to close images while a thread executes
1331 * <link to="VDMerge"/> or <link to="VDCopy"/> operating on these images.
1332 * Making them safe would require the lock to be held during the entire
1333 * operation, which prevents other concurrent acitivities.
1334 *
1335 * @note Right now this is kept as simple as possible, and does not even
1336 * attempt to provide enough information to allow e.g. concurrent write
1337 * accesses to different areas of the disk. The reason is that it is very
1338 * difficult to predict which area of a disk is affected by a write,
1339 * especially when different image formats are mixed. Maybe later a more
1340 * sophisticated interface will be provided which has the necessary information
1341 * about worst case affected areas.
1342 *
1343 * Per disk interface. Optional, needed if the disk is accessed concurrently
1344 * by several threads, e.g. when merging diff images while a VM is running.
1345 */
1346typedef struct VDINTERFACETHREADSYNC
1347{
1348 /**
1349 * Size of the thread synchronization interface.
1350 */
1351 uint32_t cbSize;
1352
1353 /**
1354 * Interface type.
1355 */
1356 VDINTERFACETYPE enmInterface;
1357
1358 /**
1359 * Start a read operation.
1360 */
1361 DECLR3CALLBACKMEMBER(int, pfnStartRead, (void *pvUser));
1362
1363 /**
1364 * Finish a read operation.
1365 */
1366 DECLR3CALLBACKMEMBER(int, pfnFinishRead, (void *pvUser));
1367
1368 /**
1369 * Start a write operation.
1370 */
1371 DECLR3CALLBACKMEMBER(int, pfnStartWrite, (void *pvUser));
1372
1373 /**
1374 * Finish a write operation.
1375 */
1376 DECLR3CALLBACKMEMBER(int, pfnFinishWrite, (void *pvUser));
1377
1378} VDINTERFACETHREADSYNC, *PVDINTERFACETHREADSYNC;
1379
1380/**
1381 * Get thread synchronization interface from opaque callback table.
1382 *
1383 * @return Pointer to the callback table.
1384 * @param pInterface Pointer to the interface descriptor.
1385 */
1386DECLINLINE(PVDINTERFACETHREADSYNC) VDGetInterfaceThreadSync(PVDINTERFACE pInterface)
1387{
1388 PVDINTERFACETHREADSYNC pInterfaceThreadSync;
1389
1390 /* Check that the interface descriptor is a thread synchronization interface. */
1391 AssertMsgReturn( (pInterface->enmInterface == VDINTERFACETYPE_THREADSYNC)
1392 && (pInterface->cbSize == sizeof(VDINTERFACE)),
1393 ("Not a thread synchronization interface"), NULL);
1394
1395 pInterfaceThreadSync = (PVDINTERFACETHREADSYNC)pInterface->pCallbacks;
1396
1397 /* Do basic checks. */
1398 AssertMsgReturn( (pInterfaceThreadSync->cbSize == sizeof(VDINTERFACETHREADSYNC))
1399 && (pInterfaceThreadSync->enmInterface == VDINTERFACETYPE_THREADSYNC),
1400 ("A non thread synchronization callback table attached to a thread synchronization interface descriptor\n"), NULL);
1401
1402 return pInterfaceThreadSync;
1403}
1404
1405/** @name Configuration interface key handling flags.
1406 * @{
1407 */
1408/** Mandatory config key. Not providing a value for this key will cause
1409 * the backend to fail. */
1410#define VD_CFGKEY_MANDATORY RT_BIT(0)
1411/** Expert config key. Not showing it by default in the GUI is is probably
1412 * a good idea, as the average user won't understand it easily. */
1413#define VD_CFGKEY_EXPERT RT_BIT(1)
1414/** @}*/
1415
1416
1417/**
1418 * Configuration value type for configuration information interface.
1419 */
1420typedef enum VDCFGVALUETYPE
1421{
1422 /** Integer value. */
1423 VDCFGVALUETYPE_INTEGER = 1,
1424 /** String value. */
1425 VDCFGVALUETYPE_STRING,
1426 /** Bytestring value. */
1427 VDCFGVALUETYPE_BYTES
1428} VDCFGVALUETYPE;
1429
1430
1431/**
1432 * Structure describing configuration keys required/supported by a backend
1433 * through the config interface.
1434 */
1435typedef struct VDCONFIGINFO
1436{
1437 /** Key name of the configuration. */
1438 const char *pszKey;
1439 /** Pointer to default value (descriptor). NULL if no useful default value
1440 * can be specified. */
1441 const char *pszDefaultValue;
1442 /** Value type for this key. */
1443 VDCFGVALUETYPE enmValueType;
1444 /** Key handling flags (a combination of VD_CFGKEY_* flags). */
1445 uint64_t uKeyFlags;
1446} VDCONFIGINFO;
1447
1448/** Pointer to structure describing configuration keys. */
1449typedef VDCONFIGINFO *PVDCONFIGINFO;
1450
1451/** Pointer to const structure describing configuration keys. */
1452typedef const VDCONFIGINFO *PCVDCONFIGINFO;
1453
1454/**
1455 * Data structure for returning a list of backend capabilities.
1456 */
1457typedef struct VDBACKENDINFO
1458{
1459 /** Name of the backend. Must be unique even with case insensitive comparison. */
1460 const char *pszBackend;
1461 /** Capabilities of the backend (a combination of the VD_CAP_* flags). */
1462 uint64_t uBackendCaps;
1463 /** Pointer to a NULL-terminated array of strings, containing the supported
1464 * file extensions. Note that some backends do not work on files, so this
1465 * pointer may just contain NULL. */
1466 const char * const *papszFileExtensions;
1467 /** Pointer to an array of structs describing each supported config key.
1468 * Terminated by a NULL config key. Note that some backends do not support
1469 * the configuration interface, so this pointer may just contain NULL.
1470 * Mandatory if the backend sets VD_CAP_CONFIG. */
1471 PCVDCONFIGINFO paConfigInfo;
1472 /** Returns a human readable hard disk location string given a
1473 * set of hard disk configuration keys. The returned string is an
1474 * equivalent of the full file path for image-based hard disks.
1475 * Mandatory for backends with no VD_CAP_FILE and NULL otherwise. */
1476 DECLR3CALLBACKMEMBER(int, pfnComposeLocation, (PVDINTERFACE pConfig, char **pszLocation));
1477 /** Returns a human readable hard disk name string given a
1478 * set of hard disk configuration keys. The returned string is an
1479 * equivalent of the file name part in the full file path for
1480 * image-based hard disks. Mandatory for backends with no
1481 * VD_CAP_FILE and NULL otherwise. */
1482 DECLR3CALLBACKMEMBER(int, pfnComposeName, (PVDINTERFACE pConfig, char **pszName));
1483} VDBACKENDINFO, *PVDBACKENDINFO;
1484
1485
1486/** Forward declaration. Only visible in the VBoxHDD module. */
1487/** I/O context */
1488typedef struct VDIOCTX *PVDIOCTX;
1489/** Storage backend handle. */
1490typedef struct VDIOSTORAGE *PVDIOSTORAGE;
1491/** Pointer to a storage backend handle. */
1492typedef PVDIOSTORAGE *PPVDIOSTORAGE;
1493
1494/**
1495 * Completion callback for meta/userdata reads or writes.
1496 *
1497 * @return VBox status code.
1498 * VINF_SUCCESS if everything was successful and the transfer can continue.
1499 * VERR_VD_ASYNC_IO_IN_PROGRESS if there is another data transfer pending.
1500 * @param pvBackendData The opaque backend data.
1501 * @param pIoCtx I/O context associated with this request.
1502 * @param pvUser Opaque user data passed during a read/write request.
1503 * @param rcReq Status code for the completed request.
1504 */
1505typedef DECLCALLBACK(int) FNVDXFERCOMPLETED(void *pvBackendData, PVDIOCTX pIoCtx, void *pvUser, int rcReq);
1506/** Pointer to FNVDXFERCOMPLETED() */
1507typedef FNVDXFERCOMPLETED *PFNVDXFERCOMPLETED;
1508
1509/** Metadata transfer handle. */
1510typedef struct VDMETAXFER *PVDMETAXFER;
1511/** Pointer to a metadata transfer handle. */
1512typedef PVDMETAXFER *PPVDMETAXFER;
1513
1514
1515/**
1516 * Support interface for I/O
1517 *
1518 * Per-image. Required.
1519 */
1520typedef struct VDINTERFACEIO
1521{
1522 /**
1523 * Size of the I/O interface.
1524 */
1525 uint32_t cbSize;
1526
1527 /**
1528 * Interface type.
1529 */
1530 VDINTERFACETYPE enmInterface;
1531
1532 /**
1533 * Open callback
1534 *
1535 * @return VBox status code.
1536 * @param pvUser The opaque data passed on container creation.
1537 * @param pszLocation Name of the location to open.
1538 * @param uOpenFlags Flags for opening the backend.
1539 * See VD_INTERFACEASYNCIO_OPEN_FLAGS_* #defines
1540 * @param ppStorage Where to store the storage handle.
1541 */
1542 DECLR3CALLBACKMEMBER(int, pfnOpen, (void *pvUser, const char *pszLocation,
1543 unsigned uOpenFlags, PPVDIOSTORAGE ppStorage));
1544
1545 /**
1546 * Close callback.
1547 *
1548 * @return VBox status code.
1549 * @param pvUser The opaque data passed on container creation.
1550 * @param pStorage The storage handle to close.
1551 */
1552 DECLR3CALLBACKMEMBER(int, pfnClose, (void *pvUser, PVDIOSTORAGE pStorage));
1553
1554 /**
1555 * Returns the size of the opened storage backend.
1556 *
1557 * @return VBox status code.
1558 * @param pvUser The opaque data passed on container creation.
1559 * @param pStorage The storage handle to get the size from.
1560 * @param pcbSize Where to store the size of the storage backend.
1561 */
1562 DECLR3CALLBACKMEMBER(int, pfnGetSize, (void *pvUser, PVDIOSTORAGE pStorage,
1563 uint64_t *pcbSize));
1564
1565 /**
1566 * Sets the size of the opened storage backend if possible.
1567 *
1568 * @return VBox status code.
1569 * @retval VERR_NOT_SUPPORTED if the backend does not support this operation.
1570 * @param pvUser The opaque data passed on container creation.
1571 * @param pStorage The storage handle.
1572 * @param cbSize The new size of the image.
1573 */
1574 DECLR3CALLBACKMEMBER(int, pfnSetSize, (void *pvUser, PVDIOSTORAGE pStorage,
1575 uint64_t cbSize));
1576
1577 /**
1578 * Synchronous write callback.
1579 *
1580 * @return VBox status code.
1581 * @param pvUser The opaque data passed on container creation.
1582 * @param pStorage The storage handle to use.
1583 * @param uOffset The offset to start from.
1584 * @param cbWrite How many bytes to write.
1585 * @param pvBuf Pointer to the bits need to be written.
1586 * @param pcbWritten Where to store how many bytes where actually written.
1587 *
1588 * @notes Do not use in code called from the async read/write entry points in the backends.
1589 * This should be only used during open/close of images and for the support functions
1590 * which are not called while a VM is running (pfnCompact).
1591 */
1592 DECLR3CALLBACKMEMBER(int, pfnWriteSync, (void *pvUser, PVDIOSTORAGE pStorage, uint64_t uOffset,
1593 size_t cbWrite, const void *pvBuf, size_t *pcbWritten));
1594
1595 /**
1596 * Synchronous read callback.
1597 *
1598 * @return VBox status code.
1599 * @param pvUser The opaque data passed on container creation.
1600 * @param pStorage The storage handle to use.
1601 * @param uOffset The offset to start from.
1602 * @param cbRead How many bytes to read.
1603 * @param pvBuf Where to store the read bits.
1604 * @param pcbRead Where to store how many bytes where actually read.
1605 *
1606 * @notes See pfnWriteSync()
1607 */
1608 DECLR3CALLBACKMEMBER(int, pfnReadSync, (void *pvUser, PVDIOSTORAGE pStorage, uint64_t uOffset,
1609 size_t cbRead, void *pvBuf, size_t *pcbRead));
1610
1611 /**
1612 * Flush data to the storage backend.
1613 *
1614 * @return VBox status code.
1615 * @param pvUser The opaque data passed on container creation.
1616 * @param pStorage The storage handle to flush.
1617 *
1618 * @notes See pfnWriteSync()
1619 */
1620 DECLR3CALLBACKMEMBER(int, pfnFlushSync, (void *pvUser, PVDIOSTORAGE pStorage));
1621
1622 /**
1623 * Initiate a asynchronous read request for user data.
1624 *
1625 * @return VBox status code.
1626 * @param pvUser The opaque user data passed on container creation.
1627 * @param pStorage The storage handle.
1628 * @param uOffset The offset to start reading from.
1629 * @param pIoCtx I/O context passed in VDAsyncRead/Write.
1630 * @param cbRead How many bytes to read.
1631 */
1632 DECLR3CALLBACKMEMBER(int, pfnReadUserAsync, (void *pvUser, PVDIOSTORAGE pStorage,
1633 uint64_t uOffset, PVDIOCTX pIoCtx,
1634 size_t cbRead));
1635
1636 /**
1637 * Initiate a asynchronous write request for user data.
1638 *
1639 * @return VBox status code.
1640 * @param pvUser The opaque user data passed on container creation.
1641 * @param pStorage The storage handle.
1642 * @param uOffset The offset to start writing to.
1643 * @param pIoCtx I/O context passed in VDAsyncRead/Write
1644 * @param cbWrite How many bytes to write.
1645 * @param pfnCompleted Completion callback.
1646 * @param pvCompleteUser Opaque user data passed in the completion callback.
1647 */
1648 DECLR3CALLBACKMEMBER(int, pfnWriteUserAsync, (void *pvUser, PVDIOSTORAGE pStorage,
1649 uint64_t uOffset, PVDIOCTX pIoCtx,
1650 size_t cbWrite,
1651 PFNVDXFERCOMPLETED pfnComplete,
1652 void *pvCompleteUser));
1653
1654 /**
1655 * Reads metadata asynchronously from storage.
1656 * The current I/O context will be halted.
1657 *
1658 * @returns VBox status code.
1659 * @param pvUser The opaque user data passed on container creation.
1660 * @param pStorage The storage handle.
1661 * @param uOffset Offset to start reading from.
1662 * @param pvBuf Where to store the data.
1663 * @param cbRead How many bytes to read.
1664 * @param pIoCtx The I/O context which triggered the read.
1665 * @param ppMetaXfer Where to store the metadata transfer handle on success.
1666 * @param pfnCompleted Completion callback.
1667 * @param pvCompleteUser Opaque user data passed in the completion callback.
1668 */
1669 DECLR3CALLBACKMEMBER(int, pfnReadMetaAsync, (void *pvUser, PVDIOSTORAGE pStorage,
1670 uint64_t uOffset, void *pvBuf,
1671 size_t cbRead, PVDIOCTX pIoCtx,
1672 PPVDMETAXFER ppMetaXfer,
1673 PFNVDXFERCOMPLETED pfnComplete,
1674 void *pvCompleteUser));
1675
1676 /**
1677 * Writes metadata asynchronously to storage.
1678 *
1679 * @returns VBox status code.
1680 * @param pvUser The opaque user data passed on container creation.
1681 * @param pStorage The storage handle.
1682 * @param uOffset Offset to start writing to.
1683 * @param pvBuf Written data.
1684 * @param cbWrite How many bytes to write.
1685 * @param pIoCtx The I/O context which triggered the write.
1686 * @param pfnCompleted Completion callback.
1687 * @param pvCompleteUser Opaque user data passed in the completion callback.
1688 */
1689 DECLR3CALLBACKMEMBER(int, pfnWriteMetaAsync, (void *pvUser, PVDIOSTORAGE pStorage,
1690 uint64_t uOffset, void *pvBuf,
1691 size_t cbWrite, PVDIOCTX pIoCtx,
1692 PFNVDXFERCOMPLETED pfnComplete,
1693 void *pvCompleteUser));
1694
1695 /**
1696 * Releases a metadata transfer handle.
1697 * The free space can be used for another transfer.
1698 *
1699 * @returns nothing.
1700 * @param pvUser The opaque user data passed on container creation.
1701 * @param pMetaXfer The metadata transfer handle to release.
1702 */
1703 DECLR3CALLBACKMEMBER(void, pfnMetaXferRelease, (void *pvUser, PVDMETAXFER pMetaXfer));
1704
1705 /**
1706 * Initiates a async flush request.
1707 *
1708 * @return VBox status code.
1709 * @param pvUser The opaque data passed on container creation.
1710 * @param pStorage The storage handle to flush.
1711 * @param pIoCtx I/O context which triggered the flush.
1712 * @param pfnCompleted Completion callback.
1713 * @param pvCompleteUser Opaque user data passed in the completion callback.
1714 */
1715 DECLR3CALLBACKMEMBER(int, pfnFlushAsync, (void *pvUser, PVDIOSTORAGE pStorage,
1716 PVDIOCTX pIoCtx,
1717 PFNVDXFERCOMPLETED pfnComplete,
1718 void *pvCompleteUser));
1719
1720 /**
1721 * Copies a buffer into the I/O context.
1722 *
1723 * @return Number of bytes copied.
1724 * @param pvUser The opaque user data passed on container creation.
1725 * @param pIoCtx I/O context to copy the data to.
1726 * @param pvBuf Buffer to copy.
1727 * @param cbBuf Number of bytes to copy.
1728 */
1729 DECLR3CALLBACKMEMBER(size_t, pfnIoCtxCopyTo, (void *pvUser, PVDIOCTX pIoCtx,
1730 void *pvBuf, size_t cbBuf));
1731
1732 /**
1733 * Copies data from the I/O context into a buffer.
1734 *
1735 * @return Number of bytes copied.
1736 * @param pvUser The opaque user data passed on container creation.
1737 * @param pIoCtx I/O context to copy the data from.
1738 * @param pvBuf Destination buffer.
1739 * @param cbBuf Number of bytes to copy.
1740 */
1741 DECLR3CALLBACKMEMBER(size_t, pfnIoCtxCopyFrom, (void *pvUser, PVDIOCTX pIoCtx,
1742 void *pvBuf, size_t cbBuf));
1743
1744 /**
1745 * Sets the buffer of the given context to a specific byte.
1746 *
1747 * @return Number of bytes set.
1748 * @param pvUser The opaque user data passed on container creation.
1749 * @param pIoCtx I/O context to copy the data from.
1750 * @param ch The byte to set.
1751 * @param cbSet Number of bytes to set.
1752 */
1753 DECLR3CALLBACKMEMBER(size_t, pfnIoCtxSet, (void *pvUser, PVDIOCTX pIoCtx,
1754 int ch, size_t cbSet));
1755
1756 /**
1757 * Creates a segment array from the I/O context data buffer.
1758 *
1759 * @returns Number of bytes the array describes.
1760 * @param pvUser The opaque user data passed on container creation.
1761 * @param pIoCtx I/O context to copy the data from.
1762 * @param paSeg The uninitialized segment array.
1763 * If NULL pcSeg will contain the number of segments needed
1764 * to describe the requested amount of data.
1765 * @param pcSeg The number of segments the given array has.
1766 * This will hold the actual number of entries needed upon return.
1767 * @param cbData Number of bytes the new array should describe.
1768 */
1769 DECLR3CALLBACKMEMBER(size_t, pfnIoCtxSegArrayCreate, (void *pvUser, PVDIOCTX pIoCtx,
1770 PRTSGSEG paSeg, unsigned *pcSeg,
1771 size_t cbData));
1772 /**
1773 * Marks the given number of bytes as completed and continues the I/O context.
1774 *
1775 * @returns nothing.
1776 * @param pvUser The opaque user data passed on container creation.
1777 * @param pIoCtx The I/O context.
1778 * @param rcReq Status code the request completed with.
1779 * @param cbCompleted Number of bytes completed.
1780 */
1781 DECLR3CALLBACKMEMBER(void, pfnIoCtxCompleted, (void *pvUser, PVDIOCTX pIoCtx,
1782 int rcReq, size_t cbCompleted));
1783} VDINTERFACEIO, *PVDINTERFACEIO;
1784
1785/**
1786 * Get async I/O interface from opaque callback table.
1787 *
1788 * @return Pointer to the callback table.
1789 * @param pInterface Pointer to the interface descriptor.
1790 */
1791DECLINLINE(PVDINTERFACEIO) VDGetInterfaceIO(PVDINTERFACE pInterface)
1792{
1793 PVDINTERFACEIO pInterfaceIO;
1794
1795 /* Check that the interface descriptor is a async I/O interface. */
1796 AssertMsgReturn( (pInterface->enmInterface == VDINTERFACETYPE_IO)
1797 && (pInterface->cbSize == sizeof(VDINTERFACE)),
1798 ("Not an I/O interface"), NULL);
1799
1800 pInterfaceIO = (PVDINTERFACEIO)pInterface->pCallbacks;
1801
1802 /* Do basic checks. */
1803 AssertMsgReturn( (pInterfaceIO->cbSize == sizeof(VDINTERFACEIO))
1804 && (pInterfaceIO->enmInterface == VDINTERFACETYPE_IO),
1805 ("A non I/O callback table attached to a I/O interface descriptor\n"), NULL);
1806
1807 return pInterfaceIO;
1808}
1809
1810/**
1811 * VBox HDD Container main structure.
1812 */
1813/* Forward declaration, VBOXHDD structure is visible only inside VBox HDD module. */
1814struct VBOXHDD;
1815typedef struct VBOXHDD VBOXHDD;
1816typedef VBOXHDD *PVBOXHDD;
1817
1818/**
1819 * Request completion callback for the async read/write API.
1820 */
1821typedef void (FNVDASYNCTRANSFERCOMPLETE) (void *pvUser1, void *pvUser2, int rcReq);
1822/** Pointer to a transfer compelte callback. */
1823typedef FNVDASYNCTRANSFERCOMPLETE *PFNVDASYNCTRANSFERCOMPLETE;
1824
1825/**
1826 * Initializes HDD backends.
1827 *
1828 * @returns VBox status code.
1829 */
1830VBOXDDU_DECL(int) VDInit(void);
1831
1832/**
1833 * Destroys loaded HDD backends.
1834 *
1835 * @returns VBox status code.
1836 */
1837VBOXDDU_DECL(int) VDShutdown(void);
1838
1839/**
1840 * Lists all HDD backends and their capabilities in a caller-provided buffer.
1841 *
1842 * @return VBox status code.
1843 * VERR_BUFFER_OVERFLOW if not enough space is passed.
1844 * @param cEntriesAlloc Number of list entries available.
1845 * @param pEntries Pointer to array for the entries.
1846 * @param pcEntriesUsed Number of entries returned.
1847 */
1848VBOXDDU_DECL(int) VDBackendInfo(unsigned cEntriesAlloc, PVDBACKENDINFO pEntries,
1849 unsigned *pcEntriesUsed);
1850
1851/**
1852 * Lists the capablities of a backend indentified by its name.
1853 *
1854 * @return VBox status code.
1855 * @param pszBackend The backend name (case insensitive).
1856 * @param pEntries Pointer to an entry.
1857 */
1858VBOXDDU_DECL(int) VDBackendInfoOne(const char *pszBackend, PVDBACKENDINFO pEntry);
1859
1860/**
1861 * Allocates and initializes an empty HDD container.
1862 * No image files are opened.
1863 *
1864 * @return VBox status code.
1865 * @param pVDIfsDisk Pointer to the per-disk VD interface list.
1866 * @param ppDisk Where to store the reference to HDD container.
1867 */
1868VBOXDDU_DECL(int) VDCreate(PVDINTERFACE pVDIfsDisk, PVBOXHDD *ppDisk);
1869
1870/**
1871 * Destroys HDD container.
1872 * If container has opened image files they will be closed.
1873 *
1874 * @param pDisk Pointer to HDD container.
1875 */
1876VBOXDDU_DECL(void) VDDestroy(PVBOXHDD pDisk);
1877
1878/**
1879 * Try to get the backend name which can use this image.
1880 *
1881 * @return VBox status code.
1882 * @param pVDIfsDisk Pointer to the per-disk VD interface list.
1883 * @param pszFilename Name of the image file for which the backend is queried.
1884 * @param ppszFormat Receives pointer of the UTF-8 string which contains the format name.
1885 * The returned pointer must be freed using RTStrFree().
1886 */
1887VBOXDDU_DECL(int) VDGetFormat(PVDINTERFACE pVDIfsDisk, const char *pszFilename, char **ppszFormat);
1888
1889/**
1890 * Opens an image file.
1891 *
1892 * The first opened image file in HDD container must have a base image type,
1893 * others (next opened images) must be differencing or undo images.
1894 * Linkage is checked for differencing image to be consistent with the previously opened image.
1895 * When another differencing image is opened and the last image was opened in read/write access
1896 * mode, then the last image is reopened in read-only with deny write sharing mode. This allows
1897 * other processes to use images in read-only mode too.
1898 *
1899 * Note that the image is opened in read-only mode if a read/write open is not possible.
1900 * Use VDIsReadOnly to check open mode.
1901 *
1902 * @return VBox status code.
1903 * @param pDisk Pointer to HDD container.
1904 * @param pszBackend Name of the image file backend to use (case insensitive).
1905 * @param pszFilename Name of the image file to open.
1906 * @param uOpenFlags Image file open mode, see VD_OPEN_FLAGS_* constants.
1907 * @param pVDIfsImage Pointer to the per-image VD interface list.
1908 */
1909VBOXDDU_DECL(int) VDOpen(PVBOXHDD pDisk, const char *pszBackend,
1910 const char *pszFilename, unsigned uOpenFlags,
1911 PVDINTERFACE pVDIfsImage);
1912
1913/**
1914 * Opens a cache image.
1915 *
1916 * @return VBox status code.
1917 * @param pDisk Pointer to the HDD container which should use the cache image.
1918 * @param pszBackend Name of the cache file backend to use (case insensitive).
1919 * @param pszFilename Name of the cache image to open.
1920 * @param uOpenFlags Image file open mode, see VD_OPEN_FLAGS_* constants.
1921 * @param pVDIfsCache Pointer to the per-cache VD interface list.
1922 */
1923VBOXDDU_DECL(int) VDCacheOpen(PVBOXHDD pDisk, const char *pszBackend,
1924 const char *pszFilename, unsigned uOpenFlags,
1925 PVDINTERFACE pVDIfsCache);
1926
1927/**
1928 * Creates and opens a new base image file.
1929 *
1930 * @return VBox status code.
1931 * @param pDisk Pointer to HDD container.
1932 * @param pszBackend Name of the image file backend to use (case insensitive).
1933 * @param pszFilename Name of the image file to create.
1934 * @param cbSize Image size in bytes.
1935 * @param uImageFlags Flags specifying special image features.
1936 * @param pszComment Pointer to image comment. NULL is ok.
1937 * @param pPCHSGeometry Pointer to physical disk geometry <= (16383,16,63). Not NULL.
1938 * @param pLCHSGeometry Pointer to logical disk geometry <= (x,255,63). Not NULL.
1939 * @param pUuid New UUID of the image. If NULL, a new UUID is created.
1940 * @param uOpenFlags Image file open mode, see VD_OPEN_FLAGS_* constants.
1941 * @param pVDIfsImage Pointer to the per-image VD interface list.
1942 * @param pVDIfsOperation Pointer to the per-operation VD interface list.
1943 */
1944VBOXDDU_DECL(int) VDCreateBase(PVBOXHDD pDisk, const char *pszBackend,
1945 const char *pszFilename, uint64_t cbSize,
1946 unsigned uImageFlags, const char *pszComment,
1947 PCPDMMEDIAGEOMETRY pPCHSGeometry,
1948 PCPDMMEDIAGEOMETRY pLCHSGeometry,
1949 PCRTUUID pUuid, unsigned uOpenFlags,
1950 PVDINTERFACE pVDIfsImage,
1951 PVDINTERFACE pVDIfsOperation);
1952
1953/**
1954 * Creates and opens a new differencing image file in HDD container.
1955 * See comments for VDOpen function about differencing images.
1956 *
1957 * @return VBox status code.
1958 * @param pDisk Pointer to HDD container.
1959 * @param pszBackend Name of the image file backend to use (case insensitive).
1960 * @param pszFilename Name of the differencing image file to create.
1961 * @param uImageFlags Flags specifying special image features.
1962 * @param pszComment Pointer to image comment. NULL is ok.
1963 * @param pUuid New UUID of the image. If NULL, a new UUID is created.
1964 * @param pParentUuid New parent UUID of the image. If NULL, the UUID is queried automatically.
1965 * @param uOpenFlags Image file open mode, see VD_OPEN_FLAGS_* constants.
1966 * @param pVDIfsImage Pointer to the per-image VD interface list.
1967 * @param pVDIfsOperation Pointer to the per-operation VD interface list.
1968 */
1969VBOXDDU_DECL(int) VDCreateDiff(PVBOXHDD pDisk, const char *pszBackend,
1970 const char *pszFilename, unsigned uImageFlags,
1971 const char *pszComment, PCRTUUID pUuid,
1972 PCRTUUID pParentUuid, unsigned uOpenFlags,
1973 PVDINTERFACE pVDIfsImage,
1974 PVDINTERFACE pVDIfsOperation);
1975
1976/**
1977 * Creates and opens new cache image file in HDD container.
1978 *
1979 * @return VBox status code.
1980 * @param pDisk Name of the cache file backend to use (case insensitive).
1981 * @param pszFilename Name of the differencing cache file to create.
1982 * @param cbSize Maximum size of the cache.
1983 * @param uImageFlags Flags specifying special cache features.
1984 * @param pszComment Pointer to image comment. NULL is ok.
1985 * @param pUuid New UUID of the image. If NULL, a new UUID is created.
1986 * @param uOpenFlags Image file open mode, see VD_OPEN_FLAGS_* constants.
1987 * @param pVDIfsCache Pointer to the per-cache VD interface list.
1988 * @param pVDIfsOperation Pointer to the per-operation VD interface list.
1989 */
1990VBOXDDU_DECL(int) VDCreateCache(PVBOXHDD pDisk, const char *pszBackend,
1991 const char *pszFilename, uint64_t cbSize,
1992 unsigned uImageFlags, const char *pszComment,
1993 PCRTUUID pUuid, unsigned uOpenFlags,
1994 PVDINTERFACE pVDIfsCache, PVDINTERFACE pVDIfsOperation);
1995
1996/**
1997 * Merges two images (not necessarily with direct parent/child relationship).
1998 * As a side effect the source image and potentially the other images which
1999 * are also merged to the destination are deleted from both the disk and the
2000 * images in the HDD container.
2001 *
2002 * @return VBox status code.
2003 * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
2004 * @param pDisk Pointer to HDD container.
2005 * @param nImageFrom Image number to merge from, counts from 0. 0 is always base image of container.
2006 * @param nImageTo Image number to merge to, counts from 0. 0 is always base image of container.
2007 * @param pVDIfsOperation Pointer to the per-operation VD interface list.
2008 */
2009VBOXDDU_DECL(int) VDMerge(PVBOXHDD pDisk, unsigned nImageFrom,
2010 unsigned nImageTo, PVDINTERFACE pVDIfsOperation);
2011
2012/**
2013 * Copies an image from one HDD container to another.
2014 * The copy is opened in the target HDD container.
2015 * It is possible to convert between different image formats, because the
2016 * backend for the destination may be different from the source.
2017 * If both the source and destination reference the same HDD container,
2018 * then the image is moved (by copying/deleting or renaming) to the new location.
2019 * The source container is unchanged if the move operation fails, otherwise
2020 * the image at the new location is opened in the same way as the old one was.
2021 *
2022 * @note The read/write accesses across disks are not synchronized, just the
2023 * accesses to each disk. Once there is a use case which requires a defined
2024 * read/write behavior in this situation this needs to be extended.
2025 *
2026 * @return VBox status code.
2027 * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
2028 * @param pDiskFrom Pointer to source HDD container.
2029 * @param nImage Image number, counts from 0. 0 is always base image of container.
2030 * @param pDiskTo Pointer to destination HDD container.
2031 * @param pszBackend Name of the image file backend to use (may be NULL to use the same as the source, case insensitive).
2032 * @param pszFilename New name of the image (may be NULL to specify that the
2033 * copy destination is the destination container, or
2034 * if pDiskFrom == pDiskTo, i.e. when moving).
2035 * @param fMoveByRename If true, attempt to perform a move by renaming (if successful the new size is ignored).
2036 * @param cbSize New image size (0 means leave unchanged).
2037 * @param uImageFlags Flags specifying special destination image features.
2038 * @param pDstUuid New UUID of the destination image. If NULL, a new UUID is created.
2039 * This parameter is used if and only if a true copy is created.
2040 * In all rename/move cases or copy to existing image cases the modification UUIDs are copied over.
2041 * @param pVDIfsOperation Pointer to the per-operation VD interface list.
2042 * @param pDstVDIfsImage Pointer to the per-image VD interface list, for the
2043 * destination image.
2044 * @param pDstVDIfsOperation Pointer to the per-operation VD interface list,
2045 * for the destination operation.
2046 */
2047VBOXDDU_DECL(int) VDCopy(PVBOXHDD pDiskFrom, unsigned nImage, PVBOXHDD pDiskTo,
2048 const char *pszBackend, const char *pszFilename,
2049 bool fMoveByRename, uint64_t cbSize,
2050 unsigned uImageFlags, PCRTUUID pDstUuid,
2051 PVDINTERFACE pVDIfsOperation,
2052 PVDINTERFACE pDstVDIfsImage,
2053 PVDINTERFACE pDstVDIfsOperation);
2054
2055/**
2056 * Optimizes the storage consumption of an image. Typically the unused blocks
2057 * have to be wiped with zeroes to achieve a substantial reduced storage use.
2058 * Another optimization done is reordering the image blocks, which can provide
2059 * a significant performance boost, as reads and writes tend to use less random
2060 * file offsets.
2061 *
2062 * @note Compaction is treated as a single operation with regard to thread
2063 * synchronization, which means that it potentially blocks other activities for
2064 * a long time. The complexity of compaction would grow even more if concurrent
2065 * accesses have to be handled.
2066 *
2067 * @return VBox status code.
2068 * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
2069 * @return VERR_VD_IMAGE_READ_ONLY if image is not writable.
2070 * @return VERR_NOT_SUPPORTED if this kind of image can be compacted, but
2071 * this isn't supported yet.
2072 * @param pDisk Pointer to HDD container.
2073 * @param nImage Image number, counts from 0. 0 is always base image of container.
2074 * @param pVDIfsOperation Pointer to the per-operation VD interface list.
2075 */
2076VBOXDDU_DECL(int) VDCompact(PVBOXHDD pDisk, unsigned nImage,
2077 PVDINTERFACE pVDIfsOperation);
2078
2079/**
2080 * Resizes the given disk image to the given size.
2081 *
2082 * @return VBox status
2083 * @return VERR_VD_IMAGE_READ_ONLY if image is not writable.
2084 * @return VERR_NOT_SUPPORTED if this kind of image can be compacted, but
2085 *
2086 * @param pDisk Pointer to the HDD container.
2087 * @param cbSize New size of the image.
2088 * @param pPCHSGeometry Pointer to the new physical disk geometry <= (16383,16,63). Not NULL.
2089 * @param pLCHSGeometry Pointer to the new logical disk geometry <= (x,255,63). Not NULL.
2090 * @param pVDIfsOperation Pointer to the per-operation VD interface list.
2091 */
2092VBOXDDU_DECL(int) VDResize(PVBOXHDD pDisk, uint64_t cbSize,
2093 PCPDMMEDIAGEOMETRY pPCHSGeometry,
2094 PCPDMMEDIAGEOMETRY pLCHSGeometry,
2095 PVDINTERFACE pVDIfsOperation);
2096
2097/**
2098 * Closes the last opened image file in HDD container.
2099 * If previous image file was opened in read-only mode (the normal case) and
2100 * the last opened image is in read-write mode then the previous image will be
2101 * reopened in read/write mode.
2102 *
2103 * @return VBox status code.
2104 * @return VERR_VD_NOT_OPENED if no image is opened in HDD container.
2105 * @param pDisk Pointer to HDD container.
2106 * @param fDelete If true, delete the image from the host disk.
2107 */
2108VBOXDDU_DECL(int) VDClose(PVBOXHDD pDisk, bool fDelete);
2109
2110/**
2111 * Closes the currently opened cache image file in HDD container.
2112 *
2113 * @return VBox status code.
2114 * @return VERR_VD_NOT_OPENED if no cache is opened in HDD container.
2115 * @param pDisk Pointer to HDD container.
2116 * @param fDelete If true, delete the image from the host disk.
2117 */
2118VBOXDDU_DECL(int) VDCacheClose(PVBOXHDD pDisk, bool fDelete);
2119
2120/**
2121 * Closes all opened image files in HDD container.
2122 *
2123 * @return VBox status code.
2124 * @param pDisk Pointer to HDD container.
2125 */
2126VBOXDDU_DECL(int) VDCloseAll(PVBOXHDD pDisk);
2127
2128/**
2129 * Read data from virtual HDD.
2130 *
2131 * @return VBox status code.
2132 * @return VERR_VD_NOT_OPENED if no image is opened in HDD container.
2133 * @param pDisk Pointer to HDD container.
2134 * @param uOffset Offset of first reading byte from start of disk.
2135 * Must be aligned to a sector boundary.
2136 * @param pvBuf Pointer to buffer for reading data.
2137 * @param cbRead Number of bytes to read.
2138 * Must be aligned to a sector boundary.
2139 */
2140VBOXDDU_DECL(int) VDRead(PVBOXHDD pDisk, uint64_t uOffset, void *pvBuf, size_t cbRead);
2141
2142/**
2143 * Write data to virtual HDD.
2144 *
2145 * @return VBox status code.
2146 * @return VERR_VD_NOT_OPENED if no image is opened in HDD container.
2147 * @param pDisk Pointer to HDD container.
2148 * @param uOffset Offset of first writing byte from start of disk.
2149 * Must be aligned to a sector boundary.
2150 * @param pvBuf Pointer to buffer for writing data.
2151 * @param cbWrite Number of bytes to write.
2152 * Must be aligned to a sector boundary.
2153 */
2154VBOXDDU_DECL(int) VDWrite(PVBOXHDD pDisk, uint64_t uOffset, const void *pvBuf, size_t cbWrite);
2155
2156/**
2157 * Make sure the on disk representation of a virtual HDD is up to date.
2158 *
2159 * @return VBox status code.
2160 * @return VERR_VD_NOT_OPENED if no image is opened in HDD container.
2161 * @param pDisk Pointer to HDD container.
2162 */
2163VBOXDDU_DECL(int) VDFlush(PVBOXHDD pDisk);
2164
2165/**
2166 * Get number of opened images in HDD container.
2167 *
2168 * @return Number of opened images for HDD container. 0 if no images have been opened.
2169 * @param pDisk Pointer to HDD container.
2170 */
2171VBOXDDU_DECL(unsigned) VDGetCount(PVBOXHDD pDisk);
2172
2173/**
2174 * Get read/write mode of HDD container.
2175 *
2176 * @return Virtual disk ReadOnly status.
2177 * @return true if no image is opened in HDD container.
2178 * @param pDisk Pointer to HDD container.
2179 */
2180VBOXDDU_DECL(bool) VDIsReadOnly(PVBOXHDD pDisk);
2181
2182/**
2183 * Get total capacity of an image in HDD container.
2184 *
2185 * @return Virtual disk size in bytes.
2186 * @return 0 if image with specified number was not opened.
2187 * @param pDisk Pointer to HDD container.
2188 * @param nImage Image number, counts from 0. 0 is always base image of container.
2189 */
2190VBOXDDU_DECL(uint64_t) VDGetSize(PVBOXHDD pDisk, unsigned nImage);
2191
2192/**
2193 * Get total file size of an image in HDD container.
2194 *
2195 * @return Virtual disk size in bytes.
2196 * @return 0 if image with specified number was not opened.
2197 * @param pDisk Pointer to HDD container.
2198 * @param nImage Image number, counts from 0. 0 is always base image of container.
2199 */
2200VBOXDDU_DECL(uint64_t) VDGetFileSize(PVBOXHDD pDisk, unsigned nImage);
2201
2202/**
2203 * Get virtual disk PCHS geometry of an image in HDD container.
2204 *
2205 * @return VBox status code.
2206 * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
2207 * @return VERR_VD_GEOMETRY_NOT_SET if no geometry present in the HDD container.
2208 * @param pDisk Pointer to HDD container.
2209 * @param nImage Image number, counts from 0. 0 is always base image of container.
2210 * @param pPCHSGeometry Where to store PCHS geometry. Not NULL.
2211 */
2212VBOXDDU_DECL(int) VDGetPCHSGeometry(PVBOXHDD pDisk, unsigned nImage,
2213 PPDMMEDIAGEOMETRY pPCHSGeometry);
2214
2215/**
2216 * Store virtual disk PCHS geometry of an image in HDD container.
2217 *
2218 * @return VBox status code.
2219 * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
2220 * @param pDisk Pointer to HDD container.
2221 * @param nImage Image number, counts from 0. 0 is always base image of container.
2222 * @param pPCHSGeometry Where to load PCHS geometry from. Not NULL.
2223 */
2224VBOXDDU_DECL(int) VDSetPCHSGeometry(PVBOXHDD pDisk, unsigned nImage,
2225 PCPDMMEDIAGEOMETRY pPCHSGeometry);
2226
2227/**
2228 * Get virtual disk LCHS geometry of an image in HDD container.
2229 *
2230 * @return VBox status code.
2231 * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
2232 * @return VERR_VD_GEOMETRY_NOT_SET if no geometry present in the HDD container.
2233 * @param pDisk Pointer to HDD container.
2234 * @param nImage Image number, counts from 0. 0 is always base image of container.
2235 * @param pLCHSGeometry Where to store LCHS geometry. Not NULL.
2236 */
2237VBOXDDU_DECL(int) VDGetLCHSGeometry(PVBOXHDD pDisk, unsigned nImage,
2238 PPDMMEDIAGEOMETRY pLCHSGeometry);
2239
2240/**
2241 * Store virtual disk LCHS geometry of an image in HDD container.
2242 *
2243 * @return VBox status code.
2244 * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
2245 * @param pDisk Pointer to HDD container.
2246 * @param nImage Image number, counts from 0. 0 is always base image of container.
2247 * @param pLCHSGeometry Where to load LCHS geometry from. Not NULL.
2248 */
2249VBOXDDU_DECL(int) VDSetLCHSGeometry(PVBOXHDD pDisk, unsigned nImage,
2250 PCPDMMEDIAGEOMETRY pLCHSGeometry);
2251
2252/**
2253 * Get version of image in HDD container.
2254 *
2255 * @return VBox status code.
2256 * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
2257 * @param pDisk Pointer to HDD container.
2258 * @param nImage Image number, counts from 0. 0 is always base image of container.
2259 * @param puVersion Where to store the image version.
2260 */
2261VBOXDDU_DECL(int) VDGetVersion(PVBOXHDD pDisk, unsigned nImage,
2262 unsigned *puVersion);
2263
2264/**
2265 * List the capabilities of image backend in HDD container.
2266 *
2267 * @return VBox status code.
2268 * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
2269 * @param pDisk Pointer to the HDD container.
2270 * @param nImage Image number, counts from 0. 0 is always base image of container.
2271 * @param pbackendInfo Where to store the backend information.
2272 */
2273VBOXDDU_DECL(int) VDBackendInfoSingle(PVBOXHDD pDisk, unsigned nImage,
2274 PVDBACKENDINFO pBackendInfo);
2275
2276/**
2277 * Get flags of image in HDD container.
2278 *
2279 * @return VBox status code.
2280 * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
2281 * @param pDisk Pointer to HDD container.
2282 * @param nImage Image number, counts from 0. 0 is always base image of container.
2283 * @param puImageFlags Where to store the image flags.
2284 */
2285VBOXDDU_DECL(int) VDGetImageFlags(PVBOXHDD pDisk, unsigned nImage, unsigned *puImageFlags);
2286
2287/**
2288 * Get open flags of image in HDD container.
2289 *
2290 * @return VBox status code.
2291 * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
2292 * @param pDisk Pointer to HDD container.
2293 * @param nImage Image number, counts from 0. 0 is always base image of container.
2294 * @param puOpenFlags Where to store the image open flags.
2295 */
2296VBOXDDU_DECL(int) VDGetOpenFlags(PVBOXHDD pDisk, unsigned nImage,
2297 unsigned *puOpenFlags);
2298
2299/**
2300 * Set open flags of image in HDD container.
2301 * This operation may cause file locking changes and/or files being reopened.
2302 * Note that in case of unrecoverable error all images in HDD container will be closed.
2303 *
2304 * @return VBox status code.
2305 * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
2306 * @param pDisk Pointer to HDD container.
2307 * @param nImage Image number, counts from 0. 0 is always base image of container.
2308 * @param uOpenFlags Image file open mode, see VD_OPEN_FLAGS_* constants.
2309 */
2310VBOXDDU_DECL(int) VDSetOpenFlags(PVBOXHDD pDisk, unsigned nImage,
2311 unsigned uOpenFlags);
2312
2313/**
2314 * Get base filename of image in HDD container. Some image formats use
2315 * other filenames as well, so don't use this for anything but informational
2316 * purposes.
2317 *
2318 * @return VBox status code.
2319 * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
2320 * @return VERR_BUFFER_OVERFLOW if pszFilename buffer too small to hold filename.
2321 * @param pDisk Pointer to HDD container.
2322 * @param nImage Image number, counts from 0. 0 is always base image of container.
2323 * @param pszFilename Where to store the image file name.
2324 * @param cbFilename Size of buffer pszFilename points to.
2325 */
2326VBOXDDU_DECL(int) VDGetFilename(PVBOXHDD pDisk, unsigned nImage,
2327 char *pszFilename, unsigned cbFilename);
2328
2329/**
2330 * Get the comment line of image in HDD container.
2331 *
2332 * @return VBox status code.
2333 * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
2334 * @return VERR_BUFFER_OVERFLOW if pszComment buffer too small to hold comment text.
2335 * @param pDisk Pointer to HDD container.
2336 * @param nImage Image number, counts from 0. 0 is always base image of container.
2337 * @param pszComment Where to store the comment string of image. NULL is ok.
2338 * @param cbComment The size of pszComment buffer. 0 is ok.
2339 */
2340VBOXDDU_DECL(int) VDGetComment(PVBOXHDD pDisk, unsigned nImage,
2341 char *pszComment, unsigned cbComment);
2342
2343/**
2344 * Changes the comment line of image in HDD container.
2345 *
2346 * @return VBox status code.
2347 * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
2348 * @param pDisk Pointer to HDD container.
2349 * @param nImage Image number, counts from 0. 0 is always base image of container.
2350 * @param pszComment New comment string (UTF-8). NULL is allowed to reset the comment.
2351 */
2352VBOXDDU_DECL(int) VDSetComment(PVBOXHDD pDisk, unsigned nImage,
2353 const char *pszComment);
2354
2355/**
2356 * Get UUID of image in HDD container.
2357 *
2358 * @return VBox status code.
2359 * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
2360 * @param pDisk Pointer to HDD container.
2361 * @param nImage Image number, counts from 0. 0 is always base image of container.
2362 * @param pUuid Where to store the image UUID.
2363 */
2364VBOXDDU_DECL(int) VDGetUuid(PVBOXHDD pDisk, unsigned nImage, PRTUUID pUuid);
2365
2366/**
2367 * Set the image's UUID. Should not be used by normal applications.
2368 *
2369 * @return VBox status code.
2370 * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
2371 * @param pDisk Pointer to HDD container.
2372 * @param nImage Image number, counts from 0. 0 is always base image of container.
2373 * @param pUuid New UUID of the image. If NULL, a new UUID is created.
2374 */
2375VBOXDDU_DECL(int) VDSetUuid(PVBOXHDD pDisk, unsigned nImage, PCRTUUID pUuid);
2376
2377/**
2378 * Get last modification UUID of image in HDD container.
2379 *
2380 * @return VBox status code.
2381 * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
2382 * @param pDisk Pointer to HDD container.
2383 * @param nImage Image number, counts from 0. 0 is always base image of container.
2384 * @param pUuid Where to store the image modification UUID.
2385 */
2386VBOXDDU_DECL(int) VDGetModificationUuid(PVBOXHDD pDisk, unsigned nImage,
2387 PRTUUID pUuid);
2388
2389/**
2390 * Set the image's last modification UUID. Should not be used by normal applications.
2391 *
2392 * @return VBox status code.
2393 * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
2394 * @param pDisk Pointer to HDD container.
2395 * @param nImage Image number, counts from 0. 0 is always base image of container.
2396 * @param pUuid New modification UUID of the image. If NULL, a new UUID is created.
2397 */
2398VBOXDDU_DECL(int) VDSetModificationUuid(PVBOXHDD pDisk, unsigned nImage,
2399 PCRTUUID pUuid);
2400
2401/**
2402 * Get parent UUID of image in HDD container.
2403 *
2404 * @return VBox status code.
2405 * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
2406 * @param pDisk Pointer to HDD container.
2407 * @param nImage Image number, counts from 0. 0 is always base image of the container.
2408 * @param pUuid Where to store the parent image UUID.
2409 */
2410VBOXDDU_DECL(int) VDGetParentUuid(PVBOXHDD pDisk, unsigned nImage,
2411 PRTUUID pUuid);
2412
2413/**
2414 * Set the image's parent UUID. Should not be used by normal applications.
2415 *
2416 * @return VBox status code.
2417 * @param pDisk Pointer to HDD container.
2418 * @param nImage Image number, counts from 0. 0 is always base image of container.
2419 * @param pUuid New parent UUID of the image. If NULL, a new UUID is created.
2420 */
2421VBOXDDU_DECL(int) VDSetParentUuid(PVBOXHDD pDisk, unsigned nImage,
2422 PCRTUUID pUuid);
2423
2424
2425/**
2426 * Debug helper - dumps all opened images in HDD container into the log file.
2427 *
2428 * @param pDisk Pointer to HDD container.
2429 */
2430VBOXDDU_DECL(void) VDDumpImages(PVBOXHDD pDisk);
2431
2432
2433/**
2434 * Query if asynchronous operations are supported for this disk.
2435 *
2436 * @return VBox status code.
2437 * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
2438 * @param pDisk Pointer to the HDD container.
2439 * @param nImage Image number, counts from 0. 0 is always base image of container.
2440 * @param pfAIOSupported Where to store if async IO is supported.
2441 */
2442VBOXDDU_DECL(int) VDImageIsAsyncIOSupported(PVBOXHDD pDisk, unsigned nImage, bool *pfAIOSupported);
2443
2444
2445/**
2446 * Start a asynchronous read request.
2447 *
2448 * @return VBox status code.
2449 * @param pDisk Pointer to the HDD container.
2450 * @param uOffset The offset of the virtual disk to read from.
2451 * @param cbRead How many bytes to read.
2452 * @param paSeg Pointer to an array of segments.
2453 * @param cSeg Number of segments in the array.
2454 * @param pfnComplete Completion callback.
2455 * @param pvUser User data which is passed on completion
2456 */
2457VBOXDDU_DECL(int) VDAsyncRead(PVBOXHDD pDisk, uint64_t uOffset, size_t cbRead,
2458 PCRTSGSEG paSeg, unsigned cSeg,
2459 PFNVDASYNCTRANSFERCOMPLETE pfnComplete,
2460 void *pvUser1, void *pvUser2);
2461
2462
2463/**
2464 * Start a asynchronous write request.
2465 *
2466 * @return VBox status code.
2467 * @param pDisk Pointer to the HDD container.
2468 * @param uOffset The offset of the virtual disk to write to.
2469 * @param cbWrtie How many bytes to write.
2470 * @param paSeg Pointer to an array of segments.
2471 * @param cSeg Number of segments in the array.
2472 * @param pfnComplete Completion callback.
2473 * @param pvUser User data which is passed on completion.
2474 */
2475VBOXDDU_DECL(int) VDAsyncWrite(PVBOXHDD pDisk, uint64_t uOffset, size_t cbWrite,
2476 PCRTSGSEG paSeg, unsigned cSeg,
2477 PFNVDASYNCTRANSFERCOMPLETE pfnComplete,
2478 void *pvUser1, void *pvUser2);
2479
2480
2481/**
2482 * Start a asynchronous flush request.
2483 *
2484 * @return VBox status code.
2485 * @param pDisk Pointer to the HDD container.
2486 * @param pfnComplete Completion callback.
2487 * @param pvUser User data which is passed on completion.
2488 */
2489VBOXDDU_DECL(int) VDAsyncFlush(PVBOXHDD pDisk,
2490 PFNVDASYNCTRANSFERCOMPLETE pfnComplete,
2491 void *pvUser1, void *pvUser2);
2492RT_C_DECLS_END
2493
2494/** @} */
2495
2496#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