VirtualBox

source: vbox/trunk/include/VBox/vd-ifs.h@ 64274

Last change on this file since 64274 was 64274, checked in by vboxsync, 8 years ago

Devices/Storage: Doxygen fixes
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 61.9 KB
Line 
1/** @file
2 * VD Container API - interfaces.
3 */
4
5/*
6 * Copyright (C) 2011-2016 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_ifs_h
27#define ___VBox_vd_ifs_h
28
29#include <iprt/assert.h>
30#include <iprt/string.h>
31#include <iprt/mem.h>
32#include <iprt/file.h>
33#include <iprt/net.h>
34#include <iprt/sg.h>
35#include <VBox/cdefs.h>
36#include <VBox/types.h>
37#include <VBox/err.h>
38
39RT_C_DECLS_BEGIN
40
41/** Interface header magic. */
42#define VDINTERFACE_MAGIC UINT32_C(0x19701015)
43
44/**
45 * Supported interface types.
46 */
47typedef enum VDINTERFACETYPE
48{
49 /** First valid interface. */
50 VDINTERFACETYPE_FIRST = 0,
51 /** Interface to pass error message to upper layers. Per-disk. */
52 VDINTERFACETYPE_ERROR = VDINTERFACETYPE_FIRST,
53 /** Interface for I/O operations. Per-image. */
54 VDINTERFACETYPE_IO,
55 /** Interface for progress notification. Per-operation. */
56 VDINTERFACETYPE_PROGRESS,
57 /** Interface for configuration information. Per-image. */
58 VDINTERFACETYPE_CONFIG,
59 /** Interface for TCP network stack. Per-image. */
60 VDINTERFACETYPE_TCPNET,
61 /** Interface for getting parent image state. Per-operation. */
62 VDINTERFACETYPE_PARENTSTATE,
63 /** Interface for synchronizing accesses from several threads. Per-disk. */
64 VDINTERFACETYPE_THREADSYNC,
65 /** Interface for I/O between the generic VBoxHDD code and the backend. Per-image (internal).
66 * This interface is completely internal and must not be used elsewhere. */
67 VDINTERFACETYPE_IOINT,
68 /** Interface to query the use of block ranges on the disk. Per-operation. */
69 VDINTERFACETYPE_QUERYRANGEUSE,
70 /** Interface for the metadata traverse callback. Per-operation. */
71 VDINTERFACETYPE_TRAVERSEMETADATA,
72 /** Interface for crypto operations. Per-filter. */
73 VDINTERFACETYPE_CRYPTO,
74 /** invalid interface. */
75 VDINTERFACETYPE_INVALID
76} VDINTERFACETYPE;
77
78/**
79 * Common structure for all interfaces and at the beginning of all types.
80 */
81typedef struct VDINTERFACE
82{
83 uint32_t u32Magic;
84 /** Human readable interface name. */
85 const char *pszInterfaceName;
86 /** Pointer to the next common interface structure. */
87 struct VDINTERFACE *pNext;
88 /** Interface type. */
89 VDINTERFACETYPE enmInterface;
90 /** Size of the interface. */
91 size_t cbSize;
92 /** Opaque user data which is passed on every call. */
93 void *pvUser;
94} VDINTERFACE;
95/** Pointer to a VDINTERFACE. */
96typedef VDINTERFACE *PVDINTERFACE;
97/** Pointer to a const VDINTERFACE. */
98typedef const VDINTERFACE *PCVDINTERFACE;
99
100/**
101 * Helper functions to handle interface lists.
102 *
103 * @note These interface lists are used consistently to pass per-disk,
104 * per-image and/or per-operation callbacks. Those three purposes are strictly
105 * separate. See the individual interface declarations for what context they
106 * apply to. The caller is responsible for ensuring that the lifetime of the
107 * interface descriptors is appropriate for the category of interface.
108 */
109
110/**
111 * Get a specific interface from a list of interfaces specified by the type.
112 *
113 * @return Pointer to the matching interface or NULL if none was found.
114 * @param pVDIfs Pointer to the VD interface list.
115 * @param enmInterface Interface to search for.
116 */
117DECLINLINE(PVDINTERFACE) VDInterfaceGet(PVDINTERFACE pVDIfs, VDINTERFACETYPE enmInterface)
118{
119 AssertMsgReturn( enmInterface >= VDINTERFACETYPE_FIRST
120 && enmInterface < VDINTERFACETYPE_INVALID,
121 ("enmInterface=%u", enmInterface), NULL);
122
123 while (pVDIfs)
124 {
125 AssertMsgBreak(pVDIfs->u32Magic == VDINTERFACE_MAGIC,
126 ("u32Magic=%#x\n", pVDIfs->u32Magic));
127
128 if (pVDIfs->enmInterface == enmInterface)
129 return pVDIfs;
130 pVDIfs = pVDIfs->pNext;
131 }
132
133 /* No matching interface was found. */
134 return NULL;
135}
136
137/**
138 * Add an interface to a list of interfaces.
139 *
140 * @return VBox status code.
141 * @param pInterface Pointer to an unitialized common interface structure.
142 * @param pszName Name of the interface.
143 * @param enmInterface Type of the interface.
144 * @param pvUser Opaque user data passed on every function call.
145 * @param cbInterface The interface size.
146 * @param ppVDIfs Pointer to the VD interface list.
147 */
148DECLINLINE(int) VDInterfaceAdd(PVDINTERFACE pInterface, const char *pszName, VDINTERFACETYPE enmInterface, void *pvUser,
149 size_t cbInterface, PVDINTERFACE *ppVDIfs)
150{
151 /* Argument checks. */
152 AssertMsgReturn( enmInterface >= VDINTERFACETYPE_FIRST
153 && enmInterface < VDINTERFACETYPE_INVALID,
154 ("enmInterface=%u", enmInterface), VERR_INVALID_PARAMETER);
155
156 AssertMsgReturn(VALID_PTR(ppVDIfs),
157 ("pInterfaceList=%#p", ppVDIfs),
158 VERR_INVALID_PARAMETER);
159
160 /* Fill out interface descriptor. */
161 pInterface->u32Magic = VDINTERFACE_MAGIC;
162 pInterface->cbSize = cbInterface;
163 pInterface->pszInterfaceName = pszName;
164 pInterface->enmInterface = enmInterface;
165 pInterface->pvUser = pvUser;
166 pInterface->pNext = *ppVDIfs;
167
168 /* Remember the new start of the list. */
169 *ppVDIfs = pInterface;
170
171 return VINF_SUCCESS;
172}
173
174/**
175 * Removes an interface from a list of interfaces.
176 *
177 * @return VBox status code
178 * @param pInterface Pointer to an initialized common interface structure to remove.
179 * @param ppVDIfs Pointer to the VD interface list to remove from.
180 */
181DECLINLINE(int) VDInterfaceRemove(PVDINTERFACE pInterface, PVDINTERFACE *ppVDIfs)
182{
183 int rc = VERR_NOT_FOUND;
184
185 /* Argument checks. */
186 AssertMsgReturn(VALID_PTR(pInterface),
187 ("pInterface=%#p", pInterface),
188 VERR_INVALID_PARAMETER);
189
190 AssertMsgReturn(VALID_PTR(ppVDIfs),
191 ("pInterfaceList=%#p", ppVDIfs),
192 VERR_INVALID_PARAMETER);
193
194 if (*ppVDIfs)
195 {
196 PVDINTERFACE pPrev = NULL;
197 PVDINTERFACE pCurr = *ppVDIfs;
198
199 while ( pCurr
200 && (pCurr != pInterface))
201 {
202 pPrev = pCurr;
203 pCurr = pCurr->pNext;
204 }
205
206 /* First interface */
207 if (!pPrev)
208 {
209 *ppVDIfs = pCurr->pNext;
210 rc = VINF_SUCCESS;
211 }
212 else if (pCurr)
213 {
214 pPrev = pCurr->pNext;
215 rc = VINF_SUCCESS;
216 }
217 }
218
219 return rc;
220}
221
222/**
223 * Interface to deliver error messages (and also informational messages)
224 * to upper layers.
225 *
226 * Per-disk interface. Optional, but think twice if you want to miss the
227 * opportunity of reporting better human-readable error messages.
228 */
229typedef struct VDINTERFACEERROR
230{
231 /**
232 * Common interface header.
233 */
234 VDINTERFACE Core;
235
236 /**
237 * Error message callback. Must be able to accept special IPRT format
238 * strings.
239 *
240 * @param pvUser The opaque data passed on container creation.
241 * @param rc The VBox error code.
242 * @param SRC_POS Use RT_SRC_POS.
243 * @param pszFormat Error message format string.
244 * @param va Error message arguments.
245 */
246 DECLR3CALLBACKMEMBER(void, pfnError, (void *pvUser, int rc, RT_SRC_POS_DECL,
247 const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(6, 0));
248
249 /**
250 * Informational message callback. May be NULL. Used e.g. in
251 * VDDumpImages(). Must be able to accept special IPRT format strings.
252 *
253 * @return VBox status code.
254 * @param pvUser The opaque data passed on container creation.
255 * @param pszFormat Message format string.
256 * @param va Message arguments.
257 */
258 DECLR3CALLBACKMEMBER(int, pfnMessage, (void *pvUser, const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(2, 0));
259
260} VDINTERFACEERROR, *PVDINTERFACEERROR;
261
262/**
263 * Get error interface from interface list.
264 *
265 * @return Pointer to the first error interface in the list.
266 * @param pVDIfs Pointer to the interface list.
267 */
268DECLINLINE(PVDINTERFACEERROR) VDIfErrorGet(PVDINTERFACE pVDIfs)
269{
270 PVDINTERFACE pIf = VDInterfaceGet(pVDIfs, VDINTERFACETYPE_ERROR);
271
272 /* Check that the interface descriptor is a progress interface. */
273 AssertMsgReturn( !pIf
274 || ( (pIf->enmInterface == VDINTERFACETYPE_ERROR)
275 && (pIf->cbSize == sizeof(VDINTERFACEERROR))),
276 ("Not an error interface\n"), NULL);
277
278 return (PVDINTERFACEERROR)pIf;
279}
280
281/**
282 * Signal an error to the frontend.
283 *
284 * @returns VBox status code.
285 * @param pIfError The error interface.
286 * @param rc The status code.
287 * @param SRC_POS The position in the source code.
288 * @param pszFormat The format string to pass.
289 * @param ... Arguments to the format string.
290 */
291DECLINLINE(int) RT_IPRT_FORMAT_ATTR(6, 7) vdIfError(PVDINTERFACEERROR pIfError, int rc, RT_SRC_POS_DECL,
292 const char *pszFormat, ...)
293{
294 va_list va;
295 va_start(va, pszFormat);
296 if (pIfError)
297 pIfError->pfnError(pIfError->Core.pvUser, rc, RT_SRC_POS_ARGS, pszFormat, va);
298 va_end(va);
299 return rc;
300}
301
302/**
303 * Signal an informational message to the frontend.
304 *
305 * @returns VBox status code.
306 * @param pIfError The error interface.
307 * @param pszFormat The format string to pass.
308 * @param ... Arguments to the format string.
309 */
310DECLINLINE(int) RT_IPRT_FORMAT_ATTR(2, 3) vdIfErrorMessage(PVDINTERFACEERROR pIfError, const char *pszFormat, ...)
311{
312 int rc = VINF_SUCCESS;
313 va_list va;
314 va_start(va, pszFormat);
315 if (pIfError && pIfError->pfnMessage)
316 rc = pIfError->pfnMessage(pIfError->Core.pvUser, pszFormat, va);
317 va_end(va);
318 return rc;
319}
320
321/**
322 * Completion callback which is called by the interface owner
323 * to inform the backend that a task finished.
324 *
325 * @return VBox status code.
326 * @param pvUser Opaque user data which is passed on request submission.
327 * @param rcReq Status code of the completed request.
328 */
329typedef DECLCALLBACK(int) FNVDCOMPLETED(void *pvUser, int rcReq);
330/** Pointer to FNVDCOMPLETED() */
331typedef FNVDCOMPLETED *PFNVDCOMPLETED;
332
333/**
334 * Support interface for I/O
335 *
336 * Per-image. Optional as input.
337 */
338typedef struct VDINTERFACEIO
339{
340 /**
341 * Common interface header.
342 */
343 VDINTERFACE Core;
344
345 /**
346 * Open callback
347 *
348 * @return VBox status code.
349 * @param pvUser The opaque data passed on container creation.
350 * @param pszLocation Name of the location to open.
351 * @param fOpen Flags for opening the backend.
352 * See RTFILE_O_* \#defines, inventing another set
353 * of open flags is not worth the mapping effort.
354 * @param pfnCompleted The callback which is called whenever a task
355 * completed. The backend has to pass the user data
356 * of the request initiator (ie the one who calls
357 * VDAsyncRead or VDAsyncWrite) in pvCompletion
358 * if this is NULL.
359 * @param ppvStorage Where to store the opaque storage handle.
360 */
361 DECLR3CALLBACKMEMBER(int, pfnOpen, (void *pvUser, const char *pszLocation,
362 uint32_t fOpen,
363 PFNVDCOMPLETED pfnCompleted,
364 void **ppvStorage));
365
366 /**
367 * Close callback.
368 *
369 * @return VBox status code.
370 * @param pvUser The opaque data passed on container creation.
371 * @param pvStorage The opaque storage handle to close.
372 */
373 DECLR3CALLBACKMEMBER(int, pfnClose, (void *pvUser, void *pvStorage));
374
375 /**
376 * Delete callback.
377 *
378 * @return VBox status code.
379 * @param pvUser The opaque data passed on container creation.
380 * @param pcszFilename Name of the file to delete.
381 */
382 DECLR3CALLBACKMEMBER(int, pfnDelete, (void *pvUser, const char *pcszFilename));
383
384 /**
385 * Move callback.
386 *
387 * @return VBox status code.
388 * @param pvUser The opaque data passed on container creation.
389 * @param pcszSrc The path to the source file.
390 * @param pcszDst The path to the destination file.
391 * This file will be created.
392 * @param fMove A combination of the RTFILEMOVE_* flags.
393 */
394 DECLR3CALLBACKMEMBER(int, pfnMove, (void *pvUser, const char *pcszSrc, const char *pcszDst, unsigned fMove));
395
396 /**
397 * Returns the free space on a disk.
398 *
399 * @return VBox status code.
400 * @param pvUser The opaque data passed on container creation.
401 * @param pcszFilename Name of a file to identify the disk.
402 * @param pcbFreeSpace Where to store the free space of the disk.
403 */
404 DECLR3CALLBACKMEMBER(int, pfnGetFreeSpace, (void *pvUser, const char *pcszFilename, int64_t *pcbFreeSpace));
405
406 /**
407 * Returns the last modification timestamp of a file.
408 *
409 * @return VBox status code.
410 * @param pvUser The opaque data passed on container creation.
411 * @param pcszFilename Name of a file to identify the disk.
412 * @param pModificationTime Where to store the timestamp of the file.
413 */
414 DECLR3CALLBACKMEMBER(int, pfnGetModificationTime, (void *pvUser, const char *pcszFilename, PRTTIMESPEC pModificationTime));
415
416 /**
417 * Returns the size of the opened storage backend.
418 *
419 * @return VBox status code.
420 * @param pvUser The opaque data passed on container creation.
421 * @param pvStorage The opaque storage handle to get the size from.
422 * @param pcb Where to store the size of the storage backend.
423 */
424 DECLR3CALLBACKMEMBER(int, pfnGetSize, (void *pvUser, void *pvStorage, uint64_t *pcb));
425
426 /**
427 * Sets the size of the opened storage backend if possible.
428 *
429 * @return VBox status code.
430 * @retval VERR_NOT_SUPPORTED if the backend does not support this operation.
431 * @param pvUser The opaque data passed on container creation.
432 * @param pvStorage The opaque storage handle to set the size for.
433 * @param cb The new size of the image.
434 *
435 * @note Depending on the host the underlying storage (backing file, etc.)
436 * might not have all required storage allocated (sparse file) which
437 * can delay writes or fail with a not enough free space error if there
438 * is not enough space on the storage medium when writing to the range for
439 * the first time.
440 * Use VDINTERFACEIO::pfnSetAllocationSize to make sure the storage is
441 * really alloacted.
442 */
443 DECLR3CALLBACKMEMBER(int, pfnSetSize, (void *pvUser, void *pvStorage, uint64_t cb));
444
445 /**
446 * Sets the size of the opened storage backend making sure the given size
447 * is really allocated.
448 *
449 * @return VBox status code.
450 * @retval VERR_NOT_SUPPORTED if the implementer of the interface doesn't support
451 * this method.
452 * @param pvUser The opaque data passed on container creation.
453 * @param pvStorage The storage handle.
454 * @param cbSize The new size of the image.
455 * @param fFlags Flags for controlling the allocation strategy.
456 * Reserved for future use, MBZ.
457 */
458 DECLR3CALLBACKMEMBER(int, pfnSetAllocationSize, (void *pvUser, void *pvStorage,
459 uint64_t cbSize, uint32_t fFlags));
460
461 /**
462 * Synchronous write callback.
463 *
464 * @return VBox status code.
465 * @param pvUser The opaque data passed on container creation.
466 * @param pvStorage The storage handle to use.
467 * @param off The offset to start from.
468 * @param pvBuf Pointer to the bits need to be written.
469 * @param cbToWrite How many bytes to write.
470 * @param pcbWritten Where to store how many bytes were actually written.
471 */
472 DECLR3CALLBACKMEMBER(int, pfnWriteSync, (void *pvUser, void *pvStorage, uint64_t off,
473 const void *pvBuf, size_t cbToWrite, size_t *pcbWritten));
474
475 /**
476 * Synchronous read callback.
477 *
478 * @return VBox status code.
479 * @param pvUser The opaque data passed on container creation.
480 * @param pvStorage The storage handle to use.
481 * @param off The offset to start from.
482 * @param pvBuf Where to store the read bits.
483 * @param cbToRead How many bytes to read.
484 * @param pcbRead Where to store how many bytes were actually read.
485 */
486 DECLR3CALLBACKMEMBER(int, pfnReadSync, (void *pvUser, void *pvStorage, uint64_t off,
487 void *pvBuf, size_t cbToRead, size_t *pcbRead));
488
489 /**
490 * Flush data to the storage backend.
491 *
492 * @return VBox status code.
493 * @param pvUser The opaque data passed on container creation.
494 * @param pvStorage The storage handle to flush.
495 */
496 DECLR3CALLBACKMEMBER(int, pfnFlushSync, (void *pvUser, void *pvStorage));
497
498 /**
499 * Initiate an asynchronous read request.
500 *
501 * @return VBox status code.
502 * @param pvUser The opaque user data passed on container creation.
503 * @param pvStorage The storage handle.
504 * @param uOffset The offset to start reading from.
505 * @param paSegments Scatter gather list to store the data in.
506 * @param cSegments Number of segments in the list.
507 * @param cbRead How many bytes to read.
508 * @param pvCompletion The opaque user data which is returned upon completion.
509 * @param ppTask Where to store the opaque task handle.
510 */
511 DECLR3CALLBACKMEMBER(int, pfnReadAsync, (void *pvUser, void *pvStorage, uint64_t uOffset,
512 PCRTSGSEG paSegments, size_t cSegments,
513 size_t cbRead, void *pvCompletion,
514 void **ppTask));
515
516 /**
517 * Initiate an asynchronous write request.
518 *
519 * @return VBox status code.
520 * @param pvUser The opaque user data passed on conatiner creation.
521 * @param pvStorage The storage handle.
522 * @param uOffset The offset to start writing to.
523 * @param paSegments Scatter gather list of the data to write
524 * @param cSegments Number of segments in the list.
525 * @param cbWrite How many bytes to write.
526 * @param pvCompletion The opaque user data which is returned upon completion.
527 * @param ppTask Where to store the opaque task handle.
528 */
529 DECLR3CALLBACKMEMBER(int, pfnWriteAsync, (void *pvUser, void *pvStorage, uint64_t uOffset,
530 PCRTSGSEG paSegments, size_t cSegments,
531 size_t cbWrite, void *pvCompletion,
532 void **ppTask));
533
534 /**
535 * Initiates an async flush request.
536 *
537 * @return VBox status code.
538 * @param pvUser The opaque data passed on container creation.
539 * @param pvStorage The storage handle to flush.
540 * @param pvCompletion The opaque user data which is returned upon completion.
541 * @param ppTask Where to store the opaque task handle.
542 */
543 DECLR3CALLBACKMEMBER(int, pfnFlushAsync, (void *pvUser, void *pvStorage,
544 void *pvCompletion, void **ppTask));
545
546} VDINTERFACEIO, *PVDINTERFACEIO;
547
548/**
549 * Get I/O interface from interface list.
550 *
551 * @return Pointer to the first I/O interface in the list.
552 * @param pVDIfs Pointer to the interface list.
553 */
554DECLINLINE(PVDINTERFACEIO) VDIfIoGet(PVDINTERFACE pVDIfs)
555{
556 PVDINTERFACE pIf = VDInterfaceGet(pVDIfs, VDINTERFACETYPE_IO);
557
558 /* Check that the interface descriptor is a progress interface. */
559 AssertMsgReturn( !pIf
560 || ( (pIf->enmInterface == VDINTERFACETYPE_IO)
561 && (pIf->cbSize == sizeof(VDINTERFACEIO))),
562 ("Not a I/O interface"), NULL);
563
564 return (PVDINTERFACEIO)pIf;
565}
566
567DECLINLINE(int) vdIfIoFileOpen(PVDINTERFACEIO pIfIo, const char *pszFilename,
568 uint32_t fOpen, PFNVDCOMPLETED pfnCompleted,
569 void **ppStorage)
570{
571 return pIfIo->pfnOpen(pIfIo->Core.pvUser, pszFilename, fOpen, pfnCompleted, ppStorage);
572}
573
574DECLINLINE(int) vdIfIoFileClose(PVDINTERFACEIO pIfIo, void *pStorage)
575{
576 return pIfIo->pfnClose(pIfIo->Core.pvUser, pStorage);
577}
578
579DECLINLINE(int) vdIfIoFileDelete(PVDINTERFACEIO pIfIo, const char *pszFilename)
580{
581 return pIfIo->pfnDelete(pIfIo->Core.pvUser, pszFilename);
582}
583
584DECLINLINE(int) vdIfIoFileMove(PVDINTERFACEIO pIfIo, const char *pszSrc,
585 const char *pszDst, unsigned fMove)
586{
587 return pIfIo->pfnMove(pIfIo->Core.pvUser, pszSrc, pszDst, fMove);
588}
589
590DECLINLINE(int) vdIfIoFileGetFreeSpace(PVDINTERFACEIO pIfIo, const char *pszFilename,
591 int64_t *pcbFree)
592{
593 return pIfIo->pfnGetFreeSpace(pIfIo->Core.pvUser, pszFilename, pcbFree);
594}
595
596DECLINLINE(int) vdIfIoFileGetModificationTime(PVDINTERFACEIO pIfIo, const char *pcszFilename,
597 PRTTIMESPEC pModificationTime)
598{
599 return pIfIo->pfnGetModificationTime(pIfIo->Core.pvUser, pcszFilename,
600 pModificationTime);
601}
602
603DECLINLINE(int) vdIfIoFileGetSize(PVDINTERFACEIO pIfIo, void *pStorage,
604 uint64_t *pcbSize)
605{
606 return pIfIo->pfnGetSize(pIfIo->Core.pvUser, pStorage, pcbSize);
607}
608
609DECLINLINE(int) vdIfIoFileSetSize(PVDINTERFACEIO pIfIo, void *pStorage,
610 uint64_t cbSize)
611{
612 return pIfIo->pfnSetSize(pIfIo->Core.pvUser, pStorage, cbSize);
613}
614
615DECLINLINE(int) vdIfIoFileWriteSync(PVDINTERFACEIO pIfIo, void *pStorage,
616 uint64_t uOffset, const void *pvBuffer, size_t cbBuffer,
617 size_t *pcbWritten)
618{
619 return pIfIo->pfnWriteSync(pIfIo->Core.pvUser, pStorage, uOffset,
620 pvBuffer, cbBuffer, pcbWritten);
621}
622
623DECLINLINE(int) vdIfIoFileReadSync(PVDINTERFACEIO pIfIo, void *pStorage,
624 uint64_t uOffset, void *pvBuffer, size_t cbBuffer,
625 size_t *pcbRead)
626{
627 return pIfIo->pfnReadSync(pIfIo->Core.pvUser, pStorage, uOffset,
628 pvBuffer, cbBuffer, pcbRead);
629}
630
631DECLINLINE(int) vdIfIoFileFlushSync(PVDINTERFACEIO pIfIo, void *pStorage)
632{
633 return pIfIo->pfnFlushSync(pIfIo->Core.pvUser, pStorage);
634}
635
636/**
637 * Create a VFS stream handle around a VD I/O interface.
638 *
639 * The I/O interface will not be closed or free by the stream, the caller will
640 * do so after it is done with the stream and has released the instances of the
641 * I/O stream object returned by this API.
642 *
643 * @return VBox status code.
644 * @param pVDIfsIo Pointer to the VD I/O interface.
645 * @param pvStorage The storage argument to pass to the interface
646 * methods.
647 * @param fFlags RTFILE_O_XXX, access mask requied.
648 * @param phVfsIos Where to return the VFS I/O stream handle on
649 * success.
650 */
651VBOXDDU_DECL(int) VDIfCreateVfsStream(PVDINTERFACEIO pVDIfsIo, void *pvStorage, uint32_t fFlags, PRTVFSIOSTREAM phVfsIos);
652
653/**
654 * Create a VFS file handle around a VD I/O interface.
655 *
656 * The I/O interface will not be closed or free by the VFS file, the caller will
657 * do so after it is done with the VFS file and has released the instances of
658 * the VFS object returned by this API.
659 *
660 * @return VBox status code.
661 * @param pVDIfs Pointer to the VD I/O interface. If NULL, then @a
662 * pVDIfsInt must be specified.
663 * @param pVDIfsInt Pointer to the internal VD I/O interface. If NULL,
664 * then @ pVDIfs must be specified.
665 * @param pvStorage The storage argument to pass to the interface
666 * methods.
667 * @param fFlags RTFILE_O_XXX, access mask requied.
668 * @param phVfsFile Where to return the VFS file handle on success.
669 */
670VBOXDDU_DECL(int) VDIfCreateVfsFile(PVDINTERFACEIO pVDIfs, struct VDINTERFACEIOINT *pVDIfsInt, void *pvStorage, uint32_t fFlags, PRTVFSFILE phVfsFile);
671
672/**
673 * Creates an VD I/O interface wrapper around an IPRT VFS I/O stream.
674 *
675 * @return VBox status code.
676 * @param hVfsIos The IPRT VFS I/O stream handle. The handle will be
677 * retained by the returned I/O interface (released on
678 * close or destruction).
679 * @param fAccessMode The access mode (RTFILE_O_ACCESS_MASK) to accept.
680 * @param ppIoIf Where to return the pointer to the VD I/O interface.
681 * This must be passed to VDIfDestroyFromVfsStream().
682 */
683VBOXDDU_DECL(int) VDIfCreateFromVfsStream(RTVFSIOSTREAM hVfsIos, uint32_t fAccessMode, PVDINTERFACEIO *ppIoIf);
684
685/**
686 * Destroys the VD I/O interface returned by VDIfCreateFromVfsStream.
687 *
688 * @returns VBox status code.
689 * @param pIoIf The I/O interface pointer returned by
690 * VDIfCreateFromVfsStream. NULL will be quietly
691 * ignored.
692 */
693VBOXDDU_DECL(int) VDIfDestroyFromVfsStream(PVDINTERFACEIO pIoIf);
694
695
696/**
697 * Callback which provides progress information about a currently running
698 * lengthy operation.
699 *
700 * @return VBox status code.
701 * @param pvUser The opaque user data associated with this interface.
702 * @param uPercentage Completion percentage.
703 */
704typedef DECLCALLBACK(int) FNVDPROGRESS(void *pvUser, unsigned uPercentage);
705/** Pointer to FNVDPROGRESS() */
706typedef FNVDPROGRESS *PFNVDPROGRESS;
707
708/**
709 * Progress notification interface
710 *
711 * Per-operation. Optional.
712 */
713typedef struct VDINTERFACEPROGRESS
714{
715 /**
716 * Common interface header.
717 */
718 VDINTERFACE Core;
719
720 /**
721 * Progress notification callbacks.
722 */
723 PFNVDPROGRESS pfnProgress;
724
725} VDINTERFACEPROGRESS, *PVDINTERFACEPROGRESS;
726
727/**
728 * Get progress interface from interface list.
729 *
730 * @return Pointer to the first progress interface in the list.
731 * @param pVDIfs Pointer to the interface list.
732 */
733DECLINLINE(PVDINTERFACEPROGRESS) VDIfProgressGet(PVDINTERFACE pVDIfs)
734{
735 PVDINTERFACE pIf = VDInterfaceGet(pVDIfs, VDINTERFACETYPE_PROGRESS);
736
737 /* Check that the interface descriptor is a progress interface. */
738 AssertMsgReturn( !pIf
739 || ( (pIf->enmInterface == VDINTERFACETYPE_PROGRESS)
740 && (pIf->cbSize == sizeof(VDINTERFACEPROGRESS))),
741 ("Not a progress interface"), NULL);
742
743 return (PVDINTERFACEPROGRESS)pIf;
744}
745
746/**
747 * Signal new progress information to the frontend.
748 *
749 * @returns VBox status code.
750 * @param pIfProgress The progress interface.
751 * @param uPercentage Completion percentage.
752 */
753DECLINLINE(int) vdIfProgress(PVDINTERFACEPROGRESS pIfProgress, unsigned uPercentage)
754{
755 if (pIfProgress)
756 return pIfProgress->pfnProgress(pIfProgress->Core.pvUser, uPercentage);
757 return VINF_SUCCESS;
758}
759
760/**
761 * Configuration information interface
762 *
763 * Per-image. Optional for most backends, but mandatory for images which do
764 * not operate on files (including standard block or character devices).
765 */
766typedef struct VDINTERFACECONFIG
767{
768 /**
769 * Common interface header.
770 */
771 VDINTERFACE Core;
772
773 /**
774 * Validates that the keys are within a set of valid names.
775 *
776 * @return true if all key names are found in pszzAllowed.
777 * @return false if not.
778 * @param pvUser The opaque user data associated with this interface.
779 * @param pszzValid List of valid key names separated by '\\0' and ending with
780 * a double '\\0'.
781 */
782 DECLR3CALLBACKMEMBER(bool, pfnAreKeysValid, (void *pvUser, const char *pszzValid));
783
784 /**
785 * Retrieves the length of the string value associated with a key (including
786 * the terminator, for compatibility with CFGMR3QuerySize).
787 *
788 * @return VBox status code.
789 * VERR_CFGM_VALUE_NOT_FOUND means that the key is not known.
790 * @param pvUser The opaque user data associated with this interface.
791 * @param pszName Name of the key to query.
792 * @param pcbValue Where to store the value length. Non-NULL.
793 */
794 DECLR3CALLBACKMEMBER(int, pfnQuerySize, (void *pvUser, const char *pszName, size_t *pcbValue));
795
796 /**
797 * Query the string value associated with a key.
798 *
799 * @return VBox status code.
800 * VERR_CFGM_VALUE_NOT_FOUND means that the key is not known.
801 * VERR_CFGM_NOT_ENOUGH_SPACE means that the buffer is not big enough.
802 * @param pvUser The opaque user data associated with this interface.
803 * @param pszName Name of the key to query.
804 * @param pszValue Pointer to buffer where to store value.
805 * @param cchValue Length of value buffer.
806 */
807 DECLR3CALLBACKMEMBER(int, pfnQuery, (void *pvUser, const char *pszName, char *pszValue, size_t cchValue));
808
809 /**
810 * Query the bytes value associated with a key.
811 *
812 * @return VBox status code.
813 * VERR_CFGM_VALUE_NOT_FOUND means that the key is not known.
814 * VERR_CFGM_NOT_ENOUGH_SPACE means that the buffer is not big enough.
815 * @param pvUser The opaque user data associated with this interface.
816 * @param pszName Name of the key to query.
817 * @param ppvData Pointer to buffer where to store the data.
818 * @param cbData Length of data buffer.
819 */
820 DECLR3CALLBACKMEMBER(int, pfnQueryBytes, (void *pvUser, const char *pszName, void *ppvData, size_t cbData));
821
822} VDINTERFACECONFIG, *PVDINTERFACECONFIG;
823
824/**
825 * Get configuration information interface from interface list.
826 *
827 * @return Pointer to the first configuration information interface in the list.
828 * @param pVDIfs Pointer to the interface list.
829 */
830DECLINLINE(PVDINTERFACECONFIG) VDIfConfigGet(PVDINTERFACE pVDIfs)
831{
832 PVDINTERFACE pIf = VDInterfaceGet(pVDIfs, VDINTERFACETYPE_CONFIG);
833
834 /* Check that the interface descriptor is a progress interface. */
835 AssertMsgReturn( !pIf
836 || ( (pIf->enmInterface == VDINTERFACETYPE_CONFIG)
837 && (pIf->cbSize == sizeof(VDINTERFACECONFIG))),
838 ("Not a config interface"), NULL);
839
840 return (PVDINTERFACECONFIG)pIf;
841}
842
843/**
844 * Query configuration, validates that the keys are within a set of valid names.
845 *
846 * @return true if all key names are found in pszzAllowed.
847 * @return false if not.
848 * @param pCfgIf Pointer to configuration callback table.
849 * @param pszzValid List of valid names separated by '\\0' and ending with
850 * a double '\\0'.
851 */
852DECLINLINE(bool) VDCFGAreKeysValid(PVDINTERFACECONFIG pCfgIf, const char *pszzValid)
853{
854 return pCfgIf->pfnAreKeysValid(pCfgIf->Core.pvUser, pszzValid);
855}
856
857/**
858 * Checks whether a given key is existing.
859 *
860 * @return true if the key exists.
861 * @return false if the key does not exist.
862 * @param pCfgIf Pointer to configuration callback table.
863 * @param pszName Name of the key.
864 */
865DECLINLINE(bool) VDCFGIsKeyExisting(PVDINTERFACECONFIG pCfgIf, const char *pszName)
866{
867 size_t cb = 0;
868 int rc = pCfgIf->pfnQuerySize(pCfgIf->Core.pvUser, pszName, &cb);
869 return rc == VERR_CFGM_VALUE_NOT_FOUND ? false : true;
870}
871
872/**
873 * Query configuration, unsigned 64-bit integer value with default.
874 *
875 * @return VBox status code.
876 * @param pCfgIf Pointer to configuration callback table.
877 * @param pszName Name of an integer value
878 * @param pu64 Where to store the value. Set to default on failure.
879 * @param u64Def The default value.
880 */
881DECLINLINE(int) VDCFGQueryU64Def(PVDINTERFACECONFIG pCfgIf,
882 const char *pszName, uint64_t *pu64,
883 uint64_t u64Def)
884{
885 char aszBuf[32];
886 int rc = pCfgIf->pfnQuery(pCfgIf->Core.pvUser, pszName, aszBuf, sizeof(aszBuf));
887 if (RT_SUCCESS(rc))
888 {
889 rc = RTStrToUInt64Full(aszBuf, 0, pu64);
890 }
891 else if (rc == VERR_CFGM_VALUE_NOT_FOUND)
892 {
893 rc = VINF_SUCCESS;
894 *pu64 = u64Def;
895 }
896 return rc;
897}
898
899/**
900 * Query configuration, unsigned 64-bit integer value.
901 *
902 * @return VBox status code.
903 * @param pCfgIf Pointer to configuration callback table.
904 * @param pszName Name of an integer value
905 * @param pu64 Where to store the value.
906 */
907DECLINLINE(int) VDCFGQueryU64(PVDINTERFACECONFIG pCfgIf, const char *pszName,
908 uint64_t *pu64)
909{
910 char aszBuf[32];
911 int rc = pCfgIf->pfnQuery(pCfgIf->Core.pvUser, pszName, aszBuf, sizeof(aszBuf));
912 if (RT_SUCCESS(rc))
913 {
914 rc = RTStrToUInt64Full(aszBuf, 0, pu64);
915 }
916
917 return rc;
918}
919
920/**
921 * Query configuration, unsigned 32-bit integer value with default.
922 *
923 * @return VBox status code.
924 * @param pCfgIf Pointer to configuration callback table.
925 * @param pszName Name of an integer value
926 * @param pu32 Where to store the value. Set to default on failure.
927 * @param u32Def The default value.
928 */
929DECLINLINE(int) VDCFGQueryU32Def(PVDINTERFACECONFIG pCfgIf,
930 const char *pszName, uint32_t *pu32,
931 uint32_t u32Def)
932{
933 uint64_t u64;
934 int rc = VDCFGQueryU64Def(pCfgIf, pszName, &u64, u32Def);
935 if (RT_SUCCESS(rc))
936 {
937 if (!(u64 & UINT64_C(0xffffffff00000000)))
938 *pu32 = (uint32_t)u64;
939 else
940 rc = VERR_CFGM_INTEGER_TOO_BIG;
941 }
942 return rc;
943}
944
945/**
946 * Query configuration, bool value with default.
947 *
948 * @return VBox status code.
949 * @param pCfgIf Pointer to configuration callback table.
950 * @param pszName Name of an integer value
951 * @param pf Where to store the value. Set to default on failure.
952 * @param fDef The default value.
953 */
954DECLINLINE(int) VDCFGQueryBoolDef(PVDINTERFACECONFIG pCfgIf,
955 const char *pszName, bool *pf,
956 bool fDef)
957{
958 uint64_t u64;
959 int rc = VDCFGQueryU64Def(pCfgIf, pszName, &u64, fDef);
960 if (RT_SUCCESS(rc))
961 *pf = u64 ? true : false;
962 return rc;
963}
964
965/**
966 * Query configuration, bool value.
967 *
968 * @return VBox status code.
969 * @param pCfgIf Pointer to configuration callback table.
970 * @param pszName Name of an integer value
971 * @param pf Where to store the value.
972 */
973DECLINLINE(int) VDCFGQueryBool(PVDINTERFACECONFIG pCfgIf, const char *pszName,
974 bool *pf)
975{
976 uint64_t u64;
977 int rc = VDCFGQueryU64(pCfgIf, pszName, &u64);
978 if (RT_SUCCESS(rc))
979 *pf = u64 ? true : false;
980 return rc;
981}
982
983/**
984 * Query configuration, dynamically allocated (RTMemAlloc) zero terminated
985 * character value.
986 *
987 * @return VBox status code.
988 * @param pCfgIf Pointer to configuration callback table.
989 * @param pszName Name of an zero terminated character value
990 * @param ppszString Where to store the string pointer. Not set on failure.
991 * Free this using RTMemFree().
992 */
993DECLINLINE(int) VDCFGQueryStringAlloc(PVDINTERFACECONFIG pCfgIf,
994 const char *pszName, char **ppszString)
995{
996 size_t cb;
997 int rc = pCfgIf->pfnQuerySize(pCfgIf->Core.pvUser, pszName, &cb);
998 if (RT_SUCCESS(rc))
999 {
1000 char *pszString = (char *)RTMemAlloc(cb);
1001 if (pszString)
1002 {
1003 rc = pCfgIf->pfnQuery(pCfgIf->Core.pvUser, pszName, pszString, cb);
1004 if (RT_SUCCESS(rc))
1005 *ppszString = pszString;
1006 else
1007 RTMemFree(pszString);
1008 }
1009 else
1010 rc = VERR_NO_MEMORY;
1011 }
1012 return rc;
1013}
1014
1015/**
1016 * Query configuration, dynamically allocated (RTMemAlloc) zero terminated
1017 * character value with default.
1018 *
1019 * @return VBox status code.
1020 * @param pCfgIf Pointer to configuration callback table.
1021 * @param pszName Name of an zero terminated character value
1022 * @param ppszString Where to store the string pointer. Not set on failure.
1023 * Free this using RTMemFree().
1024 * @param pszDef The default value.
1025 */
1026DECLINLINE(int) VDCFGQueryStringAllocDef(PVDINTERFACECONFIG pCfgIf,
1027 const char *pszName,
1028 char **ppszString,
1029 const char *pszDef)
1030{
1031 size_t cb;
1032 int rc = pCfgIf->pfnQuerySize(pCfgIf->Core.pvUser, pszName, &cb);
1033 if (rc == VERR_CFGM_VALUE_NOT_FOUND || rc == VERR_CFGM_NO_PARENT)
1034 {
1035 cb = strlen(pszDef) + 1;
1036 rc = VINF_SUCCESS;
1037 }
1038 if (RT_SUCCESS(rc))
1039 {
1040 char *pszString = (char *)RTMemAlloc(cb);
1041 if (pszString)
1042 {
1043 rc = pCfgIf->pfnQuery(pCfgIf->Core.pvUser, pszName, pszString, cb);
1044 if (rc == VERR_CFGM_VALUE_NOT_FOUND || rc == VERR_CFGM_NO_PARENT)
1045 {
1046 memcpy(pszString, pszDef, cb);
1047 rc = VINF_SUCCESS;
1048 }
1049 if (RT_SUCCESS(rc))
1050 *ppszString = pszString;
1051 else
1052 RTMemFree(pszString);
1053 }
1054 else
1055 rc = VERR_NO_MEMORY;
1056 }
1057 return rc;
1058}
1059
1060/**
1061 * Query configuration, dynamically allocated (RTMemAlloc) byte string value.
1062 *
1063 * @return VBox status code.
1064 * @param pCfgIf Pointer to configuration callback table.
1065 * @param pszName Name of an zero terminated character value
1066 * @param ppvData Where to store the byte string pointer. Not set on failure.
1067 * Free this using RTMemFree().
1068 * @param pcbData Where to store the byte string length.
1069 */
1070DECLINLINE(int) VDCFGQueryBytesAlloc(PVDINTERFACECONFIG pCfgIf,
1071 const char *pszName, void **ppvData, size_t *pcbData)
1072{
1073 size_t cb;
1074 int rc = pCfgIf->pfnQuerySize(pCfgIf->Core.pvUser, pszName, &cb);
1075 if (RT_SUCCESS(rc))
1076 {
1077 char *pbData;
1078 Assert(cb);
1079
1080 pbData = (char *)RTMemAlloc(cb);
1081 if (pbData)
1082 {
1083 if(pCfgIf->pfnQueryBytes)
1084 rc = pCfgIf->pfnQueryBytes(pCfgIf->Core.pvUser, pszName, pbData, cb);
1085 else
1086 rc = pCfgIf->pfnQuery(pCfgIf->Core.pvUser, pszName, pbData, cb);
1087
1088 if (RT_SUCCESS(rc))
1089 {
1090 *ppvData = pbData;
1091 /* Exclude terminator if the byte data was obtained using the string query callback. */
1092 *pcbData = cb;
1093 if (!pCfgIf->pfnQueryBytes)
1094 (*pcbData)--;
1095 }
1096 else
1097 RTMemFree(pbData);
1098 }
1099 else
1100 rc = VERR_NO_MEMORY;
1101 }
1102 return rc;
1103}
1104
1105/** Forward declaration of a VD socket. */
1106typedef struct VDSOCKETINT *VDSOCKET;
1107/** Pointer to a VD socket. */
1108typedef VDSOCKET *PVDSOCKET;
1109/** Nil socket handle. */
1110#define NIL_VDSOCKET ((VDSOCKET)0)
1111
1112/** Connect flag to indicate that the backend wants to use the extended
1113 * socket I/O multiplexing call. This might not be supported on all configurations
1114 * (internal networking and iSCSI)
1115 * and the backend needs to take appropriate action.
1116 */
1117#define VD_INTERFACETCPNET_CONNECT_EXTENDED_SELECT RT_BIT_32(0)
1118
1119/** @name Select events
1120 * @{ */
1121/** Readable without blocking. */
1122#define VD_INTERFACETCPNET_EVT_READ RT_BIT_32(0)
1123/** Writable without blocking. */
1124#define VD_INTERFACETCPNET_EVT_WRITE RT_BIT_32(1)
1125/** Error condition, hangup, exception or similar. */
1126#define VD_INTERFACETCPNET_EVT_ERROR RT_BIT_32(2)
1127/** Hint for the select that getting interrupted while waiting is more likely.
1128 * The interface implementation can optimize the waiting strategy based on this.
1129 * It is assumed that it is more likely to get one of the above socket events
1130 * instead of being interrupted if the flag is not set. */
1131#define VD_INTERFACETCPNET_HINT_INTERRUPT RT_BIT_32(3)
1132/** Mask of the valid bits. */
1133#define VD_INTERFACETCPNET_EVT_VALID_MASK UINT32_C(0x0000000f)
1134/** @} */
1135
1136/**
1137 * TCP network stack interface
1138 *
1139 * Per-image. Mandatory for backends which have the VD_CAP_TCPNET bit set.
1140 */
1141typedef struct VDINTERFACETCPNET
1142{
1143 /**
1144 * Common interface header.
1145 */
1146 VDINTERFACE Core;
1147
1148 /**
1149 * Creates a socket. The socket is not connected if this succeeds.
1150 *
1151 * @return iprt status code.
1152 * @retval VERR_NOT_SUPPORTED if the combination of flags is not supported.
1153 * @param fFlags Combination of the VD_INTERFACETCPNET_CONNECT_* \#defines.
1154 * @param phVdSock Where to store the handle.
1155 */
1156 DECLR3CALLBACKMEMBER(int, pfnSocketCreate, (uint32_t fFlags, PVDSOCKET phVdSock));
1157
1158 /**
1159 * Destroys the socket.
1160 *
1161 * @return iprt status code.
1162 * @param hVdSock Socket handle (/ pointer).
1163 */
1164 DECLR3CALLBACKMEMBER(int, pfnSocketDestroy, (VDSOCKET hVdSock));
1165
1166 /**
1167 * Connect as a client to a TCP port.
1168 *
1169 * @return iprt status code.
1170 * @param hVdSock Socket handle (/ pointer)..
1171 * @param pszAddress The address to connect to.
1172 * @param uPort The port to connect to.
1173 * @param cMillies Number of milliseconds to wait for the connect attempt to complete.
1174 * Use RT_INDEFINITE_WAIT to wait for ever.
1175 * Use RT_SOCKETCONNECT_DEFAULT_WAIT to wait for the default time
1176 * configured on the running system.
1177 */
1178 DECLR3CALLBACKMEMBER(int, pfnClientConnect, (VDSOCKET hVdSock, const char *pszAddress, uint32_t uPort,
1179 RTMSINTERVAL cMillies));
1180
1181 /**
1182 * Close a TCP connection.
1183 *
1184 * @return iprt status code.
1185 * @param hVdSock Socket handle (/ pointer).
1186 */
1187 DECLR3CALLBACKMEMBER(int, pfnClientClose, (VDSOCKET hVdSock));
1188
1189 /**
1190 * Returns whether the socket is currently connected to the client.
1191 *
1192 * @returns true if the socket is connected.
1193 * false otherwise.
1194 * @param hVdSock Socket handle (/ pointer).
1195 */
1196 DECLR3CALLBACKMEMBER(bool, pfnIsClientConnected, (VDSOCKET hVdSock));
1197
1198 /**
1199 * Socket I/O multiplexing.
1200 * Checks if the socket is ready for reading.
1201 *
1202 * @return iprt status code.
1203 * @param hVdSock Socket handle (/ pointer).
1204 * @param cMillies Number of milliseconds to wait for the socket.
1205 * Use RT_INDEFINITE_WAIT to wait for ever.
1206 */
1207 DECLR3CALLBACKMEMBER(int, pfnSelectOne, (VDSOCKET hVdSock, RTMSINTERVAL cMillies));
1208
1209 /**
1210 * Receive data from a socket.
1211 *
1212 * @return iprt status code.
1213 * @param hVdSock Socket handle (/ pointer).
1214 * @param pvBuffer Where to put the data we read.
1215 * @param cbBuffer Read buffer size.
1216 * @param pcbRead Number of bytes read.
1217 * If NULL the entire buffer will be filled upon successful return.
1218 * If not NULL a partial read can be done successfully.
1219 */
1220 DECLR3CALLBACKMEMBER(int, pfnRead, (VDSOCKET hVdSock, void *pvBuffer, size_t cbBuffer, size_t *pcbRead));
1221
1222 /**
1223 * Send data to a socket.
1224 *
1225 * @return iprt status code.
1226 * @param hVdSock Socket handle (/ pointer).
1227 * @param pvBuffer Buffer to write data to socket.
1228 * @param cbBuffer How much to write.
1229 */
1230 DECLR3CALLBACKMEMBER(int, pfnWrite, (VDSOCKET hVdSock, const void *pvBuffer, size_t cbBuffer));
1231
1232 /**
1233 * Send data from scatter/gather buffer to a socket.
1234 *
1235 * @return iprt status code.
1236 * @param hVdSock Socket handle (/ pointer).
1237 * @param pSgBuf Scatter/gather buffer to write data to socket.
1238 */
1239 DECLR3CALLBACKMEMBER(int, pfnSgWrite, (VDSOCKET hVdSock, PCRTSGBUF pSgBuf));
1240
1241 /**
1242 * Receive data from a socket - not blocking.
1243 *
1244 * @return iprt status code.
1245 * @param hVdSock Socket handle (/ pointer).
1246 * @param pvBuffer Where to put the data we read.
1247 * @param cbBuffer Read buffer size.
1248 * @param pcbRead Number of bytes read.
1249 */
1250 DECLR3CALLBACKMEMBER(int, pfnReadNB, (VDSOCKET hVdSock, void *pvBuffer, size_t cbBuffer, size_t *pcbRead));
1251
1252 /**
1253 * Send data to a socket - not blocking.
1254 *
1255 * @return iprt status code.
1256 * @param hVdSock Socket handle (/ pointer).
1257 * @param pvBuffer Buffer to write data to socket.
1258 * @param cbBuffer How much to write.
1259 * @param pcbWritten Number of bytes written.
1260 */
1261 DECLR3CALLBACKMEMBER(int, pfnWriteNB, (VDSOCKET hVdSock, const void *pvBuffer, size_t cbBuffer, size_t *pcbWritten));
1262
1263 /**
1264 * Send data from scatter/gather buffer to a socket - not blocking.
1265 *
1266 * @return iprt status code.
1267 * @param hVdSock Socket handle (/ pointer).
1268 * @param pSgBuf Scatter/gather buffer to write data to socket.
1269 * @param pcbWritten Number of bytes written.
1270 */
1271 DECLR3CALLBACKMEMBER(int, pfnSgWriteNB, (VDSOCKET hVdSock, PRTSGBUF pSgBuf, size_t *pcbWritten));
1272
1273 /**
1274 * Flush socket write buffers.
1275 *
1276 * @return iprt status code.
1277 * @param hVdSock Socket handle (/ pointer).
1278 */
1279 DECLR3CALLBACKMEMBER(int, pfnFlush, (VDSOCKET hVdSock));
1280
1281 /**
1282 * Enables or disables delaying sends to coalesce packets.
1283 *
1284 * @return iprt status code.
1285 * @param hVdSock Socket handle (/ pointer).
1286 * @param fEnable When set to true enables coalescing.
1287 */
1288 DECLR3CALLBACKMEMBER(int, pfnSetSendCoalescing, (VDSOCKET hVdSock, bool fEnable));
1289
1290 /**
1291 * Gets the address of the local side.
1292 *
1293 * @return iprt status code.
1294 * @param hVdSock Socket handle (/ pointer).
1295 * @param pAddr Where to store the local address on success.
1296 */
1297 DECLR3CALLBACKMEMBER(int, pfnGetLocalAddress, (VDSOCKET hVdSock, PRTNETADDR pAddr));
1298
1299 /**
1300 * Gets the address of the other party.
1301 *
1302 * @return iprt status code.
1303 * @param hVdSock Socket handle (/ pointer).
1304 * @param pAddr Where to store the peer address on success.
1305 */
1306 DECLR3CALLBACKMEMBER(int, pfnGetPeerAddress, (VDSOCKET hVdSock, PRTNETADDR pAddr));
1307
1308 /**
1309 * Socket I/O multiplexing - extended version which can be woken up.
1310 * Checks if the socket is ready for reading or writing.
1311 *
1312 * @return iprt status code.
1313 * @retval VERR_INTERRUPTED if the thread was woken up by a pfnPoke call.
1314 * @param hVdSock VD Socket handle(/pointer).
1315 * @param fEvents Mask of events to wait for.
1316 * @param pfEvents Where to store the received events.
1317 * @param cMillies Number of milliseconds to wait for the socket.
1318 * Use RT_INDEFINITE_WAIT to wait for ever.
1319 */
1320 DECLR3CALLBACKMEMBER(int, pfnSelectOneEx, (VDSOCKET hVdSock, uint32_t fEvents,
1321 uint32_t *pfEvents, RTMSINTERVAL cMillies));
1322
1323 /**
1324 * Wakes up the thread waiting in pfnSelectOneEx.
1325 *
1326 * @return iprt status code.
1327 * @param hVdSock VD Socket handle(/pointer).
1328 */
1329 DECLR3CALLBACKMEMBER(int, pfnPoke, (VDSOCKET hVdSock));
1330
1331} VDINTERFACETCPNET, *PVDINTERFACETCPNET;
1332
1333/**
1334 * Get TCP network stack interface from interface list.
1335 *
1336 * @return Pointer to the first TCP network stack interface in the list.
1337 * @param pVDIfs Pointer to the interface list.
1338 */
1339DECLINLINE(PVDINTERFACETCPNET) VDIfTcpNetGet(PVDINTERFACE pVDIfs)
1340{
1341 PVDINTERFACE pIf = VDInterfaceGet(pVDIfs, VDINTERFACETYPE_TCPNET);
1342
1343 /* Check that the interface descriptor is a progress interface. */
1344 AssertMsgReturn( !pIf
1345 || ( (pIf->enmInterface == VDINTERFACETYPE_TCPNET)
1346 && (pIf->cbSize == sizeof(VDINTERFACETCPNET))),
1347 ("Not a TCP net interface"), NULL);
1348
1349 return (PVDINTERFACETCPNET)pIf;
1350}
1351
1352
1353/**
1354 * Interface to synchronize concurrent accesses by several threads.
1355 *
1356 * @note The scope of this interface is to manage concurrent accesses after
1357 * the HDD container has been created, and they must stop before destroying the
1358 * container. Opening or closing images is covered by the synchronization, but
1359 * that does not mean it is safe to close images while a thread executes
1360 * #VDMerge or #VDCopy operating on these images. Making them safe would require
1361 * the lock to be held during the entire operation, which prevents other
1362 * concurrent acitivities.
1363 *
1364 * @note Right now this is kept as simple as possible, and does not even
1365 * attempt to provide enough information to allow e.g. concurrent write
1366 * accesses to different areas of the disk. The reason is that it is very
1367 * difficult to predict which area of a disk is affected by a write,
1368 * especially when different image formats are mixed. Maybe later a more
1369 * sophisticated interface will be provided which has the necessary information
1370 * about worst case affected areas.
1371 *
1372 * Per-disk interface. Optional, needed if the disk is accessed concurrently
1373 * by several threads, e.g. when merging diff images while a VM is running.
1374 */
1375typedef struct VDINTERFACETHREADSYNC
1376{
1377 /**
1378 * Common interface header.
1379 */
1380 VDINTERFACE Core;
1381
1382 /**
1383 * Start a read operation.
1384 */
1385 DECLR3CALLBACKMEMBER(int, pfnStartRead, (void *pvUser));
1386
1387 /**
1388 * Finish a read operation.
1389 */
1390 DECLR3CALLBACKMEMBER(int, pfnFinishRead, (void *pvUser));
1391
1392 /**
1393 * Start a write operation.
1394 */
1395 DECLR3CALLBACKMEMBER(int, pfnStartWrite, (void *pvUser));
1396
1397 /**
1398 * Finish a write operation.
1399 */
1400 DECLR3CALLBACKMEMBER(int, pfnFinishWrite, (void *pvUser));
1401
1402} VDINTERFACETHREADSYNC, *PVDINTERFACETHREADSYNC;
1403
1404/**
1405 * Get thread synchronization interface from interface list.
1406 *
1407 * @return Pointer to the first thread synchronization interface in the list.
1408 * @param pVDIfs Pointer to the interface list.
1409 */
1410DECLINLINE(PVDINTERFACETHREADSYNC) VDIfThreadSyncGet(PVDINTERFACE pVDIfs)
1411{
1412 PVDINTERFACE pIf = VDInterfaceGet(pVDIfs, VDINTERFACETYPE_THREADSYNC);
1413
1414 /* Check that the interface descriptor is a progress interface. */
1415 AssertMsgReturn( !pIf
1416 || ( (pIf->enmInterface == VDINTERFACETYPE_THREADSYNC)
1417 && (pIf->cbSize == sizeof(VDINTERFACETHREADSYNC))),
1418 ("Not a thread synchronization interface"), NULL);
1419
1420 return (PVDINTERFACETHREADSYNC)pIf;
1421}
1422
1423/**
1424 * Interface to query usage of disk ranges.
1425 *
1426 * Per-operation interface. Optional.
1427 */
1428typedef struct VDINTERFACEQUERYRANGEUSE
1429{
1430 /**
1431 * Common interface header.
1432 */
1433 VDINTERFACE Core;
1434
1435 /**
1436 * Query use of a disk range.
1437 */
1438 DECLR3CALLBACKMEMBER(int, pfnQueryRangeUse, (void *pvUser, uint64_t off, uint64_t cb,
1439 bool *pfUsed));
1440
1441} VDINTERFACEQUERYRANGEUSE, *PVDINTERFACEQUERYRANGEUSE;
1442
1443/**
1444 * Get query range use interface from interface list.
1445 *
1446 * @return Pointer to the first thread synchronization interface in the list.
1447 * @param pVDIfs Pointer to the interface list.
1448 */
1449DECLINLINE(PVDINTERFACEQUERYRANGEUSE) VDIfQueryRangeUseGet(PVDINTERFACE pVDIfs)
1450{
1451 PVDINTERFACE pIf = VDInterfaceGet(pVDIfs, VDINTERFACETYPE_QUERYRANGEUSE);
1452
1453 /* Check that the interface descriptor is a progress interface. */
1454 AssertMsgReturn( !pIf
1455 || ( (pIf->enmInterface == VDINTERFACETYPE_QUERYRANGEUSE)
1456 && (pIf->cbSize == sizeof(VDINTERFACEQUERYRANGEUSE))),
1457 ("Not a query range use interface"), NULL);
1458
1459 return (PVDINTERFACEQUERYRANGEUSE)pIf;
1460}
1461
1462DECLINLINE(int) vdIfQueryRangeUse(PVDINTERFACEQUERYRANGEUSE pIfQueryRangeUse, uint64_t off, uint64_t cb,
1463 bool *pfUsed)
1464{
1465 return pIfQueryRangeUse->pfnQueryRangeUse(pIfQueryRangeUse->Core.pvUser, off, cb, pfUsed);
1466}
1467
1468
1469/**
1470 * Interface used to retrieve keys for cryptographic operations.
1471 *
1472 * Per-module interface. Optional but cryptographic modules might fail and
1473 * return an error if this is not present.
1474 */
1475typedef struct VDINTERFACECRYPTO
1476{
1477 /**
1478 * Common interface header.
1479 */
1480 VDINTERFACE Core;
1481
1482 /**
1483 * Retains a key identified by the ID. The caller will only hold a reference
1484 * to the key and must not modify the key buffer in any way.
1485 *
1486 * @returns VBox status code.
1487 * @param pvUser The opaque user data associated with this interface.
1488 * @param pszId The alias/id for the key to retrieve.
1489 * @param ppbKey Where to store the pointer to the key buffer on success.
1490 * @param pcbKey Where to store the size of the key in bytes on success.
1491 */
1492 DECLR3CALLBACKMEMBER(int, pfnKeyRetain, (void *pvUser, const char *pszId, const uint8_t **ppbKey, size_t *pcbKey));
1493
1494 /**
1495 * Releases one reference of the key identified by the given identifier.
1496 * The caller must not access the key buffer after calling this operation.
1497 *
1498 * @returns VBox status code.
1499 * @param pvUser The opaque user data associated with this interface.
1500 * @param pszId The alias/id for the key to release.
1501 *
1502 * @note It is advised to release the key whenever it is not used anymore so
1503 * the entity storing the key can do anything to make retrieving the key
1504 * from memory more difficult like scrambling the memory buffer for
1505 * instance.
1506 */
1507 DECLR3CALLBACKMEMBER(int, pfnKeyRelease, (void *pvUser, const char *pszId));
1508
1509 /**
1510 * Gets a reference to the password identified by the given ID to open a key store supplied through the config interface.
1511 *
1512 * @returns VBox status code.
1513 * @param pvUser The opaque user data associated with this interface.
1514 * @param pszId The alias/id for the password to retain.
1515 * @param ppszPassword Where to store the password to unlock the key store on success.
1516 */
1517 DECLR3CALLBACKMEMBER(int, pfnKeyStorePasswordRetain, (void *pvUser, const char *pszId, const char **ppszPassword));
1518
1519 /**
1520 * Releases a reference of the password previously acquired with VDINTERFACECRYPTO::pfnKeyStorePasswordRetain()
1521 * identified by the given ID.
1522 *
1523 * @returns VBox status code.
1524 * @param pvUser The opaque user data associated with this interface.
1525 * @param pszId The alias/id for the password to release.
1526 */
1527 DECLR3CALLBACKMEMBER(int, pfnKeyStorePasswordRelease, (void *pvUser, const char *pszId));
1528
1529 /**
1530 * Saves a key store.
1531 *
1532 * @returns VBox status code.
1533 * @param pvUser The opaque user data associated with this interface.
1534 * @param pvKeyStore The key store to save.
1535 * @param cbKeyStore Size of the key store in bytes.
1536 *
1537 * @note The format is filter specific and should be treated as binary data.
1538 */
1539 DECLR3CALLBACKMEMBER(int, pfnKeyStoreSave, (void *pvUser, const void *pvKeyStore, size_t cbKeyStore));
1540
1541 /**
1542 * Returns the parameters after the key store was loaded successfully.
1543 *
1544 * @returns VBox status code.
1545 * @param pvUser The opaque user data associated with this interface.
1546 * @param pszCipher The cipher identifier the DEK is used for.
1547 * @param pbDek The raw DEK which was contained in the key store loaded by
1548 * VDINTERFACECRYPTO::pfnKeyStoreLoad().
1549 * @param cbDek The size of the DEK.
1550 *
1551 * @note The provided pointer to the DEK is only valid until this call returns.
1552 * The content might change afterwards with out notice (when scrambling the key
1553 * for further protection for example) or might be even freed.
1554 *
1555 * @note This method is optional and can be NULL if the caller does not require the
1556 * parameters.
1557 */
1558 DECLR3CALLBACKMEMBER(int, pfnKeyStoreReturnParameters, (void *pvUser, const char *pszCipher,
1559 const uint8_t *pbDek, size_t cbDek));
1560
1561} VDINTERFACECRYPTO, *PVDINTERFACECRYPTO;
1562
1563
1564/**
1565 * Get error interface from interface list.
1566 *
1567 * @return Pointer to the first error interface in the list.
1568 * @param pVDIfs Pointer to the interface list.
1569 */
1570DECLINLINE(PVDINTERFACECRYPTO) VDIfCryptoGet(PVDINTERFACE pVDIfs)
1571{
1572 PVDINTERFACE pIf = VDInterfaceGet(pVDIfs, VDINTERFACETYPE_CRYPTO);
1573
1574 /* Check that the interface descriptor is a crypto interface. */
1575 AssertMsgReturn( !pIf
1576 || ( (pIf->enmInterface == VDINTERFACETYPE_CRYPTO)
1577 && (pIf->cbSize == sizeof(VDINTERFACECRYPTO))),
1578 ("Not an crypto interface\n"), NULL);
1579
1580 return (PVDINTERFACECRYPTO)pIf;
1581}
1582
1583/**
1584 * Retains a key identified by the ID. The caller will only hold a reference
1585 * to the key and must not modify the key buffer in any way.
1586 *
1587 * @returns VBox status code.
1588 * @param pIfCrypto Pointer to the crypto interface.
1589 * @param pszId The alias/id for the key to retrieve.
1590 * @param ppbKey Where to store the pointer to the key buffer on success.
1591 * @param pcbKey Where to store the size of the key in bytes on success.
1592 */
1593DECLINLINE(int) vdIfCryptoKeyRetain(PVDINTERFACECRYPTO pIfCrypto, const char *pszId, const uint8_t **ppbKey, size_t *pcbKey)
1594{
1595 return pIfCrypto->pfnKeyRetain(pIfCrypto->Core.pvUser, pszId, ppbKey, pcbKey);
1596}
1597
1598/**
1599 * Releases one reference of the key identified by the given identifier.
1600 * The caller must not access the key buffer after calling this operation.
1601 *
1602 * @returns VBox status code.
1603 * @param pIfCrypto Pointer to the crypto interface.
1604 * @param pszId The alias/id for the key to release.
1605 *
1606 * @note It is advised to release the key whenever it is not used anymore so
1607 * the entity storing the key can do anything to make retrieving the key
1608 * from memory more difficult like scrambling the memory buffer for
1609 * instance.
1610 */
1611DECLINLINE(int) vdIfCryptoKeyRelease(PVDINTERFACECRYPTO pIfCrypto, const char *pszId)
1612{
1613 return pIfCrypto->pfnKeyRelease(pIfCrypto->Core.pvUser, pszId);
1614}
1615
1616/**
1617 * Gets a reference to the password identified by the given ID to open a key store supplied through the config interface.
1618 *
1619 * @returns VBox status code.
1620 * @param pIfCrypto Pointer to the crypto interface.
1621 * @param pszId The alias/id for the password to retain.
1622 * @param ppszPassword Where to store the password to unlock the key store on success.
1623 */
1624DECLINLINE(int) vdIfCryptoKeyStorePasswordRetain(PVDINTERFACECRYPTO pIfCrypto, const char *pszId, const char **ppszPassword)
1625{
1626 return pIfCrypto->pfnKeyStorePasswordRetain(pIfCrypto->Core.pvUser, pszId, ppszPassword);
1627}
1628
1629/**
1630 * Releases a reference of the password previously acquired with VDINTERFACECRYPTO::pfnKeyStorePasswordRetain()
1631 * identified by the given ID.
1632 *
1633 * @returns VBox status code.
1634 * @param pIfCrypto Pointer to the crypto interface.
1635 * @param pszId The alias/id for the password to release.
1636 */
1637DECLINLINE(int) vdIfCryptoKeyStorePasswordRelease(PVDINTERFACECRYPTO pIfCrypto, const char *pszId)
1638{
1639 return pIfCrypto->pfnKeyStorePasswordRelease(pIfCrypto->Core.pvUser, pszId);
1640}
1641
1642/**
1643 * Saves a key store.
1644 *
1645 * @returns VBox status code.
1646 * @param pIfCrypto Pointer to the crypto interface.
1647 * @param pvKeyStore The key store to save.
1648 * @param cbKeyStore Size of the key store in bytes.
1649 *
1650 * @note The format is filter specific and should be treated as binary data.
1651 */
1652DECLINLINE(int) vdIfCryptoKeyStoreSave(PVDINTERFACECRYPTO pIfCrypto, const void *pvKeyStore, size_t cbKeyStore)
1653{
1654 return pIfCrypto->pfnKeyStoreSave(pIfCrypto->Core.pvUser, pvKeyStore, cbKeyStore);
1655}
1656
1657/**
1658 * Returns the parameters after the key store was loaded successfully.
1659 *
1660 * @returns VBox status code.
1661 * @param pIfCrypto Pointer to the crypto interface.
1662 * @param pszCipher The cipher identifier the DEK is used for.
1663 * @param pbDek The raw DEK which was contained in the key store loaded by
1664 * VDINTERFACECRYPTO::pfnKeyStoreLoad().
1665 * @param cbDek The size of the DEK.
1666 *
1667 * @note The provided pointer to the DEK is only valid until this call returns.
1668 * The content might change afterwards with out notice (when scrambling the key
1669 * for further protection for example) or might be even freed.
1670 *
1671 * @note This method is optional and can be NULL if the caller does not require the
1672 * parameters.
1673 */
1674DECLINLINE(int) vdIfCryptoKeyStoreReturnParameters(PVDINTERFACECRYPTO pIfCrypto, const char *pszCipher,
1675 const uint8_t *pbDek, size_t cbDek)
1676{
1677 if (pIfCrypto->pfnKeyStoreReturnParameters)
1678 return pIfCrypto->pfnKeyStoreReturnParameters(pIfCrypto->Core.pvUser, pszCipher, pbDek, cbDek);
1679
1680 return VINF_SUCCESS;
1681}
1682
1683
1684RT_C_DECLS_END
1685
1686/** @} */
1687
1688#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