vd.h revision 19badc2a6bdaeb1208f71b7de06feec1aa7c59c9
/** Current VDI image version. */ /** Get VDI major version from combined version. */ /** Get VDI minor version from combined version. */ /** Placeholder for specifying the last opened image. */ /** @name VBox HDD container image flags /** Diff image. Mutually exclusive with fixed image. */ /** VMDK: Split image into 2GB extents. */ /** VMDK: Raw disk image (giving access to a number of host partitions). */ /** VMDK: stream optimized image, read only. */ /** VMDK: ESX variant, use in addition to other flags. */ /** VDI: Fill new blocks with zeroes while expanding image file. Only valid * for newly created images, never set for opened existing images. */ /** Mask of valid image flags for VMDK. */ /** Mask of valid image flags for VDI. */ /** Mask of all valid image flags for all formats. */ /** Default image flags. */ * Auxiliary type for describing partitions on raw disks. The entries must be * in ascending order (as far as uStart is concerned), and must not overlap. * Note that this does not correspond 1:1 to partitions, it is describing the * general meaning of contiguous areas on the disk. /** Device to use for this partition/data area. Can be the disk device if * the offset field is set appropriately. If this is NULL, then this * partition will not be accessible to the guest. The size of the data area * must still be set correctly. */ /** Pointer to the partitioning info. NULL means this is a regular data * area on disk, non-NULL denotes data which should be copied to the * partition data overlay. */ /** Offset where the data starts in this device. */ /** Offset where the data starts in the disk. */ /** Size of the data area. */ * Auxiliary data structure for creating raw disks. /** Signature for structure. Must be 'R', 'A', 'W', '\\0'. Actually a trick * to make logging of the comment string produce sensible results. */ /** Flag whether access to full disk should be given (ignoring the * partition information below). */ /** Filename for the raw disk. Ignored for partitioned raw disks. * For Linux e.g. /dev/sda, and for Windows e.g. \\\\.\\PhysicalDisk0. */ /** Number of entries in the partition descriptor array. */ /** Pointer to the partition descriptor array. */ /** @name VBox HDD container image open mode flags /** Try to open image in read/write exclusive access mode if possible, or in read-only elsewhere. */ /** Open image in read-only mode with sharing access with others. */ /** Honor zero block writes instead of ignoring them whenever possible. * This is not supported by all formats. It is silently ignored in this case. */ /** Honor writes of the same data instead of ignoring whenever possible. * This is handled generically, and is only meaningful for differential image * formats. It is silently ignored otherwise. */ /** Do not perform the base/diff image check on open. This does NOT imply * opening the image as readonly (would break e.g. adding UUIDs to VMDK files * created by other products). Images opened with this flag should only be * used for querying information, and nothing else. */ /** Open image for asynchronous access. Only available if VD_CAP_ASYNC_IO is * set. Check with VDIsAsynchonousIoSupported whether asynchronous I/O is * really supported for this file. */ /** Allow sharing of the image for writable images. May be ignored if the * format backend doesn't support this type of concurrent access. */ /** Ask the backend to switch to sequential accesses if possible. Opening * will not fail if it cannot do this, the flag will be simply ignored. */ /** Mask of valid flags. */ * Helper functions to handle open flags. * Translate VD_OPEN_FLAGS_* to RTFile open flags. * @return RTFile open flags. * @param uOpenFlags VD_OPEN_FLAGS_* open flags. * @param fCreate Flag that the file should be created. /** @name VBox HDD container backend capability flags /** Supports UUIDs as expected by VirtualBox code. */ /** Supports creating fixed size images, allocating all space instantly. */ /** Supports creating dynamically growing images, allocating space on demand. */ /** Supports creating images split in chunks of a bit less than 2GBytes. */ /** Supports being used as differencing image format backend. */ /** Supports asynchronous I/O operations for at least some configurations. */ /** The backend operates on files. The caller needs to know to handle the * location appropriately. */ /** The backend uses the config interface. The caller needs to know how to * provide the mandatory configuration parts this way. */ /** The backend uses the network stack interface. The caller has to provide * the appropriate interface. */ /** The backend supports VFS (virtual filesystem) functionality since it uses * VDINTERFACEIO exclusively for all file operations. */ /** @name VBox HDD container type. * 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. */ /** invalid interface. */ * Common structure for all interfaces. /** Human readable interface name. */ /** The size of the struct. */ /** Pointer to the next common interface structure. */ /** Opaque user data which is passed on every call. */ /** Pointer to the function call table of the interface. * As this is opaque this must be casted to the right interface * struct defined below based on the interface type in enmInterface. */ /** 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 pCallbacks The callback table 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. * Size of the error interface. * 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 opaque callback table. * @return Pointer to the callback table. * @param pInterface Pointer to the interface descriptor. /* Check that the interface descriptor is a error interface. */ (
"Not an error interface"),
NULL);
(
"A non error callback table attached to a error interface descriptor\n"),
NULL);
* 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. * Size of the I/O interface. * @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 a 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 a 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 a 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 opaque callback table. * @return Pointer to the callback table. * @param pInterface Pointer to the interface descriptor. /* Check that the interface descriptor is an I/O interface. */ (
"Not an I/O interface"),
NULL);
(
"A non I/O callback table attached to an I/O interface descriptor\n"),
NULL);
* 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. * Size of the progress interface. * Progress notification callbacks. * Get progress interface from opaque callback table. * @return Pointer to the callback table. * @param pInterface Pointer to the interface descriptor. /* Check that the interface descriptor is a progress interface. */ (
"Not a progress interface"),
NULL);
(
"A non progress callback table attached to a progress interface descriptor\n"),
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). * Size of the configuration interface. * 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 opaque callback table. * @return Pointer to the callback table. * @param pInterface Pointer to the interface descriptor. /* Check that the interface descriptor is a config interface. */ (
"Not a config interface"),
NULL);
(
"A non config callback table attached to a config interface descriptor\n"),
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 pvUser The opaque user data associated with this interface. * @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 pvUser The opaque user data associated with this interface. * @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 pvUser The opaque user data associated with this interface. * @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 pvUser The opaque user data associated with this interface. * @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 pvUser The opaque user data associated with this interface. * @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 pvUser The opaque user data associated with this interface. * @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 pvUser The opaque user data associated with this interface. * @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. * Size of the configuration interface. * 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 opaque callback table. * @return Pointer to the callback table. * @param pInterface Pointer to the interface descriptor. /* Check that the interface descriptor is a TCP network stack interface. */ (
"Not a TCP network stack interface"),
NULL);
(
"A non TCP network stack callback table attached to a TCP network stack interface descriptor\n"),
NULL);
* Interface to get the parent state. * Per-operation interface. Optional, present only if there is a parent, and * used only internally for compacting. * Size of the parent state interface. * @return VBox status code. * @return VERR_VD_NOT_OPENED if no image is opened in HDD container. * @param pvUser The opaque data passed for the operation. * @param uOffset Offset of first reading byte from start of disk. * Must be aligned to a sector boundary. * @param pvBuffer Pointer to buffer for reading data. * @param cbBuffer Number of bytes to read. * Must be aligned to a sector boundary. * Get parent state interface from opaque callback table. * @return Pointer to the callback table. * @param pInterface Pointer to the interface descriptor. /* Check that the interface descriptor is a parent state interface. */ (
"Not a parent state interface"),
NULL);
(
"A non parent state callback table attached to a parent state interface descriptor\n"),
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. * Size of the thread synchronization interface. * Start a read operation. * Finish a read operation. * Start a write operation. * Finish a write operation. * Get thread synchronization interface from opaque callback table. * @return Pointer to the callback table. * @param pInterface Pointer to the interface descriptor. /* Check that the interface descriptor is a thread synchronization interface. */ (
"Not a thread synchronization interface"),
NULL);
(
"A non thread synchronization callback table attached to a thread synchronization interface descriptor\n"),
NULL);
/** @name Configuration interface key handling flags. /** Mandatory config key. Not providing a value for this key will cause * the backend to fail. */ /** Expert config key. Not showing it by default in the GUI is is probably * a good idea, as the average user won't understand it easily. */ * Configuration value type for configuration information interface. * through the config interface. /** Key name of the configuration. */ /** Pointer to default value (descriptor). NULL if no useful default value /** Value type for this key. */ /** Key handling flags (a combination of VD_CFGKEY_* flags). */ /** Pointer to structure describing configuration keys. */ /** Pointer to const structure describing configuration keys. */ * Structure describing a file extension. /** Pointer to the NULL-terminated string containing the extension. */ /** The device type the extension supports. */ /** Pointer to a structure describing a file extension. */ /** Pointer to a const structure describing a file extension. */ * Data structure for returning a list of backend capabilities. /** Name of the backend. Must be unique even with case insensitive comparison. */ /** Capabilities of the backend (a combination of the VD_CAP_* flags). */ /** Pointer to a NULL-terminated array of strings, containing the supported * file extensions. Note that some backends do not work on files, so this * pointer may just contain NULL. */ /** Pointer to an array of structs describing each supported config key. * Terminated by a NULL config key. Note that some backends do not support * the configuration interface, so this pointer may just contain NULL. * Mandatory if the backend sets VD_CAP_CONFIG. */ /** Returns a human readable hard disk location string given a * set of hard disk configuration keys. The returned string is an * equivalent of the full file path for image-based hard disks. * Mandatory for backends with no VD_CAP_FILE and NULL otherwise. */ /** Returns a human readable hard disk name string given a * set of hard disk configuration keys. The returned string is an * equivalent of the file name part in the full file path for * image-based hard disks. Mandatory for backends with no * VD_CAP_FILE and NULL otherwise. */ /** Forward declaration. Only visible in the VBoxHDD module. */ /** Storage backend handle. */ /** Pointer to a storage backend handle. */ * @return VBox status code. * VINF_SUCCESS if everything was successful and the transfer can continue. * VERR_VD_ASYNC_IO_IN_PROGRESS if there is another data transfer pending. * @param pBackendData The opaque backend data. * @param pIoCtx I/O context associated with this request. * @param pvUser Opaque user data passed during a read/write request. * @param rcReq Status code for the completed request. /** Pointer to FNVDXFERCOMPLETED() */ /** Metadata transfer handle. */ /** Pointer to a metadata transfer handle. */ * Internal I/O interface between the generic VD layer and the backends. * Per-image. Always passed to backends. * Size of the internal I/O interface. * @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 ppStorage Where to store the storage handle. * @return VBox status code. * @param pvUser The opaque data passed on container creation. * @param pStorage The 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 storage handle to get the size from. * @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 storage handle. * @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. * @notes Do not use in code called from the async read/write entry points in the backends. * This should be only used during open/close of images and for the support functions * which are not called while a VM is running (pfnCompact). * 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. * @notes See pfnWriteSync() * 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. * @notes See pfnWriteSync() * Initiate a asynchronous read request for user data. * @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 cbRead How many bytes to read. * Initiate a asynchronous write request for user data. * @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 writing to. * @param cbWrite How many bytes to write. * @param pfnCompleted Completion callback. * @param pvCompleteUser Opaque user data passed in the completion callback. * Reads metadata asynchronously from storage. * The current I/O context will be halted. * @returns VBox status code. * @param pvUser The opaque user data passed on container creation. * @param pStorage The storage handle. * @param uOffset Offset to start reading from. * @param pvBuffer Where to store the data. * @param cbBuffer How many bytes to read. * @param pIoCtx The I/O context which triggered the read. * @param ppMetaXfer Where to store the metadata transfer handle on success. * @param pfnCompleted Completion callback. * @param pvCompleteUser Opaque user data passed in the completion callback. * Writes metadata asynchronously to storage. * @returns VBox status code. * @param pvUser The opaque user data passed on container creation. * @param pStorage The storage handle. * @param uOffset Offset to start writing to. * @param pvBuffer Written data. * @param cbBuffer How many bytes to write. * @param pIoCtx The I/O context which triggered the write. * @param pfnCompleted Completion callback. * @param pvCompleteUser Opaque user data passed in the completion callback. * Releases a metadata transfer handle. * The free space can be used for another transfer. * @param pvUser The opaque user data passed on container creation. * @param pMetaXfer The metadata transfer handle to release. * Initiates a async flush request. * @return VBox status code. * @param pvUser The opaque data passed on container creation. * @param pStorage The storage handle to flush. * @param pIoCtx I/O context which triggered the flush. * @param pfnCompleted Completion callback. * @param pvCompleteUser Opaque user data passed in the completion callback. * Copies a buffer into the I/O context. * @return Number of bytes copied. * @param pvUser The opaque user data passed on container creation. * @param pIoCtx I/O context to copy the data to. * @param pvBuffer Buffer to copy. * @param cbBuffer Number of bytes to copy. * Copies data from the I/O context into a buffer. * @return Number of bytes copied. * @param pvUser The opaque user data passed on container creation. * @param pIoCtx I/O context to copy the data from. * @param pvBuffer Destination buffer. * @param cbBuffer Number of bytes to copy. * Sets the buffer of the given context to a specific byte. * @return Number of bytes set. * @param pvUser The opaque user data passed on container creation. * @param pIoCtx I/O context to copy the data from. * @param ch The byte to set. * @param cbSet Number of bytes to set. * Creates a segment array from the I/O context data buffer. * @returns Number of bytes the array describes. * @param pvUser The opaque user data passed on container creation. * @param pIoCtx I/O context to copy the data from. * @param paSeg The uninitialized segment array. * If NULL pcSeg will contain the number of segments needed * to describe the requested amount of data. * @param pcSeg The number of segments the given array has. * This will hold the actual number of entries needed upon return. * @param cbData Number of bytes the new array should describe. * Marks the given number of bytes as completed and continues the I/O context. * @param pvUser The opaque user data passed on container creation. * @param pIoCtx The I/O context. * @param rcReq Status code the request completed with. * @param cbCompleted Number of bytes completed. * Get internal I/O interface from opaque callback table. * @return Pointer to the callback table. * @param pInterface Pointer to the interface descriptor. /* Check that the interface descriptor is an internal I/O interface. */ (
"Not an internal I/O interface"),
NULL);
(
"A non internal I/O callback table attached to an internal I/O interface descriptor\n"),
NULL);
* Request completion callback for the async read/write API. /** Pointer to a transfer compelte callback. */ /** Number of cylinders. */ /** Number of sectors. */ /** Pointer to disk geometry. */ /** Pointer to constant disk geometry. */ * VBox HDD Container main structure. /* Forward declaration, VBOXHDD structure is visible only inside VBox HDD module. */ * Initializes HDD backends. * @returns VBox status code. * Destroys loaded HDD backends. * @returns VBox status code. * Lists all HDD backends and their capabilities in a caller-provided buffer. * @return VBox status code. * VERR_BUFFER_OVERFLOW if not enough space is passed. * @param cEntriesAlloc Number of list entries available. * @param pEntries Pointer to array for the entries. * @param pcEntriesUsed Number of entries returned. * Lists the capabilities of a backend identified by its name. * @return VBox status code. * @param pszBackend The backend name (case insensitive). * @param pEntries Pointer to an entry. * Allocates and initializes an empty HDD container. * No image files are opened. * @return VBox status code. * @param pVDIfsDisk Pointer to the per-disk VD interface list. * @param enmType Type of the image container. * @param ppDisk Where to store the reference to HDD container. * Destroys HDD container. * If container has opened image files they will be closed. * @param pDisk Pointer to HDD container. * Try to get the backend name which can use this image. * @return VBox status code. * VINF_SUCCESS if a plugin was found. * ppszFormat contains the string which can be used as backend name. * VERR_NOT_SUPPORTED if no backend was found. * @param pVDIfsDisk Pointer to the per-disk VD interface list. * @param pVDIfsImage Pointer to the per-image VD interface list. * @param pszFilename Name of the image file for which the backend is queried. * @param ppszFormat Receives pointer of the UTF-8 string which contains the format name. * The returned pointer must be freed using RTStrFree(). * @param penmType Where to store the type of the image. * The first opened image file in HDD container must have a base image type, * others (next opened images) must be differencing or undo images. * Linkage is checked for differencing image to be consistent with the previously opened image. * When another differencing image is opened and the last image was opened in read/write access * mode, then the last image is reopened in read-only with deny write sharing mode. This allows * other processes to use images in read-only mode too. * Note that the image is opened in read-only mode if a read/write open is not possible. * Use VDIsReadOnly to check open mode. * @return VBox status code. * @param pDisk Pointer to HDD container. * @param pszBackend Name of the image file backend to use (case insensitive). * @param pszFilename Name of the image file to open. * @param uOpenFlags Image file open mode, see VD_OPEN_FLAGS_* constants. * @param pVDIfsImage Pointer to the per-image VD interface list. * @return VBox status code. * @param pDisk Pointer to the HDD container which should use the cache image. * @param pszBackend Name of the cache file backend to use (case insensitive). * @param pszFilename Name of the cache image to open. * @param uOpenFlags Image file open mode, see VD_OPEN_FLAGS_* constants. * @param pVDIfsCache Pointer to the per-cache VD interface list. * Creates and opens a new base image file. * @return VBox status code. * @param pDisk Pointer to HDD container. * @param pszBackend Name of the image file backend to use (case insensitive). * @param pszFilename Name of the image file to create. * @param cbSize Image size in bytes. * @param uImageFlags Flags specifying special image features. * @param pszComment Pointer to image comment. NULL is ok. * @param pPCHSGeometry Pointer to physical disk geometry <= (16383,16,63). Not NULL. * @param pLCHSGeometry Pointer to logical disk geometry <= (x,255,63). Not NULL. * @param pUuid New UUID of the image. If NULL, a new UUID is created. * @param uOpenFlags Image file open mode, see VD_OPEN_FLAGS_* constants. * @param pVDIfsImage Pointer to the per-image VD interface list. * @param pVDIfsOperation Pointer to the per-operation VD interface list. * Creates and opens a new differencing image file in HDD container. * See comments for VDOpen function about differencing images. * @return VBox status code. * @param pDisk Pointer to HDD container. * @param pszBackend Name of the image file backend to use (case insensitive). * @param pszFilename Name of the differencing image file to create. * @param uImageFlags Flags specifying special image features. * @param pszComment Pointer to image comment. NULL is ok. * @param pUuid New UUID of the image. If NULL, a new UUID is created. * @param pParentUuid New parent UUID of the image. If NULL, the UUID is queried automatically. * @param uOpenFlags Image file open mode, see VD_OPEN_FLAGS_* constants. * @param pVDIfsImage Pointer to the per-image VD interface list. * @param pVDIfsOperation Pointer to the per-operation VD interface list. * Creates and opens new cache image file in HDD container. * @return VBox status code. * @param pDisk Name of the cache file backend to use (case insensitive). * @param pszFilename Name of the differencing cache file to create. * @param cbSize Maximum size of the cache. * @param uImageFlags Flags specifying special cache features. * @param pszComment Pointer to image comment. NULL is ok. * @param pUuid New UUID of the image. If NULL, a new UUID is created. * @param uOpenFlags Image file open mode, see VD_OPEN_FLAGS_* constants. * @param pVDIfsCache Pointer to the per-cache VD interface list. * @param pVDIfsOperation Pointer to the per-operation VD interface list. * Merges two images (not necessarily with direct parent/child relationship). * As a side effect the source image and potentially the other images which * are also merged to the destination are deleted from both the disk and the * images in the HDD container. * @return VBox status code. * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened. * @param pDisk Pointer to HDD container. * @param nImageFrom Image number to merge from, counts from 0. 0 is always base image of container. * @param nImageTo Image number to merge to, counts from 0. 0 is always base image of container. * @param pVDIfsOperation Pointer to the per-operation VD interface list. * Copies an image from one HDD container to another. * The copy is opened in the target HDD container. * It is possible to convert between different image formats, because the * backend for the destination may be different from the source. * If both the source and destination reference the same HDD container, * then the image is moved (by copying/deleting or renaming) to the new location. * The source container is unchanged if the move operation fails, otherwise * the image at the new location is opened in the same way as the old one was. * @note The read/write accesses across disks are not synchronized, just the * accesses to each disk. Once there is a use case which requires a defined * read/write behavior in this situation this needs to be extended. * @return VBox status code. * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened. * @param pDiskFrom Pointer to source HDD container. * @param nImage Image number, counts from 0. 0 is always base image of container. * @param pDiskTo Pointer to destination HDD container. * @param pszBackend Name of the image file backend to use (may be NULL to use the same as the source, case insensitive). * @param pszFilename New name of the image (may be NULL to specify that the * copy destination is the destination container, or * if pDiskFrom == pDiskTo, i.e. when moving). * @param fMoveByRename If true, attempt to perform a move by renaming (if successful the new size is ignored). * @param cbSize New image size (0 means leave unchanged). * @param uImageFlags Flags specifying special destination image features. * @param pDstUuid New UUID of the destination image. If NULL, a new UUID is created. * This parameter is used if and only if a true copy is created. * In all rename/move cases or copy to existing image cases the modification UUIDs are copied over. * @param uOpenFlags Image file open mode, see VD_OPEN_FLAGS_* constants. * Only used if the destination image is created. * @param pVDIfsOperation Pointer to the per-operation VD interface list. * @param pDstVDIfsImage Pointer to the per-image VD interface list, for the * @param pDstVDIfsOperation Pointer to the per-operation VD interface list, * for the destination operation. * Optimizes the storage consumption of an image. Typically the unused blocks * have to be wiped with zeroes to achieve a substantial reduced storage use. * Another optimization done is reordering the image blocks, which can provide * a significant performance boost, as reads and writes tend to use less random * @note Compaction is treated as a single operation with regard to thread * synchronization, which means that it potentially blocks other activities for * a long time. The complexity of compaction would grow even more if concurrent * accesses have to be handled. * @return VBox status code. * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened. * @return VERR_VD_IMAGE_READ_ONLY if image is not writable. * @return VERR_NOT_SUPPORTED if this kind of image can be compacted, but * this isn't supported yet. * @param pDisk Pointer to HDD container. * @param nImage Image number, counts from 0. 0 is always base image of container. * @param pVDIfsOperation Pointer to the per-operation VD interface list. * Resizes the given disk image to the given size. * @return VERR_VD_IMAGE_READ_ONLY if image is not writable. * @return VERR_NOT_SUPPORTED if this kind of image can be compacted, but * @param pDisk Pointer to the HDD container. * @param cbSize New size of the image. * @param pPCHSGeometry Pointer to the new physical disk geometry <= (16383,16,63). Not NULL. * @param pLCHSGeometry Pointer to the new logical disk geometry <= (x,255,63). Not NULL. * @param pVDIfsOperation Pointer to the per-operation VD interface list. * Closes the last opened image file in HDD container. * If previous image file was opened in read-only mode (the normal case) and * the last opened image is in read-write mode then the previous image will be * @return VBox status code. * @return VERR_VD_NOT_OPENED if no image is opened in HDD container. * @param pDisk Pointer to HDD container. * @param fDelete If true, delete the image from the host disk. * Closes the currently opened cache image file in HDD container. * @return VBox status code. * @return VERR_VD_NOT_OPENED if no cache is opened in HDD container. * @param pDisk Pointer to HDD container. * @param fDelete If true, delete the image from the host disk. * Closes all opened image files in HDD container. * @return VBox status code. * @param pDisk Pointer to HDD container. * Read data from virtual HDD. * @return VBox status code. * @return VERR_VD_NOT_OPENED if no image is opened in HDD container. * @param pDisk Pointer to HDD container. * @param uOffset Offset of first reading byte from start of disk. * Must be aligned to a sector boundary. * @param pvBuffer Pointer to buffer for reading data. * @param cbBuffer Number of bytes to read. * Must be aligned to a sector boundary. * Write data to virtual HDD. * @return VBox status code. * @return VERR_VD_NOT_OPENED if no image is opened in HDD container. * @param pDisk Pointer to HDD container. * @param uOffset Offset of first writing byte from start of disk. * Must be aligned to a sector boundary. * @param pvBuffer Pointer to buffer for writing data. * @param cbBuffer Number of bytes to write. * Must be aligned to a sector boundary. * Make sure the on disk representation of a virtual HDD is up to date. * @return VBox status code. * @return VERR_VD_NOT_OPENED if no image is opened in HDD container. * @param pDisk Pointer to HDD container. * Get number of opened images in HDD container. * @return Number of opened images for HDD container. 0 if no images have been opened. * @param pDisk Pointer to HDD container. * @return Virtual disk ReadOnly status. * @return true if no image is opened in HDD container. * @param pDisk Pointer to HDD container. * Get total capacity of an image in HDD container. * @return Virtual disk size in bytes. * @return 0 if image with specified number was not opened. * @param pDisk Pointer to HDD container. * @param nImage Image number, counts from 0. 0 is always base image of container. * Get total file size of an image in HDD container. * @return Virtual disk size in bytes. * @return 0 if image with specified number was not opened. * @param pDisk Pointer to HDD container. * @param nImage Image number, counts from 0. 0 is always base image of container. * Get virtual disk PCHS geometry of an image in HDD container. * @return VBox status code. * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened. * @return VERR_VD_GEOMETRY_NOT_SET if no geometry present in the HDD container. * @param pDisk Pointer to HDD container. * @param nImage Image number, counts from 0. 0 is always base image of container. * @param pPCHSGeometry Where to store PCHS geometry. Not NULL. * Store virtual disk PCHS geometry of an image in HDD container. * @return VBox status code. * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened. * @param pDisk Pointer to HDD container. * @param nImage Image number, counts from 0. 0 is always base image of container. * @param pPCHSGeometry Where to load PCHS geometry from. Not NULL. * Get virtual disk LCHS geometry of an image in HDD container. * @return VBox status code. * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened. * @return VERR_VD_GEOMETRY_NOT_SET if no geometry present in the HDD container. * @param pDisk Pointer to HDD container. * @param nImage Image number, counts from 0. 0 is always base image of container. * @param pLCHSGeometry Where to store LCHS geometry. Not NULL. * Store virtual disk LCHS geometry of an image in HDD container. * @return VBox status code. * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened. * @param pDisk Pointer to HDD container. * @param nImage Image number, counts from 0. 0 is always base image of container. * @param pLCHSGeometry Where to load LCHS geometry from. Not NULL. * Get version of image in HDD container. * @return VBox status code. * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened. * @param pDisk Pointer to HDD container. * @param nImage Image number, counts from 0. 0 is always base image of container. * @param puVersion Where to store the image version. * List the capabilities of image backend in HDD container. * @return VBox status code. * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened. * @param pDisk Pointer to the HDD container. * @param nImage Image number, counts from 0. 0 is always base image of container. * @param pbackendInfo Where to store the backend information. * Get flags of image in HDD container. * @return VBox status code. * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened. * @param pDisk Pointer to HDD container. * @param nImage Image number, counts from 0. 0 is always base image of container. * @param puImageFlags Where to store the image flags. * Get open flags of image in HDD container. * @return VBox status code. * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened. * @param pDisk Pointer to HDD container. * @param nImage Image number, counts from 0. 0 is always base image of container. * @param puOpenFlags Where to store the image open flags. * Set open flags of image in HDD container. * This operation may cause file locking changes and/or files being reopened. * Note that in case of unrecoverable error all images in HDD container will be closed. * @return VBox status code. * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened. * @param pDisk Pointer to HDD container. * @param nImage Image number, counts from 0. 0 is always base image of container. * @param uOpenFlags Image file open mode, see VD_OPEN_FLAGS_* constants. * Get base filename of image in HDD container. Some image formats use * other filenames as well, so don't use this for anything but informational * @return VBox status code. * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened. * @return VERR_BUFFER_OVERFLOW if pszFilename buffer too small to hold filename. * @param pDisk Pointer to HDD container. * @param nImage Image number, counts from 0. 0 is always base image of container. * @param pszFilename Where to store the image file name. * @param cbFilename Size of buffer pszFilename points to. * Get the comment line of image in HDD container. * @return VBox status code. * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened. * @return VERR_BUFFER_OVERFLOW if pszComment buffer too small to hold comment text. * @param pDisk Pointer to HDD container. * @param nImage Image number, counts from 0. 0 is always base image of container. * @param pszComment Where to store the comment string of image. NULL is ok. * @param cbComment The size of pszComment buffer. 0 is ok. * Changes the comment line of image in HDD container. * @return VBox status code. * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened. * @param pDisk Pointer to HDD container. * @param nImage Image number, counts from 0. 0 is always base image of container. * @param pszComment New comment string (UTF-8). NULL is allowed to reset the comment. * Get UUID of image in HDD container. * @return VBox status code. * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened. * @param pDisk Pointer to HDD container. * @param nImage Image number, counts from 0. 0 is always base image of container. * @param pUuid Where to store the image UUID. * Set the image's UUID. Should not be used by normal applications. * @return VBox status code. * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened. * @param pDisk Pointer to HDD container. * @param nImage Image number, counts from 0. 0 is always base image of container. * @param pUuid New UUID of the image. If NULL, a new UUID is created. * Get last modification UUID of image in HDD container. * @return VBox status code. * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened. * @param pDisk Pointer to HDD container. * @param nImage Image number, counts from 0. 0 is always base image of container. * @param pUuid Where to store the image modification UUID. * Set the image's last modification UUID. Should not be used by normal applications. * @return VBox status code. * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened. * @param pDisk Pointer to HDD container. * @param nImage Image number, counts from 0. 0 is always base image of container. * @param pUuid New modification UUID of the image. If NULL, a new UUID is created. * Get parent UUID of image in HDD container. * @return VBox status code. * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened. * @param pDisk Pointer to HDD container. * @param nImage Image number, counts from 0. 0 is always base image of the container. * @param pUuid Where to store the parent image UUID. * Set the image's parent UUID. Should not be used by normal applications. * @return VBox status code. * @param pDisk Pointer to HDD container. * @param nImage Image number, counts from 0. 0 is always base image of container. * @param pUuid New parent UUID of the image. If NULL, a new UUID is created. * Debug helper - dumps all opened images in HDD container into the log file. * @param pDisk Pointer to HDD container. * Query if asynchronous operations are supported for this disk. * @return VBox status code. * @return VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened. * @param pDisk Pointer to the HDD container. * @param nImage Image number, counts from 0. 0 is always base image of container. * @param pfAIOSupported Where to store if async IO is supported. * Start a asynchronous read request. * @return VBox status code. * @param pDisk Pointer to the HDD container. * @param uOffset The offset of the virtual disk to read from. * @param cbRead How many bytes to read. * @param pcSgBuf Pointer to the S/G buffer to read into. * @param pfnComplete Completion callback. * @param pvUser User data which is passed on completion * Start a asynchronous write request. * @return VBox status code. * @param pDisk Pointer to the HDD container. * @param uOffset The offset of the virtual disk to write to. * @param cbWrtie How many bytes to write. * @param pcSgBuf Pointer to the S/G buffer to write from. * @param pfnComplete Completion callback. * @param pvUser User data which is passed on completion. * Start a asynchronous flush request. * @return VBox status code. * @param pDisk Pointer to the HDD container. * @param pfnComplete Completion callback. * @param pvUser User data which is passed on completion.