VirtualBox

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

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

Devices: warnings
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 61.4 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_Interfaces_h
27#define ___VBox_VD_Interfaces_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 ppStorage 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 **ppStorage));
365
366 /**
367 * Close callback.
368 *
369 * @return VBox status code.
370 * @param pvUser The opaque data passed on container creation.
371 * @param pStorage The opaque storage handle to close.
372 */
373 DECLR3CALLBACKMEMBER(int, pfnClose, (void *pvUser, void *pStorage));
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 pStorage The opaque storage handle to close.
422 * @param pcbSize Where to store the size of the storage backend.
423 */
424 DECLR3CALLBACKMEMBER(int, pfnGetSize, (void *pvUser, void *pStorage, uint64_t *pcbSize));
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 pStorage The opaque storage handle to close.
433 * @param cbSize 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 *pStorage, uint64_t cbSize));
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 pStorage 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 *pStorage,
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 pStorage The storage handle to use.
467 * @param uOffset The offset to start from.
468 * @param pvBuffer Pointer to the bits need to be written.
469 * @param cbBuffer 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 *pStorage, uint64_t uOffset,
473 const void *pvBuffer, size_t cbBuffer, 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 pStorage The storage handle to use.
481 * @param uOffset The offset to start from.
482 * @param pvBuffer Where to store the read bits.
483 * @param cbBuffer 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 *pStorage, uint64_t uOffset,
487 void *pvBuffer, size_t cbBuffer, 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 pStorage The storage handle to flush.
495 */
496 DECLR3CALLBACKMEMBER(int, pfnFlushSync, (void *pvUser, void *pStorage));
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 pStorage 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 *pStorage, 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 pStorage 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 *pStorage, 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 pStorage 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 *pStorage,
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 uPercent 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/**
748 * Configuration information interface
749 *
750 * Per-image. Optional for most backends, but mandatory for images which do
751 * not operate on files (including standard block or character devices).
752 */
753typedef struct VDINTERFACECONFIG
754{
755 /**
756 * Common interface header.
757 */
758 VDINTERFACE Core;
759
760 /**
761 * Validates that the keys are within a set of valid names.
762 *
763 * @return true if all key names are found in pszzAllowed.
764 * @return false if not.
765 * @param pvUser The opaque user data associated with this interface.
766 * @param pszzValid List of valid key names separated by '\\0' and ending with
767 * a double '\\0'.
768 */
769 DECLR3CALLBACKMEMBER(bool, pfnAreKeysValid, (void *pvUser, const char *pszzValid));
770
771 /**
772 * Retrieves the length of the string value associated with a key (including
773 * the terminator, for compatibility with CFGMR3QuerySize).
774 *
775 * @return VBox status code.
776 * VERR_CFGM_VALUE_NOT_FOUND means that the key is not known.
777 * @param pvUser The opaque user data associated with this interface.
778 * @param pszName Name of the key to query.
779 * @param pcbValue Where to store the value length. Non-NULL.
780 */
781 DECLR3CALLBACKMEMBER(int, pfnQuerySize, (void *pvUser, const char *pszName, size_t *pcbValue));
782
783 /**
784 * Query the string value associated with a key.
785 *
786 * @return VBox status code.
787 * VERR_CFGM_VALUE_NOT_FOUND means that the key is not known.
788 * VERR_CFGM_NOT_ENOUGH_SPACE means that the buffer is not big enough.
789 * @param pvUser The opaque user data associated with this interface.
790 * @param pszName Name of the key to query.
791 * @param pszValue Pointer to buffer where to store value.
792 * @param cchValue Length of value buffer.
793 */
794 DECLR3CALLBACKMEMBER(int, pfnQuery, (void *pvUser, const char *pszName, char *pszValue, size_t cchValue));
795
796 /**
797 * Query the bytes 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 ppvData Pointer to buffer where to store the data.
805 * @param cbData Length of data buffer.
806 */
807 DECLR3CALLBACKMEMBER(int, pfnQueryBytes, (void *pvUser, const char *pszName, void *ppvData, size_t cbData));
808
809} VDINTERFACECONFIG, *PVDINTERFACECONFIG;
810
811/**
812 * Get configuration information interface from interface list.
813 *
814 * @return Pointer to the first configuration information interface in the list.
815 * @param pVDIfs Pointer to the interface list.
816 */
817DECLINLINE(PVDINTERFACECONFIG) VDIfConfigGet(PVDINTERFACE pVDIfs)
818{
819 PVDINTERFACE pIf = VDInterfaceGet(pVDIfs, VDINTERFACETYPE_CONFIG);
820
821 /* Check that the interface descriptor is a progress interface. */
822 AssertMsgReturn( !pIf
823 || ( (pIf->enmInterface == VDINTERFACETYPE_CONFIG)
824 && (pIf->cbSize == sizeof(VDINTERFACECONFIG))),
825 ("Not a config interface"), NULL);
826
827 return (PVDINTERFACECONFIG)pIf;
828}
829
830/**
831 * Query configuration, validates that the keys are within a set of valid names.
832 *
833 * @return true if all key names are found in pszzAllowed.
834 * @return false if not.
835 * @param pCfgIf Pointer to configuration callback table.
836 * @param pszzValid List of valid names separated by '\\0' and ending with
837 * a double '\\0'.
838 */
839DECLINLINE(bool) VDCFGAreKeysValid(PVDINTERFACECONFIG pCfgIf, const char *pszzValid)
840{
841 return pCfgIf->pfnAreKeysValid(pCfgIf->Core.pvUser, pszzValid);
842}
843
844/**
845 * Checks whether a given key is existing.
846 *
847 * @return true if the key exists.
848 * @return false if the key does not exist.
849 * @param pCfgIf Pointer to configuration callback table.
850 * @param pszName Name of the key.
851 */
852DECLINLINE(bool) VDCFGIsKeyExisting(PVDINTERFACECONFIG pCfgIf, const char *pszName)
853{
854 size_t cb = 0;
855 int rc = pCfgIf->pfnQuerySize(pCfgIf->Core.pvUser, pszName, &cb);
856 return rc == VERR_CFGM_VALUE_NOT_FOUND ? false : true;
857}
858
859/**
860 * Query configuration, unsigned 64-bit integer value with default.
861 *
862 * @return VBox status code.
863 * @param pCfgIf Pointer to configuration callback table.
864 * @param pszName Name of an integer value
865 * @param pu64 Where to store the value. Set to default on failure.
866 * @param u64Def The default value.
867 */
868DECLINLINE(int) VDCFGQueryU64Def(PVDINTERFACECONFIG pCfgIf,
869 const char *pszName, uint64_t *pu64,
870 uint64_t u64Def)
871{
872 char aszBuf[32];
873 int rc = pCfgIf->pfnQuery(pCfgIf->Core.pvUser, pszName, aszBuf, sizeof(aszBuf));
874 if (RT_SUCCESS(rc))
875 {
876 rc = RTStrToUInt64Full(aszBuf, 0, pu64);
877 }
878 else if (rc == VERR_CFGM_VALUE_NOT_FOUND)
879 {
880 rc = VINF_SUCCESS;
881 *pu64 = u64Def;
882 }
883 return rc;
884}
885
886/**
887 * Query configuration, unsigned 64-bit integer value.
888 *
889 * @return VBox status code.
890 * @param pCfgIf Pointer to configuration callback table.
891 * @param pszName Name of an integer value
892 * @param pu64 Where to store the value.
893 */
894DECLINLINE(int) VDCFGQueryU64(PVDINTERFACECONFIG pCfgIf, const char *pszName,
895 uint64_t *pu64)
896{
897 char aszBuf[32];
898 int rc = pCfgIf->pfnQuery(pCfgIf->Core.pvUser, pszName, aszBuf, sizeof(aszBuf));
899 if (RT_SUCCESS(rc))
900 {
901 rc = RTStrToUInt64Full(aszBuf, 0, pu64);
902 }
903
904 return rc;
905}
906
907/**
908 * Query configuration, unsigned 32-bit integer value with default.
909 *
910 * @return VBox status code.
911 * @param pCfgIf Pointer to configuration callback table.
912 * @param pszName Name of an integer value
913 * @param pu32 Where to store the value. Set to default on failure.
914 * @param u32Def The default value.
915 */
916DECLINLINE(int) VDCFGQueryU32Def(PVDINTERFACECONFIG pCfgIf,
917 const char *pszName, uint32_t *pu32,
918 uint32_t u32Def)
919{
920 uint64_t u64;
921 int rc = VDCFGQueryU64Def(pCfgIf, pszName, &u64, u32Def);
922 if (RT_SUCCESS(rc))
923 {
924 if (!(u64 & UINT64_C(0xffffffff00000000)))
925 *pu32 = (uint32_t)u64;
926 else
927 rc = VERR_CFGM_INTEGER_TOO_BIG;
928 }
929 return rc;
930}
931
932/**
933 * Query configuration, bool value with default.
934 *
935 * @return VBox status code.
936 * @param pCfgIf Pointer to configuration callback table.
937 * @param pszName Name of an integer value
938 * @param pf Where to store the value. Set to default on failure.
939 * @param fDef The default value.
940 */
941DECLINLINE(int) VDCFGQueryBoolDef(PVDINTERFACECONFIG pCfgIf,
942 const char *pszName, bool *pf,
943 bool fDef)
944{
945 uint64_t u64;
946 int rc = VDCFGQueryU64Def(pCfgIf, pszName, &u64, fDef);
947 if (RT_SUCCESS(rc))
948 *pf = u64 ? true : false;
949 return rc;
950}
951
952/**
953 * Query configuration, bool value.
954 *
955 * @return VBox status code.
956 * @param pCfgIf Pointer to configuration callback table.
957 * @param pszName Name of an integer value
958 * @param pf Where to store the value.
959 */
960DECLINLINE(int) VDCFGQueryBool(PVDINTERFACECONFIG pCfgIf, const char *pszName,
961 bool *pf)
962{
963 uint64_t u64;
964 int rc = VDCFGQueryU64(pCfgIf, pszName, &u64);
965 if (RT_SUCCESS(rc))
966 *pf = u64 ? true : false;
967 return rc;
968}
969
970/**
971 * Query configuration, dynamically allocated (RTMemAlloc) zero terminated
972 * character value.
973 *
974 * @return VBox status code.
975 * @param pCfgIf Pointer to configuration callback table.
976 * @param pszName Name of an zero terminated character value
977 * @param ppszString Where to store the string pointer. Not set on failure.
978 * Free this using RTMemFree().
979 */
980DECLINLINE(int) VDCFGQueryStringAlloc(PVDINTERFACECONFIG pCfgIf,
981 const char *pszName, char **ppszString)
982{
983 size_t cb;
984 int rc = pCfgIf->pfnQuerySize(pCfgIf->Core.pvUser, pszName, &cb);
985 if (RT_SUCCESS(rc))
986 {
987 char *pszString = (char *)RTMemAlloc(cb);
988 if (pszString)
989 {
990 rc = pCfgIf->pfnQuery(pCfgIf->Core.pvUser, pszName, pszString, cb);
991 if (RT_SUCCESS(rc))
992 *ppszString = pszString;
993 else
994 RTMemFree(pszString);
995 }
996 else
997 rc = VERR_NO_MEMORY;
998 }
999 return rc;
1000}
1001
1002/**
1003 * Query configuration, dynamically allocated (RTMemAlloc) zero terminated
1004 * character value with default.
1005 *
1006 * @return VBox status code.
1007 * @param pCfgIf Pointer to configuration callback table.
1008 * @param pszName Name of an zero terminated character value
1009 * @param ppszString Where to store the string pointer. Not set on failure.
1010 * Free this using RTMemFree().
1011 * @param pszDef The default value.
1012 */
1013DECLINLINE(int) VDCFGQueryStringAllocDef(PVDINTERFACECONFIG pCfgIf,
1014 const char *pszName,
1015 char **ppszString,
1016 const char *pszDef)
1017{
1018 size_t cb;
1019 int rc = pCfgIf->pfnQuerySize(pCfgIf->Core.pvUser, pszName, &cb);
1020 if (rc == VERR_CFGM_VALUE_NOT_FOUND || rc == VERR_CFGM_NO_PARENT)
1021 {
1022 cb = strlen(pszDef) + 1;
1023 rc = VINF_SUCCESS;
1024 }
1025 if (RT_SUCCESS(rc))
1026 {
1027 char *pszString = (char *)RTMemAlloc(cb);
1028 if (pszString)
1029 {
1030 rc = pCfgIf->pfnQuery(pCfgIf->Core.pvUser, pszName, pszString, cb);
1031 if (rc == VERR_CFGM_VALUE_NOT_FOUND || rc == VERR_CFGM_NO_PARENT)
1032 {
1033 memcpy(pszString, pszDef, cb);
1034 rc = VINF_SUCCESS;
1035 }
1036 if (RT_SUCCESS(rc))
1037 *ppszString = pszString;
1038 else
1039 RTMemFree(pszString);
1040 }
1041 else
1042 rc = VERR_NO_MEMORY;
1043 }
1044 return rc;
1045}
1046
1047/**
1048 * Query configuration, dynamically allocated (RTMemAlloc) byte string value.
1049 *
1050 * @return VBox status code.
1051 * @param pCfgIf Pointer to configuration callback table.
1052 * @param pszName Name of an zero terminated character value
1053 * @param ppvData Where to store the byte string pointer. Not set on failure.
1054 * Free this using RTMemFree().
1055 * @param pcbData Where to store the byte string length.
1056 */
1057DECLINLINE(int) VDCFGQueryBytesAlloc(PVDINTERFACECONFIG pCfgIf,
1058 const char *pszName, void **ppvData, size_t *pcbData)
1059{
1060 size_t cb;
1061 int rc = pCfgIf->pfnQuerySize(pCfgIf->Core.pvUser, pszName, &cb);
1062 if (RT_SUCCESS(rc))
1063 {
1064 char *pbData;
1065 Assert(cb);
1066
1067 pbData = (char *)RTMemAlloc(cb);
1068 if (pbData)
1069 {
1070 if(pCfgIf->pfnQueryBytes)
1071 rc = pCfgIf->pfnQueryBytes(pCfgIf->Core.pvUser, pszName, pbData, cb);
1072 else
1073 rc = pCfgIf->pfnQuery(pCfgIf->Core.pvUser, pszName, pbData, cb);
1074
1075 if (RT_SUCCESS(rc))
1076 {
1077 *ppvData = pbData;
1078 /* Exclude terminator if the byte data was obtained using the string query callback. */
1079 *pcbData = cb;
1080 if (!pCfgIf->pfnQueryBytes)
1081 (*pcbData)--;
1082 }
1083 else
1084 RTMemFree(pbData);
1085 }
1086 else
1087 rc = VERR_NO_MEMORY;
1088 }
1089 return rc;
1090}
1091
1092/** Forward declaration of a VD socket. */
1093typedef struct VDSOCKETINT *VDSOCKET;
1094/** Pointer to a VD socket. */
1095typedef VDSOCKET *PVDSOCKET;
1096/** Nil socket handle. */
1097#define NIL_VDSOCKET ((VDSOCKET)0)
1098
1099/** Connect flag to indicate that the backend wants to use the extended
1100 * socket I/O multiplexing call. This might not be supported on all configurations
1101 * (internal networking and iSCSI)
1102 * and the backend needs to take appropriate action.
1103 */
1104#define VD_INTERFACETCPNET_CONNECT_EXTENDED_SELECT RT_BIT_32(0)
1105
1106/** @name Select events
1107 * @{ */
1108/** Readable without blocking. */
1109#define VD_INTERFACETCPNET_EVT_READ RT_BIT_32(0)
1110/** Writable without blocking. */
1111#define VD_INTERFACETCPNET_EVT_WRITE RT_BIT_32(1)
1112/** Error condition, hangup, exception or similar. */
1113#define VD_INTERFACETCPNET_EVT_ERROR RT_BIT_32(2)
1114/** Hint for the select that getting interrupted while waiting is more likely.
1115 * The interface implementation can optimize the waiting strategy based on this.
1116 * It is assumed that it is more likely to get one of the above socket events
1117 * instead of being interrupted if the flag is not set. */
1118#define VD_INTERFACETCPNET_HINT_INTERRUPT RT_BIT_32(3)
1119/** Mask of the valid bits. */
1120#define VD_INTERFACETCPNET_EVT_VALID_MASK UINT32_C(0x0000000f)
1121/** @} */
1122
1123/**
1124 * TCP network stack interface
1125 *
1126 * Per-image. Mandatory for backends which have the VD_CAP_TCPNET bit set.
1127 */
1128typedef struct VDINTERFACETCPNET
1129{
1130 /**
1131 * Common interface header.
1132 */
1133 VDINTERFACE Core;
1134
1135 /**
1136 * Creates a socket. The socket is not connected if this succeeds.
1137 *
1138 * @return iprt status code.
1139 * @retval VERR_NOT_SUPPORTED if the combination of flags is not supported.
1140 * @param fFlags Combination of the VD_INTERFACETCPNET_CONNECT_* \#defines.
1141 * @param pSock Where to store the handle.
1142 */
1143 DECLR3CALLBACKMEMBER(int, pfnSocketCreate, (uint32_t fFlags, PVDSOCKET pSock));
1144
1145 /**
1146 * Destroys the socket.
1147 *
1148 * @return iprt status code.
1149 * @param Sock Socket handle (/ pointer).
1150 */
1151 DECLR3CALLBACKMEMBER(int, pfnSocketDestroy, (VDSOCKET Sock));
1152
1153 /**
1154 * Connect as a client to a TCP port.
1155 *
1156 * @return iprt status code.
1157 * @param Sock Socket handle (/ pointer)..
1158 * @param pszAddress The address to connect to.
1159 * @param uPort The port to connect to.
1160 * @param cMillies Number of milliseconds to wait for the connect attempt to complete.
1161 * Use RT_INDEFINITE_WAIT to wait for ever.
1162 * Use RT_SOCKETCONNECT_DEFAULT_WAIT to wait for the default time
1163 * configured on the running system.
1164 */
1165 DECLR3CALLBACKMEMBER(int, pfnClientConnect, (VDSOCKET Sock, const char *pszAddress, uint32_t uPort,
1166 RTMSINTERVAL cMillies));
1167
1168 /**
1169 * Close a TCP connection.
1170 *
1171 * @return iprt status code.
1172 * @param Sock Socket handle (/ pointer).
1173 */
1174 DECLR3CALLBACKMEMBER(int, pfnClientClose, (VDSOCKET Sock));
1175
1176 /**
1177 * Returns whether the socket is currently connected to the client.
1178 *
1179 * @returns true if the socket is connected.
1180 * false otherwise.
1181 * @param Sock Socket handle (/ pointer).
1182 */
1183 DECLR3CALLBACKMEMBER(bool, pfnIsClientConnected, (VDSOCKET Sock));
1184
1185 /**
1186 * Socket I/O multiplexing.
1187 * Checks if the socket is ready for reading.
1188 *
1189 * @return iprt status code.
1190 * @param Sock Socket handle (/ pointer).
1191 * @param cMillies Number of milliseconds to wait for the socket.
1192 * Use RT_INDEFINITE_WAIT to wait for ever.
1193 */
1194 DECLR3CALLBACKMEMBER(int, pfnSelectOne, (VDSOCKET Sock, RTMSINTERVAL cMillies));
1195
1196 /**
1197 * Receive data from a socket.
1198 *
1199 * @return iprt status code.
1200 * @param Sock Socket handle (/ pointer).
1201 * @param pvBuffer Where to put the data we read.
1202 * @param cbBuffer Read buffer size.
1203 * @param pcbRead Number of bytes read.
1204 * If NULL the entire buffer will be filled upon successful return.
1205 * If not NULL a partial read can be done successfully.
1206 */
1207 DECLR3CALLBACKMEMBER(int, pfnRead, (VDSOCKET Sock, void *pvBuffer, size_t cbBuffer, size_t *pcbRead));
1208
1209 /**
1210 * Send data to a socket.
1211 *
1212 * @return iprt status code.
1213 * @param Sock Socket handle (/ pointer).
1214 * @param pvBuffer Buffer to write data to socket.
1215 * @param cbBuffer How much to write.
1216 */
1217 DECLR3CALLBACKMEMBER(int, pfnWrite, (VDSOCKET Sock, const void *pvBuffer, size_t cbBuffer));
1218
1219 /**
1220 * Send data from scatter/gather buffer to a socket.
1221 *
1222 * @return iprt status code.
1223 * @param Sock Socket handle (/ pointer).
1224 * @param pSgBuffer Scatter/gather buffer to write data to socket.
1225 */
1226 DECLR3CALLBACKMEMBER(int, pfnSgWrite, (VDSOCKET Sock, PCRTSGBUF pSgBuffer));
1227
1228 /**
1229 * Receive data from a socket - not blocking.
1230 *
1231 * @return iprt status code.
1232 * @param Sock Socket handle (/ pointer).
1233 * @param pvBuffer Where to put the data we read.
1234 * @param cbBuffer Read buffer size.
1235 * @param pcbRead Number of bytes read.
1236 */
1237 DECLR3CALLBACKMEMBER(int, pfnReadNB, (VDSOCKET Sock, void *pvBuffer, size_t cbBuffer, size_t *pcbRead));
1238
1239 /**
1240 * Send data to a socket - not blocking.
1241 *
1242 * @return iprt status code.
1243 * @param Sock Socket handle (/ pointer).
1244 * @param pvBuffer Buffer to write data to socket.
1245 * @param cbBuffer How much to write.
1246 * @param pcbWritten Number of bytes written.
1247 */
1248 DECLR3CALLBACKMEMBER(int, pfnWriteNB, (VDSOCKET Sock, const void *pvBuffer, size_t cbBuffer, size_t *pcbWritten));
1249
1250 /**
1251 * Send data from scatter/gather buffer to a socket - not blocking.
1252 *
1253 * @return iprt status code.
1254 * @param Sock Socket handle (/ pointer).
1255 * @param pSgBuffer Scatter/gather buffer to write data to socket.
1256 * @param pcbWritten Number of bytes written.
1257 */
1258 DECLR3CALLBACKMEMBER(int, pfnSgWriteNB, (VDSOCKET Sock, PRTSGBUF pSgBuffer, size_t *pcbWritten));
1259
1260 /**
1261 * Flush socket write buffers.
1262 *
1263 * @return iprt status code.
1264 * @param Sock Socket handle (/ pointer).
1265 */
1266 DECLR3CALLBACKMEMBER(int, pfnFlush, (VDSOCKET Sock));
1267
1268 /**
1269 * Enables or disables delaying sends to coalesce packets.
1270 *
1271 * @return iprt status code.
1272 * @param Sock Socket handle (/ pointer).
1273 * @param fEnable When set to true enables coalescing.
1274 */
1275 DECLR3CALLBACKMEMBER(int, pfnSetSendCoalescing, (VDSOCKET Sock, bool fEnable));
1276
1277 /**
1278 * Gets the address of the local side.
1279 *
1280 * @return iprt status code.
1281 * @param Sock Socket handle (/ pointer).
1282 * @param pAddr Where to store the local address on success.
1283 */
1284 DECLR3CALLBACKMEMBER(int, pfnGetLocalAddress, (VDSOCKET Sock, PRTNETADDR pAddr));
1285
1286 /**
1287 * Gets the address of the other party.
1288 *
1289 * @return iprt status code.
1290 * @param Sock Socket handle (/ pointer).
1291 * @param pAddr Where to store the peer address on success.
1292 */
1293 DECLR3CALLBACKMEMBER(int, pfnGetPeerAddress, (VDSOCKET Sock, PRTNETADDR pAddr));
1294
1295 /**
1296 * Socket I/O multiplexing - extended version which can be woken up.
1297 * Checks if the socket is ready for reading or writing.
1298 *
1299 * @return iprt status code.
1300 * @retval VERR_INTERRUPTED if the thread was woken up by a pfnPoke call.
1301 * @param hVdSock VD Socket handle(/pointer).
1302 * @param fEvents Mask of events to wait for.
1303 * @param pfEvents Where to store the received events.
1304 * @param cMillies Number of milliseconds to wait for the socket.
1305 * Use RT_INDEFINITE_WAIT to wait for ever.
1306 */
1307 DECLR3CALLBACKMEMBER(int, pfnSelectOneEx, (VDSOCKET Sock, uint32_t fEvents,
1308 uint32_t *pfEvents, RTMSINTERVAL cMillies));
1309
1310 /**
1311 * Wakes up the thread waiting in pfnSelectOneEx.
1312 *
1313 * @return iprt status code.
1314 * @param hVdSock VD Socket handle(/pointer).
1315 */
1316 DECLR3CALLBACKMEMBER(int, pfnPoke, (VDSOCKET Sock));
1317
1318} VDINTERFACETCPNET, *PVDINTERFACETCPNET;
1319
1320/**
1321 * Get TCP network stack interface from interface list.
1322 *
1323 * @return Pointer to the first TCP network stack interface in the list.
1324 * @param pVDIfs Pointer to the interface list.
1325 */
1326DECLINLINE(PVDINTERFACETCPNET) VDIfTcpNetGet(PVDINTERFACE pVDIfs)
1327{
1328 PVDINTERFACE pIf = VDInterfaceGet(pVDIfs, VDINTERFACETYPE_TCPNET);
1329
1330 /* Check that the interface descriptor is a progress interface. */
1331 AssertMsgReturn( !pIf
1332 || ( (pIf->enmInterface == VDINTERFACETYPE_TCPNET)
1333 && (pIf->cbSize == sizeof(VDINTERFACETCPNET))),
1334 ("Not a TCP net interface"), NULL);
1335
1336 return (PVDINTERFACETCPNET)pIf;
1337}
1338
1339
1340/**
1341 * Interface to synchronize concurrent accesses by several threads.
1342 *
1343 * @note The scope of this interface is to manage concurrent accesses after
1344 * the HDD container has been created, and they must stop before destroying the
1345 * container. Opening or closing images is covered by the synchronization, but
1346 * that does not mean it is safe to close images while a thread executes
1347 * #VDMerge or #VDCopy operating on these images. Making them safe would require
1348 * the lock to be held during the entire operation, which prevents other
1349 * concurrent acitivities.
1350 *
1351 * @note Right now this is kept as simple as possible, and does not even
1352 * attempt to provide enough information to allow e.g. concurrent write
1353 * accesses to different areas of the disk. The reason is that it is very
1354 * difficult to predict which area of a disk is affected by a write,
1355 * especially when different image formats are mixed. Maybe later a more
1356 * sophisticated interface will be provided which has the necessary information
1357 * about worst case affected areas.
1358 *
1359 * Per-disk interface. Optional, needed if the disk is accessed concurrently
1360 * by several threads, e.g. when merging diff images while a VM is running.
1361 */
1362typedef struct VDINTERFACETHREADSYNC
1363{
1364 /**
1365 * Common interface header.
1366 */
1367 VDINTERFACE Core;
1368
1369 /**
1370 * Start a read operation.
1371 */
1372 DECLR3CALLBACKMEMBER(int, pfnStartRead, (void *pvUser));
1373
1374 /**
1375 * Finish a read operation.
1376 */
1377 DECLR3CALLBACKMEMBER(int, pfnFinishRead, (void *pvUser));
1378
1379 /**
1380 * Start a write operation.
1381 */
1382 DECLR3CALLBACKMEMBER(int, pfnStartWrite, (void *pvUser));
1383
1384 /**
1385 * Finish a write operation.
1386 */
1387 DECLR3CALLBACKMEMBER(int, pfnFinishWrite, (void *pvUser));
1388
1389} VDINTERFACETHREADSYNC, *PVDINTERFACETHREADSYNC;
1390
1391/**
1392 * Get thread synchronization interface from interface list.
1393 *
1394 * @return Pointer to the first thread synchronization interface in the list.
1395 * @param pVDIfs Pointer to the interface list.
1396 */
1397DECLINLINE(PVDINTERFACETHREADSYNC) VDIfThreadSyncGet(PVDINTERFACE pVDIfs)
1398{
1399 PVDINTERFACE pIf = VDInterfaceGet(pVDIfs, VDINTERFACETYPE_THREADSYNC);
1400
1401 /* Check that the interface descriptor is a progress interface. */
1402 AssertMsgReturn( !pIf
1403 || ( (pIf->enmInterface == VDINTERFACETYPE_THREADSYNC)
1404 && (pIf->cbSize == sizeof(VDINTERFACETHREADSYNC))),
1405 ("Not a thread synchronization interface"), NULL);
1406
1407 return (PVDINTERFACETHREADSYNC)pIf;
1408}
1409
1410/**
1411 * Interface to query usage of disk ranges.
1412 *
1413 * Per-operation interface. Optional.
1414 */
1415typedef struct VDINTERFACEQUERYRANGEUSE
1416{
1417 /**
1418 * Common interface header.
1419 */
1420 VDINTERFACE Core;
1421
1422 /**
1423 * Query use of a disk range.
1424 */
1425 DECLR3CALLBACKMEMBER(int, pfnQueryRangeUse, (void *pvUser, uint64_t off, uint64_t cb,
1426 bool *pfUsed));
1427
1428} VDINTERFACEQUERYRANGEUSE, *PVDINTERFACEQUERYRANGEUSE;
1429
1430/**
1431 * Get query range use interface from interface list.
1432 *
1433 * @return Pointer to the first thread synchronization interface in the list.
1434 * @param pVDIfs Pointer to the interface list.
1435 */
1436DECLINLINE(PVDINTERFACEQUERYRANGEUSE) VDIfQueryRangeUseGet(PVDINTERFACE pVDIfs)
1437{
1438 PVDINTERFACE pIf = VDInterfaceGet(pVDIfs, VDINTERFACETYPE_QUERYRANGEUSE);
1439
1440 /* Check that the interface descriptor is a progress interface. */
1441 AssertMsgReturn( !pIf
1442 || ( (pIf->enmInterface == VDINTERFACETYPE_QUERYRANGEUSE)
1443 && (pIf->cbSize == sizeof(VDINTERFACEQUERYRANGEUSE))),
1444 ("Not a query range use interface"), NULL);
1445
1446 return (PVDINTERFACEQUERYRANGEUSE)pIf;
1447}
1448
1449DECLINLINE(int) vdIfQueryRangeUse(PVDINTERFACEQUERYRANGEUSE pIfQueryRangeUse, uint64_t off, uint64_t cb,
1450 bool *pfUsed)
1451{
1452 return pIfQueryRangeUse->pfnQueryRangeUse(pIfQueryRangeUse->Core.pvUser, off, cb, pfUsed);
1453}
1454
1455
1456/**
1457 * Interface used to retrieve keys for cryptographic operations.
1458 *
1459 * Per-module interface. Optional but cryptographic modules might fail and
1460 * return an error if this is not present.
1461 */
1462typedef struct VDINTERFACECRYPTO
1463{
1464 /**
1465 * Common interface header.
1466 */
1467 VDINTERFACE Core;
1468
1469 /**
1470 * Retains a key identified by the ID. The caller will only hold a reference
1471 * to the key and must not modify the key buffer in any way.
1472 *
1473 * @returns VBox status code.
1474 * @param pvUser The opaque user data associated with this interface.
1475 * @param pszId The alias/id for the key to retrieve.
1476 * @param ppbKey Where to store the pointer to the key buffer on success.
1477 * @param pcbKey Where to store the size of the key in bytes on success.
1478 */
1479 DECLR3CALLBACKMEMBER(int, pfnKeyRetain, (void *pvUser, const char *pszId, const uint8_t **ppbKey, size_t *pcbKey));
1480
1481 /**
1482 * Releases one reference of the key identified by the given identifier.
1483 * The caller must not access the key buffer after calling this operation.
1484 *
1485 * @returns VBox status code.
1486 * @param pvUser The opaque user data associated with this interface.
1487 * @param pszId The alias/id for the key to release.
1488 *
1489 * @note It is advised to release the key whenever it is not used anymore so
1490 * the entity storing the key can do anything to make retrieving the key
1491 * from memory more difficult like scrambling the memory buffer for
1492 * instance.
1493 */
1494 DECLR3CALLBACKMEMBER(int, pfnKeyRelease, (void *pvUser, const char *pszId));
1495
1496 /**
1497 * Gets a reference to the password identified by the given ID to open a key store supplied through the config interface.
1498 *
1499 * @returns VBox status code.
1500 * @param pvUser The opaque user data associated with this interface.
1501 * @param pszId The alias/id for the password to retain.
1502 * @param ppszPassword Where to store the password to unlock the key store on success.
1503 */
1504 DECLR3CALLBACKMEMBER(int, pfnKeyStorePasswordRetain, (void *pvUser, const char *pszId, const char **ppszPassword));
1505
1506 /**
1507 * Releases a reference of the password previously acquired with VDINTERFACECRYPTO::pfnKeyStorePasswordRetain()
1508 * identified by the given ID.
1509 *
1510 * @returns VBox status code.
1511 * @param pvUser The opaque user data associated with this interface.
1512 * @param pszId The alias/id for the password to release.
1513 */
1514 DECLR3CALLBACKMEMBER(int, pfnKeyStorePasswordRelease, (void *pvUser, const char *pszId));
1515
1516 /**
1517 * Saves a key store.
1518 *
1519 * @returns VBox status code.
1520 * @param pvUser The opaque user data associated with this interface.
1521 * @param pvKeyStore The key store to save.
1522 * @param cbKeyStore Size of the key store in bytes.
1523 *
1524 * @note The format is filter specific and should be treated as binary data.
1525 */
1526 DECLR3CALLBACKMEMBER(int, pfnKeyStoreSave, (void *pvUser, const void *pvKeyStore, size_t cbKeyStore));
1527
1528 /**
1529 * Returns the parameters after the key store was loaded successfully.
1530 *
1531 * @returns VBox status code.
1532 * @param pvUser The opaque user data associated with this interface.
1533 * @param pszCipher The cipher identifier the DEK is used for.
1534 * @param pbDek The raw DEK which was contained in the key store loaded by
1535 * VDINTERFACECRYPTO::pfnKeyStoreLoad().
1536 * @param cbDek The size of the DEK.
1537 *
1538 * @note The provided pointer to the DEK is only valid until this call returns.
1539 * The content might change afterwards with out notice (when scrambling the key
1540 * for further protection for example) or might be even freed.
1541 *
1542 * @note This method is optional and can be NULL if the caller does not require the
1543 * parameters.
1544 */
1545 DECLR3CALLBACKMEMBER(int, pfnKeyStoreReturnParameters, (void *pvUser, const char *pszCipher,
1546 const uint8_t *pbDek, size_t cbDek));
1547
1548} VDINTERFACECRYPTO, *PVDINTERFACECRYPTO;
1549
1550
1551/**
1552 * Get error interface from interface list.
1553 *
1554 * @return Pointer to the first error interface in the list.
1555 * @param pVDIfs Pointer to the interface list.
1556 */
1557DECLINLINE(PVDINTERFACECRYPTO) VDIfCryptoGet(PVDINTERFACE pVDIfs)
1558{
1559 PVDINTERFACE pIf = VDInterfaceGet(pVDIfs, VDINTERFACETYPE_CRYPTO);
1560
1561 /* Check that the interface descriptor is a crypto interface. */
1562 AssertMsgReturn( !pIf
1563 || ( (pIf->enmInterface == VDINTERFACETYPE_CRYPTO)
1564 && (pIf->cbSize == sizeof(VDINTERFACECRYPTO))),
1565 ("Not an crypto interface\n"), NULL);
1566
1567 return (PVDINTERFACECRYPTO)pIf;
1568}
1569
1570/**
1571 * Retains a key identified by the ID. The caller will only hold a reference
1572 * to the key and must not modify the key buffer in any way.
1573 *
1574 * @returns VBox status code.
1575 * @param pIfCrypto Pointer to the crypto interface.
1576 * @param pszId The alias/id for the key to retrieve.
1577 * @param ppbKey Where to store the pointer to the key buffer on success.
1578 * @param pcbKey Where to store the size of the key in bytes on success.
1579 */
1580DECLINLINE(int) vdIfCryptoKeyRetain(PVDINTERFACECRYPTO pIfCrypto, const char *pszId, const uint8_t **ppbKey, size_t *pcbKey)
1581{
1582 return pIfCrypto->pfnKeyRetain(pIfCrypto->Core.pvUser, pszId, ppbKey, pcbKey);
1583}
1584
1585/**
1586 * Releases one reference of the key identified by the given identifier.
1587 * The caller must not access the key buffer after calling this operation.
1588 *
1589 * @returns VBox status code.
1590 * @param pIfCrypto Pointer to the crypto interface.
1591 * @param pszId The alias/id for the key to release.
1592 *
1593 * @note It is advised to release the key whenever it is not used anymore so
1594 * the entity storing the key can do anything to make retrieving the key
1595 * from memory more difficult like scrambling the memory buffer for
1596 * instance.
1597 */
1598DECLINLINE(int) vdIfCryptoKeyRelease(PVDINTERFACECRYPTO pIfCrypto, const char *pszId)
1599{
1600 return pIfCrypto->pfnKeyRelease(pIfCrypto->Core.pvUser, pszId);
1601}
1602
1603/**
1604 * Gets a reference to the password identified by the given ID to open a key store supplied through the config interface.
1605 *
1606 * @returns VBox status code.
1607 * @param pIfCrypto Pointer to the crypto interface.
1608 * @param pszId The alias/id for the password to retain.
1609 * @param ppszPassword Where to store the password to unlock the key store on success.
1610 */
1611DECLINLINE(int) vdIfCryptoKeyStorePasswordRetain(PVDINTERFACECRYPTO pIfCrypto, const char *pszId, const char **ppszPassword)
1612{
1613 return pIfCrypto->pfnKeyStorePasswordRetain(pIfCrypto->Core.pvUser, pszId, ppszPassword);
1614}
1615
1616/**
1617 * Releases a reference of the password previously acquired with VDINTERFACECRYPTO::pfnKeyStorePasswordRetain()
1618 * identified by the given ID.
1619 *
1620 * @returns VBox status code.
1621 * @param pIfCrypto Pointer to the crypto interface.
1622 * @param pszId The alias/id for the password to release.
1623 */
1624DECLINLINE(int) vdIfCryptoKeyStorePasswordRelease(PVDINTERFACECRYPTO pIfCrypto, const char *pszId)
1625{
1626 return pIfCrypto->pfnKeyStorePasswordRelease(pIfCrypto->Core.pvUser, pszId);
1627}
1628
1629/**
1630 * Saves a key store.
1631 *
1632 * @returns VBox status code.
1633 * @param pIfCrypto Pointer to the crypto interface.
1634 * @param pvKeyStore The key store to save.
1635 * @param cbKeyStore Size of the key store in bytes.
1636 *
1637 * @note The format is filter specific and should be treated as binary data.
1638 */
1639DECLINLINE(int) vdIfCryptoKeyStoreSave(PVDINTERFACECRYPTO pIfCrypto, const void *pvKeyStore, size_t cbKeyStore)
1640{
1641 return pIfCrypto->pfnKeyStoreSave(pIfCrypto->Core.pvUser, pvKeyStore, cbKeyStore);
1642}
1643
1644/**
1645 * Returns the parameters after the key store was loaded successfully.
1646 *
1647 * @returns VBox status code.
1648 * @param pIfCrypto Pointer to the crypto interface.
1649 * @param pszCipher The cipher identifier the DEK is used for.
1650 * @param pbDek The raw DEK which was contained in the key store loaded by
1651 * VDINTERFACECRYPTO::pfnKeyStoreLoad().
1652 * @param cbDek The size of the DEK.
1653 *
1654 * @note The provided pointer to the DEK is only valid until this call returns.
1655 * The content might change afterwards with out notice (when scrambling the key
1656 * for further protection for example) or might be even freed.
1657 *
1658 * @note This method is optional and can be NULL if the caller does not require the
1659 * parameters.
1660 */
1661DECLINLINE(int) vdIfCryptoKeyStoreReturnParameters(PVDINTERFACECRYPTO pIfCrypto, const char *pszCipher,
1662 const uint8_t *pbDek, size_t cbDek)
1663{
1664 if (pIfCrypto->pfnKeyStoreReturnParameters)
1665 return pIfCrypto->pfnKeyStoreReturnParameters(pIfCrypto->Core.pvUser, pszCipher, pbDek, cbDek);
1666
1667 return VINF_SUCCESS;
1668}
1669
1670
1671RT_C_DECLS_END
1672
1673/** @} */
1674
1675#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