ホーム › Storage.InstallableFileSystems › FilterFindFirst

FilterFindFirst

関数

登録済みミニフィルターの列挙を開始する。

DLLFLTLIB.dll呼出規約winapi

シグネチャ

// FLTLIB.dll
#include <windows.h>

HRESULT FilterFindFirst(
    FILTER_INFORMATION_CLASS dwInformationClass,
    void* lpBuffer,
    DWORD dwBufferSize,
    DWORD* lpBytesReturned,
    HANDLE* lpFilterFind
);

パラメーター

名前

型

方向

説明

dwInformationClass

FILTER_INFORMATION_CLASS

要求するフィルタードライバー情報の種類。このパラメーターには、次のいずれかの値を指定する必要があります。

値	意味
FilterFullInformation	lpBuffer パラメーターが指すバッファーは、ミニフィルターインスタンスごとに FILTER_FULL_INFORMATION 構造体を受け取ります。レガシーフィルターは無視されます。
FilterAggregateBasicInformation	lpBuffer パラメーターが指すバッファーは、ミニフィルターインスタンスまたはレガシーフィルターごとに FILTER_AGGREGATE_BASIC_INFORMATION 構造体を受け取ります。この dwInformationClass の値は、Windows Server 2003 with SP1 および filter manager rollup を適用した Windows XP with SP2 以降で使用できます。Windows XP with SP2 向けの filter manager rollup パッケージの詳細については、Microsoft サポート技術情報の記事 914882「 The filter manager rollup package for Windows XP SP2」を参照してください。
FilterAggregateStandardInformation	lpBuffer パラメーターが指すバッファーは、ミニフィルターインスタンスまたはレガシーフィルターごとに FILTER_AGGREGATE_STANDARD_INFORMATION 構造体を受け取ります。この dwInformationClass の値は、Windows Vista 以降で使用できます。

lpBuffer

void*

out

要求した情報を受け取る、呼び出し元が割り当てたバッファーへのポインター。バッファーに返される情報の型は、dwInformationClass パラメーターによって決まります。

dwBufferSize

DWORD

lpBuffer パラメーターが指すバッファーのサイズ (バイト単位)。呼び出し元は、指定する dwInformationClass に応じてこのパラメーターを設定してください。

lpBytesReturned

DWORD*

out

FilterFindFirst の呼び出しが成功した場合に、lpBuffer が指すバッファーに返されたバイト数を受け取る、呼び出し元が割り当てた変数へのポインター。このパラメーターは必須であり、NULL にすることはできません。

lpFilterFind

HANDLE*

out

FilterFindFirst の呼び出しが成功した場合にフィルタードライバーの検索ハンドルを受け取る、呼び出し元が割り当てた変数へのポインター。失敗した場合は INVALID_HANDLE_VALUE を受け取ります。この検索ハンドルは、後続の FilterFindNext および FilterFindClose の呼び出しで使用できます。

戻り値の型: HRESULT

公式ドキュメント

FilterFindFirst 関数は、フィルタードライバー (ミニフィルタードライバーインスタンスまたはレガシーフィルタードライバー) に関する情報を返します。この関数は、登録済みフィルターのグローバルリスト内のフィルターの列挙を開始するために使用します。

戻り値

FilterFindFirst は、成功した場合は S_OK を返します。それ以外の場合は、次のような HRESULT エラー値を返します。

戻り値	説明
HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER)	lpBuffer が指すバッファーは、要求された情報を格納するのに十分な大きさではありません。この値が返された場合、lpBytesReturned には、指定した dwInformationClass の構造体に必要なバッファーのサイズ (バイト単位) が格納されます。
HRESULT_FROM_WIN32(ERROR_INVALID_PARAMETER)	dwInformationClass パラメーターに無効な値が指定されました。たとえば、Windows Vista より前のオペレーティングシステムで FilterAggregateStandardInformation を指定した場合、FilterFindFirst はこの HRESULT 値を返します。
HRESULT_FROM_WIN32(ERROR_NO_MORE_ITEMS)	登録済みフィルターのグローバルリスト内にフィルタードライバーが見つかりませんでした。

解説(Remarks)

FilterFindFirst 関数は、検索ハンドルを開き、登録済みフィルターのグローバルリスト内で最初に見つかったフィルタードライバーに関する情報を返します。検索ハンドルを確立した後は、FilterFindNext 関数を呼び出して、グローバルリスト内の他のフィルターを検索します。検索ハンドルが不要になったら、FilterFindClose を呼び出して閉じてください。

Microsoft Windows Server 2003 with SP1 および filter manager rollup を適用した Windows XP with Service Pack 1 (SP1) 以降では、FilterFindFirst と FilterFindNext は、レガシーフィルタードライバーの情報とミニフィルタードライバーインスタンスの情報の両方を提供できます。それ以前のバージョンの Windows では、FilterFindFirst と FilterFindNext はミニフィルターに関する情報しか提供できません (前述の dwInformationClass パラメーターの説明を参照してください)。

FilterFindFirst と FilterFindNext は、ベースファイルシステムから遠い順にフィルタードライバーの情報を返します。ベースファイルシステムから最も遠いフィルターの情報が最初に返されます。2 番目に遠いフィルターの情報が 2 番目に返されます。ベースファイルシステムに最も近いフィルターの情報が最後に返されます。

入力の dwBufferSize が小さすぎる場合、lpFilterFind は INVALID_HANDLE_VALUE を受け取り、lpBytesReturned は要求された情報を格納するのに必要なバイト数を受け取ります。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での呼び出し定義

// FLTLIB.dll
#include <windows.h>

HRESULT FilterFindFirst(
    FILTER_INFORMATION_CLASS dwInformationClass,
    void* lpBuffer,
    DWORD dwBufferSize,
    DWORD* lpBytesReturned,
    HANDLE* lpFilterFind
);

[DllImport("FLTLIB.dll", ExactSpelling = true)]
static extern int FilterFindFirst(
    int dwInformationClass,   // FILTER_INFORMATION_CLASS
    IntPtr lpBuffer,   // void* out
    uint dwBufferSize,   // DWORD
    out uint lpBytesReturned,   // DWORD* out
    IntPtr lpFilterFind   // HANDLE* out
);

<DllImport("FLTLIB.dll", ExactSpelling:=True)>
Public Shared Function FilterFindFirst(
    dwInformationClass As Integer,   ' FILTER_INFORMATION_CLASS
    lpBuffer As IntPtr,   ' void* out
    dwBufferSize As UInteger,   ' DWORD
    <Out> ByRef lpBytesReturned As UInteger,   ' DWORD* out
    lpFilterFind As IntPtr   ' HANDLE* out
) As Integer
End Function

' dwInformationClass : FILTER_INFORMATION_CLASS
' lpBuffer : void* out
' dwBufferSize : DWORD
' lpBytesReturned : DWORD* out
' lpFilterFind : HANDLE* out
Declare PtrSafe Function FilterFindFirst Lib "fltlib" ( _
    ByVal dwInformationClass As Long, _
    ByVal lpBuffer As LongPtr, _
    ByVal dwBufferSize As Long, _
    ByRef lpBytesReturned As Long, _
    ByVal lpFilterFind As LongPtr) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

FilterFindFirst = ctypes.windll.fltlib.FilterFindFirst
FilterFindFirst.restype = ctypes.c_int
FilterFindFirst.argtypes = [
    ctypes.c_int,  # dwInformationClass : FILTER_INFORMATION_CLASS
    ctypes.POINTER(None),  # lpBuffer : void* out
    wintypes.DWORD,  # dwBufferSize : DWORD
    ctypes.POINTER(wintypes.DWORD),  # lpBytesReturned : DWORD* out
    ctypes.c_void_p,  # lpFilterFind : HANDLE* out
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('FLTLIB.dll')
FilterFindFirst = Fiddle::Function.new(
  lib['FilterFindFirst'],
  [
    Fiddle::TYPE_INT,  # dwInformationClass : FILTER_INFORMATION_CLASS
    Fiddle::TYPE_VOIDP,  # lpBuffer : void* out
    -Fiddle::TYPE_INT,  # dwBufferSize : DWORD
    Fiddle::TYPE_VOIDP,  # lpBytesReturned : DWORD* out
    Fiddle::TYPE_VOIDP,  # lpFilterFind : HANDLE* out
  ],
  Fiddle::TYPE_INT)

#[link(name = "fltlib")]
extern "system" {
    fn FilterFindFirst(
        dwInformationClass: i32,  // FILTER_INFORMATION_CLASS
        lpBuffer: *mut (),  // void* out
        dwBufferSize: u32,  // DWORD
        lpBytesReturned: *mut u32,  // DWORD* out
        lpFilterFind: *mut *mut core::ffi::c_void  // HANDLE* out
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("FLTLIB.dll")]
public static extern int FilterFindFirst(int dwInformationClass, IntPtr lpBuffer, uint dwBufferSize, out uint lpBytesReturned, IntPtr lpFilterFind);
"@
$api = Add-Type -MemberDefinition $sig -Name 'FLTLIB_FilterFindFirst' -Namespace Win32 -PassThru
# $api::FilterFindFirst(dwInformationClass, lpBuffer, dwBufferSize, lpBytesReturned, lpFilterFind)

#uselib "FLTLIB.dll"
#func global FilterFindFirst "FilterFindFirst" sptr, sptr, sptr, sptr, sptr
; FilterFindFirst dwInformationClass, lpBuffer, dwBufferSize, varptr(lpBytesReturned), lpFilterFind   ; 戻り値は stat
; dwInformationClass : FILTER_INFORMATION_CLASS -> "sptr"
; lpBuffer : void* out -> "sptr"
; dwBufferSize : DWORD -> "sptr"
; lpBytesReturned : DWORD* out -> "sptr"
; lpFilterFind : HANDLE* out -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "FLTLIB.dll"
#cfunc global FilterFindFirst "FilterFindFirst" int, sptr, int, var, sptr
; res = FilterFindFirst(dwInformationClass, lpBuffer, dwBufferSize, lpBytesReturned, lpFilterFind)
; dwInformationClass : FILTER_INFORMATION_CLASS -> "int"
; lpBuffer : void* out -> "sptr"
; dwBufferSize : DWORD -> "int"
; lpBytesReturned : DWORD* out -> "var"
; lpFilterFind : HANDLE* out -> "sptr"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "FLTLIB.dll"
#cfunc global FilterFindFirst "FilterFindFirst" int, sptr, int, sptr, sptr
; res = FilterFindFirst(dwInformationClass, lpBuffer, dwBufferSize, varptr(lpBytesReturned), lpFilterFind)
; dwInformationClass : FILTER_INFORMATION_CLASS -> "int"
; lpBuffer : void* out -> "sptr"
; dwBufferSize : DWORD -> "int"
; lpBytesReturned : DWORD* out -> "sptr"
; lpFilterFind : HANDLE* out -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。