VBoxHDD-new.h revision d9d5fbda1b8f7a6f7fae555db60d0e636fd03af8
/** 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. /** Device to use for this partition. 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 partition must still /** Offset where the partition data starts in this device. */ /** Offset where the partition data starts in the disk. */ /** Size of the partition. */ /** Size of the partitioning info to prepend. */ /** Offset where the partitioning info starts in the disk. */ /** Pointer to the partitioning info to prepend. */ * 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 partitions array. */ /** Pointer to the partitions 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 internally implies * opening the image as readonly. Images opened with this flag should only be * used for querying information, and nothing else. */ /** Mask of valid flags. */ * Error message callback. * @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. /** Pointer to a FNVDERROR(). */ * VBox HDD Container main structure. /* Forward declaration, VBOXHDD structure is visible only inside VBox HDD module. */ * Allocates and initializes an empty HDD container. * No image files are opened. * @returns VBox status code. * @param pfnError Callback for setting extended error information. * @param pvErrorUser Opaque parameter for pfnError. * @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. * @returns VBox status code. * @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(). * 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. * @returns VBox status code. * @param pDisk Pointer to HDD container. * @param pszBackend Name of the image file backend to use. * @param pszFilename Name of the image file to open. * @param uOpenFlags Image file open mode, see VD_OPEN_FLAGS_* constants. * Creates and opens a new base image file. * @returns VBox status code. * @param pDisk Pointer to HDD container. * @param pszBackend Name of the image file backend to use. * @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. * 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 pszBackend Name of the image file backend to use. * @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. * 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. * 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. * @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 pszBackend Name of the image file backend to use (may be NULL to use the same as the source). * @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. * Closes all opened image files in HDD container. * @returns VBox status code. * @param pDisk Pointer to HDD container. * 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. * 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 writing byte from start of disk. * @param pvBuf Pointer to buffer for writing data. * @param cbWrite Number of bytes to write. * 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 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. * @returns Virtual disk size in bytes. * @returns 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. * @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. * Store virtual disk PCHS geometry of an 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 pPCHSGeometry Where to load PCHS geometry from. Not NULL. * Get virtual disk LCHS geometry of an image 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. * Store virtual disk LCHS geometry of an 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 pLCHSGeometry Where to load LCHS geometry from. Not NULL. * 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. * 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. * 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. * 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 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. * 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. * 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 the 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. * Debug helper - dumps all opened images in HDD container into the log file. * @param pDisk Pointer to HDD container.