[38469] | 1 | /** @file
|
---|
| 2 | * VD Container API - interfaces.
|
---|
| 3 | */
|
---|
| 4 |
|
---|
| 5 | /*
|
---|
[44529] | 6 | * Copyright (C) 2011-2012 Oracle Corporation
|
---|
[38469] | 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 |
|
---|
| 39 | RT_C_DECLS_BEGIN
|
---|
| 40 |
|
---|
| 41 | /** Interface header magic. */
|
---|
| 42 | #define VDINTERFACE_MAGIC UINT32_C(0x19701015)
|
---|
| 43 |
|
---|
| 44 | /**
|
---|
| 45 | * Supported interface types.
|
---|
| 46 | */
|
---|
| 47 | typedef 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,
|
---|
[40030] | 68 | /** Interface to query the use of block ranges on the disk. Per-operation. */
|
---|
| 69 | VDINTERFACETYPE_QUERYRANGEUSE,
|
---|
[50988] | 70 | /** Interface for the metadata traverse callback. Per-operation. */
|
---|
| 71 | VDINTERFACETYPE_TRAVERSEMETADATA,
|
---|
[51752] | 72 | /** Interface for crypto opertions. Per-disk. */
|
---|
| 73 | VDINTERFACETYPE_CRYPTO,
|
---|
[38469] | 74 | /** invalid interface. */
|
---|
| 75 | VDINTERFACETYPE_INVALID
|
---|
| 76 | } VDINTERFACETYPE;
|
---|
| 77 |
|
---|
| 78 | /**
|
---|
| 79 | * Common structure for all interfaces and at the beginning of all types.
|
---|
| 80 | */
|
---|
| 81 | typedef 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. */
|
---|
| 96 | typedef VDINTERFACE *PVDINTERFACE;
|
---|
| 97 | /** Pointer to a const VDINTERFACE. */
|
---|
| 98 | typedef 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 | */
|
---|
| 117 | DECLINLINE(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 ppVDIfs Pointer to the VD interface list.
|
---|
| 146 | */
|
---|
| 147 | DECLINLINE(int) VDInterfaceAdd(PVDINTERFACE pInterface, const char *pszName,
|
---|
| 148 | 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 | */
|
---|
| 181 | DECLINLINE(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 | */
|
---|
| 229 | typedef 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 RT_SRC_POS_DECL 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, const char *pszFormat, va_list va));
|
---|
| 247 |
|
---|
| 248 | /**
|
---|
| 249 | * Informational message callback. May be NULL. Used e.g. in
|
---|
| 250 | * VDDumpImages(). Must be able to accept special IPRT format strings.
|
---|
| 251 | *
|
---|
| 252 | * @return VBox status code.
|
---|
| 253 | * @param pvUser The opaque data passed on container creation.
|
---|
| 254 | * @param pszFormat Message format string.
|
---|
| 255 | * @param va Message arguments.
|
---|
| 256 | */
|
---|
| 257 | DECLR3CALLBACKMEMBER(int, pfnMessage, (void *pvUser, const char *pszFormat, va_list va));
|
---|
| 258 |
|
---|
| 259 | } VDINTERFACEERROR, *PVDINTERFACEERROR;
|
---|
| 260 |
|
---|
| 261 | /**
|
---|
| 262 | * Get error interface from interface list.
|
---|
| 263 | *
|
---|
| 264 | * @return Pointer to the first error interface in the list.
|
---|
| 265 | * @param pVDIfs Pointer to the interface list.
|
---|
| 266 | */
|
---|
| 267 | DECLINLINE(PVDINTERFACEERROR) VDIfErrorGet(PVDINTERFACE pVDIfs)
|
---|
| 268 | {
|
---|
| 269 | PVDINTERFACE pIf = VDInterfaceGet(pVDIfs, VDINTERFACETYPE_ERROR);
|
---|
| 270 |
|
---|
| 271 | /* Check that the interface descriptor is a progress interface. */
|
---|
| 272 | AssertMsgReturn( !pIf
|
---|
| 273 | || ( (pIf->enmInterface == VDINTERFACETYPE_ERROR)
|
---|
| 274 | && (pIf->cbSize == sizeof(VDINTERFACEERROR))),
|
---|
| 275 | ("Not an error interface\n"), NULL);
|
---|
| 276 |
|
---|
| 277 | return (PVDINTERFACEERROR)pIf;
|
---|
| 278 | }
|
---|
| 279 |
|
---|
| 280 | /**
|
---|
| 281 | * Signal an error to the frontend.
|
---|
| 282 | *
|
---|
| 283 | * @returns VBox status code.
|
---|
| 284 | * @param pIfError The error interface.
|
---|
| 285 | * @param rc The status code.
|
---|
| 286 | * @param RT_SRC_POS_DECL The position in the source code.
|
---|
| 287 | * @param pszFormat The format string to pass.
|
---|
| 288 | * @param ... Arguments to the format string.
|
---|
| 289 | */
|
---|
| 290 | DECLINLINE(int) vdIfError(PVDINTERFACEERROR pIfError, int rc, RT_SRC_POS_DECL,
|
---|
| 291 | const char *pszFormat, ...)
|
---|
| 292 | {
|
---|
| 293 | va_list va;
|
---|
| 294 | va_start(va, pszFormat);
|
---|
| 295 | if (pIfError)
|
---|
| 296 | pIfError->pfnError(pIfError->Core.pvUser, rc, RT_SRC_POS_ARGS, pszFormat, va);
|
---|
| 297 | va_end(va);
|
---|
| 298 | return rc;
|
---|
| 299 | }
|
---|
| 300 |
|
---|
| 301 | /**
|
---|
| 302 | * Signal an informational message to the frontend.
|
---|
| 303 | *
|
---|
| 304 | * @returns VBox status code.
|
---|
| 305 | * @param pIfError The error interface.
|
---|
| 306 | * @param pszFormat The format string to pass.
|
---|
| 307 | * @param ... Arguments to the format string.
|
---|
| 308 | */
|
---|
| 309 | DECLINLINE(int) vdIfErrorMessage(PVDINTERFACEERROR pIfError, const char *pszFormat, ...)
|
---|
| 310 | {
|
---|
| 311 | int rc = VINF_SUCCESS;
|
---|
| 312 | va_list va;
|
---|
| 313 | va_start(va, pszFormat);
|
---|
[43787] | 314 | if (pIfError && pIfError->pfnMessage)
|
---|
[38469] | 315 | rc = pIfError->pfnMessage(pIfError->Core.pvUser, pszFormat, va);
|
---|
| 316 | va_end(va);
|
---|
| 317 | return rc;
|
---|
| 318 | }
|
---|
| 319 |
|
---|
| 320 | /**
|
---|
| 321 | * Completion callback which is called by the interface owner
|
---|
| 322 | * to inform the backend that a task finished.
|
---|
| 323 | *
|
---|
| 324 | * @return VBox status code.
|
---|
| 325 | * @param pvUser Opaque user data which is passed on request submission.
|
---|
| 326 | * @param rcReq Status code of the completed request.
|
---|
| 327 | */
|
---|
| 328 | typedef DECLCALLBACK(int) FNVDCOMPLETED(void *pvUser, int rcReq);
|
---|
| 329 | /** Pointer to FNVDCOMPLETED() */
|
---|
| 330 | typedef FNVDCOMPLETED *PFNVDCOMPLETED;
|
---|
| 331 |
|
---|
| 332 | /**
|
---|
| 333 | * Support interface for I/O
|
---|
| 334 | *
|
---|
| 335 | * Per-image. Optional as input.
|
---|
| 336 | */
|
---|
| 337 | typedef struct VDINTERFACEIO
|
---|
| 338 | {
|
---|
| 339 | /**
|
---|
| 340 | * Common interface header.
|
---|
| 341 | */
|
---|
| 342 | VDINTERFACE Core;
|
---|
| 343 |
|
---|
| 344 | /**
|
---|
| 345 | * Open callback
|
---|
| 346 | *
|
---|
| 347 | * @return VBox status code.
|
---|
| 348 | * @param pvUser The opaque data passed on container creation.
|
---|
| 349 | * @param pszLocation Name of the location to open.
|
---|
| 350 | * @param fOpen Flags for opening the backend.
|
---|
| 351 | * See RTFILE_O_* #defines, inventing another set
|
---|
| 352 | * of open flags is not worth the mapping effort.
|
---|
| 353 | * @param pfnCompleted The callback which is called whenever a task
|
---|
| 354 | * completed. The backend has to pass the user data
|
---|
| 355 | * of the request initiator (ie the one who calls
|
---|
| 356 | * VDAsyncRead or VDAsyncWrite) in pvCompletion
|
---|
| 357 | * if this is NULL.
|
---|
| 358 | * @param ppStorage Where to store the opaque storage handle.
|
---|
| 359 | */
|
---|
| 360 | DECLR3CALLBACKMEMBER(int, pfnOpen, (void *pvUser, const char *pszLocation,
|
---|
| 361 | uint32_t fOpen,
|
---|
| 362 | PFNVDCOMPLETED pfnCompleted,
|
---|
| 363 | void **ppStorage));
|
---|
| 364 |
|
---|
| 365 | /**
|
---|
| 366 | * Close callback.
|
---|
| 367 | *
|
---|
| 368 | * @return VBox status code.
|
---|
| 369 | * @param pvUser The opaque data passed on container creation.
|
---|
| 370 | * @param pStorage The opaque storage handle to close.
|
---|
| 371 | */
|
---|
| 372 | DECLR3CALLBACKMEMBER(int, pfnClose, (void *pvUser, void *pStorage));
|
---|
| 373 |
|
---|
| 374 | /**
|
---|
| 375 | * Delete callback.
|
---|
| 376 | *
|
---|
| 377 | * @return VBox status code.
|
---|
| 378 | * @param pvUser The opaque data passed on container creation.
|
---|
| 379 | * @param pcszFilename Name of the file to delete.
|
---|
| 380 | */
|
---|
| 381 | DECLR3CALLBACKMEMBER(int, pfnDelete, (void *pvUser, const char *pcszFilename));
|
---|
| 382 |
|
---|
| 383 | /**
|
---|
| 384 | * Move callback.
|
---|
| 385 | *
|
---|
| 386 | * @return VBox status code.
|
---|
| 387 | * @param pvUser The opaque data passed on container creation.
|
---|
| 388 | * @param pcszSrc The path to the source file.
|
---|
| 389 | * @param pcszDst The path to the destination file.
|
---|
| 390 | * This file will be created.
|
---|
| 391 | * @param fMove A combination of the RTFILEMOVE_* flags.
|
---|
| 392 | */
|
---|
| 393 | DECLR3CALLBACKMEMBER(int, pfnMove, (void *pvUser, const char *pcszSrc, const char *pcszDst, unsigned fMove));
|
---|
| 394 |
|
---|
| 395 | /**
|
---|
| 396 | * Returns the free space on a disk.
|
---|
| 397 | *
|
---|
| 398 | * @return VBox status code.
|
---|
| 399 | * @param pvUser The opaque data passed on container creation.
|
---|
| 400 | * @param pcszFilename Name of a file to identify the disk.
|
---|
| 401 | * @param pcbFreeSpace Where to store the free space of the disk.
|
---|
| 402 | */
|
---|
| 403 | DECLR3CALLBACKMEMBER(int, pfnGetFreeSpace, (void *pvUser, const char *pcszFilename, int64_t *pcbFreeSpace));
|
---|
| 404 |
|
---|
| 405 | /**
|
---|
| 406 | * Returns the last modification timestamp of a file.
|
---|
| 407 | *
|
---|
| 408 | * @return VBox status code.
|
---|
| 409 | * @param pvUser The opaque data passed on container creation.
|
---|
| 410 | * @param pcszFilename Name of a file to identify the disk.
|
---|
| 411 | * @param pModificationTime Where to store the timestamp of the file.
|
---|
| 412 | */
|
---|
| 413 | DECLR3CALLBACKMEMBER(int, pfnGetModificationTime, (void *pvUser, const char *pcszFilename, PRTTIMESPEC pModificationTime));
|
---|
| 414 |
|
---|
| 415 | /**
|
---|
| 416 | * Returns the size of the opened storage backend.
|
---|
| 417 | *
|
---|
| 418 | * @return VBox status code.
|
---|
| 419 | * @param pvUser The opaque data passed on container creation.
|
---|
| 420 | * @param pStorage The opaque storage handle to close.
|
---|
| 421 | * @param pcbSize Where to store the size of the storage backend.
|
---|
| 422 | */
|
---|
| 423 | DECLR3CALLBACKMEMBER(int, pfnGetSize, (void *pvUser, void *pStorage, uint64_t *pcbSize));
|
---|
| 424 |
|
---|
| 425 | /**
|
---|
| 426 | * Sets the size of the opened storage backend if possible.
|
---|
| 427 | *
|
---|
| 428 | * @return VBox status code.
|
---|
| 429 | * @retval VERR_NOT_SUPPORTED if the backend does not support this operation.
|
---|
| 430 | * @param pvUser The opaque data passed on container creation.
|
---|
| 431 | * @param pStorage The opaque storage handle to close.
|
---|
| 432 | * @param cbSize The new size of the image.
|
---|
| 433 | */
|
---|
| 434 | DECLR3CALLBACKMEMBER(int, pfnSetSize, (void *pvUser, void *pStorage, uint64_t cbSize));
|
---|
| 435 |
|
---|
| 436 | /**
|
---|
| 437 | * Synchronous write callback.
|
---|
| 438 | *
|
---|
| 439 | * @return VBox status code.
|
---|
| 440 | * @param pvUser The opaque data passed on container creation.
|
---|
| 441 | * @param pStorage The storage handle to use.
|
---|
| 442 | * @param uOffset The offset to start from.
|
---|
| 443 | * @param pvBuffer Pointer to the bits need to be written.
|
---|
| 444 | * @param cbBuffer How many bytes to write.
|
---|
| 445 | * @param pcbWritten Where to store how many bytes were actually written.
|
---|
| 446 | */
|
---|
| 447 | DECLR3CALLBACKMEMBER(int, pfnWriteSync, (void *pvUser, void *pStorage, uint64_t uOffset,
|
---|
| 448 | const void *pvBuffer, size_t cbBuffer, size_t *pcbWritten));
|
---|
| 449 |
|
---|
| 450 | /**
|
---|
| 451 | * Synchronous read callback.
|
---|
| 452 | *
|
---|
| 453 | * @return VBox status code.
|
---|
| 454 | * @param pvUser The opaque data passed on container creation.
|
---|
| 455 | * @param pStorage The storage handle to use.
|
---|
| 456 | * @param uOffset The offset to start from.
|
---|
| 457 | * @param pvBuffer Where to store the read bits.
|
---|
| 458 | * @param cbBuffer How many bytes to read.
|
---|
| 459 | * @param pcbRead Where to store how many bytes were actually read.
|
---|
| 460 | */
|
---|
| 461 | DECLR3CALLBACKMEMBER(int, pfnReadSync, (void *pvUser, void *pStorage, uint64_t uOffset,
|
---|
| 462 | void *pvBuffer, size_t cbBuffer, size_t *pcbRead));
|
---|
| 463 |
|
---|
| 464 | /**
|
---|
| 465 | * Flush data to the storage backend.
|
---|
| 466 | *
|
---|
| 467 | * @return VBox status code.
|
---|
| 468 | * @param pvUser The opaque data passed on container creation.
|
---|
| 469 | * @param pStorage The storage handle to flush.
|
---|
| 470 | */
|
---|
| 471 | DECLR3CALLBACKMEMBER(int, pfnFlushSync, (void *pvUser, void *pStorage));
|
---|
| 472 |
|
---|
| 473 | /**
|
---|
| 474 | * Initiate an asynchronous read request.
|
---|
| 475 | *
|
---|
| 476 | * @return VBox status code.
|
---|
| 477 | * @param pvUser The opaque user data passed on container creation.
|
---|
| 478 | * @param pStorage The storage handle.
|
---|
| 479 | * @param uOffset The offset to start reading from.
|
---|
| 480 | * @param paSegments Scatter gather list to store the data in.
|
---|
| 481 | * @param cSegments Number of segments in the list.
|
---|
| 482 | * @param cbRead How many bytes to read.
|
---|
| 483 | * @param pvCompletion The opaque user data which is returned upon completion.
|
---|
| 484 | * @param ppTask Where to store the opaque task handle.
|
---|
| 485 | */
|
---|
| 486 | DECLR3CALLBACKMEMBER(int, pfnReadAsync, (void *pvUser, void *pStorage, uint64_t uOffset,
|
---|
| 487 | PCRTSGSEG paSegments, size_t cSegments,
|
---|
| 488 | size_t cbRead, void *pvCompletion,
|
---|
| 489 | void **ppTask));
|
---|
| 490 |
|
---|
| 491 | /**
|
---|
| 492 | * Initiate an asynchronous write request.
|
---|
| 493 | *
|
---|
| 494 | * @return VBox status code.
|
---|
| 495 | * @param pvUser The opaque user data passed on conatiner creation.
|
---|
| 496 | * @param pStorage The storage handle.
|
---|
| 497 | * @param uOffset The offset to start writing to.
|
---|
| 498 | * @param paSegments Scatter gather list of the data to write
|
---|
| 499 | * @param cSegments Number of segments in the list.
|
---|
| 500 | * @param cbWrite How many bytes to write.
|
---|
| 501 | * @param pvCompletion The opaque user data which is returned upon completion.
|
---|
| 502 | * @param ppTask Where to store the opaque task handle.
|
---|
| 503 | */
|
---|
| 504 | DECLR3CALLBACKMEMBER(int, pfnWriteAsync, (void *pvUser, void *pStorage, uint64_t uOffset,
|
---|
| 505 | PCRTSGSEG paSegments, size_t cSegments,
|
---|
| 506 | size_t cbWrite, void *pvCompletion,
|
---|
| 507 | void **ppTask));
|
---|
| 508 |
|
---|
| 509 | /**
|
---|
| 510 | * Initiates an async flush request.
|
---|
| 511 | *
|
---|
| 512 | * @return VBox status code.
|
---|
| 513 | * @param pvUser The opaque data passed on container creation.
|
---|
| 514 | * @param pStorage The storage handle to flush.
|
---|
| 515 | * @param pvCompletion The opaque user data which is returned upon completion.
|
---|
| 516 | * @param ppTask Where to store the opaque task handle.
|
---|
| 517 | */
|
---|
| 518 | DECLR3CALLBACKMEMBER(int, pfnFlushAsync, (void *pvUser, void *pStorage,
|
---|
| 519 | void *pvCompletion, void **ppTask));
|
---|
| 520 |
|
---|
| 521 | } VDINTERFACEIO, *PVDINTERFACEIO;
|
---|
| 522 |
|
---|
| 523 | /**
|
---|
| 524 | * Get I/O interface from interface list.
|
---|
| 525 | *
|
---|
| 526 | * @return Pointer to the first I/O interface in the list.
|
---|
| 527 | * @param pVDIfs Pointer to the interface list.
|
---|
| 528 | */
|
---|
| 529 | DECLINLINE(PVDINTERFACEIO) VDIfIoGet(PVDINTERFACE pVDIfs)
|
---|
| 530 | {
|
---|
| 531 | PVDINTERFACE pIf = VDInterfaceGet(pVDIfs, VDINTERFACETYPE_IO);
|
---|
| 532 |
|
---|
| 533 | /* Check that the interface descriptor is a progress interface. */
|
---|
| 534 | AssertMsgReturn( !pIf
|
---|
| 535 | || ( (pIf->enmInterface == VDINTERFACETYPE_IO)
|
---|
| 536 | && (pIf->cbSize == sizeof(VDINTERFACEIO))),
|
---|
| 537 | ("Not a I/O interface"), NULL);
|
---|
| 538 |
|
---|
| 539 | return (PVDINTERFACEIO)pIf;
|
---|
| 540 | }
|
---|
| 541 |
|
---|
| 542 | DECLINLINE(int) vdIfIoFileOpen(PVDINTERFACEIO pIfIo, const char *pszFilename,
|
---|
| 543 | uint32_t fOpen, PFNVDCOMPLETED pfnCompleted,
|
---|
| 544 | void **ppStorage)
|
---|
| 545 | {
|
---|
| 546 | return pIfIo->pfnOpen(pIfIo->Core.pvUser, pszFilename, fOpen, pfnCompleted, ppStorage);
|
---|
| 547 | }
|
---|
| 548 |
|
---|
| 549 | DECLINLINE(int) vdIfIoFileClose(PVDINTERFACEIO pIfIo, void *pStorage)
|
---|
| 550 | {
|
---|
| 551 | return pIfIo->pfnClose(pIfIo->Core.pvUser, pStorage);
|
---|
| 552 | }
|
---|
| 553 |
|
---|
| 554 | DECLINLINE(int) vdIfIoFileDelete(PVDINTERFACEIO pIfIo, const char *pszFilename)
|
---|
| 555 | {
|
---|
| 556 | return pIfIo->pfnDelete(pIfIo->Core.pvUser, pszFilename);
|
---|
| 557 | }
|
---|
| 558 |
|
---|
| 559 | DECLINLINE(int) vdIfIoFileMove(PVDINTERFACEIO pIfIo, const char *pszSrc,
|
---|
| 560 | const char *pszDst, unsigned fMove)
|
---|
| 561 | {
|
---|
| 562 | return pIfIo->pfnMove(pIfIo->Core.pvUser, pszSrc, pszDst, fMove);
|
---|
| 563 | }
|
---|
| 564 |
|
---|
| 565 | DECLINLINE(int) vdIfIoFileGetFreeSpace(PVDINTERFACEIO pIfIo, const char *pszFilename,
|
---|
| 566 | int64_t *pcbFree)
|
---|
| 567 | {
|
---|
| 568 | return pIfIo->pfnGetFreeSpace(pIfIo->Core.pvUser, pszFilename, pcbFree);
|
---|
| 569 | }
|
---|
| 570 |
|
---|
| 571 | DECLINLINE(int) vdIfIoFileGetModificationTime(PVDINTERFACEIO pIfIo, const char *pcszFilename,
|
---|
| 572 | PRTTIMESPEC pModificationTime)
|
---|
| 573 | {
|
---|
| 574 | return pIfIo->pfnGetModificationTime(pIfIo->Core.pvUser, pcszFilename,
|
---|
| 575 | pModificationTime);
|
---|
| 576 | }
|
---|
| 577 |
|
---|
| 578 | DECLINLINE(int) vdIfIoFileGetSize(PVDINTERFACEIO pIfIo, void *pStorage,
|
---|
| 579 | uint64_t *pcbSize)
|
---|
| 580 | {
|
---|
| 581 | return pIfIo->pfnGetSize(pIfIo->Core.pvUser, pStorage, pcbSize);
|
---|
| 582 | }
|
---|
| 583 |
|
---|
| 584 | DECLINLINE(int) vdIfIoFileSetSize(PVDINTERFACEIO pIfIo, void *pStorage,
|
---|
| 585 | uint64_t cbSize)
|
---|
| 586 | {
|
---|
| 587 | return pIfIo->pfnSetSize(pIfIo->Core.pvUser, pStorage, cbSize);
|
---|
| 588 | }
|
---|
| 589 |
|
---|
| 590 | DECLINLINE(int) vdIfIoFileWriteSync(PVDINTERFACEIO pIfIo, void *pStorage,
|
---|
| 591 | uint64_t uOffset, const void *pvBuffer, size_t cbBuffer,
|
---|
| 592 | size_t *pcbWritten)
|
---|
| 593 | {
|
---|
| 594 | return pIfIo->pfnWriteSync(pIfIo->Core.pvUser, pStorage, uOffset,
|
---|
| 595 | pvBuffer, cbBuffer, pcbWritten);
|
---|
| 596 | }
|
---|
| 597 |
|
---|
| 598 | DECLINLINE(int) vdIfIoFileReadSync(PVDINTERFACEIO pIfIo, void *pStorage,
|
---|
| 599 | uint64_t uOffset, void *pvBuffer, size_t cbBuffer,
|
---|
| 600 | size_t *pcbRead)
|
---|
| 601 | {
|
---|
| 602 | return pIfIo->pfnReadSync(pIfIo->Core.pvUser, pStorage, uOffset,
|
---|
| 603 | pvBuffer, cbBuffer, pcbRead);
|
---|
| 604 | }
|
---|
| 605 |
|
---|
| 606 | DECLINLINE(int) vdIfIoFileFlushSync(PVDINTERFACEIO pIfIo, void *pStorage)
|
---|
| 607 | {
|
---|
| 608 | return pIfIo->pfnFlushSync(pIfIo->Core.pvUser, pStorage);
|
---|
| 609 | }
|
---|
| 610 |
|
---|
| 611 | /**
|
---|
[47345] | 612 | * Create a VFS stream handle around a VD I/O interface.
|
---|
| 613 | *
|
---|
| 614 | * The I/O interface will not be closed or free by the stream, the caller will
|
---|
| 615 | * do so after it is done with the stream and has released the instances of the
|
---|
| 616 | * I/O stream object returned by this API.
|
---|
| 617 | *
|
---|
| 618 | * @return VBox status code.
|
---|
| 619 | * @param pVDIfsIo Pointer to the VD I/O interface.
|
---|
[47349] | 620 | * @param pvStorage The storage argument to pass to the interface
|
---|
| 621 | * methods.
|
---|
[47345] | 622 | * @param fFlags RTFILE_O_XXX, access mask requied.
|
---|
| 623 | * @param phVfsIos Where to return the VFS I/O stream handle on
|
---|
| 624 | * success.
|
---|
| 625 | */
|
---|
[47349] | 626 | VBOXDDU_DECL(int) VDIfCreateVfsStream(PVDINTERFACEIO pVDIfsIo, void *pvStorage, uint32_t fFlags, PRTVFSIOSTREAM phVfsIos);
|
---|
[47345] | 627 |
|
---|
[48849] | 628 | /**
|
---|
| 629 | * Create a VFS file handle around a VD I/O interface.
|
---|
| 630 | *
|
---|
| 631 | * The I/O interface will not be closed or free by the VFS file, the caller will
|
---|
| 632 | * do so after it is done with the VFS file and has released the instances of
|
---|
| 633 | * the VFS object returned by this API.
|
---|
| 634 | *
|
---|
| 635 | * @return VBox status code.
|
---|
[48871] | 636 | * @param pVDIfs Pointer to the VD I/O interface. If NULL, then @a
|
---|
| 637 | * pVDIfsInt must be specified.
|
---|
| 638 | * @param pVDIfsInt Pointer to the internal VD I/O interface. If NULL,
|
---|
| 639 | * then @ pVDIfs must be specified.
|
---|
[48849] | 640 | * @param pvStorage The storage argument to pass to the interface
|
---|
| 641 | * methods.
|
---|
| 642 | * @param fFlags RTFILE_O_XXX, access mask requied.
|
---|
| 643 | * @param phVfsFile Where to return the VFS file handle on success.
|
---|
| 644 | */
|
---|
[48871] | 645 | VBOXDDU_DECL(int) VDIfCreateVfsFile(PVDINTERFACEIO pVDIfs, struct VDINTERFACEIOINT *pVDIfsInt, void *pvStorage, uint32_t fFlags, PRTVFSFILE phVfsFile);
|
---|
[47345] | 646 |
|
---|
[48849] | 647 |
|
---|
[47345] | 648 | /**
|
---|
[38469] | 649 | * Callback which provides progress information about a currently running
|
---|
| 650 | * lengthy operation.
|
---|
| 651 | *
|
---|
| 652 | * @return VBox status code.
|
---|
| 653 | * @param pvUser The opaque user data associated with this interface.
|
---|
| 654 | * @param uPercent Completion percentage.
|
---|
| 655 | */
|
---|
| 656 | typedef DECLCALLBACK(int) FNVDPROGRESS(void *pvUser, unsigned uPercentage);
|
---|
| 657 | /** Pointer to FNVDPROGRESS() */
|
---|
| 658 | typedef FNVDPROGRESS *PFNVDPROGRESS;
|
---|
| 659 |
|
---|
| 660 | /**
|
---|
| 661 | * Progress notification interface
|
---|
| 662 | *
|
---|
| 663 | * Per-operation. Optional.
|
---|
| 664 | */
|
---|
| 665 | typedef struct VDINTERFACEPROGRESS
|
---|
| 666 | {
|
---|
| 667 | /**
|
---|
| 668 | * Common interface header.
|
---|
| 669 | */
|
---|
| 670 | VDINTERFACE Core;
|
---|
| 671 |
|
---|
| 672 | /**
|
---|
| 673 | * Progress notification callbacks.
|
---|
| 674 | */
|
---|
| 675 | PFNVDPROGRESS pfnProgress;
|
---|
| 676 |
|
---|
| 677 | } VDINTERFACEPROGRESS, *PVDINTERFACEPROGRESS;
|
---|
| 678 |
|
---|
| 679 | /**
|
---|
| 680 | * Get progress interface from interface list.
|
---|
| 681 | *
|
---|
| 682 | * @return Pointer to the first progress interface in the list.
|
---|
| 683 | * @param pVDIfs Pointer to the interface list.
|
---|
| 684 | */
|
---|
| 685 | DECLINLINE(PVDINTERFACEPROGRESS) VDIfProgressGet(PVDINTERFACE pVDIfs)
|
---|
| 686 | {
|
---|
| 687 | PVDINTERFACE pIf = VDInterfaceGet(pVDIfs, VDINTERFACETYPE_PROGRESS);
|
---|
| 688 |
|
---|
| 689 | /* Check that the interface descriptor is a progress interface. */
|
---|
| 690 | AssertMsgReturn( !pIf
|
---|
| 691 | || ( (pIf->enmInterface == VDINTERFACETYPE_PROGRESS)
|
---|
| 692 | && (pIf->cbSize == sizeof(VDINTERFACEPROGRESS))),
|
---|
| 693 | ("Not a progress interface"), NULL);
|
---|
| 694 |
|
---|
| 695 | return (PVDINTERFACEPROGRESS)pIf;
|
---|
| 696 | }
|
---|
| 697 |
|
---|
| 698 |
|
---|
| 699 | /**
|
---|
| 700 | * Configuration information interface
|
---|
| 701 | *
|
---|
| 702 | * Per-image. Optional for most backends, but mandatory for images which do
|
---|
| 703 | * not operate on files (including standard block or character devices).
|
---|
| 704 | */
|
---|
| 705 | typedef struct VDINTERFACECONFIG
|
---|
| 706 | {
|
---|
| 707 | /**
|
---|
| 708 | * Common interface header.
|
---|
| 709 | */
|
---|
| 710 | VDINTERFACE Core;
|
---|
| 711 |
|
---|
| 712 | /**
|
---|
| 713 | * Validates that the keys are within a set of valid names.
|
---|
| 714 | *
|
---|
| 715 | * @return true if all key names are found in pszzAllowed.
|
---|
| 716 | * @return false if not.
|
---|
| 717 | * @param pvUser The opaque user data associated with this interface.
|
---|
| 718 | * @param pszzValid List of valid key names separated by '\\0' and ending with
|
---|
| 719 | * a double '\\0'.
|
---|
| 720 | */
|
---|
| 721 | DECLR3CALLBACKMEMBER(bool, pfnAreKeysValid, (void *pvUser, const char *pszzValid));
|
---|
| 722 |
|
---|
| 723 | /**
|
---|
| 724 | * Retrieves the length of the string value associated with a key (including
|
---|
| 725 | * the terminator, for compatibility with CFGMR3QuerySize).
|
---|
| 726 | *
|
---|
| 727 | * @return VBox status code.
|
---|
| 728 | * VERR_CFGM_VALUE_NOT_FOUND means that the key is not known.
|
---|
| 729 | * @param pvUser The opaque user data associated with this interface.
|
---|
| 730 | * @param pszName Name of the key to query.
|
---|
| 731 | * @param pcbValue Where to store the value length. Non-NULL.
|
---|
| 732 | */
|
---|
| 733 | DECLR3CALLBACKMEMBER(int, pfnQuerySize, (void *pvUser, const char *pszName, size_t *pcbValue));
|
---|
| 734 |
|
---|
| 735 | /**
|
---|
| 736 | * Query the string value associated with a key.
|
---|
| 737 | *
|
---|
| 738 | * @return VBox status code.
|
---|
| 739 | * VERR_CFGM_VALUE_NOT_FOUND means that the key is not known.
|
---|
| 740 | * VERR_CFGM_NOT_ENOUGH_SPACE means that the buffer is not big enough.
|
---|
| 741 | * @param pvUser The opaque user data associated with this interface.
|
---|
| 742 | * @param pszName Name of the key to query.
|
---|
| 743 | * @param pszValue Pointer to buffer where to store value.
|
---|
| 744 | * @param cchValue Length of value buffer.
|
---|
| 745 | */
|
---|
| 746 | DECLR3CALLBACKMEMBER(int, pfnQuery, (void *pvUser, const char *pszName, char *pszValue, size_t cchValue));
|
---|
| 747 |
|
---|
[51102] | 748 | /**
|
---|
| 749 | * Query the bytes value associated with a key.
|
---|
| 750 | *
|
---|
| 751 | * @return VBox status code.
|
---|
| 752 | * VERR_CFGM_VALUE_NOT_FOUND means that the key is not known.
|
---|
| 753 | * VERR_CFGM_NOT_ENOUGH_SPACE means that the buffer is not big enough.
|
---|
| 754 | * @param pvUser The opaque user data associated with this interface.
|
---|
| 755 | * @param pszName Name of the key to query.
|
---|
| 756 | * @param ppvData Pointer to buffer where to store the data.
|
---|
| 757 | * @param cbData Length of data buffer.
|
---|
| 758 | */
|
---|
| 759 | DECLR3CALLBACKMEMBER(int, pfnQueryBytes, (void *pvUser, const char *pszName, void *ppvData, size_t cbData));
|
---|
| 760 |
|
---|
[38469] | 761 | } VDINTERFACECONFIG, *PVDINTERFACECONFIG;
|
---|
| 762 |
|
---|
| 763 | /**
|
---|
| 764 | * Get configuration information interface from interface list.
|
---|
| 765 | *
|
---|
| 766 | * @return Pointer to the first configuration information interface in the list.
|
---|
| 767 | * @param pVDIfs Pointer to the interface list.
|
---|
| 768 | */
|
---|
| 769 | DECLINLINE(PVDINTERFACECONFIG) VDIfConfigGet(PVDINTERFACE pVDIfs)
|
---|
| 770 | {
|
---|
| 771 | PVDINTERFACE pIf = VDInterfaceGet(pVDIfs, VDINTERFACETYPE_CONFIG);
|
---|
| 772 |
|
---|
| 773 | /* Check that the interface descriptor is a progress interface. */
|
---|
| 774 | AssertMsgReturn( !pIf
|
---|
| 775 | || ( (pIf->enmInterface == VDINTERFACETYPE_CONFIG)
|
---|
| 776 | && (pIf->cbSize == sizeof(VDINTERFACECONFIG))),
|
---|
| 777 | ("Not a config interface"), NULL);
|
---|
| 778 |
|
---|
| 779 | return (PVDINTERFACECONFIG)pIf;
|
---|
| 780 | }
|
---|
| 781 |
|
---|
| 782 | /**
|
---|
| 783 | * Query configuration, validates that the keys are within a set of valid names.
|
---|
| 784 | *
|
---|
| 785 | * @return true if all key names are found in pszzAllowed.
|
---|
| 786 | * @return false if not.
|
---|
| 787 | * @param pCfgIf Pointer to configuration callback table.
|
---|
| 788 | * @param pszzValid List of valid names separated by '\\0' and ending with
|
---|
| 789 | * a double '\\0'.
|
---|
| 790 | */
|
---|
| 791 | DECLINLINE(bool) VDCFGAreKeysValid(PVDINTERFACECONFIG pCfgIf, const char *pszzValid)
|
---|
| 792 | {
|
---|
| 793 | return pCfgIf->pfnAreKeysValid(pCfgIf->Core.pvUser, pszzValid);
|
---|
| 794 | }
|
---|
| 795 |
|
---|
| 796 | /**
|
---|
| 797 | * Query configuration, unsigned 64-bit integer value with default.
|
---|
| 798 | *
|
---|
| 799 | * @return VBox status code.
|
---|
| 800 | * @param pCfgIf Pointer to configuration callback table.
|
---|
| 801 | * @param pszName Name of an integer value
|
---|
| 802 | * @param pu64 Where to store the value. Set to default on failure.
|
---|
| 803 | * @param u64Def The default value.
|
---|
| 804 | */
|
---|
| 805 | DECLINLINE(int) VDCFGQueryU64Def(PVDINTERFACECONFIG pCfgIf,
|
---|
| 806 | const char *pszName, uint64_t *pu64,
|
---|
| 807 | uint64_t u64Def)
|
---|
| 808 | {
|
---|
| 809 | char aszBuf[32];
|
---|
| 810 | int rc = pCfgIf->pfnQuery(pCfgIf->Core.pvUser, pszName, aszBuf, sizeof(aszBuf));
|
---|
| 811 | if (RT_SUCCESS(rc))
|
---|
| 812 | {
|
---|
| 813 | rc = RTStrToUInt64Full(aszBuf, 0, pu64);
|
---|
| 814 | }
|
---|
| 815 | else if (rc == VERR_CFGM_VALUE_NOT_FOUND)
|
---|
| 816 | {
|
---|
| 817 | rc = VINF_SUCCESS;
|
---|
| 818 | *pu64 = u64Def;
|
---|
| 819 | }
|
---|
| 820 | return rc;
|
---|
| 821 | }
|
---|
| 822 |
|
---|
| 823 | /**
|
---|
| 824 | * Query configuration, unsigned 32-bit integer value with default.
|
---|
| 825 | *
|
---|
| 826 | * @return VBox status code.
|
---|
| 827 | * @param pCfgIf Pointer to configuration callback table.
|
---|
| 828 | * @param pszName Name of an integer value
|
---|
| 829 | * @param pu32 Where to store the value. Set to default on failure.
|
---|
| 830 | * @param u32Def The default value.
|
---|
| 831 | */
|
---|
| 832 | DECLINLINE(int) VDCFGQueryU32Def(PVDINTERFACECONFIG pCfgIf,
|
---|
| 833 | const char *pszName, uint32_t *pu32,
|
---|
| 834 | uint32_t u32Def)
|
---|
| 835 | {
|
---|
| 836 | uint64_t u64;
|
---|
| 837 | int rc = VDCFGQueryU64Def(pCfgIf, pszName, &u64, u32Def);
|
---|
| 838 | if (RT_SUCCESS(rc))
|
---|
| 839 | {
|
---|
| 840 | if (!(u64 & UINT64_C(0xffffffff00000000)))
|
---|
| 841 | *pu32 = (uint32_t)u64;
|
---|
| 842 | else
|
---|
| 843 | rc = VERR_CFGM_INTEGER_TOO_BIG;
|
---|
| 844 | }
|
---|
| 845 | return rc;
|
---|
| 846 | }
|
---|
| 847 |
|
---|
| 848 | /**
|
---|
| 849 | * Query configuration, bool value with default.
|
---|
| 850 | *
|
---|
| 851 | * @return VBox status code.
|
---|
| 852 | * @param pCfgIf Pointer to configuration callback table.
|
---|
| 853 | * @param pszName Name of an integer value
|
---|
| 854 | * @param pf Where to store the value. Set to default on failure.
|
---|
| 855 | * @param fDef The default value.
|
---|
| 856 | */
|
---|
| 857 | DECLINLINE(int) VDCFGQueryBoolDef(PVDINTERFACECONFIG pCfgIf,
|
---|
| 858 | const char *pszName, bool *pf,
|
---|
| 859 | bool fDef)
|
---|
| 860 | {
|
---|
| 861 | uint64_t u64;
|
---|
| 862 | int rc = VDCFGQueryU64Def(pCfgIf, pszName, &u64, fDef);
|
---|
| 863 | if (RT_SUCCESS(rc))
|
---|
| 864 | *pf = u64 ? true : false;
|
---|
| 865 | return rc;
|
---|
| 866 | }
|
---|
| 867 |
|
---|
| 868 | /**
|
---|
| 869 | * Query configuration, dynamically allocated (RTMemAlloc) zero terminated
|
---|
| 870 | * character value.
|
---|
| 871 | *
|
---|
| 872 | * @return VBox status code.
|
---|
| 873 | * @param pCfgIf Pointer to configuration callback table.
|
---|
| 874 | * @param pszName Name of an zero terminated character value
|
---|
| 875 | * @param ppszString Where to store the string pointer. Not set on failure.
|
---|
| 876 | * Free this using RTMemFree().
|
---|
| 877 | */
|
---|
| 878 | DECLINLINE(int) VDCFGQueryStringAlloc(PVDINTERFACECONFIG pCfgIf,
|
---|
| 879 | const char *pszName, char **ppszString)
|
---|
| 880 | {
|
---|
| 881 | size_t cb;
|
---|
| 882 | int rc = pCfgIf->pfnQuerySize(pCfgIf->Core.pvUser, pszName, &cb);
|
---|
| 883 | if (RT_SUCCESS(rc))
|
---|
| 884 | {
|
---|
| 885 | char *pszString = (char *)RTMemAlloc(cb);
|
---|
| 886 | if (pszString)
|
---|
| 887 | {
|
---|
| 888 | rc = pCfgIf->pfnQuery(pCfgIf->Core.pvUser, pszName, pszString, cb);
|
---|
| 889 | if (RT_SUCCESS(rc))
|
---|
| 890 | *ppszString = pszString;
|
---|
| 891 | else
|
---|
| 892 | RTMemFree(pszString);
|
---|
| 893 | }
|
---|
| 894 | else
|
---|
| 895 | rc = VERR_NO_MEMORY;
|
---|
| 896 | }
|
---|
| 897 | return rc;
|
---|
| 898 | }
|
---|
| 899 |
|
---|
| 900 | /**
|
---|
| 901 | * Query configuration, dynamically allocated (RTMemAlloc) zero terminated
|
---|
| 902 | * character value with default.
|
---|
| 903 | *
|
---|
| 904 | * @return VBox status code.
|
---|
| 905 | * @param pCfgIf Pointer to configuration callback table.
|
---|
| 906 | * @param pszName Name of an zero terminated character value
|
---|
| 907 | * @param ppszString Where to store the string pointer. Not set on failure.
|
---|
| 908 | * Free this using RTMemFree().
|
---|
| 909 | * @param pszDef The default value.
|
---|
| 910 | */
|
---|
| 911 | DECLINLINE(int) VDCFGQueryStringAllocDef(PVDINTERFACECONFIG pCfgIf,
|
---|
| 912 | const char *pszName,
|
---|
| 913 | char **ppszString,
|
---|
| 914 | const char *pszDef)
|
---|
| 915 | {
|
---|
| 916 | size_t cb;
|
---|
| 917 | int rc = pCfgIf->pfnQuerySize(pCfgIf->Core.pvUser, pszName, &cb);
|
---|
| 918 | if (rc == VERR_CFGM_VALUE_NOT_FOUND || rc == VERR_CFGM_NO_PARENT)
|
---|
| 919 | {
|
---|
| 920 | cb = strlen(pszDef) + 1;
|
---|
| 921 | rc = VINF_SUCCESS;
|
---|
| 922 | }
|
---|
| 923 | if (RT_SUCCESS(rc))
|
---|
| 924 | {
|
---|
| 925 | char *pszString = (char *)RTMemAlloc(cb);
|
---|
| 926 | if (pszString)
|
---|
| 927 | {
|
---|
| 928 | rc = pCfgIf->pfnQuery(pCfgIf->Core.pvUser, pszName, pszString, cb);
|
---|
| 929 | if (rc == VERR_CFGM_VALUE_NOT_FOUND || rc == VERR_CFGM_NO_PARENT)
|
---|
| 930 | {
|
---|
| 931 | memcpy(pszString, pszDef, cb);
|
---|
| 932 | rc = VINF_SUCCESS;
|
---|
| 933 | }
|
---|
| 934 | if (RT_SUCCESS(rc))
|
---|
| 935 | *ppszString = pszString;
|
---|
| 936 | else
|
---|
| 937 | RTMemFree(pszString);
|
---|
| 938 | }
|
---|
| 939 | else
|
---|
| 940 | rc = VERR_NO_MEMORY;
|
---|
| 941 | }
|
---|
| 942 | return rc;
|
---|
| 943 | }
|
---|
| 944 |
|
---|
| 945 | /**
|
---|
| 946 | * Query configuration, dynamically allocated (RTMemAlloc) byte string value.
|
---|
| 947 | *
|
---|
| 948 | * @return VBox status code.
|
---|
| 949 | * @param pCfgIf Pointer to configuration callback table.
|
---|
| 950 | * @param pszName Name of an zero terminated character value
|
---|
| 951 | * @param ppvData Where to store the byte string pointer. Not set on failure.
|
---|
| 952 | * Free this using RTMemFree().
|
---|
| 953 | * @param pcbData Where to store the byte string length.
|
---|
| 954 | */
|
---|
| 955 | DECLINLINE(int) VDCFGQueryBytesAlloc(PVDINTERFACECONFIG pCfgIf,
|
---|
| 956 | const char *pszName, void **ppvData, size_t *pcbData)
|
---|
| 957 | {
|
---|
| 958 | size_t cb;
|
---|
| 959 | int rc = pCfgIf->pfnQuerySize(pCfgIf->Core.pvUser, pszName, &cb);
|
---|
| 960 | if (RT_SUCCESS(rc))
|
---|
| 961 | {
|
---|
| 962 | char *pbData;
|
---|
| 963 | Assert(cb);
|
---|
| 964 |
|
---|
| 965 | pbData = (char *)RTMemAlloc(cb);
|
---|
| 966 | if (pbData)
|
---|
| 967 | {
|
---|
[51102] | 968 | if(pCfgIf->pfnQueryBytes)
|
---|
| 969 | rc = pCfgIf->pfnQueryBytes(pCfgIf->Core.pvUser, pszName, pbData, cb);
|
---|
| 970 | else
|
---|
| 971 | rc = pCfgIf->pfnQuery(pCfgIf->Core.pvUser, pszName, pbData, cb);
|
---|
| 972 |
|
---|
[38469] | 973 | if (RT_SUCCESS(rc))
|
---|
| 974 | {
|
---|
| 975 | *ppvData = pbData;
|
---|
[51108] | 976 | /* Exclude terminator if the byte data was obtained using the string query callback. */
|
---|
[51102] | 977 | *pcbData = cb;
|
---|
[51108] | 978 | if (!pCfgIf->pfnQueryBytes)
|
---|
[51162] | 979 | (*pcbData)--;
|
---|
[38469] | 980 | }
|
---|
| 981 | else
|
---|
| 982 | RTMemFree(pbData);
|
---|
| 983 | }
|
---|
| 984 | else
|
---|
| 985 | rc = VERR_NO_MEMORY;
|
---|
| 986 | }
|
---|
| 987 | return rc;
|
---|
| 988 | }
|
---|
| 989 |
|
---|
| 990 | /** Forward declaration of a VD socket. */
|
---|
| 991 | typedef struct VDSOCKETINT *VDSOCKET;
|
---|
| 992 | /** Pointer to a VD socket. */
|
---|
| 993 | typedef VDSOCKET *PVDSOCKET;
|
---|
| 994 | /** Nil socket handle. */
|
---|
| 995 | #define NIL_VDSOCKET ((VDSOCKET)0)
|
---|
| 996 |
|
---|
| 997 | /** Connect flag to indicate that the backend wants to use the extended
|
---|
| 998 | * socket I/O multiplexing call. This might not be supported on all configurations
|
---|
| 999 | * (internal networking and iSCSI)
|
---|
| 1000 | * and the backend needs to take appropriate action.
|
---|
| 1001 | */
|
---|
| 1002 | #define VD_INTERFACETCPNET_CONNECT_EXTENDED_SELECT RT_BIT_32(0)
|
---|
| 1003 |
|
---|
| 1004 | /** @name Select events
|
---|
| 1005 | * @{ */
|
---|
| 1006 | /** Readable without blocking. */
|
---|
| 1007 | #define VD_INTERFACETCPNET_EVT_READ RT_BIT_32(0)
|
---|
| 1008 | /** Writable without blocking. */
|
---|
| 1009 | #define VD_INTERFACETCPNET_EVT_WRITE RT_BIT_32(1)
|
---|
| 1010 | /** Error condition, hangup, exception or similar. */
|
---|
| 1011 | #define VD_INTERFACETCPNET_EVT_ERROR RT_BIT_32(2)
|
---|
| 1012 | /** Hint for the select that getting interrupted while waiting is more likely.
|
---|
| 1013 | * The interface implementation can optimize the waiting strategy based on this.
|
---|
| 1014 | * It is assumed that it is more likely to get one of the above socket events
|
---|
| 1015 | * instead of being interrupted if the flag is not set. */
|
---|
| 1016 | #define VD_INTERFACETCPNET_HINT_INTERRUPT RT_BIT_32(3)
|
---|
| 1017 | /** Mask of the valid bits. */
|
---|
| 1018 | #define VD_INTERFACETCPNET_EVT_VALID_MASK UINT32_C(0x0000000f)
|
---|
| 1019 | /** @} */
|
---|
| 1020 |
|
---|
| 1021 | /**
|
---|
| 1022 | * TCP network stack interface
|
---|
| 1023 | *
|
---|
| 1024 | * Per-image. Mandatory for backends which have the VD_CAP_TCPNET bit set.
|
---|
| 1025 | */
|
---|
| 1026 | typedef struct VDINTERFACETCPNET
|
---|
| 1027 | {
|
---|
| 1028 | /**
|
---|
| 1029 | * Common interface header.
|
---|
| 1030 | */
|
---|
| 1031 | VDINTERFACE Core;
|
---|
| 1032 |
|
---|
| 1033 | /**
|
---|
| 1034 | * Creates a socket. The socket is not connected if this succeeds.
|
---|
| 1035 | *
|
---|
| 1036 | * @return iprt status code.
|
---|
| 1037 | * @retval VERR_NOT_SUPPORTED if the combination of flags is not supported.
|
---|
| 1038 | * @param fFlags Combination of the VD_INTERFACETCPNET_CONNECT_* #defines.
|
---|
| 1039 | * @param pSock Where to store the handle.
|
---|
| 1040 | */
|
---|
| 1041 | DECLR3CALLBACKMEMBER(int, pfnSocketCreate, (uint32_t fFlags, PVDSOCKET pSock));
|
---|
| 1042 |
|
---|
| 1043 | /**
|
---|
| 1044 | * Destroys the socket.
|
---|
| 1045 | *
|
---|
| 1046 | * @return iprt status code.
|
---|
| 1047 | * @param Sock Socket descriptor.
|
---|
| 1048 | */
|
---|
| 1049 | DECLR3CALLBACKMEMBER(int, pfnSocketDestroy, (VDSOCKET Sock));
|
---|
| 1050 |
|
---|
| 1051 | /**
|
---|
| 1052 | * Connect as a client to a TCP port.
|
---|
| 1053 | *
|
---|
| 1054 | * @return iprt status code.
|
---|
| 1055 | * @param Sock Socket descriptor.
|
---|
| 1056 | * @param pszAddress The address to connect to.
|
---|
| 1057 | * @param uPort The port to connect to.
|
---|
| 1058 | */
|
---|
| 1059 | DECLR3CALLBACKMEMBER(int, pfnClientConnect, (VDSOCKET Sock, const char *pszAddress, uint32_t uPort));
|
---|
| 1060 |
|
---|
| 1061 | /**
|
---|
| 1062 | * Close a TCP connection.
|
---|
| 1063 | *
|
---|
| 1064 | * @return iprt status code.
|
---|
| 1065 | * @param Sock Socket descriptor.
|
---|
| 1066 | */
|
---|
| 1067 | DECLR3CALLBACKMEMBER(int, pfnClientClose, (VDSOCKET Sock));
|
---|
| 1068 |
|
---|
| 1069 | /**
|
---|
| 1070 | * Returns whether the socket is currently connected to the client.
|
---|
| 1071 | *
|
---|
| 1072 | * @returns true if the socket is connected.
|
---|
| 1073 | * false otherwise.
|
---|
| 1074 | * @param Sock Socket descriptor.
|
---|
| 1075 | */
|
---|
| 1076 | DECLR3CALLBACKMEMBER(bool, pfnIsClientConnected, (VDSOCKET Sock));
|
---|
| 1077 |
|
---|
| 1078 | /**
|
---|
| 1079 | * Socket I/O multiplexing.
|
---|
| 1080 | * Checks if the socket is ready for reading.
|
---|
| 1081 | *
|
---|
| 1082 | * @return iprt status code.
|
---|
| 1083 | * @param Sock Socket descriptor.
|
---|
| 1084 | * @param cMillies Number of milliseconds to wait for the socket.
|
---|
| 1085 | * Use RT_INDEFINITE_WAIT to wait for ever.
|
---|
| 1086 | */
|
---|
| 1087 | DECLR3CALLBACKMEMBER(int, pfnSelectOne, (VDSOCKET Sock, RTMSINTERVAL cMillies));
|
---|
| 1088 |
|
---|
| 1089 | /**
|
---|
| 1090 | * Receive data from a socket.
|
---|
| 1091 | *
|
---|
| 1092 | * @return iprt status code.
|
---|
| 1093 | * @param Sock Socket descriptor.
|
---|
| 1094 | * @param pvBuffer Where to put the data we read.
|
---|
| 1095 | * @param cbBuffer Read buffer size.
|
---|
| 1096 | * @param pcbRead Number of bytes read.
|
---|
| 1097 | * If NULL the entire buffer will be filled upon successful return.
|
---|
| 1098 | * If not NULL a partial read can be done successfully.
|
---|
| 1099 | */
|
---|
| 1100 | DECLR3CALLBACKMEMBER(int, pfnRead, (VDSOCKET Sock, void *pvBuffer, size_t cbBuffer, size_t *pcbRead));
|
---|
| 1101 |
|
---|
| 1102 | /**
|
---|
| 1103 | * Send data to a socket.
|
---|
| 1104 | *
|
---|
| 1105 | * @return iprt status code.
|
---|
| 1106 | * @param Sock Socket descriptor.
|
---|
| 1107 | * @param pvBuffer Buffer to write data to socket.
|
---|
| 1108 | * @param cbBuffer How much to write.
|
---|
| 1109 | */
|
---|
| 1110 | DECLR3CALLBACKMEMBER(int, pfnWrite, (VDSOCKET Sock, const void *pvBuffer, size_t cbBuffer));
|
---|
| 1111 |
|
---|
| 1112 | /**
|
---|
| 1113 | * Send data from scatter/gather buffer to a socket.
|
---|
| 1114 | *
|
---|
| 1115 | * @return iprt status code.
|
---|
| 1116 | * @param Sock Socket descriptor.
|
---|
| 1117 | * @param pSgBuffer Scatter/gather buffer to write data to socket.
|
---|
| 1118 | */
|
---|
| 1119 | DECLR3CALLBACKMEMBER(int, pfnSgWrite, (VDSOCKET Sock, PCRTSGBUF pSgBuffer));
|
---|
| 1120 |
|
---|
| 1121 | /**
|
---|
| 1122 | * Receive data from a socket - not blocking.
|
---|
| 1123 | *
|
---|
| 1124 | * @return iprt status code.
|
---|
| 1125 | * @param Sock Socket descriptor.
|
---|
| 1126 | * @param pvBuffer Where to put the data we read.
|
---|
| 1127 | * @param cbBuffer Read buffer size.
|
---|
| 1128 | * @param pcbRead Number of bytes read.
|
---|
| 1129 | */
|
---|
| 1130 | DECLR3CALLBACKMEMBER(int, pfnReadNB, (VDSOCKET Sock, void *pvBuffer, size_t cbBuffer, size_t *pcbRead));
|
---|
| 1131 |
|
---|
| 1132 | /**
|
---|
| 1133 | * Send data to a socket - not blocking.
|
---|
| 1134 | *
|
---|
| 1135 | * @return iprt status code.
|
---|
| 1136 | * @param Sock Socket descriptor.
|
---|
| 1137 | * @param pvBuffer Buffer to write data to socket.
|
---|
| 1138 | * @param cbBuffer How much to write.
|
---|
| 1139 | * @param pcbWritten Number of bytes written.
|
---|
| 1140 | */
|
---|
| 1141 | DECLR3CALLBACKMEMBER(int, pfnWriteNB, (VDSOCKET Sock, const void *pvBuffer, size_t cbBuffer, size_t *pcbWritten));
|
---|
| 1142 |
|
---|
| 1143 | /**
|
---|
| 1144 | * Send data from scatter/gather buffer to a socket - not blocking.
|
---|
| 1145 | *
|
---|
| 1146 | * @return iprt status code.
|
---|
| 1147 | * @param Sock Socket descriptor.
|
---|
| 1148 | * @param pSgBuffer Scatter/gather buffer to write data to socket.
|
---|
| 1149 | * @param pcbWritten Number of bytes written.
|
---|
| 1150 | */
|
---|
| 1151 | DECLR3CALLBACKMEMBER(int, pfnSgWriteNB, (VDSOCKET Sock, PRTSGBUF pSgBuffer, size_t *pcbWritten));
|
---|
| 1152 |
|
---|
| 1153 | /**
|
---|
| 1154 | * Flush socket write buffers.
|
---|
| 1155 | *
|
---|
| 1156 | * @return iprt status code.
|
---|
| 1157 | * @param Sock Socket descriptor.
|
---|
| 1158 | */
|
---|
| 1159 | DECLR3CALLBACKMEMBER(int, pfnFlush, (VDSOCKET Sock));
|
---|
| 1160 |
|
---|
| 1161 | /**
|
---|
| 1162 | * Enables or disables delaying sends to coalesce packets.
|
---|
| 1163 | *
|
---|
| 1164 | * @return iprt status code.
|
---|
| 1165 | * @param Sock Socket descriptor.
|
---|
| 1166 | * @param fEnable When set to true enables coalescing.
|
---|
| 1167 | */
|
---|
| 1168 | DECLR3CALLBACKMEMBER(int, pfnSetSendCoalescing, (VDSOCKET Sock, bool fEnable));
|
---|
| 1169 |
|
---|
| 1170 | /**
|
---|
| 1171 | * Gets the address of the local side.
|
---|
| 1172 | *
|
---|
| 1173 | * @return iprt status code.
|
---|
| 1174 | * @param Sock Socket descriptor.
|
---|
| 1175 | * @param pAddr Where to store the local address on success.
|
---|
| 1176 | */
|
---|
| 1177 | DECLR3CALLBACKMEMBER(int, pfnGetLocalAddress, (VDSOCKET Sock, PRTNETADDR pAddr));
|
---|
| 1178 |
|
---|
| 1179 | /**
|
---|
| 1180 | * Gets the address of the other party.
|
---|
| 1181 | *
|
---|
| 1182 | * @return iprt status code.
|
---|
| 1183 | * @param Sock Socket descriptor.
|
---|
| 1184 | * @param pAddr Where to store the peer address on success.
|
---|
| 1185 | */
|
---|
| 1186 | DECLR3CALLBACKMEMBER(int, pfnGetPeerAddress, (VDSOCKET Sock, PRTNETADDR pAddr));
|
---|
| 1187 |
|
---|
| 1188 | /**
|
---|
| 1189 | * Socket I/O multiplexing - extended version which can be woken up.
|
---|
| 1190 | * Checks if the socket is ready for reading or writing.
|
---|
| 1191 | *
|
---|
| 1192 | * @return iprt status code.
|
---|
| 1193 | * @retval VERR_INTERRUPTED if the thread was woken up by a pfnPoke call.
|
---|
| 1194 | * @param Sock Socket descriptor.
|
---|
| 1195 | * @param fEvents Mask of events to wait for.
|
---|
| 1196 | * @param pfEvents Where to store the received events.
|
---|
| 1197 | * @param cMillies Number of milliseconds to wait for the socket.
|
---|
| 1198 | * Use RT_INDEFINITE_WAIT to wait for ever.
|
---|
| 1199 | */
|
---|
| 1200 | DECLR3CALLBACKMEMBER(int, pfnSelectOneEx, (VDSOCKET Sock, uint32_t fEvents,
|
---|
| 1201 | uint32_t *pfEvents, RTMSINTERVAL cMillies));
|
---|
| 1202 |
|
---|
| 1203 | /**
|
---|
| 1204 | * Wakes up the thread waiting in pfnSelectOneEx.
|
---|
| 1205 | *
|
---|
| 1206 | * @return iprt status code.
|
---|
| 1207 | * @param Sock Socket descriptor.
|
---|
| 1208 | */
|
---|
| 1209 | DECLR3CALLBACKMEMBER(int, pfnPoke, (VDSOCKET Sock));
|
---|
| 1210 |
|
---|
| 1211 | } VDINTERFACETCPNET, *PVDINTERFACETCPNET;
|
---|
| 1212 |
|
---|
| 1213 | /**
|
---|
| 1214 | * Get TCP network stack interface from interface list.
|
---|
| 1215 | *
|
---|
| 1216 | * @return Pointer to the first TCP network stack interface in the list.
|
---|
| 1217 | * @param pVDIfs Pointer to the interface list.
|
---|
| 1218 | */
|
---|
| 1219 | DECLINLINE(PVDINTERFACETCPNET) VDIfTcpNetGet(PVDINTERFACE pVDIfs)
|
---|
| 1220 | {
|
---|
| 1221 | PVDINTERFACE pIf = VDInterfaceGet(pVDIfs, VDINTERFACETYPE_TCPNET);
|
---|
| 1222 |
|
---|
| 1223 | /* Check that the interface descriptor is a progress interface. */
|
---|
| 1224 | AssertMsgReturn( !pIf
|
---|
| 1225 | || ( (pIf->enmInterface == VDINTERFACETYPE_TCPNET)
|
---|
| 1226 | && (pIf->cbSize == sizeof(VDINTERFACETCPNET))),
|
---|
| 1227 | ("Not a TCP net interface"), NULL);
|
---|
| 1228 |
|
---|
| 1229 | return (PVDINTERFACETCPNET)pIf;
|
---|
| 1230 | }
|
---|
| 1231 |
|
---|
| 1232 |
|
---|
| 1233 | /**
|
---|
| 1234 | * Interface to synchronize concurrent accesses by several threads.
|
---|
| 1235 | *
|
---|
| 1236 | * @note The scope of this interface is to manage concurrent accesses after
|
---|
| 1237 | * the HDD container has been created, and they must stop before destroying the
|
---|
| 1238 | * container. Opening or closing images is covered by the synchronization, but
|
---|
| 1239 | * that does not mean it is safe to close images while a thread executes
|
---|
| 1240 | * <link to="VDMerge"/> or <link to="VDCopy"/> operating on these images.
|
---|
| 1241 | * Making them safe would require the lock to be held during the entire
|
---|
| 1242 | * operation, which prevents other concurrent acitivities.
|
---|
| 1243 | *
|
---|
| 1244 | * @note Right now this is kept as simple as possible, and does not even
|
---|
| 1245 | * attempt to provide enough information to allow e.g. concurrent write
|
---|
| 1246 | * accesses to different areas of the disk. The reason is that it is very
|
---|
| 1247 | * difficult to predict which area of a disk is affected by a write,
|
---|
| 1248 | * especially when different image formats are mixed. Maybe later a more
|
---|
| 1249 | * sophisticated interface will be provided which has the necessary information
|
---|
| 1250 | * about worst case affected areas.
|
---|
| 1251 | *
|
---|
| 1252 | * Per-disk interface. Optional, needed if the disk is accessed concurrently
|
---|
| 1253 | * by several threads, e.g. when merging diff images while a VM is running.
|
---|
| 1254 | */
|
---|
| 1255 | typedef struct VDINTERFACETHREADSYNC
|
---|
| 1256 | {
|
---|
| 1257 | /**
|
---|
| 1258 | * Common interface header.
|
---|
| 1259 | */
|
---|
| 1260 | VDINTERFACE Core;
|
---|
| 1261 |
|
---|
| 1262 | /**
|
---|
| 1263 | * Start a read operation.
|
---|
| 1264 | */
|
---|
| 1265 | DECLR3CALLBACKMEMBER(int, pfnStartRead, (void *pvUser));
|
---|
| 1266 |
|
---|
| 1267 | /**
|
---|
| 1268 | * Finish a read operation.
|
---|
| 1269 | */
|
---|
| 1270 | DECLR3CALLBACKMEMBER(int, pfnFinishRead, (void *pvUser));
|
---|
| 1271 |
|
---|
| 1272 | /**
|
---|
| 1273 | * Start a write operation.
|
---|
| 1274 | */
|
---|
| 1275 | DECLR3CALLBACKMEMBER(int, pfnStartWrite, (void *pvUser));
|
---|
| 1276 |
|
---|
| 1277 | /**
|
---|
| 1278 | * Finish a write operation.
|
---|
| 1279 | */
|
---|
| 1280 | DECLR3CALLBACKMEMBER(int, pfnFinishWrite, (void *pvUser));
|
---|
| 1281 |
|
---|
| 1282 | } VDINTERFACETHREADSYNC, *PVDINTERFACETHREADSYNC;
|
---|
| 1283 |
|
---|
| 1284 | /**
|
---|
| 1285 | * Get thread synchronization interface from interface list.
|
---|
| 1286 | *
|
---|
| 1287 | * @return Pointer to the first thread synchronization interface in the list.
|
---|
| 1288 | * @param pVDIfs Pointer to the interface list.
|
---|
| 1289 | */
|
---|
| 1290 | DECLINLINE(PVDINTERFACETHREADSYNC) VDIfThreadSyncGet(PVDINTERFACE pVDIfs)
|
---|
| 1291 | {
|
---|
| 1292 | PVDINTERFACE pIf = VDInterfaceGet(pVDIfs, VDINTERFACETYPE_THREADSYNC);
|
---|
| 1293 |
|
---|
| 1294 | /* Check that the interface descriptor is a progress interface. */
|
---|
| 1295 | AssertMsgReturn( !pIf
|
---|
| 1296 | || ( (pIf->enmInterface == VDINTERFACETYPE_THREADSYNC)
|
---|
| 1297 | && (pIf->cbSize == sizeof(VDINTERFACETHREADSYNC))),
|
---|
| 1298 | ("Not a thread synchronization interface"), NULL);
|
---|
| 1299 |
|
---|
| 1300 | return (PVDINTERFACETHREADSYNC)pIf;
|
---|
| 1301 | }
|
---|
| 1302 |
|
---|
[40030] | 1303 | /**
|
---|
| 1304 | * Interface to query usage of disk ranges.
|
---|
| 1305 | *
|
---|
| 1306 | * Per-operation interface. Optional.
|
---|
| 1307 | */
|
---|
| 1308 | typedef struct VDINTERFACEQUERYRANGEUSE
|
---|
| 1309 | {
|
---|
| 1310 | /**
|
---|
| 1311 | * Common interface header.
|
---|
| 1312 | */
|
---|
| 1313 | VDINTERFACE Core;
|
---|
| 1314 |
|
---|
| 1315 | /**
|
---|
| 1316 | * Query use of a disk range.
|
---|
| 1317 | */
|
---|
| 1318 | DECLR3CALLBACKMEMBER(int, pfnQueryRangeUse, (void *pvUser, uint64_t off, uint64_t cb,
|
---|
| 1319 | bool *pfUsed));
|
---|
| 1320 |
|
---|
| 1321 | } VDINTERFACEQUERYRANGEUSE, *PVDINTERFACEQUERYRANGEUSE;
|
---|
| 1322 |
|
---|
| 1323 | /**
|
---|
| 1324 | * Get query range use interface from interface list.
|
---|
| 1325 | *
|
---|
| 1326 | * @return Pointer to the first thread synchronization interface in the list.
|
---|
| 1327 | * @param pVDIfs Pointer to the interface list.
|
---|
| 1328 | */
|
---|
| 1329 | DECLINLINE(PVDINTERFACEQUERYRANGEUSE) VDIfQueryRangeUseGet(PVDINTERFACE pVDIfs)
|
---|
| 1330 | {
|
---|
| 1331 | PVDINTERFACE pIf = VDInterfaceGet(pVDIfs, VDINTERFACETYPE_QUERYRANGEUSE);
|
---|
| 1332 |
|
---|
| 1333 | /* Check that the interface descriptor is a progress interface. */
|
---|
| 1334 | AssertMsgReturn( !pIf
|
---|
| 1335 | || ( (pIf->enmInterface == VDINTERFACETYPE_QUERYRANGEUSE)
|
---|
| 1336 | && (pIf->cbSize == sizeof(VDINTERFACEQUERYRANGEUSE))),
|
---|
| 1337 | ("Not a query range use interface"), NULL);
|
---|
| 1338 |
|
---|
| 1339 | return (PVDINTERFACEQUERYRANGEUSE)pIf;
|
---|
| 1340 | }
|
---|
| 1341 |
|
---|
| 1342 | DECLINLINE(int) vdIfQueryRangeUse(PVDINTERFACEQUERYRANGEUSE pIfQueryRangeUse, uint64_t off, uint64_t cb,
|
---|
| 1343 | bool *pfUsed)
|
---|
| 1344 | {
|
---|
| 1345 | return pIfQueryRangeUse->pfnQueryRangeUse(pIfQueryRangeUse->Core.pvUser, off, cb, pfUsed);
|
---|
| 1346 | }
|
---|
| 1347 |
|
---|
[51752] | 1348 |
|
---|
| 1349 | /**
|
---|
| 1350 | * Interface used to retrieve keys for cryptographic operations.
|
---|
| 1351 | *
|
---|
| 1352 | * Per-module interface. Optional but cryptographic modules might fail and
|
---|
| 1353 | * return an error if this is not present.
|
---|
| 1354 | */
|
---|
| 1355 | typedef struct VDINTERFACECRYPTO
|
---|
| 1356 | {
|
---|
| 1357 | /**
|
---|
| 1358 | * Common interface header.
|
---|
| 1359 | */
|
---|
| 1360 | VDINTERFACE Core;
|
---|
| 1361 |
|
---|
| 1362 | /**
|
---|
| 1363 | * Retains a key identified by the ID. The caller will only hold a reference
|
---|
| 1364 | * to the key and must not modify the key buffer in any way.
|
---|
| 1365 | *
|
---|
| 1366 | * @returns VBox status code.
|
---|
| 1367 | * @param pvUser The opaque user data associated with this interface.
|
---|
| 1368 | * @param pszId The alias/id for the key to retrieve.
|
---|
| 1369 | * @param ppbKey Where to store the pointer to the key buffer on success.
|
---|
| 1370 | * @param pcbKey Where to store the size of the key in bytes on success.
|
---|
| 1371 | */
|
---|
| 1372 | DECLR3CALLBACKMEMBER(int, pfnKeyRetain, (void *pvUser, const char *pszId, const uint8_t **ppbKey, size_t *pcbKey));
|
---|
| 1373 |
|
---|
| 1374 | /**
|
---|
| 1375 | * Releases one reference of the key identified by the given identifier.
|
---|
| 1376 | * The caller must not access the key buffer after calling this operation.
|
---|
| 1377 | *
|
---|
| 1378 | * @returns VBox status code.
|
---|
| 1379 | * @param pvUser The opaque user data associated with this interface.
|
---|
| 1380 | * @param pszId The alias/id for the key to release.
|
---|
| 1381 | *
|
---|
| 1382 | * @note: It is advised to release the key whenever it is not used anymore so the entity
|
---|
| 1383 | * storing the key can do anything to make retrieving the key from memory more
|
---|
| 1384 | * difficult like scrambling the memory buffer for instance.
|
---|
| 1385 | */
|
---|
| 1386 | DECLR3CALLBACKMEMBER(int, pfnKeyRelease, (void *pvUser, const char *pszId));
|
---|
| 1387 |
|
---|
| 1388 | } VDINTERFACECRYPTO, *PVDINTERFACECRYPTO;
|
---|
| 1389 |
|
---|
| 1390 |
|
---|
| 1391 | /**
|
---|
| 1392 | * Get error interface from interface list.
|
---|
| 1393 | *
|
---|
| 1394 | * @return Pointer to the first error interface in the list.
|
---|
| 1395 | * @param pVDIfs Pointer to the interface list.
|
---|
| 1396 | */
|
---|
| 1397 | DECLINLINE(PVDINTERFACECRYPTO) VDIfCryptoGet(PVDINTERFACE pVDIfs)
|
---|
| 1398 | {
|
---|
| 1399 | PVDINTERFACE pIf = VDInterfaceGet(pVDIfs, VDINTERFACETYPE_CRYPTO);
|
---|
| 1400 |
|
---|
| 1401 | /* Check that the interface descriptor is a crypto interface. */
|
---|
| 1402 | AssertMsgReturn( !pIf
|
---|
| 1403 | || ( (pIf->enmInterface == VDINTERFACETYPE_CRYPTO)
|
---|
| 1404 | && (pIf->cbSize == sizeof(VDINTERFACECRYPTO))),
|
---|
| 1405 | ("Not an crypto interface\n"), NULL);
|
---|
| 1406 |
|
---|
| 1407 | return (PVDINTERFACECRYPTO)pIf;
|
---|
| 1408 | }
|
---|
| 1409 |
|
---|
| 1410 | /**
|
---|
| 1411 | * @copydoc VDINTERFACECRYPTOKEYS::pfnKeyRetain
|
---|
| 1412 | */
|
---|
| 1413 | DECLINLINE(int) vdIfCryptoKeyRetain(PVDINTERFACECRYPTO pIfCrypto, const char *pszId, const uint8_t **ppbKey, size_t *pcbKey)
|
---|
| 1414 | {
|
---|
| 1415 | return pIfCrypto->pfnKeyRetain(pIfCrypto->Core.pvUser, pszId, ppbKey, pcbKey);
|
---|
| 1416 | }
|
---|
| 1417 |
|
---|
| 1418 | /**
|
---|
| 1419 | * @copydoc VDINTERFACECRYPTOKEYS::pfnKeyRelease
|
---|
| 1420 | */
|
---|
| 1421 | DECLINLINE(int) vdIfCryptoKeyRelease(PVDINTERFACECRYPTO pIfCrypto, const char *pszId)
|
---|
| 1422 | {
|
---|
| 1423 | return pIfCrypto->pfnKeyRelease(pIfCrypto->Core.pvUser, pszId);
|
---|
| 1424 | }
|
---|
| 1425 |
|
---|
[38469] | 1426 | RT_C_DECLS_END
|
---|
| 1427 |
|
---|
| 1428 | /** @} */
|
---|
| 1429 |
|
---|
| 1430 | #endif
|
---|