FilterInstanceFindFirst function (fltuser.h)
The FilterInstanceFindFirst function returns information about a minifilter driver instance and is used as a starting point for scanning the instances of a minifilter.
Syntax
HRESULT FilterInstanceFindFirst(
[in] LPCWSTR lpFilterName,
[in] INSTANCE_INFORMATION_CLASS dwInformationClass,
[out] LPVOID lpBuffer,
[in] DWORD dwBufferSize,
[out] LPDWORD lpBytesReturned,
[out] LPHANDLE lpFilterInstanceFind
);
Parameters
[in] lpFilterName
Pointer to a null-terminated wide-character string that contains the name of the minifilter driver that owns the instance.
[in] dwInformationClass
The type of instance information structure returned. This parameter must be one of the following values.
| Value | Meaning |
|---|---|
| InstanceBasicInformation | Return an INSTANCE_BASIC_INFORMATION structure for the instance. |
| InstanceFullInformation | Return an INSTANCE_FULL_INFORMATION structure for the instance. |
| InstancePartialInformation | Return an INSTANCE_PARTIAL_INFORMATION structure for the instance. |
| InstanceAggregateStandardInformation | Return an INSTANCE_AGGREGATE_STANDARD_INFORMATION structure for the instance. The LegacyFilter portion of the structure is not utilized. 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 FilterInstanceFindFirst succeeds. This parameter is required and cannot be NULL.
[out] lpFilterInstanceFind
Pointer to a caller-allocated variable that receives a search handle for the minifilter if the call to FilterInstanceFindFirst succeeds; otherwise, it receives INVALID_HANDLE_VALUE. This search handle can be used in subsequent calls to FilterInstanceFindNext and FilterInstanceFindClose.
Return value
FilterInstanceFindFirst returns S_OK if successful. Otherwise, it returns an HRESULT error value, such as one of the following:
| Return code | Description |
|---|---|
|
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. |
|
An invalid value was specified for the dwInformationClass parameter. For example, if InstanceAggregateStandardInformation is specified for operating systems prior to Windows Vista, the function returns this HRESULT value. |
|
The minifilter specified by the lpFilterName parameter does not have an instance on the file system stack. |
Remarks
The FilterInstanceFindFirst function opens a search handle and returns information about an instance for the minifilter named by lpFilterName. After the search handle has been established, call FilterInstanceFindNext to search for other instances of the same minifilter. When the search handle is no longer needed, close it by calling FilterInstanceFindClose.
Requirements
| Requirement | Value |
|---|---|
| Target Platform | Universal |
| Header | fltuser.h (include FltUser.h) |
| Library | FltLib.lib |
| DLL | FltLib.dll |