Expand Minimize

FltGetVolumeName routine

The FltGetVolumeName routine gets the volume name for a given volume.

Syntax


NTSTATUS FltGetVolumeName(
  _In_         PFLT_VOLUME Volume,
  _Inout_opt_  PUNICODE_STRING VolumeName,
  _Out_opt_    PULONG BufferSizeNeeded
);

Parameters

Volume [in]

An opaque pointer for the volume.

VolumeName [in, out, optional]

A pointer to a caller-allocated UNICODE_STRING structure that contains the volume's non-persistent device object name (for example, "\Device\HarddiskVolume1") when STATUS_SUCCESS is returned. Be aware that pool for the Buffer member of this structure is caller-allocated also. This parameter is optional and can be NULL. However, VolumeName must be non-NULL if BufferSizeNeeded is NULL.

BufferSizeNeeded [out, optional]

A pointer to a caller-allocated variable that receives the size, in bytes, of the requested volume name. If FltGetVolumeName returns STATUS_BUFFER_TOO_SMALL, BufferSizeNeeded receives the size of the buffer (pointed to by the Buffer member of the UNICODE_STRING structure) that is required for this routine to succeed.

BufferSizeNeeded is optional and can be NULL. However, BufferSizeNeeded must be non-NULL if VolumeName is NULL.

Return value

FltGetVolumeName returns one of the following NTSTATUS values:

Return codeDescription
STATUS_SUCCESS

The UNICODE_STRING structure, pointed to by VolumeName, contains the name of the volume in the Buffer member for the structure and the length of the name, in bytes, in the Length member.

STATUS_BUFFER_TOO_SMALL

The Buffer member of the UNICODE_STRING structure, pointed to by VolumeName, is too small (as indicated by its MaximumLength member) to contain the entire volume name. This is an error code.

STATUS_INVALID_PARAMETER

VolumeName and BufferSizeNeeded are both NULL. This is an error code.

 

Remarks

For this routine to succeed, the Buffer member of the UNICODE_STRING structure (pointed to by VolumeName) must be large enough, as indicated by its MaximumLength member, to contain the entire volume name string. The following pseudocode shows one possible method to successfully acquire a volume name:

  1. Call FltGetVolumeName to determine the required pool for Buffer and the required size for MaximumLength. For example:
    
    FltGetVolumeName(VolumePtr, NULL, &VolumeNameSize);
    
    
  2. Allocate VolumeNameSize bytes of pool for Buffer and set MaximumLength to VolumeNameSize.

  3. Call FltGetVolumeName again to acquire the volume name. For example:
    
    FltGetVolumeName(VolumePtr, &VolumeNameStruct, NULL);
    
    

    VolumeNameStruct.Buffer contains the Unicode volume name string, which is VolumeNameStruct.Length bytes in length.

To get the volume GUID name for a given volume, call FltGetVolumeGuidName.

To get an opaque volume pointer for a volume with a given name, call FltGetVolumeFromName.

For more information about how to name a volume, see Supporting Mount Manager Requests in a Storage Class Driver.

Requirements

Header

Fltkernel.h (include FltKernel.h)

Library

FltMgr.lib

IRQL

<= APC_LEVEL

See also

FilterGetDosName
FltGetVolumeFromName
FltGetVolumeGuidName
UNICODE_STRING

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft