VBoxHDD-new.cpp revision 8083a259c13e6e26e56ca2582edbad4a8cfac25a
/** Buffer size used for merging images. */ * VBox HDD Container image descriptor. /** Link to parent image descriptor, if any. */ /** Link to child image descriptor, if any. */ /** Container base filename. (UTF-8) */ /** Data managed by the backend which keeps the actual info. */ /** Image open flags (only those handled generically in this code and which * the backends will never ever see). */ * VBox HDD Container main structure, private part. /** Structure signature (VBOXHDDDISK_SIGNATURE). */ /** Number of opened images. */ /** Last opened image in the chain. * The same as pBase if only one image is used. */ /** Flags representing the modification state. */ /** Cached size of this disk. */ /** Cached PCHS geometry for this disk. */ /** Cached LCHS geometry for this disk. */ /** Error message processing callback. */ /** Opaque data for error callback. */ /** Handle for the shared object / DLL. */ /** Function pointers for the various backend methods. */ * internal: issue early error message. * internal: issue error message. * internal: add image structure to the end of images list. * internal: remove image structure from the images list. * internal: find image by index into the images list. * internal: read the specified amount of data in whatever blocks the backend /* Loop until all read. */ /* Search for image with allocated block. Do not attempt to read more * than the previous reads marked as valid. Otherwise this would return * stale data when different block sizes are used for the images. */ /* No image in the chain contains the data for the block. */ * internal: mark the disk as not modified. /* generate new last-modified uuid */ * internal: mark the disk as modified. /* First modify, so create a UUID and ensure it's written to disk. */ * internal: write a complete block (only used for diff images), taking the * remaining data from parent images. This implementation does not optimize * anything (except that it tries to read only that portions from parent * images that are really needed). /* Read the data that goes before the write to fill the block. */ /* Copy the data to the right place in the buffer. */ /* Read the data that goes after the write to fill the block. */ /* If we have data to be written, use that instead of reading * data from the image. */ /* Figure out how much we cannnot read from the image, because * the last block to write might exceed the nominal size of the * image for technical reasons. */ /* The rest must be read from the image. */ /* Now assemble the remaining data. */ /* Zero out the remainder of this block. Will never be visible, as this * is beyond the limit of the image. */ /* Write the full block to the virtual disk. */ * internal: write a complete block (only used for diff images), taking the * remaining data from parent images. This implementation optimized out writes * that do not change the data relative to the state as of the parent images. /* Figure out how much we cannnot read from the image, because * the last block to write might exceed the nominal size of the * image for technical reasons. */ /* If we have data to be written, use that instead of reading * data from the image. */ /* The rest must be read from the image. */ /* Read the entire data of the block so that we can compare whether it will * be modified by the write or not. */ /* Check if the write would modify anything in this block. */ /* Block is completely unchanged, so no need to write anything. */ /* Copy the data to the right place in the buffer. */ /* Handle the data that goes after the write to fill the block. */ /* Now assemble the remaining data. */ /* Zero out the remainder of this block. Will never be visible, as this * is beyond the limit of the image. */ /* Write the full block to the virtual disk. */ * internal: write buffer to the image, taking care of block boundaries and /* Loop until all written. */ /* Try to write the possibly partial block to the last opened image. * This works when the block is already allocated in this image or * if it is a full-block write, which automatically allocates a new /* Optimized write, suppress writing to a so far unallocated * block if the data is in fact not changed. */ /* Normal write, not optimized in any way. The block will * be written no matter what. This will usually (unless the * backend has some further optimization enabled) cause the * block to be allocated. */ * Allocates and initializes an empty HDD container. * No image files are opened. * @returns VBox status code. * @param pszBackend Name of the image file backend to use. * @param pfnError Callback for setting extended error information. * @param pvErrorUser Opaque parameter for pfnError. * @param ppDisk Where to store the reference to HDD container. LogFlowFunc((
"pszBackend=\"%s\" pfnError=%#p pvErrorUser=%#p\n",
/* If no static backend is found try loading a shared module with * pszBackend as filename. */ /* HDD Format Plugins have VBoxHDD as prefix, prepend it. */ /* Try to load the plugin (RTldrLoad takes care of the suffix). */ /* Get the function table. */ /* Check if the sizes match. If not this plugin is too old. */ * 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. * @returns 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 plugin was found. * @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(). /* First check if static backends support this file format. */ /* Copy the name into the new string. */ /* Then check if plugin backends support this file format. */ /* To get all entries with VBoxHDD as prefix. */ /* The plugins are in the same directory as the other shared libs. */ /* allocate new buffer. */ /* We got the new entry. */ /* Get the function table. */ /* Check if the plugin can handle this file. */ /* Report the format name. */ * We take the first plugin which can handle this file. * The first opened image file in HDD container must have a base image type, * others (next opened images) must be a differencing or undo images. * Linkage is checked for differencing image to be in consistence 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. * @returns VBox status code. * @param pDisk Pointer to HDD container. * @param pszFilename Name of the image file to open. * @param uOpenFlags Image file open mode, see VD_OPEN_FLAGS_* constants. LogFlowFunc((
"pDisk=%#p pszFilename=\"%s\" uOpenFlags=%#x\n",
/* Force readonly for images without base/diff consistency checking. */ /* Set up image descriptor. */ /* If the open in read-write mode failed, retry in read-only mode. */ /* Check image type. As the image itself has no idea whether it's a * base image or not, this info is derived here. Image 0 can be fixed * or normal, all others must be normal images. */ /** @todo optionally check UUIDs */ /* Cache disk information. */ /* Cache PCHS geometry. */ /* Make sure the PCHS geometry is properly clipped. */ /* Cache LCHS geometry. */ /* Make sure the LCHS geometry is properly clipped. */ /* Switch previous image to read-only mode. */ /* Image successfully opened, make it the last image. */ /* Error detected, but image opened. Close image. */ * Creates and opens a new base image file. * @returns VBox status code. * @param pDisk Pointer to HDD container. * @param pszFilename Name of the image file to create. * @param enmType Image type, only base image types are acceptable. * @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 <= (1024,255,63). Not NULL. * @param uOpenFlags Image file open mode, see VD_OPEN_FLAGS_* constants. * @param pfnProgress Progress callback. Optional. NULL if not to be used. * @param pvUser User argument for the progress callback. LogFlowFunc((
"pszFilename=\"%s\" enmType=%#x cbSize=%llu uImageFlags=%#x pszComment=\"%s\" PCHS=%u/%u/%u LCHS=%u/%u/%u uOpenFlags=%#x pfnProgress=%#p pvUser=%#p\n",
/* Set up image descriptor. */ /** @todo optionally check UUIDs */ /* Cache disk information. */ /* Cache PCHS geometry. */ /* Make sure the CHS geometry is properly clipped. */ /* Cache LCHS geometry. */ /* Make sure the CHS geometry is properly clipped. */ /* Image successfully opened, make it the last image. */ /* Error detected, but image opened. Close and delete image. */ * Creates and opens a new differencing image file in HDD container. * See comments for VDOpen function about differencing images. * @returns VBox status code. * @param pDisk Pointer to HDD container. * @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 uOpenFlags Image file open mode, see VD_OPEN_FLAGS_* constants. * @param pfnProgress Progress callback. Optional. NULL if not to be used. * @param pvUser User argument for the progress callback. LogFlowFunc((
"pDisk=%#p pszFilename=\"%s\" uImageFlags=%#x pszComment=\"%s\" uOpenFlags=%#x pfnProgress=%#p pvUser=%#p\n",
/* Set up image descriptor. */ /** @todo optionally check UUIDs */ /* Image successfully opened, make it the last image. */ /* Error detected, but image opened. Close and delete image. */ * 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. * @returns VBox status code. * @returns VERR_VDI_IMAGE_NOT_FOUND if image with specified number was not opened. * @param pDisk Pointer to HDD container. * @param nImageFrom Name of the image file to merge from. * @param nImageTo Name of the image file to merge to. * @param pfnProgress Progress callback. Optional. NULL if not to be used. * @param pvUser User argument for the progress callback. LogFlowFunc((
"pDisk=%#p nImageFrom=%u nImageTo=%u pfnProgress=%#p pvUser=%#p\n",
/* Check if destination image is writable. */ /* Get size of destination image. */ /* Allocate tmp buffer. */ /* Merging is done directly on the images itself. This potentially * causes trouble if the disk is full in the middle of operation. */ /** @todo write alternative implementation which works with temporary * images (which is safer, but requires even more space). Also has the * drawback that merging into a raw disk parent simply isn't possible * this way (but in that case disk full isn't really a problem). */ /* Merge parent state into child. This means writing all not * allocated blocks in the destination image which are allocated in * the images to be merged. */ /* Search for image with allocated block. Do not attempt to * read more than the previous reads marked as valid. * Otherwise this would return stale data when different * block sizes are used for the images. */ /* Merge child state into parent. This means writing all blocks * which are allocated in the image up to the source image to the /* Search for image with allocated block. Do not attempt to * read more than the previous reads marked as valid. Otherwise * this would return stale data when different block sizes are * used for the images. */ /* Update parent UUID so that image chain is consistent. */ /* Delete the no longer needed images. */ * 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 HDD container may be different from the * 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. * @returns VBox status code. * @returns VERR_VDI_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 pszFilename New name of the image (may be NULL if pDiskFrom == pDiskTo). * @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 pfnProgress Progress callback. Optional. NULL if not to be used. * @param pvUser User argument for the progress callback. * Closes the last opened image file in HDD container. * If previous image file was opened in read-only mode (that is normal) and closing image * was opened in read-write mode (the whole disk was in read-write mode) - the previous image * @returns VBox status code. * @returns VERR_VDI_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. /* Remove image from list of opened images. */ /* Close (and optionally delete) image. */ /* Free remaining resources related to the image. */ /* If disk was previously in read/write mode, make sure it will stay * like this (if possible) after closing this image. Set the open flags /* Cache disk information. */ /* Cache PCHS geometry. */ /* Make sure the PCHS geometry is properly clipped. */ /* Cache LCHS geometry. */ /* Make sure the LCHS geometry is properly clipped. */ * Closes all opened image files in HDD container. * @returns VBox status code. * @param pDisk Pointer to HDD container. /* Remove image from list of opened images. */ /* Free remaining resources related to the image. */ * Read data from virtual HDD. * @returns VBox status code. * @returns VERR_VDI_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. * @param pvBuf Pointer to buffer for reading data. * @param cbRead Number of bytes to read. LogFlowFunc((
"pDisk=%#p uOffset=%llu pvBuf=%p cbRead=%llu\n",
(
"uOffset=%llu cbRead=%llu pDisk->cbSize=%llu\n",
* Write data to virtual HDD. * @returns VBox status code. * @returns VERR_VDI_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. * @param pvBuf Pointer to buffer for writing data. * @param cbWrite Number of bytes to write. LogFlowFunc((
"pDisk=%#p uOffset=%llu pvBuf=%p cbWrite=%llu\n",
(
"uOffset=%llu cbWrite=%llu pDisk->cbSize=%llu\n",
* Make sure the on disk representation of a virtual HDD is up to date. * @returns VBox status code. * @returns VERR_VDI_NOT_OPENED if no image is opened in HDD container. * @param pDisk Pointer to HDD container. * Get number of opened images in HDD container. * @returns Number of opened images for HDD container. 0 if no images have been opened. * @param pDisk Pointer to HDD container. * @returns Virtual disk ReadOnly status. * @returns true if no image is opened in HDD container. * @param pDisk Pointer to HDD container. * Get total capacity of an image in HDD container. * @returns Virtual disk size in bytes. * @returns 0 if no image with specified number was not opened. * @param pDisk Pointer to HDD container. * @param nImage Image number, counds from 0. 0 is always base image of container. * Get total file size of an image in HDD container. * @returns Virtual disk size in bytes. * @returns 0 if no image is opened in HDD container. * @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 stored in HDD container. * @returns VBox status code. * @returns VERR_VDI_IMAGE_NOT_FOUND if image with specified number was not opened. * @returns VERR_VDI_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. LogFlowFunc((
"pDisk=%#p nImage=%u pPCHSGeometry=%#p\n",
/* Use cached information if possible. */ * Store virtual disk PCHS geometry in HDD container. * Note that in case of unrecoverable error all images in HDD container will be closed. * @returns VBox status code. * @returns VERR_VDI_IMAGE_NOT_FOUND if image with specified number was not opened. * @returns VERR_VDI_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 load PCHS geometry from. Not NULL. LogFlowFunc((
"pDisk=%#p nImage=%u pPCHSGeometry=%#p PCHS=%u/%u/%u\n",
/* Only update geometry if it is changed. Avoids similar checks * in every backend. Most of the time the new geometry is set * to the previous values, so no need to go through the hassle * of updating an image which could be opened in read-only mode /* Cache new geometry values in any case. */ /* Make sure the CHS geometry is properly clipped. */ /* Only update geometry if it is changed. Avoids similar checks * in every backend. Most of the time the new geometry is set * to the previous values, so no need to go through the hassle * of updating an image which could be opened in read-only mode * Get virtual disk LCHS geometry stored in HDD container. * @returns VBox status code. * @returns VERR_VDI_IMAGE_NOT_FOUND if image with specified number was not opened. * @returns VERR_VDI_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. LogFlowFunc((
"pDisk=%#p nImage=%u pLCHSGeometry=%#p\n",
/* Use cached information if possible. */ * Store virtual disk LCHS geometry in HDD container. * Note that in case of unrecoverable error all images in HDD container will be closed. * @returns VBox status code. * @returns VERR_VDI_IMAGE_NOT_FOUND if image with specified number was not opened. * @returns VERR_VDI_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 load LCHS geometry from. Not NULL. LogFlowFunc((
"pDisk=%#p nImage=%u pLCHSGeometry=%#p LCHS=%u/%u/%u\n",
/* Only update geometry if it is changed. Avoids similar checks * in every backend. Most of the time the new geometry is set * to the previous values, so no need to go through the hassle * of updating an image which could be opened in read-only mode /* Cache new geometry values in any case. */ /* Make sure the CHS geometry is properly clipped. */ /* Only update geometry if it is changed. Avoids similar checks * in every backend. Most of the time the new geometry is set * to the previous values, so no need to go through the hassle * of updating an image which could be opened in read-only mode * Get version of image in HDD container. * @returns VBox status code. * @returns VERR_VDI_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. * Get type of image in HDD container. * @returns VBox status code. * @returns VERR_VDI_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 penmType Where to store the image type. * Get flags of image in HDD container. * @returns VBox status code. * @returns VERR_VDI_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. * @returns VBox status code. * @returns VERR_VDI_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. * @returns VBox status code. * @returns VERR_VDI_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 * @returns VBox status code. * @returns VERR_VDI_IMAGE_NOT_FOUND if image with specified number was not opened. * @returns 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. LogFlowFunc((
"pDisk=%#p nImage=%u pszFilename=%#p cbFilename=%u\n",
* Get the comment line of image in HDD container. * @returns VBox status code. * @returns VERR_VDI_IMAGE_NOT_FOUND if image with specified number was not opened. * @returns 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. LogFlowFunc((
"pDisk=%#p nImage=%u pszComment=%#p cbComment=%u\n",
* Changes the comment line of image in HDD container. * @returns VBox status code. * @returns VERR_VDI_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. LogFlowFunc((
"pDisk=%#p nImage=%u pszComment=%#p \"%s\"\n",
* Get UUID of image in HDD container. * @returns VBox status code. * @returns VERR_VDI_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 creation UUID. * Set the image's UUID. Should not be used by normal applications. * @returns VBox status code. * @returns VERR_VDI_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. LogFlowFunc((
"pDisk=%#p nImage=%u pUuid=%#p {%Vuuid}\n",
* Get last modification UUID of image in HDD container. * @returns VBox status code. * @returns VERR_VDI_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. * @returns VBox status code. * @returns VERR_VDI_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. LogFlowFunc((
"pDisk=%#p nImage=%u pUuid=%#p {%Vuuid}\n",
* Get parent UUID of image in HDD container. * @returns VBox status code. * @returns VERR_VDI_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 parent image UUID. * Set the image's parent UUID. Should not be used by normal applications. * @returns 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. LogFlowFunc((
"pDisk=%#p nImage=%u pUuid=%#p {%Vuuid}\n",
* Debug helper - dumps all opened images in HDD container into the log file. * @param pDisk Pointer to HDD container. RTLogPrintf(
"--- Dumping VD Disk, Backend=%s, Images=%u\n",