ホーム › Storage.InstallableFileSystems › FilterFindNext

FilterFindNext

関数

ミニフィルター列挙で次のフィルター情報を取得する。

DLLFLTLIB.dll呼出規約winapi

シグネチャ

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

HRESULT FilterFindNext(
    HANDLE hFilterFind,
    FILTER_INFORMATION_CLASS dwInformationClass,
    void* lpBuffer,
    DWORD dwBufferSize,
    DWORD* lpBytesReturned
);

パラメーター

名前

型

方向

説明

hFilterFind

HANDLE

直前の FilterFindFirst の呼び出しによって返されたフィルター検索ハンドルです。

dwInformationClass

FILTER_INFORMATION_CLASS

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

値	意味
FilterFullInformation	lpBuffer パラメーターが指すバッファーは、各ミニフィルターインスタンスについての FILTER_FULL_INFORMATION 構造体を受け取ります。レガシフィルターは無視されます。
FilterAggregateBasicInformation	lpBuffer パラメーターが指すバッファーは、各ミニフィルターインスタンスまたはレガシフィルターについての FILTER_AGGREGATE_BASIC_INFORMATION 構造体を受け取ります。この dwInformationClass の値は、Microsoft Windows Server 2003 SP1 および Windows XP SP2 (フィルターマネージャーのロールアップ適用) 以降で使用できます。Windows XP SP2 向けのフィルターマネージャーのロールアップパッケージの詳細については、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

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

戻り値の型: HRESULT

公式ドキュメント

FilterFindNext 関数は、FilterFindFirst の呼び出しによって開始されたフィルター検索を続行します。

戻り値

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

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

解説(Remarks)

FilterFindFirst を呼び出してフィルター検索ハンドルを確立した後、FilterFindNext 関数を使用して、登録済みフィルターのグローバルリスト内の残りのフィルターを検索します。

FilterFindNext は、1 回の呼び出しにつき 1 つのフィルタードライバー (ミニフィルタードライバーインスタンスまたはレガシフィルタードライバー) を検索します。

Microsoft Windows Server 2003 SP1 および Microsoft Windows XP SP2 (フィルターマネージャーのロールアップ適用) 以降では、FilterFindFirst と FilterFindNext は、レガシフィルタードライバーの情報とミニフィルタードライバーインスタンスの情報を提供できます。これより前のバージョンの Windows では、FilterFindFirst と FilterFindNext はミニフィルターに関する情報のみを提供できます (前述の dwInformationClass パラメーターの説明を参照してください)。

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

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

各言語での呼び出し定義

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

HRESULT FilterFindNext(
    HANDLE hFilterFind,
    FILTER_INFORMATION_CLASS dwInformationClass,
    void* lpBuffer,
    DWORD dwBufferSize,
    DWORD* lpBytesReturned
);

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

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

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

import ctypes
from ctypes import wintypes

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

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('FLTLIB.dll')
FilterFindNext = Fiddle::Function.new(
  lib['FilterFindNext'],
  [
    Fiddle::TYPE_VOIDP,  # hFilterFind : HANDLE
    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_INT)

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

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

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

出力引数:

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