FilterVolumeFindFirst function (fltuser.h)

The FilterVolumeFindFirst function returns information about a volume.

Syntax

HRESULT FilterVolumeFindFirst(
  [in]  FILTER_VOLUME_INFORMATION_CLASS dwInformationClass,
  [out] LPVOID                          lpBuffer,
  [in]  DWORD                           dwBufferSize,
  [out] LPDWORD                         lpBytesReturned,
  [out] PHANDLE                         lpVolumeFind
);

Parameters

[in] dwInformationClass

Type of requested information. This parameter can be one of the following values.

Value	Meaning
FilterVolumeBasicInformation	The buffer pointed to by the lpBuffer parameter receives a FILTER_VOLUME_BASIC_INFORMATION structure for the volume.
FilterVolumeStandardInformation	The buffer pointed to by the lpBuffer parameter receives a FILTER_VOLUME_STANDARD_INFORMATION structure for the volume. This structure is available starting with Windows Vista.

[out] lpBuffer

Pointer to a caller-allocated buffer that receives the requested information. The type of the information returned in the buffer is defined by the dwInformationClass parameter.

[in] dwBufferSize

Size, in bytes, of the buffer that the lpBuffer parameter points to. The caller should set this parameter according to the given dwInformationClass.

[out] lpBytesReturned

Pointer to a caller-allocated variable that receives the number of bytes returned in the buffer that lpBuffer points to if the call to FilterVolumeFindFirst succeeds. This parameter is required and cannot be NULL.

[out] lpVolumeFind

Pointer to a caller-allocated variable that receives a search handle for the minifilter if the call to FilterVolumeFindFirst succeeds; otherwise, it receives INVALID_HANDLE_VALUE. This search handle can be used in subsequent calls to FilterVolumeFindNext and FilterVolumeFindClose.

Return value

FilterVolumeFindFirst returns S_OK if it successfully returns information about a volume. Otherwise, it returns an HRESULT error value, such as one of the following:

Return code	Description
HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER)	The buffer pointed to by lpBuffer is not large enough to contain the requested information. When this value is returned, lpBytesReturned will contain the size, in bytes, of the buffer required for the given dwInformationClass structure.
HRESULT_FROM_WIN32(ERROR_INVALID_PARAMETER)	An invalid value was specified for the dwInformationClass parameter. For example, if FilterVolumeStandardInformation is specified for an operating system prior to Windows Vista, FilterVolumeFindFirst returns this HRESULT value.
HRESULT_FROM_WIN32(ERROR_NO_MORE_ITEMS)	A volume was not found in the list of volumes known to the filter manager.

Remarks

This FilterVolumeFindFirst function is used to begin scanning the volumes that are known to the filter manager.

FilterVolumeFindFirst opens a search handle and returns information about the first volume found in the list of volumes known to the filter manager. After the search handle has been established, use the FilterVolumeFindNext function to search for other volumes in the filter manager's list. When the search handle is no longer required, close it by calling FilterVolumeFindClose.

Note that when using FilterVolumeFindFirst and FilterVolumeFindNext to enumerate the list of volumes known to the filter manager, it is possible for two or more volumes in the list to have the same name. For more information, see Understanding Volume Enumerations with Duplicate Volume Names.

Requirements

Requirement	Value
Target Platform	Universal
Header	fltuser.h (include FltUser.h)
Library	FltLib.lib
DLL	FltLib.dll

See also

FILTER_VOLUME_BASIC_INFORMATION

FILTER_VOLUME_STANDARD_INFORMATION

FilterVolumeFindClose

FilterVolumeFindNext