Expand Minimize

FltGetVolumeGuidName routine

The FltGetVolumeGuidName routine returns the volume name for a given volume, in volume globally unique identifier (GUID) format.

Syntax


NTSTATUS FltGetVolumeGuidName(
  _In_       PFLT_VOLUME Volume,
  _Out_      PUNICODE_STRING VolumeGuidName,
  _Out_opt_  PULONG BufferSizeNeeded
);

Parameters

Volume [in]

Opaque pointer for the volume. Must be a local file system volume. This parameter is required and cannot be NULL.

VolumeGuidName [out]

Pointer to a caller-allocated UNICODE_STRING structure that receives the volume's GUID name. This parameter is required and cannot be NULL.

BufferSizeNeeded [out, optional]

Pointer to a caller-allocated variable that receives the size, in bytes, of the requested volume GUID name. If FltGetVolumeGuidName returns STATUS_BUFFER_TOO_SMALL, you can use the value of the variable to determine the required size for the structure that the VolumeGuidName parameter points to. This parameter is optional and can be NULL.

Return value

FltGetVolumeGuidName returns STATUS_SUCCESS or an appropriate NTSTATUS value, such as one of the following:

Return codeDescription
STATUS_BUFFER_TOO_SMALL

The buffer pointed to by the VolumeGuidName parameter is too small to hold the volume GUID. If the caller provides a non-NULL value for the BufferSizeNeeded parameter, this parameter receives the required buffer size. This is an error code.

STATUS_INSUFFICIENT_RESOURCES

FltGetVolumeGuidName encountered a pool allocation failure. This is an error code.

STATUS_INVALID_DEVICE_REQUEST

The Volume parameter is a handle for a network volume. This is an error code.

STATUS_FLT_VOLUME_NOT_FOUND

No matching volume was found. This is an error code.

 

Remarks

The returned volume GUID name is expressed in the following format:

\??\Volume{GUID}

where GUID is a globally unique identifier that identifies the volume.

This format, which is the same as that used by the mount manager, is described in Supporting Mount Manager Requests in a Storage Class Driver.

FltGetVolumeGuidName cannot safely be called from a pre-mount or post-mount callback. It cannot safely be called because even when the post-mount callback is called, the mount processing has not been completed by the I/O manager, and this causes a deadlock with the mount manager in certain cases.

On Windows Vista and later, a minifilter driver can safely call FltGetVolumeGuidName from its InstanceSetupCallback routine (PFLT_INSTANCE_SETUP_CALLBACK) because the callback is called on the first I/O operation for a new volume after all of the mount processing is completed.

On Windows operating systems earlier than Windows Vista, FltGetVolumeGuidName cannot safely be called from an InstanceSetupCallback routine because the mount manager might issue a file I/O operation while holding a lock, which can cause a deadlock.

It is important to note that the volume GUID is not the same as the volume object ID. The volume GUID, or unique volume name, is a file system-independent value; it is assigned to the underlying storage volume by the mount manager. The volume object ID is assigned to the file system volume by the file system.

To get the volume object ID for a volume, call ZwQueryVolumeInformationFile, specifying FileFsObjectIdInformation for the FsInformationClass parameter.

FltGetVolumeGuidName is roughly equivalent to the Win32 GetVolumeNameForVolumeMountPoint function. (GetVolumeNameForVolumeMountPoint is documented in the Microsoft Windows SDK.)

Requirements

Header

Fltkernel.h (include Fltkernel.h)

Library

FltMgr.lib

IRQL

PASSIVE_LEVEL

See also

FILE_FS_OBJECTID_INFORMATION
PFLT_INSTANCE_SETUP_CALLBACK
UNICODE_STRING
ZwQueryVolumeInformationFile

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft