Changeset 85877 in vbox for trunk/include

Timestamp:

Aug 24, 2020 5:03:23 PM (4 years ago)

Author:

vboxsync

Message:

Main: bugref:9224: DVM API changes

Location:

trunk/include/iprt

Files:

• dvm.h (modified) (3 diffs)
• mangling.h (modified) (1 diff)

trunk/include/iprt/dvm.h

@@ -241 +241 @@
 
 /**
+ * Gets the UUID of the disk if applicable.
+ *
+ * Disks using the MBR format may return the 32-bit disk identity in the
+ * u32TimeLow field and set the rest to zero.
+ *
+ * @returns IPRT status code.
+ * @retval  VERR_NOT_SUPPORTED if the partition scheme doesn't do UUIDs.
+ * @retval  VINF_NOT_SUPPORTED if non-UUID disk ID is returned.
+ * @param   hVolMgr     The volume manager handle.
+ * @param   pUuid       Where to return the UUID.
+ *
+ * @todo It's quite possible this should be turned into a map-level edition of
+ *       RTDvmVolumeQueryProp...
+ */
+RTDECL(int) RTDvmMapQueryDiskUuid(RTDVM hVolMgr, PRTUUID pUuid);
+
+/**
  * Gets the number of valid partitions in the map.
  *
@@ -355 +372 @@
 
 /**
- * Queries the range of the given volume on the underyling medium.
+ * Queries the range of the given volume on the underlying medium.
  *
  * @returns IPRT status code.
@@ -361 +378 @@
  * @param   hVol            The volume handle.
  * @param   poffStart       Where to store the start offset in bytes on the underlying medium.
- * @param   poffEnd         Where to store the end offset in bytes on the underlying medium (inclusive).
- */
-RTDECL(int) RTDvmVolumeQueryRange(RTDVMVOLUME hVol, uint64_t *poffStart, uint64_t *poffEnd);
+ * @param   poffLast        Where to store the last offset in bytes on the underlying medium (inclusive).
+ */
+RTDECL(int) RTDvmVolumeQueryRange(RTDVMVOLUME hVol, uint64_t *poffStart, uint64_t *poffLast);
+
+/**
+ * Returns the partition/whatever table location of the volume.
+ *
+ * For volume format with a single table, like GPT and BSD-labels, it will
+ * return the location of that table.  Though for GPT, the fake MBR will not be
+ * included.
+ *
+ * For logical (extended) MBR-style volumes, this will return the location of
+ * the extended partition table.  For primary volumes the MBR location is
+ * returned.  The special MBR case is why this operation is done on the volume
+ * rather than the volume manager.
+ *
+ * Using RTDvmVolumeGetIndex with RTDVMVOLIDX_IN_PART_TABLE should get you
+ * the index in the table returned by this function.
+ *
+ * @returns IPRT status code.
+ * @param   hVol            The volume handle.
+ * @param   poffTable       Where to return the byte offset on the underlying
+ *                          media of the (partition/volume/whatever) table.
+ * @param   pcbTable        Where to return the table size in bytes.  (This does
+ *                          not include any alignment padding or such, just
+ *                          padding up to sector/block size.)
+ */
+RTDECL(int) RTDvmVolumeQueryTableLocation(RTDVMVOLUME hVol, uint64_t *poffTable, uint64_t *pcbTable);
+
+/**
+ * RTDvmVolumeGetIndex indexes.
+ */
+typedef enum RTDVMVOLIDX
+{
+    /** Invalid zero value. */
+    RTDVMVOLIDX_INVALID = 0,
+    /** Only consider user visible ones, i.e. don't count MBR extended partition
+     *  entries and such like. */
+    RTDVMVOLIDX_USER_VISIBLE,
+    /** Index when all volumes, user visible, hidden, special, whatever ones are
+     * included.
+     *
+     * For MBR this is 1-based index where all primary entires are included whether
+     * in use or not.  Only non-empty entries in extended tables are counted, though
+     * the forward link is included. */
+    RTDVMVOLIDX_ALL,
+    /** The raw index within the partition/volume/whatever table.  This have a kind
+     *  of special meaning to MBR, where there are multiple tables. */
+    RTDVMVOLIDX_IN_TABLE,
+    /** Follows the linux /dev/sdaX convention as closely as absolutely possible. */
+    RTDVMVOLIDX_LINUX,
+    /** End of valid indexes. */
+    RTDVMVOLIDX_END,
+    /** Make sure the type is 32-bit.   */
+    RTDVMVOLIDX_32BIT_HACK = 0x7fffffff
+} RTDVMVOLIDX;
+
+/**
+ * Gets the tiven index for the specified volume.
+ *
+ * @returns The requested index, UINT32_MAX on failure.
+ * @param   hVol            The volume handle.
+ * @param   enmIndex        Which kind of index to get for the volume.
+ */
+RTDECL(uint32_t) RTDvmVolumeGetIndex(RTDVMVOLUME hVol, RTDVMVOLIDX enmIndex);
+
+/**
+ * Volume properties queriable via RTDvmVolumeQueryProp.
+ *
+ * @note Integer values can typically be queried in multiple sizes.  This is
+ *       handled by the frontend code.  The format specific backends only
+ *       have to handle the smallest allowed size.
+ */
+typedef enum RTDVMVOLPROP
+{
+    /** Customary invalid zero value. */
+    RTDVMVOLPROP_INVALID = 0,
+    /** unsigned[16,32,64]:     MBR first cylinder (0-based, CHS). */
+    RTDVMVOLPROP_MBR_FIRST_CYLINDER,
+    /** unsigned[8,16,32,64]:   MBR first head (0-based, CHS). */
+    RTDVMVOLPROP_MBR_FIRST_HEAD,
+    /** unsigned[8,16,32,64]:   MBR first sector (1-based, CHS). */
+    RTDVMVOLPROP_MBR_FIRST_SECTOR,
+    /** unsigned[16,32,64]:     MBR last cylinder (0-based, CHS). */
+    RTDVMVOLPROP_MBR_LAST_CYLINDER,
+    /** unsigned[8,16,32,64]:   MBR last head (0-based, CHS). */
+    RTDVMVOLPROP_MBR_LAST_HEAD,
+    /** unsigned[8,16,32,64]:   MBR last sector (1-based, CHS). */
+    RTDVMVOLPROP_MBR_LAST_SECTOR,
+    /** unsigned[8,16,32,64]:   MBR partition type. */
+    RTDVMVOLPROP_MBR_TYPE,
+    /** RTUUID:                 GPT volume type. */
+    RTDVMVOLPROP_GPT_TYPE,
+    /** RTUUID:                 GPT volume UUID. */
+    RTDVMVOLPROP_GPT_UUID,
+    /** End of valid values. */
+    RTDVMVOLPROP_END,
+    /** Make sure the type is 32-bit. */
+    RTDVMVOLPROP_32BIT_HACK = 0x7fffffff
+} RTDVMVOLPROP;
+
+/**
+ * Query a generic volume property.
+ *
+ * This is an extensible interface for retriving mostly format specific
+ * information, or information that's not commonly used.  (It's modelled after
+ * RTLdrQueryPropEx.)
+ *
+ * @returns IPRT status code.
+ * @retval  VERR_NOT_SUPPORTED if the property query isn't supported (either all
+ *          or that specific property).  The caller  must  handle this result.
+ * @retval  VERR_NOT_FOUND is currently not returned, but intended for cases
+ *          where it wasn't present in the tables.
+ * @retval  VERR_INVALID_FUNCTION if the @a enmProperty value is wrong.
+ * @retval  VERR_INVALID_PARAMETER if the fixed buffer size is wrong. Correct
+ *          size in @a *pcbRet.
+ * @retval  VERR_BUFFER_OVERFLOW if the property doesn't have a fixed size
+ *          buffer and the buffer isn't big enough. Correct size in @a *pcbRet.
+ * @retval  VERR_INVALID_HANDLE if the handle is invalid.
+ * @param   hVol        Handle to the volume.
+ * @param   enmProperty The property to query.
+ * @param   pvBuf       Pointer to the input / output buffer.  In most cases
+ *                      it's only used for returning data.
+ * @param   cbBuf       The size of the buffer.
+ * @param   pcbRet      Where to return the amount of data returned.  On
+ *                      buffer size errors, this is set to the correct size.
+ *                      Optional.
+ * @sa      RTDvmVolumeGetPropU64
+ */
+RTDECL(int) RTDvmVolumeQueryProp(RTDVMVOLUME hVol, RTDVMVOLPROP enmProperty, void *pvBuf, size_t cbBuf, size_t *pcbBuf);
+
+/**
+ * Wrapper around RTDvmVolumeQueryProp for simplifying getting unimportant
+ * integer properties.
+ *
+ * @returns The property value if supported and found, the default value if not.
+ *          Errors other than VERR_NOT_SUPPORTED and VERR_NOT_FOUND are
+ *          asserted.
+ * @param   hVol        Handle to the volume.
+ * @param   enmProperty The property to query.
+ * @param   uDefault    The value to return on error.
+ * @sa      RTDvmVolumeQueryProp
+ */
+RTDECL(uint64_t) RTDvmVolumeGetPropU64(RTDVMVOLUME hVol, RTDVMVOLPROP enmProperty, uint64_t uDefault);
 
 /**

trunk/include/iprt/mangling.h

@@ -833 +833 @@
 # define RTDvmMapQueryFirstVolume                       RT_MANGLER(RTDvmMapQueryFirstVolume)
 # define RTDvmMapQueryNextVolume                        RT_MANGLER(RTDvmMapQueryNextVolume)
+# define RTDvmMapQueryDiskUuid                          RT_MANGLER(RTDvmMapQueryDiskUuid)
 # define RTDvmVolumeRetain                              RT_MANGLER(RTDvmVolumeRetain)
 # define RTDvmVolumeRelease                             RT_MANGLER(RTDvmVolumeRelease)
+# define RTDvmVolumeGetIndex                            RT_MANGLER(RTDvmVolumeGetIndex)
+# define RTDvmVolumeGetPropU64                          RT_MANGLER(RTDvmVolumeGetPropU64)
 # define RTDvmVolumeGetSize                             RT_MANGLER(RTDvmVolumeGetSize)
 # define RTDvmVolumeQueryName                           RT_MANGLER(RTDvmVolumeQueryName)
+# define RTDvmVolumeQueryProp                           RT_MANGLER(RTDvmVolumeQueryProp)
+# define RTDvmVolumeQueryTableLocation                  RT_MANGLER(RTDvmVolumeQueryTableLocation)
 # define RTDvmVolumeGetType                             RT_MANGLER(RTDvmVolumeGetType)
 # define RTDvmVolumeGetFlags                            RT_MANGLER(RTDvmVolumeGetFlags)