vd-ifs.h revision 10d930a35bb172f2a8982a4e30107f8bfcd8d132
/** Interface header magic. */ * Supported interface types. /** First valid interface. */ /** Interface to pass error message to upper layers. Per-disk. */ /** Interface for I/O operations. Per-image. */ /** Interface for progress notification. Per-operation. */ /** Interface for configuration information. Per-image. */ /** Interface for TCP network stack. Per-image. */ /** Interface for getting parent image state. Per-operation. */ /** Interface for synchronizing accesses from several threads. Per-disk. */ /** Interface for I/O between the generic VBoxHDD code and the backend. Per-image (internal). * This interface is completely internal and must not be used elsewhere. */ /** Interface to query the use of block ranges on the disk. Per-operation. */ /** invalid interface. */ * Common structure for all interfaces and at the beginning of all types. /** Human readable interface name. */ /** Pointer to the next common interface structure. */ /** Size of the interface. */ /** Opaque user data which is passed on every call. */ /** Pointer to a VDINTERFACE. */ /** Pointer to a const VDINTERFACE. */ * Helper functions to handle interface lists. * @note These interface lists are used consistently to pass per-disk, * per-image and/or per-operation callbacks. Those three purposes are strictly * separate. See the individual interface declarations for what context they * apply to. The caller is responsible for ensuring that the lifetime of the * interface descriptors is appropriate for the category of interface. * Get a specific interface from a list of interfaces specified by the type. * @return Pointer to the matching interface or NULL if none was found. * @param pVDIfs Pointer to the VD interface list. * @param enmInterface Interface to search for. /* No matching interface was found. */ * Add an interface to a list of interfaces. * @return VBox status code. * @param pInterface Pointer to an unitialized common interface structure. * @param pszName Name of the interface. * @param enmInterface Type of the interface. * @param pvUser Opaque user data passed on every function call. * @param ppVDIfs Pointer to the VD interface list. /* Fill out interface descriptor. */ /* Remember the new start of the list. */ * Removes an interface from a list of interfaces. * @return VBox status code * @param pInterface Pointer to an initialized common interface structure to remove. * @param ppVDIfs Pointer to the VD interface list to remove from. * Interface to deliver error messages (and also informational messages) * Per-disk interface. Optional, but think twice if you want to miss the * opportunity of reporting better human-readable error messages. * Common interface header. * Error message callback. Must be able to accept special IPRT format * @param pvUser The opaque data passed on container creation. * @param rc The VBox error code. * @param RT_SRC_POS_DECL Use RT_SRC_POS. * @param pszFormat Error message format string. * @param va Error message arguments. * Informational message callback. May be NULL. Used e.g. in * VDDumpImages(). Must be able to accept special IPRT format strings. * @return VBox status code. * @param pvUser The opaque data passed on container creation. * @param pszFormat Message format string. * @param va Message arguments. * Get error interface from interface list. * @return Pointer to the first error interface in the list. * @param pVDIfs Pointer to the interface list. /* Check that the interface descriptor is a progress interface. */ (
"Not an error interface\n"),
NULL);
* Signal an error to the frontend. * @returns VBox status code. * @param pIfError The error interface. * @param rc The status code. * @param RT_SRC_POS_DECL The position in the source code. * @param pszFormat The format string to pass. * @param ... Arguments to the format string. * Signal an informational message to the frontend. * @returns VBox status code. * @param pIfError The error interface. * @param pszFormat The format string to pass. * @param ... Arguments to the format string. * Completion callback which is called by the interface owner * to inform the backend that a task finished. * @return VBox status code. * @param pvUser Opaque user data which is passed on request submission. * @param rcReq Status code of the completed request. /** Pointer to FNVDCOMPLETED() */ * Support interface for I/O * Per-image. Optional as input. * Common interface header. * @return VBox status code. * @param pvUser The opaque data passed on container creation. * @param pszLocation Name of the location to open. * @param fOpen Flags for opening the backend. * See RTFILE_O_* #defines, inventing another set * of open flags is not worth the mapping effort. * @param pfnCompleted The callback which is called whenever a task * completed. The backend has to pass the user data * of the request initiator (ie the one who calls * VDAsyncRead or VDAsyncWrite) in pvCompletion * @param ppStorage Where to store the opaque storage handle. * @return VBox status code. * @param pvUser The opaque data passed on container creation. * @param pStorage The opaque storage handle to close. * @return VBox status code. * @param pvUser The opaque data passed on container creation. * @param pcszFilename Name of the file to delete. * @return VBox status code. * @param pvUser The opaque data passed on container creation. * @param pcszSrc The path to the source file. * @param pcszDst The path to the destination file. * This file will be created. * @param fMove A combination of the RTFILEMOVE_* flags. * Returns the free space on a disk. * @return VBox status code. * @param pvUser The opaque data passed on container creation. * @param pcszFilename Name of a file to identify the disk. * @param pcbFreeSpace Where to store the free space of the disk. * Returns the last modification timestamp of a file. * @return VBox status code. * @param pvUser The opaque data passed on container creation. * @param pcszFilename Name of a file to identify the disk. * @param pModificationTime Where to store the timestamp of the file. * Returns the size of the opened storage backend. * @return VBox status code. * @param pvUser The opaque data passed on container creation. * @param pStorage The opaque storage handle to close. * @param pcbSize Where to store the size of the storage backend. * Sets the size of the opened storage backend if possible. * @return VBox status code. * @retval VERR_NOT_SUPPORTED if the backend does not support this operation. * @param pvUser The opaque data passed on container creation. * @param pStorage The opaque storage handle to close. * @param cbSize The new size of the image. * Synchronous write callback. * @return VBox status code. * @param pvUser The opaque data passed on container creation. * @param pStorage The storage handle to use. * @param uOffset The offset to start from. * @param pvBuffer Pointer to the bits need to be written. * @param cbBuffer How many bytes to write. * @param pcbWritten Where to store how many bytes were actually written. * Synchronous read callback. * @return VBox status code. * @param pvUser The opaque data passed on container creation. * @param pStorage The storage handle to use. * @param uOffset The offset to start from. * @param pvBuffer Where to store the read bits. * @param cbBuffer How many bytes to read. * @param pcbRead Where to store how many bytes were actually read. * Flush data to the storage backend. * @return VBox status code. * @param pvUser The opaque data passed on container creation. * @param pStorage The storage handle to flush. * Initiate an asynchronous read request. * @return VBox status code. * @param pvUser The opaque user data passed on container creation. * @param pStorage The storage handle. * @param uOffset The offset to start reading from. * @param paSegments Scatter gather list to store the data in. * @param cSegments Number of segments in the list. * @param cbRead How many bytes to read. * @param pvCompletion The opaque user data which is returned upon completion. * @param ppTask Where to store the opaque task handle. * Initiate an asynchronous write request. * @return VBox status code. * @param pvUser The opaque user data passed on conatiner creation. * @param pStorage The storage handle. * @param uOffset The offset to start writing to. * @param paSegments Scatter gather list of the data to write * @param cSegments Number of segments in the list. * @param cbWrite How many bytes to write. * @param pvCompletion The opaque user data which is returned upon completion. * @param ppTask Where to store the opaque task handle. * Initiates an async flush request. * @return VBox status code. * @param pvUser The opaque data passed on container creation. * @param pStorage The storage handle to flush. * @param pvCompletion The opaque user data which is returned upon completion. * @param ppTask Where to store the opaque task handle. * Get I/O interface from interface list. * @return Pointer to the first I/O interface in the list. * @param pVDIfs Pointer to the interface list. /* Check that the interface descriptor is a progress interface. */ (
"Not a I/O interface"),
NULL);
* Create a VFS stream handle around a VD I/O interface. * The I/O interface will not be closed or free by the stream, the caller will * do so after it is done with the stream and has released the instances of the * I/O stream object returned by this API. * @return VBox status code. * @param pVDIfsIo Pointer to the VD I/O interface. * @param pvStorage The storage argument to pass to the interface * @param fFlags RTFILE_O_XXX, access mask requied. * @param phVfsIos Where to return the VFS I/O stream handle on * Callback which provides progress information about a currently running * @return VBox status code. * @param pvUser The opaque user data associated with this interface. * @param uPercent Completion percentage. /** Pointer to FNVDPROGRESS() */ * Progress notification interface * Per-operation. Optional. * Common interface header. * Progress notification callbacks. * Get progress interface from interface list. * @return Pointer to the first progress interface in the list. * @param pVDIfs Pointer to the interface list. /* Check that the interface descriptor is a progress interface. */ (
"Not a progress interface"),
NULL);
* Configuration information interface * Per-image. Optional for most backends, but mandatory for images which do * not operate on files (including standard block or character devices). * Common interface header. * Validates that the keys are within a set of valid names. * @return true if all key names are found in pszzAllowed. * @param pvUser The opaque user data associated with this interface. * @param pszzValid List of valid key names separated by '\\0' and ending with * Retrieves the length of the string value associated with a key (including * the terminator, for compatibility with CFGMR3QuerySize). * @return VBox status code. * VERR_CFGM_VALUE_NOT_FOUND means that the key is not known. * @param pvUser The opaque user data associated with this interface. * @param pszName Name of the key to query. * @param pcbValue Where to store the value length. Non-NULL. * Query the string value associated with a key. * @return VBox status code. * VERR_CFGM_VALUE_NOT_FOUND means that the key is not known. * VERR_CFGM_NOT_ENOUGH_SPACE means that the buffer is not big enough. * @param pvUser The opaque user data associated with this interface. * @param pszName Name of the key to query. * @param pszValue Pointer to buffer where to store value. * @param cchValue Length of value buffer. * Get configuration information interface from interface list. * @return Pointer to the first configuration information interface in the list. * @param pVDIfs Pointer to the interface list. /* Check that the interface descriptor is a progress interface. */ (
"Not a config interface"),
NULL);
* Query configuration, validates that the keys are within a set of valid names. * @return true if all key names are found in pszzAllowed. * @param pCfgIf Pointer to configuration callback table. * @param pszzValid List of valid names separated by '\\0' and ending with * Query configuration, unsigned 64-bit integer value with default. * @return VBox status code. * @param pCfgIf Pointer to configuration callback table. * @param pszName Name of an integer value * @param pu64 Where to store the value. Set to default on failure. * @param u64Def The default value. * Query configuration, unsigned 32-bit integer value with default. * @return VBox status code. * @param pCfgIf Pointer to configuration callback table. * @param pszName Name of an integer value * @param pu32 Where to store the value. Set to default on failure. * @param u32Def The default value. * Query configuration, bool value with default. * @return VBox status code. * @param pCfgIf Pointer to configuration callback table. * @param pszName Name of an integer value * @param pf Where to store the value. Set to default on failure. * @param fDef The default value. *
pf =
u64 ?
true :
false;
* Query configuration, dynamically allocated (RTMemAlloc) zero terminated * @return VBox status code. * @param pCfgIf Pointer to configuration callback table. * @param pszName Name of an zero terminated character value * @param ppszString Where to store the string pointer. Not set on failure. * Free this using RTMemFree(). * Query configuration, dynamically allocated (RTMemAlloc) zero terminated * character value with default. * @return VBox status code. * @param pCfgIf Pointer to configuration callback table. * @param pszName Name of an zero terminated character value * @param ppszString Where to store the string pointer. Not set on failure. * Free this using RTMemFree(). * @param pszDef The default value. * Query configuration, dynamically allocated (RTMemAlloc) byte string value. * @return VBox status code. * @param pCfgIf Pointer to configuration callback table. * @param pszName Name of an zero terminated character value * @param ppvData Where to store the byte string pointer. Not set on failure. * Free this using RTMemFree(). * @param pcbData Where to store the byte string length. *
pcbData =
cb -
1;
/* Exclude terminator of the queried string. *//** Forward declaration of a VD socket. */ /** Pointer to a VD socket. */ /** Nil socket handle. */ /** Connect flag to indicate that the backend wants to use the extended * socket I/O multiplexing call. This might not be supported on all configurations * (internal networking and iSCSI) * and the backend needs to take appropriate action. /** Readable without blocking. */ /** Writable without blocking. */ /** Error condition, hangup, exception or similar. */ /** Hint for the select that getting interrupted while waiting is more likely. * The interface implementation can optimize the waiting strategy based on this. * It is assumed that it is more likely to get one of the above socket events * instead of being interrupted if the flag is not set. */ /** Mask of the valid bits. */ * TCP network stack interface * Per-image. Mandatory for backends which have the VD_CAP_TCPNET bit set. * Common interface header. * Creates a socket. The socket is not connected if this succeeds. * @return iprt status code. * @retval VERR_NOT_SUPPORTED if the combination of flags is not supported. * @param fFlags Combination of the VD_INTERFACETCPNET_CONNECT_* #defines. * @param pSock Where to store the handle. * @return iprt status code. * @param Sock Socket descriptor. * Connect as a client to a TCP port. * @return iprt status code. * @param Sock Socket descriptor. * @param pszAddress The address to connect to. * @param uPort The port to connect to. * Close a TCP connection. * @return iprt status code. * @param Sock Socket descriptor. * Returns whether the socket is currently connected to the client. * @returns true if the socket is connected. * @param Sock Socket descriptor. * Socket I/O multiplexing. * Checks if the socket is ready for reading. * @return iprt status code. * @param Sock Socket descriptor. * @param cMillies Number of milliseconds to wait for the socket. * Use RT_INDEFINITE_WAIT to wait for ever. * Receive data from a socket. * @return iprt status code. * @param Sock Socket descriptor. * @param pvBuffer Where to put the data we read. * @param cbBuffer Read buffer size. * @param pcbRead Number of bytes read. * If NULL the entire buffer will be filled upon successful return. * If not NULL a partial read can be done successfully. * @return iprt status code. * @param Sock Socket descriptor. * @param pvBuffer Buffer to write data to socket. * @param cbBuffer How much to write. * @return iprt status code. * @param Sock Socket descriptor. * @param pSgBuffer Scatter/gather buffer to write data to socket. * Receive data from a socket - not blocking. * @return iprt status code. * @param Sock Socket descriptor. * @param pvBuffer Where to put the data we read. * @param cbBuffer Read buffer size. * @param pcbRead Number of bytes read. * Send data to a socket - not blocking. * @return iprt status code. * @param Sock Socket descriptor. * @param pvBuffer Buffer to write data to socket. * @param cbBuffer How much to write. * @param pcbWritten Number of bytes written. * Send data from scatter/gather buffer to a socket - not blocking. * @return iprt status code. * @param Sock Socket descriptor. * @param pSgBuffer Scatter/gather buffer to write data to socket. * @param pcbWritten Number of bytes written. * Flush socket write buffers. * @return iprt status code. * @param Sock Socket descriptor. * Enables or disables delaying sends to coalesce packets. * @return iprt status code. * @param Sock Socket descriptor. * @param fEnable When set to true enables coalescing. * Gets the address of the local side. * @return iprt status code. * @param Sock Socket descriptor. * @param pAddr Where to store the local address on success. * Gets the address of the other party. * @return iprt status code. * @param Sock Socket descriptor. * @param pAddr Where to store the peer address on success. * Socket I/O multiplexing - extended version which can be woken up. * Checks if the socket is ready for reading or writing. * @return iprt status code. * @retval VERR_INTERRUPTED if the thread was woken up by a pfnPoke call. * @param Sock Socket descriptor. * @param fEvents Mask of events to wait for. * @param pfEvents Where to store the received events. * @param cMillies Number of milliseconds to wait for the socket. * Use RT_INDEFINITE_WAIT to wait for ever. * Wakes up the thread waiting in pfnSelectOneEx. * @return iprt status code. * @param Sock Socket descriptor. * Get TCP network stack interface from interface list. * @return Pointer to the first TCP network stack interface in the list. * @param pVDIfs Pointer to the interface list. /* Check that the interface descriptor is a progress interface. */ (
"Not a TCP net interface"),
NULL);
* Interface to synchronize concurrent accesses by several threads. * @note The scope of this interface is to manage concurrent accesses after * the HDD container has been created, and they must stop before destroying the * container. Opening or closing images is covered by the synchronization, but * that does not mean it is safe to close images while a thread executes * <link to="VDMerge"/> or <link to="VDCopy"/> operating on these images. * Making them safe would require the lock to be held during the entire * operation, which prevents other concurrent acitivities. * @note Right now this is kept as simple as possible, and does not even * attempt to provide enough information to allow e.g. concurrent write * accesses to different areas of the disk. The reason is that it is very * difficult to predict which area of a disk is affected by a write, * especially when different image formats are mixed. Maybe later a more * sophisticated interface will be provided which has the necessary information * about worst case affected areas. * Per-disk interface. Optional, needed if the disk is accessed concurrently * by several threads, e.g. when merging diff images while a VM is running. * Common interface header. * Start a read operation. * Finish a read operation. * Start a write operation. * Finish a write operation. * Get thread synchronization interface from interface list. * @return Pointer to the first thread synchronization interface in the list. * @param pVDIfs Pointer to the interface list. /* Check that the interface descriptor is a progress interface. */ (
"Not a thread synchronization interface"),
NULL);
* Interface to query usage of disk ranges. * Per-operation interface. Optional. * Common interface header. * Query use of a disk range. * Get query range use interface from interface list. * @return Pointer to the first thread synchronization interface in the list. * @param pVDIfs Pointer to the interface list. /* Check that the interface descriptor is a progress interface. */ (
"Not a query range use interface"),
NULL);