3.2.4.4.1.23 IVolumeClient::Format (Opnum 26)

  • Article

The Format method formats the specified volume, partition, or logical drive with a file system.

 HRESULT Format(
   [in] LdmObjectId storageId,
   [in] FILE_SYSTEM_INFO fsSpec,
   [in] boolean quickFormat,
   [in] boolean force,
   [in] hyper storageLastKnownState,
   [out] TASK_INFO* tinfo
 );

storageId: Specifies the object identifier of the volume, partition, or logical drive on which the new file system is being created.

fsSpec: A FILE_SYSTEM_INFO structure that specifies details about the file system being created.<84>

quickFormat: Boolean value that indicates whether the file system will be fully formatted.

Value

Meaning

FALSE

0

File system will be fully formatted. Full format requires verifying the accessibility of all sectors on the volume.

TRUE

1

File system will be quickly formatted.

force: Boolean value that indicates whether the file system will be formatted if the volume, partition, or logical drive cannot be locked.

Value

Meaning

FALSE

0

File system will not be formatted unless its underlying storage can be locked.

TRUE

1

File system will be formatted regardless of whether the underlying volume, partition, or logical drive can be locked.

storageLastKnownState: Last known modification sequence number of the volume, partition, or logical drive on which the file system is being created.

tinfo: Pointer to a TASK_INFO structure that the client uses to track the request's progress.

Return Values: The method MUST return 0 or a nonerror HRESULT on success, or an implementation-specific nonzero error code on failure (as specified in [MS-ERREF]; see also section 2.2.1 for HRESULT values predefined by the Disk Management Remote Protocol).

Upon receiving this message, the server MUST validate parameters:

  1. Verify that the volume, partition, or logical drive specified by storageId is in the list of storage objects; and check whether storageLastKnownState matches the LastKnownState field of the object.

  2. Verify that tinfo is not NULL.

If parameter validation fails, the server MUST fail the operation immediately, returning an appropriate error as its response to the client.

Otherwise, the server MUST process the message as follows:

  1. Attempt to start formatting the partition with the file system specified by fsSpec, as specified by the quickFormat parameter and the force parameter.<85>

  2. Fill in the tinfo output parameter.

    TASK_INFO member

    Required for this operation

    TASK_INFO::id

    Required.

    TASK_INFO::storageId

    Not required.

    TASK_INFO::createTime

    Not required.<86>

    TASK_INFO::clientID

    Not required.<87>

    TASK_INFO::percentComplete

    Required for any task that returns REQ_IN_PROGRESS.

    TASK_INFO::status

    Required.

    TASK_INFO::type

    Required if PercentageComplete is being used.

    TASK_INFO::error

    Required.

    TASK_INFO::tflag

    Not required.<88>

  3. Return a response to the client that contains tinfo and the status of the operation.

Note The server MAY decide not to wait for the formatting to complete before returning the response to the client.<89> All rules for handling asynchronous tasks apply here.

If the operation is successful, the server MUST make the following changes to the list of storage objects before returning the response:

  1. Modify the storage object specified by storageId to account for the change of status.

  2. Create a new file system object.

When the formatting is completed, the server MUST make the following change to the list of storage objects.

  • Modify the storage object specified by storageId to account for the change of status.