VirtualBox

Changeset 86526 in vbox for trunk/src


Ignore:
Timestamp:
Oct 11, 2020 6:40:21 PM (4 years ago)
Author:
vboxsync
Message:

Storage/VD: Get rid of duplicate doxygen comments for the public API

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/VBox/Storage/VD.cpp

    r86044 r86526  
    50225022}
    50235023
    5024 /**
    5025  * Initializes HDD backends.
    5026  *
    5027  * @returns VBox status code.
    5028  */
     5024
    50295025VBOXDDU_DECL(int) VDInit(void)
    50305026{
    … …  
    50345030}
    50355031
    5036 /**
    5037  * Destroys loaded HDD backends.
    5038  *
    5039  * @returns VBox status code.
    5040  */
     5032
    50415033VBOXDDU_DECL(int) VDShutdown(void)
    50425034{
    … …  
    50445036}
    50455037
    5046 /**
    5047  * Loads a single plugin given by filename.
    5048  *
    5049  * @returns VBox status code.
    5050  * @param   pszFilename     The plugin filename to load.
    5051  */
     5038
    50525039VBOXDDU_DECL(int) VDPluginLoadFromFilename(const char *pszFilename)
    50535040{
    … …  
    50805067}
    50815068
    5082 /**
    5083  * Unloads a single plugin given by filename.
    5084  *
    5085  * @returns VBox status code.
    5086  * @param   pszFilename     The plugin filename to unload.
    5087  */
     5069
    50885070VBOXDDU_DECL(int) VDPluginUnloadFromFilename(const char *pszFilename)
    50895071{
    … …  
    50985080}
    50995081
    5100 /**
    5101  * Unload all plugins from a given path.
    5102  *
    5103  * @returns VBox statuse code.
    5104  * @param   pszPath         The path to unload plugins from.
    5105  */
     5082
    51065083VBOXDDU_DECL(int) VDPluginUnloadFromPath(const char *pszPath)
    51075084{
    … …  
    51165093}
    51175094
    5118 /**
    5119  * Lists all HDD backends and their capabilities in a caller-provided buffer.
    5120  *
    5121  * @returns VBox status code.
    5122  *          VERR_BUFFER_OVERFLOW if not enough space is passed.
    5123  * @param   cEntriesAlloc   Number of list entries available.
    5124  * @param   pEntries        Pointer to array for the entries.
    5125  * @param   pcEntriesUsed   Number of entries returned.
    5126  */
     5095
    51275096VBOXDDU_DECL(int) VDBackendInfo(unsigned cEntriesAlloc, PVDBACKENDINFO pEntries,
    51285097                                unsigned *pcEntriesUsed)
    … …  
    51705139}
    51715140
    5172 /**
    5173  * Lists the capabilities of a backend identified by its name.
    5174  *
    5175  * @returns VBox status code.
    5176  * @param   pszBackend      The backend name.
    5177  * @param   pEntry          Pointer to an entry.
    5178  */
     5141
    51795142VBOXDDU_DECL(int) VDBackendInfoOne(const char *pszBackend, PVDBACKENDINFO pEntry)
    51805143{
    … …  
    52035166}
    52045167
    5205 /**
    5206  * Lists all filters and their capabilities in a caller-provided buffer.
    5207  *
    5208  * @return  VBox status code.
    5209  *          VERR_BUFFER_OVERFLOW if not enough space is passed.
    5210  * @param   cEntriesAlloc   Number of list entries available.
    5211  * @param   pEntries        Pointer to array for the entries.
    5212  * @param   pcEntriesUsed   Number of entries returned.
    5213  */
     5168
    52145169VBOXDDU_DECL(int) VDFilterInfo(unsigned cEntriesAlloc, PVDFILTERINFO pEntries,
    52155170                               unsigned *pcEntriesUsed)
    … …  
    52515206}
    52525207
    5253 /**
    5254  * Lists the capabilities of a filter identified by its name.
    5255  *
    5256  * @return  VBox status code.
    5257  * @param   pszFilter       The filter name (case insensitive).
    5258  * @param   pEntry          Pointer to an entry.
    5259  */
     5208
    52605209VBOXDDU_DECL(int) VDFilterInfoOne(const char *pszFilter, PVDFILTERINFO pEntry)
    52615210{
    … …  
    52825231}
    52835232
    5284 /**
    5285  * Allocates and initializes an empty HDD container.
    5286  * No image files are opened.
    5287  *
    5288  * @returns VBox status code.
    5289  * @param   pVDIfsDisk      Pointer to the per-disk VD interface list.
    5290  * @param   enmType         Type of the image container.
    5291  * @param   ppDisk          Where to store the reference to HDD container.
    5292  */
     5233
    52935234VBOXDDU_DECL(int) VDCreate(PVDINTERFACE pVDIfsDisk, VDTYPE enmType, PVDISK *ppDisk)
    52945235{
    … …  
    53675308}
    53685309
    5369 /**
    5370  * Destroys HDD container.
    5371  * If container has opened image files they will be closed.
    5372  *
    5373  * @returns VBox status code.
    5374  * @param   pDisk           Pointer to HDD container.
    5375  */
     5310
    53765311VBOXDDU_DECL(int) VDDestroy(PVDISK pDisk)
    53775312{
    … …  
    53985333}
    53995334
    5400 /**
    5401  * Try to get the backend name which can use this image.
    5402  *
    5403  * @returns VBox status code.
    5404  *          VINF_SUCCESS if a plugin was found.
    5405  *                       ppszFormat contains the string which can be used as backend name.
    5406  *          VERR_NOT_SUPPORTED if no backend was found.
    5407  * @param   pVDIfsDisk      Pointer to the per-disk VD interface list.
    5408  * @param   pVDIfsImage     Pointer to the per-image VD interface list.
    5409  * @param   pszFilename     Name of the image file for which the backend is queried.
    5410  * @param   enmDesiredType  The desired image type, VDTYPE_INVALID if anything goes.
    5411  * @param   ppszFormat      Receives pointer of the UTF-8 string which contains the format name.
    5412  *                          The returned pointer must be freed using RTStrFree().
    5413  * @param   penmType        Where to store the type of the image.
    5414  */
     5335
    54155336VBOXDDU_DECL(int) VDGetFormat(PVDINTERFACE pVDIfsDisk, PVDINTERFACE pVDIfsImage,
    54165337                              const char *pszFilename, VDTYPE enmDesiredType,
    … …  
    55675488}
    55685489
    5569 /**
    5570  * Opens an image file.
    5571  *
    5572  * The first opened image file in HDD container must have a base image type,
    5573  * others (next opened images) must be a differencing or undo images.
    5574  * Linkage is checked for differencing image to be in consistence with the previously opened image.
    5575  * When another differencing image is opened and the last image was opened in read/write access
    5576  * mode, then the last image is reopened in read-only with deny write sharing mode. This allows
    5577  * other processes to use images in read-only mode too.
    5578  *
    5579  * Note that the image is opened in read-only mode if a read/write open is not possible.
    5580  * Use VDIsReadOnly to check open mode.
    5581  *
    5582  * @returns VBox status code.
    5583  * @param   pDisk           Pointer to HDD container.
    5584  * @param   pszBackend      Name of the image file backend to use.
    5585  * @param   pszFilename     Name of the image file to open.
    5586  * @param   uOpenFlags      Image file open mode, see VD_OPEN_FLAGS_* constants.
    5587  * @param   pVDIfsImage     Pointer to the per-image VD interface list.
    5588  */
     5490
    55895491VBOXDDU_DECL(int) VDOpen(PVDISK pDisk, const char *pszBackend,
    55905492                         const char *pszFilename, unsigned uOpenFlags,
    … …  
    59055807}
    59065808
    5907 /**
    5908  * Opens a cache image.
    5909  *
    5910  * @return  VBox status code.
    5911  * @param   pDisk           Pointer to the HDD container which should use the cache image.
    5912  * @param   pszBackend      Name of the cache file backend to use (case insensitive).
    5913  * @param   pszFilename     Name of the cache image to open.
    5914  * @param   uOpenFlags      Image file open mode, see VD_OPEN_FLAGS_* constants.
    5915  * @param   pVDIfsCache     Pointer to the per-cache VD interface list.
    5916  */
     5809
    59175810VBOXDDU_DECL(int) VDCacheOpen(PVDISK pDisk, const char *pszBackend,
    59185811                              const char *pszFilename, unsigned uOpenFlags,
    … …  
    60875980}
    60885981
     5982
    60895983VBOXDDU_DECL(int) VDFilterAdd(PVDISK pDisk, const char *pszFilter, uint32_t fFlags,
    60905984                              PVDINTERFACE pVDIfsFilter)
    … …  
    61816075}
    61826076
    6183 /**
    6184  * Creates and opens a new base image file.
    6185  *
    6186  * @returns VBox status code.
    6187  * @param   pDisk           Pointer to HDD container.
    6188  * @param   pszBackend      Name of the image file backend to use.
    6189  * @param   pszFilename     Name of the image file to create.
    6190  * @param   cbSize          Image size in bytes.
    6191  * @param   uImageFlags     Flags specifying special image features.
    6192  * @param   pszComment      Pointer to image comment. NULL is ok.
    6193  * @param   pPCHSGeometry   Pointer to physical disk geometry <= (16383,16,63). Not NULL.
    6194  * @param   pLCHSGeometry   Pointer to logical disk geometry <= (x,255,63). Not NULL.
    6195  * @param   pUuid           New UUID of the image. If NULL, a new UUID is created.
    6196  * @param   uOpenFlags      Image file open mode, see VD_OPEN_FLAGS_* constants.
    6197  * @param   pVDIfsImage     Pointer to the per-image VD interface list.
    6198  * @param   pVDIfsOperation Pointer to the per-operation VD interface list.
    6199  */
     6077
    62006078VBOXDDU_DECL(int) VDCreateBase(PVDISK pDisk, const char *pszBackend,
    62016079                               const char *pszFilename, uint64_t cbSize,
    … …  
    64876365}
    64886366
    6489 /**
    6490  * Creates and opens a new differencing image file in HDD container.
    6491  * See comments for VDOpen function about differencing images.
    6492  *
    6493  * @returns VBox status code.
    6494  * @param   pDisk           Pointer to HDD container.
    6495  * @param   pszBackend      Name of the image file backend to use.
    6496  * @param   pszFilename     Name of the differencing image file to create.
    6497  * @param   uImageFlags     Flags specifying special image features.
    6498  * @param   pszComment      Pointer to image comment. NULL is ok.
    6499  * @param   pUuid           New UUID of the image. If NULL, a new UUID is created.
    6500  * @param   pParentUuid     New parent UUID of the image. If NULL, the UUID is queried automatically.
    6501  * @param   uOpenFlags      Image file open mode, see VD_OPEN_FLAGS_* constants.
    6502  * @param   pVDIfsImage     Pointer to the per-image VD interface list.
    6503  * @param   pVDIfsOperation Pointer to the per-operation VD interface list.
    6504  */
     6367
    65056368VBOXDDU_DECL(int) VDCreateDiff(PVDISK pDisk, const char *pszBackend,
    65066369                               const char *pszFilename, unsigned uImageFlags,
    … …  
    67656628
    67666629
    6767 /**
    6768  * Creates and opens new cache image file in HDD container.
    6769  *
    6770  * @return  VBox status code.
    6771  * @param   pDisk           Name of the cache file backend to use (case insensitive).
    6772  * @param   pszFilename     Name of the differencing cache file to create.
    6773  * @param   cbSize          Maximum size of the cache.
    6774  * @param   uImageFlags     Flags specifying special cache features.
    6775  * @param   pszComment      Pointer to image comment. NULL is ok.
    6776  * @param   pUuid           New UUID of the image. If NULL, a new UUID is created.
    6777  * @param   uOpenFlags      Image file open mode, see VD_OPEN_FLAGS_* constants.
    6778  * @param   pVDIfsCache     Pointer to the per-cache VD interface list.
    6779  * @param   pVDIfsOperation Pointer to the per-operation VD interface list.
    6780  */
    67816630VBOXDDU_DECL(int) VDCreateCache(PVDISK pDisk, const char *pszBackend,
    67826631                                const char *pszFilename, uint64_t cbSize,
    … …  
    69816830}
    69826831
    6983 /**
    6984  * Merges two images (not necessarily with direct parent/child relationship).
    6985  * As a side effect the source image and potentially the other images which
    6986  * are also merged to the destination are deleted from both the disk and the
    6987  * images in the HDD container.
    6988  *
    6989  * @returns VBox status code.
    6990  * @returns VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
    6991  * @param   pDisk           Pointer to HDD container.
    6992  * @param   nImageFrom      Name of the image file to merge from.
    6993  * @param   nImageTo        Name of the image file to merge to.
    6994  * @param   pVDIfsOperation Pointer to the per-operation VD interface list.
    6995  */
     6832
    69966833VBOXDDU_DECL(int) VDMerge(PVDISK pDisk, unsigned nImageFrom,
    69976834                          unsigned nImageTo, PVDINTERFACE pVDIfsOperation)
    … …  
    74337270}
    74347271
    7435 /**
    7436  * Copies an image from one HDD container to another - extended version.
    7437  * The copy is opened in the target HDD container.
    7438  * It is possible to convert between different image formats, because the
    7439  * backend for the destination may be different from the source.
    7440  * If both the source and destination reference the same HDD container,
    7441  * then the image is moved (by copying/deleting or renaming) to the new location.
    7442  * The source container is unchanged if the move operation fails, otherwise
    7443  * the image at the new location is opened in the same way as the old one was.
    7444  *
    7445  * @note The read/write accesses across disks are not synchronized, just the
    7446  * accesses to each disk. Once there is a use case which requires a defined
    7447  * read/write behavior in this situation this needs to be extended.
    7448  *
    7449  * @returns VBox status code.
    7450  * @retval  VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
    7451  * @param   pDiskFrom       Pointer to source HDD container.
    7452  * @param   nImage          Image number, counts from 0. 0 is always base image of container.
    7453  * @param   pDiskTo         Pointer to destination HDD container.
    7454  * @param   pszBackend      Name of the image file backend to use (may be NULL to use the same as the source, case insensitive).
    7455  * @param   pszFilename     New name of the image (may be NULL to specify that the
    7456  *                          copy destination is the destination container, or
    7457  *                          if pDiskFrom == pDiskTo, i.e. when moving).
    7458  * @param   fMoveByRename   If true, attempt to perform a move by renaming (if successful the new size is ignored).
    7459  * @param   cbSize          New image size (0 means leave unchanged).
    7460  * @param   nImageFromSame  todo
    7461  * @param   nImageToSame    todo
    7462  * @param   uImageFlags     Flags specifying special destination image features.
    7463  * @param   pDstUuid        New UUID of the destination image. If NULL, a new UUID is created.
    7464  *                          This parameter is used if and only if a true copy is created.
    7465  *                          In all rename/move cases or copy to existing image cases the modification UUIDs are copied over.
    7466  * @param   uOpenFlags      Image file open mode, see VD_OPEN_FLAGS_* constants.
    7467  *                          Only used if the destination image is created.
    7468  * @param   pVDIfsOperation Pointer to the per-operation VD interface list.
    7469  * @param   pDstVDIfsImage  Pointer to the per-image VD interface list, for the
    7470  *                          destination image.
    7471  * @param   pDstVDIfsOperation Pointer to the per-operation VD interface list,
    7472  *                          for the destination operation.
    7473  */
     7272
    74747273VBOXDDU_DECL(int) VDCopyEx(PVDISK pDiskFrom, unsigned nImage, PVDISK pDiskTo,
    74757274                           const char *pszBackend, const char *pszFilename,
    … …  
    77727571}
    77737572
    7774 /**
    7775  * Copies an image from one HDD container to another.
    7776  * The copy is opened in the target HDD container.
    7777  * It is possible to convert between different image formats, because the
    7778  * backend for the destination may be different from the source.
    7779  * If both the source and destination reference the same HDD container,
    7780  * then the image is moved (by copying/deleting or renaming) to the new location.
    7781  * The source container is unchanged if the move operation fails, otherwise
    7782  * the image at the new location is opened in the same way as the old one was.
    7783  *
    7784  * @returns VBox status code.
    7785  * @returns VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
    7786  * @param   pDiskFrom       Pointer to source HDD container.
    7787  * @param   nImage          Image number, counts from 0. 0 is always base image of container.
    7788  * @param   pDiskTo         Pointer to destination HDD container.
    7789  * @param   pszBackend      Name of the image file backend to use.
    7790  * @param   pszFilename     New name of the image (may be NULL if pDiskFrom == pDiskTo).
    7791  * @param   fMoveByRename   If true, attempt to perform a move by renaming (if successful the new size is ignored).
    7792  * @param   cbSize          New image size (0 means leave unchanged).
    7793  * @param   uImageFlags     Flags specifying special destination image features.
    7794  * @param   pDstUuid        New UUID of the destination image. If NULL, a new UUID is created.
    7795  *                          This parameter is used if and only if a true copy is created.
    7796  *                          In all rename/move cases the UUIDs are copied over.
    7797  * @param   uOpenFlags      Image file open mode, see VD_OPEN_FLAGS_* constants.
    7798  *                          Only used if the destination image is created.
    7799  * @param   pVDIfsOperation Pointer to the per-operation VD interface list.
    7800  * @param   pDstVDIfsImage  Pointer to the per-image VD interface list, for the
    7801  *                          destination image.
    7802  * @param   pDstVDIfsOperation Pointer to the per-image VD interface list,
    7803  *                          for the destination image.
    7804  */
     7573
    78057574VBOXDDU_DECL(int) VDCopy(PVDISK pDiskFrom, unsigned nImage, PVDISK pDiskTo,
    78067575                         const char *pszBackend, const char *pszFilename,
    … …  
    78177586}
    78187587
    7819 /**
    7820  * Optimizes the storage consumption of an image. Typically the unused blocks
    7821  * have to be wiped with zeroes to achieve a substantial reduced storage use.
    7822  * Another optimization done is reordering the image blocks, which can provide
    7823  * a significant performance boost, as reads and writes tend to use less random
    7824  * file offsets.
    7825  *
    7826  * @return  VBox status code.
    7827  * @return  VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
    7828  * @return  VERR_VD_IMAGE_READ_ONLY if image is not writable.
    7829  * @return  VERR_NOT_SUPPORTED if this kind of image can be compacted, but
    7830  *                             the code for this isn't implemented yet.
    7831  * @param   pDisk           Pointer to HDD container.
    7832  * @param   nImage          Image number, counts from 0. 0 is always base image of container.
    7833  * @param   pVDIfsOperation Pointer to the per-operation VD interface list.
    7834  */
     7588
    78357589VBOXDDU_DECL(int) VDCompact(PVDISK pDisk, unsigned nImage,
    78367590                            PVDINTERFACE pVDIfsOperation)
    … …  
    79287682}
    79297683
    7930 /**
    7931  * Resizes the given disk image to the given size.
    7932  *
    7933  * @return  VBox status
    7934  * @return  VERR_VD_IMAGE_READ_ONLY if image is not writable.
    7935  * @return  VERR_NOT_SUPPORTED if this kind of image can be compacted, but
    7936  *
    7937  * @param   pDisk           Pointer to the HDD container.
    7938  * @param   cbSize          New size of the image.
    7939  * @param   pPCHSGeometry   Pointer to the new physical disk geometry <= (16383,16,63). Not NULL.
    7940  * @param   pLCHSGeometry   Pointer to the new logical disk geometry <= (x,255,63). Not NULL.
    7941  * @param   pVDIfsOperation Pointer to the per-operation VD interface list.
    7942  */
     7684
    79437685VBOXDDU_DECL(int) VDResize(PVDISK pDisk, uint64_t cbSize,
    79447686                           PCVDGEOMETRY pPCHSGeometry,
    … …  
    82547996}
    82557997
    8256 /**
    8257  * Closes the last opened image file in HDD container.
    8258  * If previous image file was opened in read-only mode (the normal case) and
    8259  * the last opened image is in read-write mode then the previous image will be
    8260  * reopened in read/write mode.
    8261  *
    8262  * @returns VBox status code.
    8263  * @returns VERR_VD_NOT_OPENED if no image is opened in HDD container.
    8264  * @param   pDisk           Pointer to HDD container.
    8265  * @param   fDelete         If true, delete the image from the host disk.
    8266  */
     7998
    82677999VBOXDDU_DECL(int) VDClose(PVDISK pDisk, bool fDelete)
    82688000{
    … …  
    83678099}
    83688100
    8369 /**
    8370  * Closes the currently opened cache image file in HDD container.
    8371  *
    8372  * @return  VBox status code.
    8373  * @return  VERR_VD_NOT_OPENED if no cache is opened in HDD container.
    8374  * @param   pDisk           Pointer to HDD container.
    8375  * @param   fDelete         If true, delete the image from the host disk.
    8376  */
     8101
    83778102VBOXDDU_DECL(int) VDCacheClose(PVDISK pDisk, bool fDelete)
    83788103{
    … …  
    84678192}
    84688193
    8469 /**
    8470  * Closes all opened image files in HDD container.
    8471  *
    8472  * @returns VBox status code.
    8473  * @param   pDisk           Pointer to HDD container.
    8474  */
     8194
    84758195VBOXDDU_DECL(int) VDCloseAll(PVDISK pDisk)
    84768196{
    … …  
    85318251}
    85328252
    8533 /**
    8534  * Removes all filters of the given HDD container.
    8535  *
    8536  * @return  VBox status code.
    8537  * @param   pDisk           Pointer to HDD container.
    8538  */
     8253
    85398254VBOXDDU_DECL(int) VDFilterRemoveAll(PVDISK pDisk)
    85408255{
    … …  
    85818296}
    85828297
    8583 /**
    8584  * Read data from virtual HDD.
    8585  *
    8586  * @returns VBox status code.
    8587  * @retval  VERR_VD_NOT_OPENED if no image is opened in HDD container.
    8588  * @param   pDisk           Pointer to HDD container.
    8589  * @param   uOffset         Offset of first reading byte from start of disk.
    8590  * @param   pvBuf           Pointer to buffer for reading data.
    8591  * @param   cbRead          Number of bytes to read.
    8592  */
     8298
    85938299VBOXDDU_DECL(int) VDRead(PVDISK pDisk, uint64_t uOffset, void *pvBuf,
    85948300                         size_t cbRead)
    … …  
    86498355}
    86508356
    8651 /**
    8652  * Write data to virtual HDD.
    8653  *
    8654  * @returns VBox status code.
    8655  * @retval  VERR_VD_NOT_OPENED if no image is opened in HDD container.
    8656  * @param   pDisk           Pointer to HDD container.
    8657  * @param   uOffset         Offset of the first byte being
    8658  *                          written from start of disk.
    8659  * @param   pvBuf           Pointer to buffer for writing data.
    8660  * @param   cbWrite         Number of bytes to write.
    8661  */
     8357
    86628358VBOXDDU_DECL(int) VDWrite(PVDISK pDisk, uint64_t uOffset, const void *pvBuf,
    86638359                          size_t cbWrite)
    … …  
    87248420}
    87258421
    8726 /**
    8727  * Make sure the on disk representation of a virtual HDD is up to date.
    8728  *
    8729  * @returns VBox status code.
    8730  * @retval  VERR_VD_NOT_OPENED if no image is opened in HDD container.
    8731  * @param   pDisk           Pointer to HDD container.
    8732  */
     8422
    87338423VBOXDDU_DECL(int) VDFlush(PVDISK pDisk)
    87348424{
    … …  
    87798469}
    87808470
    8781 /**
    8782  * Get number of opened images in HDD container.
    8783  *
    8784  * @returns Number of opened images for HDD container. 0 if no images have been opened.
    8785  * @param   pDisk           Pointer to HDD container.
    8786  */
     8471
    87878472VBOXDDU_DECL(unsigned) VDGetCount(PVDISK pDisk)
    87888473{
    … …  
    88158500}
    88168501
    8817 /**
    8818  * Get read/write mode of HDD container.
    8819  *
    8820  * @returns Virtual disk ReadOnly status.
    8821  * @returns true if no image is opened in HDD container.
    8822  * @param   pDisk           Pointer to HDD container.
    8823  */
     8502
    88248503VBOXDDU_DECL(bool) VDIsReadOnly(PVDISK pDisk)
    88258504{
    … …  
    88578536}
    88588537
    8859 /**
    8860  * Get sector size of an image in HDD container.
    8861  *
    8862  * @return  Virtual disk sector size in bytes.
    8863  * @return  0 if image with specified number was not opened.
    8864  * @param   pDisk           Pointer to HDD container.
    8865  * @param   nImage          Image number, counts from 0. 0 is always base image of container.
    8866  */
     8538
    88678539VBOXDDU_DECL(uint32_t) VDGetSectorSize(PVDISK pDisk, unsigned nImage)
    88688540{
    … …  
    89098581}
    89108582
    8911 /**
    8912  * Get total capacity of an image in HDD container.
    8913  *
    8914  * @returns Virtual disk size in bytes.
    8915  * @returns 0 if no image with specified number was not opened.
    8916  * @param   pDisk           Pointer to HDD container.
    8917  * @param   nImage          Image number, counts from 0. 0 is always base image of container.
    8918  */
     8583
    89198584VBOXDDU_DECL(uint64_t) VDGetSize(PVDISK pDisk, unsigned nImage)
    89208585{
    … …  
    89508615}
    89518616
    8952 /**
    8953  * Get total file size of an image in HDD container.
    8954  *
    8955  * @returns Virtual disk size in bytes.
    8956  * @returns 0 if no image is opened in HDD container.
    8957  * @param   pDisk           Pointer to HDD container.
    8958  * @param   nImage          Image number, counts from 0. 0 is always base image of container.
    8959  */
     8617
    89608618VBOXDDU_DECL(uint64_t) VDGetFileSize(PVDISK pDisk, unsigned nImage)
    89618619{
    … …  
    89908648}
    89918649
    8992 /**
    8993  * Get virtual disk PCHS geometry stored in HDD container.
    8994  *
    8995  * @returns VBox status code.
    8996  * @returns VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
    8997  * @returns VERR_VD_GEOMETRY_NOT_SET if no geometry present in the HDD container.
    8998  * @param   pDisk           Pointer to HDD container.
    8999  * @param   nImage          Image number, counts from 0. 0 is always base image of container.
    9000  * @param   pPCHSGeometry   Where to store PCHS geometry. Not NULL.
    9001  */
     8650
    90028651VBOXDDU_DECL(int) VDGetPCHSGeometry(PVDISK pDisk, unsigned nImage,
    90038652                                    PVDGEOMETRY pPCHSGeometry)
    … …  
    90528701}
    90538702
    9054 /**
    9055  * Store virtual disk PCHS geometry in HDD container.
    9056  *
    9057  * Note that in case of unrecoverable error all images in HDD container will be closed.
    9058  *
    9059  * @returns VBox status code.
    9060  * @returns VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
    9061  * @returns VERR_VD_GEOMETRY_NOT_SET if no geometry present in the HDD container.
    9062  * @param   pDisk           Pointer to HDD container.
    9063  * @param   nImage          Image number, counts from 0. 0 is always base image of container.
    9064  * @param   pPCHSGeometry   Where to load PCHS geometry from. Not NULL.
    9065  */
     8703
    90668704VBOXDDU_DECL(int) VDSetPCHSGeometry(PVDISK pDisk, unsigned nImage,
    90678705                                    PCVDGEOMETRY pPCHSGeometry)
    … …  
    91588796}
    91598797
    9160 /**
    9161  * Get virtual disk LCHS geometry stored in HDD container.
    9162  *
    9163  * @returns VBox status code.
    9164  * @returns VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
    9165  * @returns VERR_VD_GEOMETRY_NOT_SET if no geometry present in the HDD container.
    9166  * @param   pDisk           Pointer to HDD container.
    9167  * @param   nImage          Image number, counts from 0. 0 is always base image of container.
    9168  * @param   pLCHSGeometry   Where to store LCHS geometry. Not NULL.
    9169  */
     8798
    91708799VBOXDDU_DECL(int) VDGetLCHSGeometry(PVDISK pDisk, unsigned nImage,
    91718800                                    PVDGEOMETRY pLCHSGeometry)
    … …  
    92208849}
    92218850
    9222 /**
    9223  * Store virtual disk LCHS geometry in HDD container.
    9224  *
    9225  * Note that in case of unrecoverable error all images in HDD container will be closed.
    9226  *
    9227  * @returns VBox status code.
    9228  * @returns VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
    9229  * @returns VERR_VD_GEOMETRY_NOT_SET if no geometry present in the HDD container.
    9230  * @param   pDisk           Pointer to HDD container.
    9231  * @param   nImage          Image number, counts from 0. 0 is always base image of container.
    9232  * @param   pLCHSGeometry   Where to load LCHS geometry from. Not NULL.
    9233  */
     8851
    92348852VBOXDDU_DECL(int) VDSetLCHSGeometry(PVDISK pDisk, unsigned nImage,
    92358853                                    PCVDGEOMETRY pLCHSGeometry)
    … …  
    93268944}
    93278945
    9328 /**
    9329  * Queries the available regions of an image in the given VD container.
    9330  *
    9331  * @return  VBox status code.
    9332  * @retval  VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
    9333  * @retval  VERR_NOT_SUPPORTED if the image backend doesn't support region lists.
    9334  * @param   pDisk           Pointer to HDD container.
    9335  * @param   nImage          Image number, counts from 0. 0 is always base image of container.
    9336  * @param   fFlags          Combination of VD_REGION_LIST_F_* flags.
    9337  * @param   ppRegionList    Where to store the pointer to the region list on success, must be freed
    9338  *                          with VDRegionListFree().
    9339  */
     8946
    93408947VBOXDDU_DECL(int) VDQueryRegions(PVDISK pDisk, unsigned nImage, uint32_t fFlags,
    93418948                                 PPVDREGIONLIST ppRegionList)
    … …  
    93868993}
    93878994
    9388 /**
    9389  * Frees a region list previously queried with VDQueryRegions().
    9390  *
    9391  * @return  nothing.
    9392  * @param   pRegionList     The region list to free.
    9393  */
     8995
    93948996VBOXDDU_DECL(void) VDRegionListFree(PVDREGIONLIST pRegionList)
    93958997{
    … …  
    93978999}
    93989000
    9399 /**
    9400  * Get version of image in HDD container.
    9401  *
    9402  * @returns VBox status code.
    9403  * @returns VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
    9404  * @param   pDisk           Pointer to HDD container.
    9405  * @param   nImage          Image number, counts from 0. 0 is always base image of container.
    9406  * @param   puVersion       Where to store the image version.
    9407  */
     9001
    94089002VBOXDDU_DECL(int) VDGetVersion(PVDISK pDisk, unsigned nImage,
    94099003                               unsigned *puVersion)
    … …  
    94469040}
    94479041
    9448 /**
    9449  * List the capabilities of image backend in HDD container.
    9450  *
    9451  * @returns VBox status code.
    9452  * @retval  VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
    9453  * @param   pDisk           Pointer to the HDD container.
    9454  * @param   nImage          Image number, counts from 0. 0 is always base image of container.
    9455  * @param   pBackendInfo    Where to store the backend information.
    9456  */
     9042
    94579043VBOXDDU_DECL(int) VDBackendInfoSingle(PVDISK pDisk, unsigned nImage,
    94589044                                      PVDBACKENDINFO pBackendInfo)
    … …  
    94989084}
    94999085
    9500 /**
    9501  * Get flags of image in HDD container.
    9502  *
    9503  * @returns VBox status code.
    9504  * @returns VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
    9505  * @param   pDisk           Pointer to HDD container.
    9506  * @param   nImage          Image number, counts from 0. 0 is always base image of container.
    9507  * @param   puImageFlags    Where to store the image flags.
    9508  */
     9086
    95099087VBOXDDU_DECL(int) VDGetImageFlags(PVDISK pDisk, unsigned nImage,
    95109088                                  unsigned *puImageFlags)
    … …  
    95479125}
    95489126
    9549 /**
    9550  * Get open flags of image in HDD container.
    9551  *
    9552  * @returns VBox status code.
    9553  * @returns VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
    9554  * @param   pDisk           Pointer to HDD container.
    9555  * @param   nImage          Image number, counts from 0. 0 is always base image of container.
    9556  * @param   puOpenFlags     Where to store the image open flags.
    9557  */
     9127
    95589128VBOXDDU_DECL(int) VDGetOpenFlags(PVDISK pDisk, unsigned nImage,
    95599129                                 unsigned *puOpenFlags)
    … …  
    95969166}
    95979167
    9598 /**
    9599  * Set open flags of image in HDD container.
    9600  * This operation may cause file locking changes and/or files being reopened.
    9601  * Note that in case of unrecoverable error all images in HDD container will be closed.
    9602  *
    9603  * @returns VBox status code.
    9604  * @returns VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
    9605  * @param   pDisk           Pointer to HDD container.
    9606  * @param   nImage          Image number, counts from 0. 0 is always base image of container.
    9607  * @param   uOpenFlags      Image file open mode, see VD_OPEN_FLAGS_* constants.
    9608  */
     9168
    96099169VBOXDDU_DECL(int) VDSetOpenFlags(PVDISK pDisk, unsigned nImage,
    96109170                                 unsigned uOpenFlags)
    … …  
    96549214}
    96559215
    9656 /**
    9657  * Get base filename of image in HDD container. Some image formats use
    9658  * other filenames as well, so don't use this for anything but informational
    9659  * purposes.
    9660  *
    9661  * @returns VBox status code.
    9662  * @returns VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
    9663  * @returns VERR_BUFFER_OVERFLOW if pszFilename buffer too small to hold filename.
    9664  * @param   pDisk           Pointer to HDD container.
    9665  * @param   nImage          Image number, counts from 0. 0 is always base image of container.
    9666  * @param   pszFilename     Where to store the image file name.
    9667  * @param   cbFilename      Size of buffer pszFilename points to.
    9668  */
     9216
    96699217VBOXDDU_DECL(int) VDGetFilename(PVDISK pDisk, unsigned nImage,
    96709218                                char *pszFilename, unsigned cbFilename)
    … …  
    97219269}
    97229270
    9723 /**
    9724  * Get the comment line of image in HDD container.
    9725  *
    9726  * @returns VBox status code.
    9727  * @returns VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
    9728  * @returns VERR_BUFFER_OVERFLOW if pszComment buffer too small to hold comment text.
    9729  * @param   pDisk           Pointer to HDD container.
    9730  * @param   nImage          Image number, counts from 0. 0 is always base image of container.
    9731  * @param   pszComment      Where to store the comment string of image. NULL is ok.
    9732  * @param   cbComment       The size of pszComment buffer. 0 is ok.
    9733  */
     9271
    97349272VBOXDDU_DECL(int) VDGetComment(PVDISK pDisk, unsigned nImage,
    97359273                               char *pszComment, unsigned cbComment)
    … …  
    97769314}
    97779315
    9778 /**
    9779  * Changes the comment line of image in HDD container.
    9780  *
    9781  * @returns VBox status code.
    9782  * @returns VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
    9783  * @param   pDisk           Pointer to HDD container.
    9784  * @param   nImage          Image number, counts from 0. 0 is always base image of container.
    9785  * @param   pszComment      New comment string (UTF-8). NULL is allowed to reset the comment.
    9786  */
     9316
    97879317VBOXDDU_DECL(int) VDSetComment(PVDISK pDisk, unsigned nImage,
    97889318                               const char *pszComment)
    … …  
    98269356
    98279357
    9828 /**
    9829  * Get UUID of image in HDD container.
    9830  *
    9831  * @returns VBox status code.
    9832  * @returns VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
    9833  * @param   pDisk           Pointer to HDD container.
    9834  * @param   nImage          Image number, counts from 0. 0 is always base image of container.
    9835  * @param   pUuid           Where to store the image creation UUID.
    9836  */
    98379358VBOXDDU_DECL(int) VDGetUuid(PVDISK pDisk, unsigned nImage, PRTUUID pUuid)
    98389359{
    … …  
    98739394}
    98749395
    9875 /**
    9876  * Set the image's UUID. Should not be used by normal applications.
    9877  *
    9878  * @returns VBox status code.
    9879  * @returns VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
    9880  * @param   pDisk           Pointer to HDD container.
    9881  * @param   nImage          Image number, counts from 0. 0 is always base image of container.
    9882  * @param   pUuid           New UUID of the image. If NULL, a new UUID is created.
    9883  */
     9396
    98849397VBOXDDU_DECL(int) VDSetUuid(PVDISK pDisk, unsigned nImage, PCRTUUID pUuid)
    98859398{
    … …  
    99269439}
    99279440
    9928 /**
    9929  * Get last modification UUID of image in HDD container.
    9930  *
    9931  * @returns VBox status code.
    9932  * @returns VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
    9933  * @param   pDisk           Pointer to HDD container.
    9934  * @param   nImage          Image number, counts from 0. 0 is always base image of container.
    9935  * @param   pUuid           Where to store the image modification UUID.
    9936  */
     9441
    99379442VBOXDDU_DECL(int) VDGetModificationUuid(PVDISK pDisk, unsigned nImage, PRTUUID pUuid)
    99389443{
    … …  
    99749479}
    99759480
    9976 /**
    9977  * Set the image's last modification UUID. Should not be used by normal applications.
    9978  *
    9979  * @returns VBox status code.
    9980  * @returns VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
    9981  * @param   pDisk           Pointer to HDD container.
    9982  * @param   nImage          Image number, counts from 0. 0 is always base image of container.
    9983  * @param   pUuid           New modification UUID of the image. If NULL, a new UUID is created.
    9984  */
     9481
    99859482VBOXDDU_DECL(int) VDSetModificationUuid(PVDISK pDisk, unsigned nImage, PCRTUUID pUuid)
    99869483{
    … …  
    100299526}
    100309527
    10031 /**
    10032  * Get parent UUID of image in HDD container.
    10033  *
    10034  * @returns VBox status code.
    10035  * @returns VERR_VD_IMAGE_NOT_FOUND if image with specified number was not opened.
    10036  * @param   pDisk           Pointer to HDD container.
    10037  * @param   nImage          Image number, counts from 0. 0 is always base image of container.
    10038  * @param   pUuid           Where to store the parent image UUID.
    10039  */
     9528
    100409529VBOXDDU_DECL(int) VDGetParentUuid(PVDISK pDisk, unsigned nImage,
    100419530                                  PRTUUID pUuid)
    … …  
    100779566}
    100789567
    10079 /**
    10080  * Set the image's parent UUID. Should not be used by normal applications.
    10081  *
    10082  * @returns VBox status code.
    10083  * @param   pDisk           Pointer to HDD container.
    10084  * @param   nImage          Image number, counts from 0. 0 is always base image of container.
    10085  * @param   pUuid           New parent UUID of the image. If NULL, a new UUID is created.
    10086  */
     9568
    100879569VBOXDDU_DECL(int) VDSetParentUuid(PVDISK pDisk, unsigned nImage,
    100889570                                  PCRTUUID pUuid)
    … …  
    101329614
    101339615
    10134 /**
    10135  * Debug helper - dumps all opened images in HDD container into the log file.
    10136  *
    10137  * @param   pDisk           Pointer to HDD container.
    10138  */
    101399616VBOXDDU_DECL(void) VDDumpImages(PVDISK pDisk)
    101409617{
Note: See TracChangeset for help on using the changeset viewer.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette