e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * VD Container API - interfaces.
d1aab951b0bd1de1a8a51daca46fce06daaed8d7vboxsync * Copyright (C) 2011-2015 Oracle Corporation
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * This file is part of VirtualBox Open Source Edition (OSE), as
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * available from http://www.virtualbox.org. This file is free software;
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * you can redistribute it and/or modify it under the terms of the GNU
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * General Public License (GPL) as published by the Free Software
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Foundation, in version 2 as it comes in the "COPYING" file of the
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * The contents of this file may alternatively be used under the terms
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * of the Common Development and Distribution License Version 1.0
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * VirtualBox OSE distribution, in which case the provisions of the
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * CDDL are applicable instead of those of the GPL.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * You may elect to license modified versions of this file under the
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * terms and conditions of either the GPL or the CDDL or both.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync/** Interface header magic. */
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Supported interface types.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync /** First valid interface. */
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync /** Interface to pass error message to upper layers. Per-disk. */
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync /** Interface for I/O operations. Per-image. */
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync /** Interface for progress notification. Per-operation. */
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync /** Interface for configuration information. Per-image. */
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync /** Interface for TCP network stack. Per-image. */
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync /** Interface for getting parent image state. Per-operation. */
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync /** Interface for synchronizing accesses from several threads. Per-disk. */
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync /** Interface for I/O between the generic VBoxHDD code and the backend. Per-image (internal).
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * This interface is completely internal and must not be used elsewhere. */
e170d0511a1456f1677c93e03a78d7162ae82472vboxsync /** Interface to query the use of block ranges on the disk. Per-operation. */
5af981fb39925101cec5e22afb746e2125b55ce4vboxsync /** Interface for the metadata traverse callback. Per-operation. */
7cb5e5e023bd9dc218e5b159d4a421245101edb2vboxsync /** Interface for crypto operations. Per-filter. */
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync /** invalid interface. */
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Common structure for all interfaces and at the beginning of all types.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync /** Human readable interface name. */
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync /** Pointer to the next common interface structure. */
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync /** Interface type. */
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync /** Size of the interface. */
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync /** Opaque user data which is passed on every call. */
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync/** Pointer to a VDINTERFACE. */
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync/** Pointer to a const VDINTERFACE. */
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Helper functions to handle interface lists.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @note These interface lists are used consistently to pass per-disk,
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * per-image and/or per-operation callbacks. Those three purposes are strictly
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * separate. See the individual interface declarations for what context they
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * apply to. The caller is responsible for ensuring that the lifetime of the
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * interface descriptors is appropriate for the category of interface.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Get a specific interface from a list of interfaces specified by the type.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @return Pointer to the matching interface or NULL if none was found.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pVDIfs Pointer to the VD interface list.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param enmInterface Interface to search for.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsyncDECLINLINE(PVDINTERFACE) VDInterfaceGet(PVDINTERFACE pVDIfs, VDINTERFACETYPE enmInterface)
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync AssertMsgReturn( enmInterface >= VDINTERFACETYPE_FIRST
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync AssertMsgBreak(pVDIfs->u32Magic == VDINTERFACE_MAGIC,
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync /* No matching interface was found. */
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Add an interface to a list of interfaces.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @return VBox status code.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pInterface Pointer to an unitialized common interface structure.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pszName Name of the interface.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param enmInterface Type of the interface.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pvUser Opaque user data passed on every function call.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param ppVDIfs Pointer to the VD interface list.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsyncDECLINLINE(int) VDInterfaceAdd(PVDINTERFACE pInterface, const char *pszName,
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync /* Argument checks. */
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync AssertMsgReturn( enmInterface >= VDINTERFACETYPE_FIRST
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync ("enmInterface=%u", enmInterface), VERR_INVALID_PARAMETER);
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync /* Fill out interface descriptor. */
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync /* Remember the new start of the list. */
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Removes an interface from a list of interfaces.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @return VBox status code
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pInterface Pointer to an initialized common interface structure to remove.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param ppVDIfs Pointer to the VD interface list to remove from.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsyncDECLINLINE(int) VDInterfaceRemove(PVDINTERFACE pInterface, PVDINTERFACE *ppVDIfs)
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync /* Argument checks. */
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync /* First interface */
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Interface to deliver error messages (and also informational messages)
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * to upper layers.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Per-disk interface. Optional, but think twice if you want to miss the
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * opportunity of reporting better human-readable error messages.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Common interface header.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Error message callback. Must be able to accept special IPRT format
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pvUser The opaque data passed on container creation.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param rc The VBox error code.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param RT_SRC_POS_DECL Use RT_SRC_POS.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pszFormat Error message format string.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param va Error message arguments.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync DECLR3CALLBACKMEMBER(void, pfnError, (void *pvUser, int rc, RT_SRC_POS_DECL, const char *pszFormat, va_list va));
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Informational message callback. May be NULL. Used e.g. in
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * VDDumpImages(). Must be able to accept special IPRT format strings.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @return VBox status code.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pvUser The opaque data passed on container creation.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pszFormat Message format string.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param va Message arguments.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync DECLR3CALLBACKMEMBER(int, pfnMessage, (void *pvUser, const char *pszFormat, va_list va));
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Get error interface from interface list.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @return Pointer to the first error interface in the list.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pVDIfs Pointer to the interface list.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsyncDECLINLINE(PVDINTERFACEERROR) VDIfErrorGet(PVDINTERFACE pVDIfs)
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync PVDINTERFACE pIf = VDInterfaceGet(pVDIfs, VDINTERFACETYPE_ERROR);
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync /* Check that the interface descriptor is a progress interface. */
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Signal an error to the frontend.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @returns VBox status code.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pIfError The error interface.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param rc The status code.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param RT_SRC_POS_DECL The position in the source code.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pszFormat The format string to pass.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param ... Arguments to the format string.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsyncDECLINLINE(int) vdIfError(PVDINTERFACEERROR pIfError, int rc, RT_SRC_POS_DECL,
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync const char *pszFormat, ...)
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync pIfError->pfnError(pIfError->Core.pvUser, rc, RT_SRC_POS_ARGS, pszFormat, va);
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Signal an informational message to the frontend.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @returns VBox status code.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pIfError The error interface.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pszFormat The format string to pass.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param ... Arguments to the format string.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsyncDECLINLINE(int) vdIfErrorMessage(PVDINTERFACEERROR pIfError, const char *pszFormat, ...)
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync rc = pIfError->pfnMessage(pIfError->Core.pvUser, pszFormat, va);
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Completion callback which is called by the interface owner
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * to inform the backend that a task finished.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @return VBox status code.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pvUser Opaque user data which is passed on request submission.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param rcReq Status code of the completed request.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsynctypedef DECLCALLBACK(int) FNVDCOMPLETED(void *pvUser, int rcReq);
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync/** Pointer to FNVDCOMPLETED() */
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Support interface for I/O
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Per-image. Optional as input.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Common interface header.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Open callback
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @return VBox status code.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pvUser The opaque data passed on container creation.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pszLocation Name of the location to open.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param fOpen Flags for opening the backend.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * See RTFILE_O_* #defines, inventing another set
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * of open flags is not worth the mapping effort.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pfnCompleted The callback which is called whenever a task
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * completed. The backend has to pass the user data
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * of the request initiator (ie the one who calls
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * VDAsyncRead or VDAsyncWrite) in pvCompletion
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * if this is NULL.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param ppStorage Where to store the opaque storage handle.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync DECLR3CALLBACKMEMBER(int, pfnOpen, (void *pvUser, const char *pszLocation,
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Close callback.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @return VBox status code.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pvUser The opaque data passed on container creation.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pStorage The opaque storage handle to close.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync DECLR3CALLBACKMEMBER(int, pfnClose, (void *pvUser, void *pStorage));
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Delete callback.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @return VBox status code.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pvUser The opaque data passed on container creation.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pcszFilename Name of the file to delete.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync DECLR3CALLBACKMEMBER(int, pfnDelete, (void *pvUser, const char *pcszFilename));
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Move callback.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @return VBox status code.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pvUser The opaque data passed on container creation.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pcszSrc The path to the source file.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pcszDst The path to the destination file.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * This file will be created.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param fMove A combination of the RTFILEMOVE_* flags.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync DECLR3CALLBACKMEMBER(int, pfnMove, (void *pvUser, const char *pcszSrc, const char *pcszDst, unsigned fMove));
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Returns the free space on a disk.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @return VBox status code.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pvUser The opaque data passed on container creation.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pcszFilename Name of a file to identify the disk.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pcbFreeSpace Where to store the free space of the disk.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync DECLR3CALLBACKMEMBER(int, pfnGetFreeSpace, (void *pvUser, const char *pcszFilename, int64_t *pcbFreeSpace));
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Returns the last modification timestamp of a file.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @return VBox status code.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pvUser The opaque data passed on container creation.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pcszFilename Name of a file to identify the disk.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pModificationTime Where to store the timestamp of the file.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync DECLR3CALLBACKMEMBER(int, pfnGetModificationTime, (void *pvUser, const char *pcszFilename, PRTTIMESPEC pModificationTime));
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Returns the size of the opened storage backend.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @return VBox status code.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pvUser The opaque data passed on container creation.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pStorage The opaque storage handle to close.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pcbSize Where to store the size of the storage backend.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync DECLR3CALLBACKMEMBER(int, pfnGetSize, (void *pvUser, void *pStorage, uint64_t *pcbSize));
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Sets the size of the opened storage backend if possible.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @return VBox status code.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @retval VERR_NOT_SUPPORTED if the backend does not support this operation.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pvUser The opaque data passed on container creation.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pStorage The opaque storage handle to close.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param cbSize The new size of the image.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync DECLR3CALLBACKMEMBER(int, pfnSetSize, (void *pvUser, void *pStorage, uint64_t cbSize));
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Synchronous write callback.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @return VBox status code.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pvUser The opaque data passed on container creation.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pStorage The storage handle to use.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param uOffset The offset to start from.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pvBuffer Pointer to the bits need to be written.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param cbBuffer How many bytes to write.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pcbWritten Where to store how many bytes were actually written.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync DECLR3CALLBACKMEMBER(int, pfnWriteSync, (void *pvUser, void *pStorage, uint64_t uOffset,
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync const void *pvBuffer, size_t cbBuffer, size_t *pcbWritten));
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Synchronous read callback.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @return VBox status code.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pvUser The opaque data passed on container creation.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pStorage The storage handle to use.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param uOffset The offset to start from.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pvBuffer Where to store the read bits.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param cbBuffer How many bytes to read.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pcbRead Where to store how many bytes were actually read.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync DECLR3CALLBACKMEMBER(int, pfnReadSync, (void *pvUser, void *pStorage, uint64_t uOffset,
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync void *pvBuffer, size_t cbBuffer, size_t *pcbRead));
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Flush data to the storage backend.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @return VBox status code.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pvUser The opaque data passed on container creation.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pStorage The storage handle to flush.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync DECLR3CALLBACKMEMBER(int, pfnFlushSync, (void *pvUser, void *pStorage));
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Initiate an asynchronous read request.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @return VBox status code.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pvUser The opaque user data passed on container creation.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pStorage The storage handle.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param uOffset The offset to start reading from.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param paSegments Scatter gather list to store the data in.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param cSegments Number of segments in the list.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param cbRead How many bytes to read.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pvCompletion The opaque user data which is returned upon completion.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param ppTask Where to store the opaque task handle.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync DECLR3CALLBACKMEMBER(int, pfnReadAsync, (void *pvUser, void *pStorage, uint64_t uOffset,
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Initiate an asynchronous write request.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @return VBox status code.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pvUser The opaque user data passed on conatiner creation.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pStorage The storage handle.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param uOffset The offset to start writing to.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param paSegments Scatter gather list of the data to write
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param cSegments Number of segments in the list.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param cbWrite How many bytes to write.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pvCompletion The opaque user data which is returned upon completion.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param ppTask Where to store the opaque task handle.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync DECLR3CALLBACKMEMBER(int, pfnWriteAsync, (void *pvUser, void *pStorage, uint64_t uOffset,
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Initiates an async flush request.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @return VBox status code.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pvUser The opaque data passed on container creation.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pStorage The storage handle to flush.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pvCompletion The opaque user data which is returned upon completion.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param ppTask Where to store the opaque task handle.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync DECLR3CALLBACKMEMBER(int, pfnFlushAsync, (void *pvUser, void *pStorage,
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Get I/O interface from interface list.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @return Pointer to the first I/O interface in the list.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pVDIfs Pointer to the interface list.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsyncDECLINLINE(PVDINTERFACEIO) VDIfIoGet(PVDINTERFACE pVDIfs)
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync PVDINTERFACE pIf = VDInterfaceGet(pVDIfs, VDINTERFACETYPE_IO);
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync /* Check that the interface descriptor is a progress interface. */
e4f367251aede667a6de69baa54ef9eb5f150871vboxsyncDECLINLINE(int) vdIfIoFileOpen(PVDINTERFACEIO pIfIo, const char *pszFilename,
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync return pIfIo->pfnOpen(pIfIo->Core.pvUser, pszFilename, fOpen, pfnCompleted, ppStorage);
e4f367251aede667a6de69baa54ef9eb5f150871vboxsyncDECLINLINE(int) vdIfIoFileClose(PVDINTERFACEIO pIfIo, void *pStorage)
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync return pIfIo->pfnClose(pIfIo->Core.pvUser, pStorage);
e4f367251aede667a6de69baa54ef9eb5f150871vboxsyncDECLINLINE(int) vdIfIoFileDelete(PVDINTERFACEIO pIfIo, const char *pszFilename)
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync return pIfIo->pfnDelete(pIfIo->Core.pvUser, pszFilename);
e4f367251aede667a6de69baa54ef9eb5f150871vboxsyncDECLINLINE(int) vdIfIoFileMove(PVDINTERFACEIO pIfIo, const char *pszSrc,
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync return pIfIo->pfnMove(pIfIo->Core.pvUser, pszSrc, pszDst, fMove);
e4f367251aede667a6de69baa54ef9eb5f150871vboxsyncDECLINLINE(int) vdIfIoFileGetFreeSpace(PVDINTERFACEIO pIfIo, const char *pszFilename,
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync return pIfIo->pfnGetFreeSpace(pIfIo->Core.pvUser, pszFilename, pcbFree);
e4f367251aede667a6de69baa54ef9eb5f150871vboxsyncDECLINLINE(int) vdIfIoFileGetModificationTime(PVDINTERFACEIO pIfIo, const char *pcszFilename,
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync return pIfIo->pfnGetModificationTime(pIfIo->Core.pvUser, pcszFilename,
e4f367251aede667a6de69baa54ef9eb5f150871vboxsyncDECLINLINE(int) vdIfIoFileGetSize(PVDINTERFACEIO pIfIo, void *pStorage,
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync return pIfIo->pfnGetSize(pIfIo->Core.pvUser, pStorage, pcbSize);
e4f367251aede667a6de69baa54ef9eb5f150871vboxsyncDECLINLINE(int) vdIfIoFileSetSize(PVDINTERFACEIO pIfIo, void *pStorage,
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync return pIfIo->pfnSetSize(pIfIo->Core.pvUser, pStorage, cbSize);
e4f367251aede667a6de69baa54ef9eb5f150871vboxsyncDECLINLINE(int) vdIfIoFileWriteSync(PVDINTERFACEIO pIfIo, void *pStorage,
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync uint64_t uOffset, const void *pvBuffer, size_t cbBuffer,
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync return pIfIo->pfnWriteSync(pIfIo->Core.pvUser, pStorage, uOffset,
e4f367251aede667a6de69baa54ef9eb5f150871vboxsyncDECLINLINE(int) vdIfIoFileReadSync(PVDINTERFACEIO pIfIo, void *pStorage,
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync return pIfIo->pfnReadSync(pIfIo->Core.pvUser, pStorage, uOffset,
e4f367251aede667a6de69baa54ef9eb5f150871vboxsyncDECLINLINE(int) vdIfIoFileFlushSync(PVDINTERFACEIO pIfIo, void *pStorage)
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync return pIfIo->pfnFlushSync(pIfIo->Core.pvUser, pStorage);
2698330926679dd315ebf905a0996726d3c31d28vboxsync * Create a VFS stream handle around a VD I/O interface.
2698330926679dd315ebf905a0996726d3c31d28vboxsync * The I/O interface will not be closed or free by the stream, the caller will
2698330926679dd315ebf905a0996726d3c31d28vboxsync * do so after it is done with the stream and has released the instances of the
2698330926679dd315ebf905a0996726d3c31d28vboxsync * I/O stream object returned by this API.
2698330926679dd315ebf905a0996726d3c31d28vboxsync * @return VBox status code.
2698330926679dd315ebf905a0996726d3c31d28vboxsync * @param pVDIfsIo Pointer to the VD I/O interface.
10d930a35bb172f2a8982a4e30107f8bfcd8d132vboxsync * @param pvStorage The storage argument to pass to the interface
2698330926679dd315ebf905a0996726d3c31d28vboxsync * @param fFlags RTFILE_O_XXX, access mask requied.
2698330926679dd315ebf905a0996726d3c31d28vboxsync * @param phVfsIos Where to return the VFS I/O stream handle on
10d930a35bb172f2a8982a4e30107f8bfcd8d132vboxsyncVBOXDDU_DECL(int) VDIfCreateVfsStream(PVDINTERFACEIO pVDIfsIo, void *pvStorage, uint32_t fFlags, PRTVFSIOSTREAM phVfsIos);
7e22f7c2837d391a86b63ea8fa2eafc84276852bvboxsync * Create a VFS file handle around a VD I/O interface.
7e22f7c2837d391a86b63ea8fa2eafc84276852bvboxsync * The I/O interface will not be closed or free by the VFS file, the caller will
7e22f7c2837d391a86b63ea8fa2eafc84276852bvboxsync * do so after it is done with the VFS file and has released the instances of
7e22f7c2837d391a86b63ea8fa2eafc84276852bvboxsync * the VFS object returned by this API.
7e22f7c2837d391a86b63ea8fa2eafc84276852bvboxsync * @return VBox status code.
1871a062626cda3c5b5fbfca979f4e1c167efd47vboxsync * @param pVDIfs Pointer to the VD I/O interface. If NULL, then @a
1871a062626cda3c5b5fbfca979f4e1c167efd47vboxsync * pVDIfsInt must be specified.
1871a062626cda3c5b5fbfca979f4e1c167efd47vboxsync * @param pVDIfsInt Pointer to the internal VD I/O interface. If NULL,
1871a062626cda3c5b5fbfca979f4e1c167efd47vboxsync * then @ pVDIfs must be specified.
7e22f7c2837d391a86b63ea8fa2eafc84276852bvboxsync * @param pvStorage The storage argument to pass to the interface
7e22f7c2837d391a86b63ea8fa2eafc84276852bvboxsync * @param fFlags RTFILE_O_XXX, access mask requied.
7e22f7c2837d391a86b63ea8fa2eafc84276852bvboxsync * @param phVfsFile Where to return the VFS file handle on success.
1871a062626cda3c5b5fbfca979f4e1c167efd47vboxsyncVBOXDDU_DECL(int) VDIfCreateVfsFile(PVDINTERFACEIO pVDIfs, struct VDINTERFACEIOINT *pVDIfsInt, void *pvStorage, uint32_t fFlags, PRTVFSFILE phVfsFile);
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Callback which provides progress information about a currently running
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * lengthy operation.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @return VBox status code.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pvUser The opaque user data associated with this interface.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param uPercent Completion percentage.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsynctypedef DECLCALLBACK(int) FNVDPROGRESS(void *pvUser, unsigned uPercentage);
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync/** Pointer to FNVDPROGRESS() */
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Progress notification interface
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Per-operation. Optional.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Common interface header.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Progress notification callbacks.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Get progress interface from interface list.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @return Pointer to the first progress interface in the list.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pVDIfs Pointer to the interface list.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsyncDECLINLINE(PVDINTERFACEPROGRESS) VDIfProgressGet(PVDINTERFACE pVDIfs)
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync PVDINTERFACE pIf = VDInterfaceGet(pVDIfs, VDINTERFACETYPE_PROGRESS);
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync /* Check that the interface descriptor is a progress interface. */
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync || ( (pIf->enmInterface == VDINTERFACETYPE_PROGRESS)
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Configuration information interface
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Per-image. Optional for most backends, but mandatory for images which do
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * not operate on files (including standard block or character devices).
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Common interface header.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Validates that the keys are within a set of valid names.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @return true if all key names are found in pszzAllowed.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @return false if not.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pvUser The opaque user data associated with this interface.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pszzValid List of valid key names separated by '\\0' and ending with
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * a double '\\0'.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync DECLR3CALLBACKMEMBER(bool, pfnAreKeysValid, (void *pvUser, const char *pszzValid));
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Retrieves the length of the string value associated with a key (including
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * the terminator, for compatibility with CFGMR3QuerySize).
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @return VBox status code.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * VERR_CFGM_VALUE_NOT_FOUND means that the key is not known.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pvUser The opaque user data associated with this interface.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pszName Name of the key to query.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pcbValue Where to store the value length. Non-NULL.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync DECLR3CALLBACKMEMBER(int, pfnQuerySize, (void *pvUser, const char *pszName, size_t *pcbValue));
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Query the string value associated with a key.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @return VBox status code.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * VERR_CFGM_VALUE_NOT_FOUND means that the key is not known.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * VERR_CFGM_NOT_ENOUGH_SPACE means that the buffer is not big enough.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pvUser The opaque user data associated with this interface.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pszName Name of the key to query.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pszValue Pointer to buffer where to store value.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param cchValue Length of value buffer.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync DECLR3CALLBACKMEMBER(int, pfnQuery, (void *pvUser, const char *pszName, char *pszValue, size_t cchValue));
e7bd3b41269a08b3f1c33641fb9fe0b809598c9evboxsync * Query the bytes value associated with a key.
e7bd3b41269a08b3f1c33641fb9fe0b809598c9evboxsync * @return VBox status code.
e7bd3b41269a08b3f1c33641fb9fe0b809598c9evboxsync * VERR_CFGM_VALUE_NOT_FOUND means that the key is not known.
e7bd3b41269a08b3f1c33641fb9fe0b809598c9evboxsync * VERR_CFGM_NOT_ENOUGH_SPACE means that the buffer is not big enough.
e7bd3b41269a08b3f1c33641fb9fe0b809598c9evboxsync * @param pvUser The opaque user data associated with this interface.
e7bd3b41269a08b3f1c33641fb9fe0b809598c9evboxsync * @param pszName Name of the key to query.
e7bd3b41269a08b3f1c33641fb9fe0b809598c9evboxsync * @param ppvData Pointer to buffer where to store the data.
e7bd3b41269a08b3f1c33641fb9fe0b809598c9evboxsync * @param cbData Length of data buffer.
e7bd3b41269a08b3f1c33641fb9fe0b809598c9evboxsync DECLR3CALLBACKMEMBER(int, pfnQueryBytes, (void *pvUser, const char *pszName, void *ppvData, size_t cbData));
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Get configuration information interface from interface list.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @return Pointer to the first configuration information interface in the list.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pVDIfs Pointer to the interface list.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsyncDECLINLINE(PVDINTERFACECONFIG) VDIfConfigGet(PVDINTERFACE pVDIfs)
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync PVDINTERFACE pIf = VDInterfaceGet(pVDIfs, VDINTERFACETYPE_CONFIG);
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync /* Check that the interface descriptor is a progress interface. */
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Query configuration, validates that the keys are within a set of valid names.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @return true if all key names are found in pszzAllowed.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @return false if not.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pCfgIf Pointer to configuration callback table.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pszzValid List of valid names separated by '\\0' and ending with
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * a double '\\0'.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsyncDECLINLINE(bool) VDCFGAreKeysValid(PVDINTERFACECONFIG pCfgIf, const char *pszzValid)
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync return pCfgIf->pfnAreKeysValid(pCfgIf->Core.pvUser, pszzValid);
d1aab951b0bd1de1a8a51daca46fce06daaed8d7vboxsync * Checks whether a given key is existing.
d1aab951b0bd1de1a8a51daca46fce06daaed8d7vboxsync * @return true if the key exists.
d1aab951b0bd1de1a8a51daca46fce06daaed8d7vboxsync * @return false if the key does not exist.
d1aab951b0bd1de1a8a51daca46fce06daaed8d7vboxsync * @param pCfgIf Pointer to configuration callback table.
d1aab951b0bd1de1a8a51daca46fce06daaed8d7vboxsync * @param pszName Name of the key.
d1aab951b0bd1de1a8a51daca46fce06daaed8d7vboxsyncDECLINLINE(bool) VDCFGIsKeyExisting(PVDINTERFACECONFIG pCfgIf, const char *pszName)
d1aab951b0bd1de1a8a51daca46fce06daaed8d7vboxsync int rc = pCfgIf->pfnQuerySize(pCfgIf->Core.pvUser, pszName, &cb);
d1aab951b0bd1de1a8a51daca46fce06daaed8d7vboxsync return rc == VERR_CFGM_VALUE_NOT_FOUND ? false : true;
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Query configuration, unsigned 64-bit integer value with default.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @return VBox status code.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pCfgIf Pointer to configuration callback table.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pszName Name of an integer value
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pu64 Where to store the value. Set to default on failure.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param u64Def The default value.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsyncDECLINLINE(int) VDCFGQueryU64Def(PVDINTERFACECONFIG pCfgIf,
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync int rc = pCfgIf->pfnQuery(pCfgIf->Core.pvUser, pszName, aszBuf, sizeof(aszBuf));
7cb5e5e023bd9dc218e5b159d4a421245101edb2vboxsync * Query configuration, unsigned 64-bit integer value.
7cb5e5e023bd9dc218e5b159d4a421245101edb2vboxsync * @return VBox status code.
7cb5e5e023bd9dc218e5b159d4a421245101edb2vboxsync * @param pCfgIf Pointer to configuration callback table.
7cb5e5e023bd9dc218e5b159d4a421245101edb2vboxsync * @param pszName Name of an integer value
7cb5e5e023bd9dc218e5b159d4a421245101edb2vboxsync * @param pu64 Where to store the value.
7cb5e5e023bd9dc218e5b159d4a421245101edb2vboxsyncDECLINLINE(int) VDCFGQueryU64(PVDINTERFACECONFIG pCfgIf, const char *pszName,
7cb5e5e023bd9dc218e5b159d4a421245101edb2vboxsync int rc = pCfgIf->pfnQuery(pCfgIf->Core.pvUser, pszName, aszBuf, sizeof(aszBuf));
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Query configuration, unsigned 32-bit integer value with default.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @return VBox status code.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pCfgIf Pointer to configuration callback table.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pszName Name of an integer value
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pu32 Where to store the value. Set to default on failure.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param u32Def The default value.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsyncDECLINLINE(int) VDCFGQueryU32Def(PVDINTERFACECONFIG pCfgIf,
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync int rc = VDCFGQueryU64Def(pCfgIf, pszName, &u64, u32Def);
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Query configuration, bool value with default.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @return VBox status code.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pCfgIf Pointer to configuration callback table.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pszName Name of an integer value
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pf Where to store the value. Set to default on failure.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param fDef The default value.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsyncDECLINLINE(int) VDCFGQueryBoolDef(PVDINTERFACECONFIG pCfgIf,
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync int rc = VDCFGQueryU64Def(pCfgIf, pszName, &u64, fDef);
7cb5e5e023bd9dc218e5b159d4a421245101edb2vboxsync * Query configuration, bool value.
7cb5e5e023bd9dc218e5b159d4a421245101edb2vboxsync * @return VBox status code.
7cb5e5e023bd9dc218e5b159d4a421245101edb2vboxsync * @param pCfgIf Pointer to configuration callback table.
7cb5e5e023bd9dc218e5b159d4a421245101edb2vboxsync * @param pszName Name of an integer value
7cb5e5e023bd9dc218e5b159d4a421245101edb2vboxsync * @param pf Where to store the value.
7cb5e5e023bd9dc218e5b159d4a421245101edb2vboxsyncDECLINLINE(int) VDCFGQueryBool(PVDINTERFACECONFIG pCfgIf, const char *pszName,
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Query configuration, dynamically allocated (RTMemAlloc) zero terminated
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * character value.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @return VBox status code.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pCfgIf Pointer to configuration callback table.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pszName Name of an zero terminated character value
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param ppszString Where to store the string pointer. Not set on failure.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Free this using RTMemFree().
e4f367251aede667a6de69baa54ef9eb5f150871vboxsyncDECLINLINE(int) VDCFGQueryStringAlloc(PVDINTERFACECONFIG pCfgIf,
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync int rc = pCfgIf->pfnQuerySize(pCfgIf->Core.pvUser, pszName, &cb);
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync rc = pCfgIf->pfnQuery(pCfgIf->Core.pvUser, pszName, pszString, cb);
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Query configuration, dynamically allocated (RTMemAlloc) zero terminated
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * character value with default.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @return VBox status code.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pCfgIf Pointer to configuration callback table.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pszName Name of an zero terminated character value
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param ppszString Where to store the string pointer. Not set on failure.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Free this using RTMemFree().
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pszDef The default value.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsyncDECLINLINE(int) VDCFGQueryStringAllocDef(PVDINTERFACECONFIG pCfgIf,
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync const char *pszName,
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync const char *pszDef)
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync int rc = pCfgIf->pfnQuerySize(pCfgIf->Core.pvUser, pszName, &cb);
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync if (rc == VERR_CFGM_VALUE_NOT_FOUND || rc == VERR_CFGM_NO_PARENT)
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync rc = pCfgIf->pfnQuery(pCfgIf->Core.pvUser, pszName, pszString, cb);
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync if (rc == VERR_CFGM_VALUE_NOT_FOUND || rc == VERR_CFGM_NO_PARENT)
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Query configuration, dynamically allocated (RTMemAlloc) byte string value.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @return VBox status code.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pCfgIf Pointer to configuration callback table.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pszName Name of an zero terminated character value
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param ppvData Where to store the byte string pointer. Not set on failure.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Free this using RTMemFree().
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pcbData Where to store the byte string length.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsyncDECLINLINE(int) VDCFGQueryBytesAlloc(PVDINTERFACECONFIG pCfgIf,
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync const char *pszName, void **ppvData, size_t *pcbData)
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync int rc = pCfgIf->pfnQuerySize(pCfgIf->Core.pvUser, pszName, &cb);
e7bd3b41269a08b3f1c33641fb9fe0b809598c9evboxsync rc = pCfgIf->pfnQueryBytes(pCfgIf->Core.pvUser, pszName, pbData, cb);
e7bd3b41269a08b3f1c33641fb9fe0b809598c9evboxsync rc = pCfgIf->pfnQuery(pCfgIf->Core.pvUser, pszName, pbData, cb);
4e8f351dab9ac3fd2e77e9b2e5b47dd314ae308evboxsync /* Exclude terminator if the byte data was obtained using the string query callback. */
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync/** Forward declaration of a VD socket. */
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync/** Pointer to a VD socket. */
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync/** Nil socket handle. */
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync/** Connect flag to indicate that the backend wants to use the extended
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * socket I/O multiplexing call. This might not be supported on all configurations
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * (internal networking and iSCSI)
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * and the backend needs to take appropriate action.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync#define VD_INTERFACETCPNET_CONNECT_EXTENDED_SELECT RT_BIT_32(0)
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync/** @name Select events
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync/** Readable without blocking. */
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync/** Writable without blocking. */
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync/** Error condition, hangup, exception or similar. */
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync/** Hint for the select that getting interrupted while waiting is more likely.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * The interface implementation can optimize the waiting strategy based on this.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * It is assumed that it is more likely to get one of the above socket events
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * instead of being interrupted if the flag is not set. */
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync#define VD_INTERFACETCPNET_HINT_INTERRUPT RT_BIT_32(3)
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync/** Mask of the valid bits. */
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync#define VD_INTERFACETCPNET_EVT_VALID_MASK UINT32_C(0x0000000f)
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * TCP network stack interface
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Per-image. Mandatory for backends which have the VD_CAP_TCPNET bit set.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Common interface header.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Creates a socket. The socket is not connected if this succeeds.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @return iprt status code.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @retval VERR_NOT_SUPPORTED if the combination of flags is not supported.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param fFlags Combination of the VD_INTERFACETCPNET_CONNECT_* #defines.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pSock Where to store the handle.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync DECLR3CALLBACKMEMBER(int, pfnSocketCreate, (uint32_t fFlags, PVDSOCKET pSock));
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Destroys the socket.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @return iprt status code.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param Sock Socket descriptor.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync DECLR3CALLBACKMEMBER(int, pfnSocketDestroy, (VDSOCKET Sock));
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Connect as a client to a TCP port.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @return iprt status code.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param Sock Socket descriptor.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pszAddress The address to connect to.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param uPort The port to connect to.
d8c1ea9ddf56bd31af2c314604613d9d695f6e89vboxsync * @param cMillies Number of milliseconds to wait for the connect attempt to complete.
d8c1ea9ddf56bd31af2c314604613d9d695f6e89vboxsync * Use RT_INDEFINITE_WAIT to wait for ever.
d8c1ea9ddf56bd31af2c314604613d9d695f6e89vboxsync * Use RT_SOCKETCONNECT_DEFAULT_WAIT to wait for the default time
d8c1ea9ddf56bd31af2c314604613d9d695f6e89vboxsync * configured on the running system.
d8c1ea9ddf56bd31af2c314604613d9d695f6e89vboxsync DECLR3CALLBACKMEMBER(int, pfnClientConnect, (VDSOCKET Sock, const char *pszAddress, uint32_t uPort,
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Close a TCP connection.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @return iprt status code.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param Sock Socket descriptor.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync DECLR3CALLBACKMEMBER(int, pfnClientClose, (VDSOCKET Sock));
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Returns whether the socket is currently connected to the client.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @returns true if the socket is connected.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * false otherwise.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param Sock Socket descriptor.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync DECLR3CALLBACKMEMBER(bool, pfnIsClientConnected, (VDSOCKET Sock));
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Socket I/O multiplexing.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Checks if the socket is ready for reading.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @return iprt status code.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param Sock Socket descriptor.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param cMillies Number of milliseconds to wait for the socket.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Use RT_INDEFINITE_WAIT to wait for ever.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync DECLR3CALLBACKMEMBER(int, pfnSelectOne, (VDSOCKET Sock, RTMSINTERVAL cMillies));
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Receive data from a socket.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @return iprt status code.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param Sock Socket descriptor.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pvBuffer Where to put the data we read.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param cbBuffer Read buffer size.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pcbRead Number of bytes read.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * If NULL the entire buffer will be filled upon successful return.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * If not NULL a partial read can be done successfully.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync DECLR3CALLBACKMEMBER(int, pfnRead, (VDSOCKET Sock, void *pvBuffer, size_t cbBuffer, size_t *pcbRead));
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Send data to a socket.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @return iprt status code.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param Sock Socket descriptor.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pvBuffer Buffer to write data to socket.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param cbBuffer How much to write.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync DECLR3CALLBACKMEMBER(int, pfnWrite, (VDSOCKET Sock, const void *pvBuffer, size_t cbBuffer));
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Send data from scatter/gather buffer to a socket.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @return iprt status code.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param Sock Socket descriptor.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pSgBuffer Scatter/gather buffer to write data to socket.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync DECLR3CALLBACKMEMBER(int, pfnSgWrite, (VDSOCKET Sock, PCRTSGBUF pSgBuffer));
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Receive data from a socket - not blocking.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @return iprt status code.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param Sock Socket descriptor.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pvBuffer Where to put the data we read.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param cbBuffer Read buffer size.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pcbRead Number of bytes read.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync DECLR3CALLBACKMEMBER(int, pfnReadNB, (VDSOCKET Sock, void *pvBuffer, size_t cbBuffer, size_t *pcbRead));
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Send data to a socket - not blocking.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @return iprt status code.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param Sock Socket descriptor.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pvBuffer Buffer to write data to socket.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param cbBuffer How much to write.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pcbWritten Number of bytes written.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync DECLR3CALLBACKMEMBER(int, pfnWriteNB, (VDSOCKET Sock, const void *pvBuffer, size_t cbBuffer, size_t *pcbWritten));
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Send data from scatter/gather buffer to a socket - not blocking.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @return iprt status code.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param Sock Socket descriptor.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pSgBuffer Scatter/gather buffer to write data to socket.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pcbWritten Number of bytes written.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync DECLR3CALLBACKMEMBER(int, pfnSgWriteNB, (VDSOCKET Sock, PRTSGBUF pSgBuffer, size_t *pcbWritten));
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Flush socket write buffers.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @return iprt status code.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param Sock Socket descriptor.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync DECLR3CALLBACKMEMBER(int, pfnFlush, (VDSOCKET Sock));
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Enables or disables delaying sends to coalesce packets.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @return iprt status code.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param Sock Socket descriptor.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param fEnable When set to true enables coalescing.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync DECLR3CALLBACKMEMBER(int, pfnSetSendCoalescing, (VDSOCKET Sock, bool fEnable));
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Gets the address of the local side.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @return iprt status code.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param Sock Socket descriptor.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pAddr Where to store the local address on success.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync DECLR3CALLBACKMEMBER(int, pfnGetLocalAddress, (VDSOCKET Sock, PRTNETADDR pAddr));
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Gets the address of the other party.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @return iprt status code.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param Sock Socket descriptor.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pAddr Where to store the peer address on success.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync DECLR3CALLBACKMEMBER(int, pfnGetPeerAddress, (VDSOCKET Sock, PRTNETADDR pAddr));
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Socket I/O multiplexing - extended version which can be woken up.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Checks if the socket is ready for reading or writing.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @return iprt status code.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @retval VERR_INTERRUPTED if the thread was woken up by a pfnPoke call.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param Sock Socket descriptor.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param fEvents Mask of events to wait for.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pfEvents Where to store the received events.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param cMillies Number of milliseconds to wait for the socket.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Use RT_INDEFINITE_WAIT to wait for ever.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync DECLR3CALLBACKMEMBER(int, pfnSelectOneEx, (VDSOCKET Sock, uint32_t fEvents,
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Wakes up the thread waiting in pfnSelectOneEx.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @return iprt status code.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param Sock Socket descriptor.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync DECLR3CALLBACKMEMBER(int, pfnPoke, (VDSOCKET Sock));
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Get TCP network stack interface from interface list.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @return Pointer to the first TCP network stack interface in the list.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pVDIfs Pointer to the interface list.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsyncDECLINLINE(PVDINTERFACETCPNET) VDIfTcpNetGet(PVDINTERFACE pVDIfs)
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync PVDINTERFACE pIf = VDInterfaceGet(pVDIfs, VDINTERFACETYPE_TCPNET);
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync /* Check that the interface descriptor is a progress interface. */
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Interface to synchronize concurrent accesses by several threads.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @note The scope of this interface is to manage concurrent accesses after
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * the HDD container has been created, and they must stop before destroying the
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * container. Opening or closing images is covered by the synchronization, but
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * that does not mean it is safe to close images while a thread executes
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * <link to="VDMerge"/> or <link to="VDCopy"/> operating on these images.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Making them safe would require the lock to be held during the entire
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * operation, which prevents other concurrent acitivities.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @note Right now this is kept as simple as possible, and does not even
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * attempt to provide enough information to allow e.g. concurrent write
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * accesses to different areas of the disk. The reason is that it is very
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * difficult to predict which area of a disk is affected by a write,
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * especially when different image formats are mixed. Maybe later a more
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * sophisticated interface will be provided which has the necessary information
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * about worst case affected areas.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Per-disk interface. Optional, needed if the disk is accessed concurrently
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * by several threads, e.g. when merging diff images while a VM is running.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Common interface header.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Start a read operation.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync DECLR3CALLBACKMEMBER(int, pfnStartRead, (void *pvUser));
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Finish a read operation.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync DECLR3CALLBACKMEMBER(int, pfnFinishRead, (void *pvUser));
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Start a write operation.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync DECLR3CALLBACKMEMBER(int, pfnStartWrite, (void *pvUser));
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Finish a write operation.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync DECLR3CALLBACKMEMBER(int, pfnFinishWrite, (void *pvUser));
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * Get thread synchronization interface from interface list.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @return Pointer to the first thread synchronization interface in the list.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync * @param pVDIfs Pointer to the interface list.
e4f367251aede667a6de69baa54ef9eb5f150871vboxsyncDECLINLINE(PVDINTERFACETHREADSYNC) VDIfThreadSyncGet(PVDINTERFACE pVDIfs)
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync PVDINTERFACE pIf = VDInterfaceGet(pVDIfs, VDINTERFACETYPE_THREADSYNC);
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync /* Check that the interface descriptor is a progress interface. */
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync || ( (pIf->enmInterface == VDINTERFACETYPE_THREADSYNC)
e4f367251aede667a6de69baa54ef9eb5f150871vboxsync && (pIf->cbSize == sizeof(VDINTERFACETHREADSYNC))),
e170d0511a1456f1677c93e03a78d7162ae82472vboxsync * Interface to query usage of disk ranges.
e170d0511a1456f1677c93e03a78d7162ae82472vboxsync * Per-operation interface. Optional.
e170d0511a1456f1677c93e03a78d7162ae82472vboxsync * Common interface header.
e170d0511a1456f1677c93e03a78d7162ae82472vboxsync * Query use of a disk range.
e170d0511a1456f1677c93e03a78d7162ae82472vboxsync DECLR3CALLBACKMEMBER(int, pfnQueryRangeUse, (void *pvUser, uint64_t off, uint64_t cb,
e170d0511a1456f1677c93e03a78d7162ae82472vboxsync} VDINTERFACEQUERYRANGEUSE, *PVDINTERFACEQUERYRANGEUSE;
e170d0511a1456f1677c93e03a78d7162ae82472vboxsync * Get query range use interface from interface list.
e170d0511a1456f1677c93e03a78d7162ae82472vboxsync * @return Pointer to the first thread synchronization interface in the list.
e170d0511a1456f1677c93e03a78d7162ae82472vboxsync * @param pVDIfs Pointer to the interface list.
e170d0511a1456f1677c93e03a78d7162ae82472vboxsyncDECLINLINE(PVDINTERFACEQUERYRANGEUSE) VDIfQueryRangeUseGet(PVDINTERFACE pVDIfs)
e170d0511a1456f1677c93e03a78d7162ae82472vboxsync PVDINTERFACE pIf = VDInterfaceGet(pVDIfs, VDINTERFACETYPE_QUERYRANGEUSE);
e170d0511a1456f1677c93e03a78d7162ae82472vboxsync /* Check that the interface descriptor is a progress interface. */
e170d0511a1456f1677c93e03a78d7162ae82472vboxsync || ( (pIf->enmInterface == VDINTERFACETYPE_QUERYRANGEUSE)
e170d0511a1456f1677c93e03a78d7162ae82472vboxsync && (pIf->cbSize == sizeof(VDINTERFACEQUERYRANGEUSE))),
e170d0511a1456f1677c93e03a78d7162ae82472vboxsyncDECLINLINE(int) vdIfQueryRangeUse(PVDINTERFACEQUERYRANGEUSE pIfQueryRangeUse, uint64_t off, uint64_t cb,
e170d0511a1456f1677c93e03a78d7162ae82472vboxsync return pIfQueryRangeUse->pfnQueryRangeUse(pIfQueryRangeUse->Core.pvUser, off, cb, pfUsed);
c5abe3ea9c7ac6dec34f42af30612534bea951ffvboxsync * Interface used to retrieve keys for cryptographic operations.
c5abe3ea9c7ac6dec34f42af30612534bea951ffvboxsync * Per-module interface. Optional but cryptographic modules might fail and
c5abe3ea9c7ac6dec34f42af30612534bea951ffvboxsync * return an error if this is not present.
c5abe3ea9c7ac6dec34f42af30612534bea951ffvboxsync * Common interface header.
c5abe3ea9c7ac6dec34f42af30612534bea951ffvboxsync * Retains a key identified by the ID. The caller will only hold a reference
c5abe3ea9c7ac6dec34f42af30612534bea951ffvboxsync * to the key and must not modify the key buffer in any way.
c5abe3ea9c7ac6dec34f42af30612534bea951ffvboxsync * @returns VBox status code.
c5abe3ea9c7ac6dec34f42af30612534bea951ffvboxsync * @param pvUser The opaque user data associated with this interface.
c5abe3ea9c7ac6dec34f42af30612534bea951ffvboxsync * @param pszId The alias/id for the key to retrieve.
c5abe3ea9c7ac6dec34f42af30612534bea951ffvboxsync * @param ppbKey Where to store the pointer to the key buffer on success.
c5abe3ea9c7ac6dec34f42af30612534bea951ffvboxsync * @param pcbKey Where to store the size of the key in bytes on success.
c5abe3ea9c7ac6dec34f42af30612534bea951ffvboxsync DECLR3CALLBACKMEMBER(int, pfnKeyRetain, (void *pvUser, const char *pszId, const uint8_t **ppbKey, size_t *pcbKey));
c5abe3ea9c7ac6dec34f42af30612534bea951ffvboxsync * Releases one reference of the key identified by the given identifier.
c5abe3ea9c7ac6dec34f42af30612534bea951ffvboxsync * The caller must not access the key buffer after calling this operation.
c5abe3ea9c7ac6dec34f42af30612534bea951ffvboxsync * @returns VBox status code.
c5abe3ea9c7ac6dec34f42af30612534bea951ffvboxsync * @param pvUser The opaque user data associated with this interface.
c5abe3ea9c7ac6dec34f42af30612534bea951ffvboxsync * @param pszId The alias/id for the key to release.
c5abe3ea9c7ac6dec34f42af30612534bea951ffvboxsync * @note: It is advised to release the key whenever it is not used anymore so the entity
c5abe3ea9c7ac6dec34f42af30612534bea951ffvboxsync * storing the key can do anything to make retrieving the key from memory more
c5abe3ea9c7ac6dec34f42af30612534bea951ffvboxsync * difficult like scrambling the memory buffer for instance.
c5abe3ea9c7ac6dec34f42af30612534bea951ffvboxsync DECLR3CALLBACKMEMBER(int, pfnKeyRelease, (void *pvUser, const char *pszId));
d1aab951b0bd1de1a8a51daca46fce06daaed8d7vboxsync * Gets a reference to the password identified by the given ID to open a key store supplied through the config interface.
7cb5e5e023bd9dc218e5b159d4a421245101edb2vboxsync * @returns VBox status code.
7cb5e5e023bd9dc218e5b159d4a421245101edb2vboxsync * @param pvUser The opaque user data associated with this interface.
d1aab951b0bd1de1a8a51daca46fce06daaed8d7vboxsync * @param pszId The alias/id for the password to retain.
7cb5e5e023bd9dc218e5b159d4a421245101edb2vboxsync * @param ppszPassword Where to store the password to unlock the key store on success.
d1aab951b0bd1de1a8a51daca46fce06daaed8d7vboxsync DECLR3CALLBACKMEMBER(int, pfnKeyStorePasswordRetain, (void *pvUser, const char *pszId, const char **ppszPassword));
d1aab951b0bd1de1a8a51daca46fce06daaed8d7vboxsync * Releases a reference of the password previously acquired with VDINTERFACECRYPTO::pfnKeyStorePasswordRetain()
d1aab951b0bd1de1a8a51daca46fce06daaed8d7vboxsync * identified by the given ID.
d1aab951b0bd1de1a8a51daca46fce06daaed8d7vboxsync * @returns VBox status code.
d1aab951b0bd1de1a8a51daca46fce06daaed8d7vboxsync * @param pvUser The opaque user data associated with this interface.
d1aab951b0bd1de1a8a51daca46fce06daaed8d7vboxsync * @param pszId The alias/id for the password to release.
d1aab951b0bd1de1a8a51daca46fce06daaed8d7vboxsync DECLR3CALLBACKMEMBER(int, pfnKeyStorePasswordRelease, (void *pvUser, const char *pszId));
7cb5e5e023bd9dc218e5b159d4a421245101edb2vboxsync * Saves a key store.
7cb5e5e023bd9dc218e5b159d4a421245101edb2vboxsync * @returns VBox status code.
7cb5e5e023bd9dc218e5b159d4a421245101edb2vboxsync * @param pvUser The opaque user data associated with this interface.
7cb5e5e023bd9dc218e5b159d4a421245101edb2vboxsync * @param pvKeyStore The key store to save.
7cb5e5e023bd9dc218e5b159d4a421245101edb2vboxsync * @param cbKeyStore Size of the key store in bytes.
7cb5e5e023bd9dc218e5b159d4a421245101edb2vboxsync * @note The format is filter specific and should be treated as binary data.
7cb5e5e023bd9dc218e5b159d4a421245101edb2vboxsync DECLR3CALLBACKMEMBER(int, pfnKeyStoreSave, (void *pvUser, const void *pvKeyStore, size_t cbKeyStore));
7cb5e5e023bd9dc218e5b159d4a421245101edb2vboxsync * Returns the parameters after the key store was loaded successfully.
7cb5e5e023bd9dc218e5b159d4a421245101edb2vboxsync * @returns VBox status code.
7cb5e5e023bd9dc218e5b159d4a421245101edb2vboxsync * @param pvUser The opaque user data associated with this interface.
7cb5e5e023bd9dc218e5b159d4a421245101edb2vboxsync * @param pszCipher The cipher identifier the DEK is used for.
7cb5e5e023bd9dc218e5b159d4a421245101edb2vboxsync * @param pbDek The raw DEK which was contained in the key store loaded by
7cb5e5e023bd9dc218e5b159d4a421245101edb2vboxsync * VDINTERFACECRYPTO::pfnKeyStoreLoad().
7cb5e5e023bd9dc218e5b159d4a421245101edb2vboxsync * @param cbDek The size of the DEK.
7cb5e5e023bd9dc218e5b159d4a421245101edb2vboxsync * @note The provided pointer to the DEK is only valid until this call returns.
7cb5e5e023bd9dc218e5b159d4a421245101edb2vboxsync * The content might change afterwards with out notice (when scrambling the key
7cb5e5e023bd9dc218e5b159d4a421245101edb2vboxsync * for further protection for example) or might be even freed.
7cb5e5e023bd9dc218e5b159d4a421245101edb2vboxsync * @note This method is optional and can be NULL if the caller does not require the
7cb5e5e023bd9dc218e5b159d4a421245101edb2vboxsync * parameters.
7cb5e5e023bd9dc218e5b159d4a421245101edb2vboxsync DECLR3CALLBACKMEMBER(int, pfnKeyStoreReturnParameters, (void *pvUser, const char *pszCipher,
c5abe3ea9c7ac6dec34f42af30612534bea951ffvboxsync * Get error interface from interface list.
c5abe3ea9c7ac6dec34f42af30612534bea951ffvboxsync * @return Pointer to the first error interface in the list.
c5abe3ea9c7ac6dec34f42af30612534bea951ffvboxsync * @param pVDIfs Pointer to the interface list.
c5abe3ea9c7ac6dec34f42af30612534bea951ffvboxsyncDECLINLINE(PVDINTERFACECRYPTO) VDIfCryptoGet(PVDINTERFACE pVDIfs)
c5abe3ea9c7ac6dec34f42af30612534bea951ffvboxsync PVDINTERFACE pIf = VDInterfaceGet(pVDIfs, VDINTERFACETYPE_CRYPTO);
c5abe3ea9c7ac6dec34f42af30612534bea951ffvboxsync /* Check that the interface descriptor is a crypto interface. */
7cb5e5e023bd9dc218e5b159d4a421245101edb2vboxsync * @copydoc VDINTERFACECRYPTO::pfnKeyRetain
c5abe3ea9c7ac6dec34f42af30612534bea951ffvboxsyncDECLINLINE(int) vdIfCryptoKeyRetain(PVDINTERFACECRYPTO pIfCrypto, const char *pszId, const uint8_t **ppbKey, size_t *pcbKey)
c5abe3ea9c7ac6dec34f42af30612534bea951ffvboxsync return pIfCrypto->pfnKeyRetain(pIfCrypto->Core.pvUser, pszId, ppbKey, pcbKey);
7cb5e5e023bd9dc218e5b159d4a421245101edb2vboxsync * @copydoc VDINTERFACECRYPTO::pfnKeyRelease
c5abe3ea9c7ac6dec34f42af30612534bea951ffvboxsyncDECLINLINE(int) vdIfCryptoKeyRelease(PVDINTERFACECRYPTO pIfCrypto, const char *pszId)
c5abe3ea9c7ac6dec34f42af30612534bea951ffvboxsync return pIfCrypto->pfnKeyRelease(pIfCrypto->Core.pvUser, pszId);
d1aab951b0bd1de1a8a51daca46fce06daaed8d7vboxsync * @copydoc VDINTERFACECRYPTO::pfnKeyStorePasswordRetain
d1aab951b0bd1de1a8a51daca46fce06daaed8d7vboxsyncDECLINLINE(int) vdIfCryptoKeyStorePasswordRetain(PVDINTERFACECRYPTO pIfCrypto, const char *pszId, const char **ppszPassword)
d1aab951b0bd1de1a8a51daca46fce06daaed8d7vboxsync return pIfCrypto->pfnKeyStorePasswordRetain(pIfCrypto->Core.pvUser, pszId, ppszPassword);
d1aab951b0bd1de1a8a51daca46fce06daaed8d7vboxsync * @copydoc VDINTERFACECRYPTO::pfnKeyStorePasswordRelease
d1aab951b0bd1de1a8a51daca46fce06daaed8d7vboxsyncDECLINLINE(int) vdIfCryptoKeyStorePasswordRelease(PVDINTERFACECRYPTO pIfCrypto, const char *pszId)
d1aab951b0bd1de1a8a51daca46fce06daaed8d7vboxsync return pIfCrypto->pfnKeyStorePasswordRelease(pIfCrypto->Core.pvUser, pszId);
7cb5e5e023bd9dc218e5b159d4a421245101edb2vboxsync * @copydoc VDINTERFACECRYPTO::pfnKeyStoreSave
7cb5e5e023bd9dc218e5b159d4a421245101edb2vboxsyncDECLINLINE(int) vdIfCryptoKeyStoreSave(PVDINTERFACECRYPTO pIfCrypto, const void *pvKeyStore, size_t cbKeyStore)
7cb5e5e023bd9dc218e5b159d4a421245101edb2vboxsync return pIfCrypto->pfnKeyStoreSave(pIfCrypto->Core.pvUser, pvKeyStore, cbKeyStore);
7cb5e5e023bd9dc218e5b159d4a421245101edb2vboxsync * @copydoc VDINTERFACECRYPTO::pfnKeyStoreReturnParameters
7cb5e5e023bd9dc218e5b159d4a421245101edb2vboxsyncDECLINLINE(int) vdIfCryptoKeyStoreReturnParameters(PVDINTERFACECRYPTO pIfCrypto, const char *pszCipher,