FltCreateCommunicationPort 関数 (fltkernel.h)
FltCreateCommunicationPort は、ミニフィルター ドライバーがユーザー モード アプリケーションからの接続要求を受信できる通信サーバー ポートを作成します。
構文
NTSTATUS FLTAPI FltCreateCommunicationPort(
[in] PFLT_FILTER Filter,
[out] PFLT_PORT *ServerPort,
[in] POBJECT_ATTRIBUTES ObjectAttributes,
[in, optional] PVOID ServerPortCookie,
[in] PFLT_CONNECT_NOTIFY ConnectNotifyCallback,
[in] PFLT_DISCONNECT_NOTIFY DisconnectNotifyCallback,
[in, optional] PFLT_MESSAGE_NOTIFY MessageNotifyCallback,
[in] LONG MaxConnections
);
パラメーター
[in] Filter
呼び出し元の不透明なフィルター ポインター。
[out] ServerPort
通信サーバー ポートの不透明なポート ハンドルを受け取る呼び出し元によって割り当てられた変数へのポインター。 ミニフィルター ドライバーは、このハンドルを使用して、ユーザー モード アプリケーションからの受信接続要求をリッスンします。
[in] ObjectAttributes
通信サーバー ポートの属性を指定する OBJECT_ATTRIBUTES 構造体へのポインター。 この構造体は、 InitializeObjectAttributes の以前の呼び出しによって初期化されている必要があります。 このパラメーターは必須であり、 NULL にすることはできません。 通信ポート オブジェクトのこの構造体のメンバーは、次のとおりです。
| メンバー | 値 |
|---|---|
| ULONG の 長さ |
InitializeObjectAttributes は、 このメンバーを sizeof(OBJECT_ATTRIBUTES) に設定します。 |
| PUNICODE_STRING ObjectName | ポート オブジェクトの一意の名前 (L"\\MyFilterPort"など) を含む UNICODE_STRING 構造体へのポインター。 |
| PSECURITY_DESCRIPTOR SecurityDescriptor | ポート オブジェクトに適用するセキュリティ記述子 (SECURITY_DESCRIPTOR) へのポインター。 必要に応じて、 FltBuildDefaultSecurityDescriptor を呼び出すことによって、既定のセキュリティ記述子を作成できます。 |
| ULONG 属性 | ポート ハンドルに必要な属性を指定するフラグのビットマスク。 これらのフラグには、OBJ_KERNEL_HANDLEを含める必要があります。 呼び出し元は必要に応じて、OBJ_CASE_INSENSITIVE フラグを設定することもできます。これは、名前参照コードが完全一致検索を実行するのではなく 、ObjectName の大文字と小文字を無視する必要があることを示します。 |
[in, optional] ServerPortCookie
ミニフィルター ドライバーによって定義されたコンテキスト情報へのポインター。 この情報を使用して、同じミニフィルター ドライバーによって作成された複数の通信サーバー ポートを区別できます。 フィルター マネージャーは、このコンテキスト ポインターをパラメーターとして ConnectNotifyCallback ルーチンに渡します。 このパラメーターは省略可能であり、 NULL にすることができます。
[in] ConnectNotifyCallback
呼び出し元が指定したコールバック ルーチンへのポインター。 フィルター マネージャーは、ユーザー モード アプリケーションが FilterConnectCommunicationPort を 呼び出してミニフィルター ドライバーに接続要求を送信するたびに、このルーチンを呼び出します。 このパラメーターは必須であり、 NULL にすることはできません。 このルーチンは、IRQL = PASSIVE_LEVELで呼び出されます。
このルーチンは、次のように宣言されています。
typedef NTSTATUS
(*PFLT_CONNECT_NOTIFY) (
IN PFLT_PORT ClientPort,
IN PVOID ServerPortCookie,
IN PVOID ConnectionContext,
IN ULONG SizeOfContext,
OUT PVOID *ConnectionPortCookie
);
ClientPort
ユーザー モード アプリケーションとカーネル モード ミニフィルター ドライバーの間で確立される新しいクライアント ポートの不透明なハンドル。
ミニフィルター ドライバーは、この クライアント ポート でメッセージを送信および返信するときに、このハンドルを ClientPort パラメーターとして FltSendMessage に渡す必要があります。 (これは、FltCreateCommunicationPort によって返される ServerPort ハンドルと同じではないことに注意してください)。
ミニフィルター ドライバーは、最終的にこのクライアント ポートを閉じる必要があります。 クライアント ポートは、通常はミニフィルター ドライバーの DisconnectNotifyCallback ルーチンから FltCloseClientPort を呼び出すことによって閉じられます。
ServerPortCookie
ミニフィルター ドライバーによって定義されたコンテキスト情報へのポインター。 この情報を使用して、同じミニフィルター ドライバーによって作成された複数の通信サーバー ポートを区別できます。 サーバー ポートが作成されると、ミニフィルター ドライバーは、このコンテキスト ポインターを FltCreateCommunicationPort へのパラメーターとして渡しました。
ConnectionContext
ユーザー モード アプリケーションが lpContext パラメーターで FilterConnectCommunicationPort に渡したコンテキスト情報ポインター。
SizeOfContext
ConnectionContext が指すバッファーのサイズ (バイト単位)。
ConnectionPortCookie
このクライアント ポートを一意に識別する情報へのポインター。 この情報は、ミニフィルター ドライバーによって定義されます。 フィルター マネージャーは、ミニフィルター ドライバーの DisconnectNotifyCallback ルーチンと MessageNotifyCallback ルーチンにパラメーターとしてこのコンテキスト ポインター を 渡します。
[in] DisconnectNotifyCallback
クライアント ポートのユーザー モード ハンドル数が 0 に達したとき、またはミニフィルター ドライバーがアンロードされるときに呼び出される呼び出し元から指定されたコールバック ルーチンへのポインター。 このパラメーターは必須であり、 NULL にすることはできません。 このルーチンは、IRQL = PASSIVE_LEVELで呼び出されます。
このルーチンは、次のように宣言されています。
typedef VOID
(*PFLT_DISCONNECT_NOTIFY) (
IN PVOID ConnectionCookie
);
ConnectionCookie
このクライアント ポートを一意に識別する情報へのポインター。 この情報は、ミニフィルター ドライバーによって定義されます。 クライアント ポートが作成されると、ミニフィルター ドライバーは ConnectNotifyCallback ルーチンの ConnectionPortCookie パラメーターでこのコンテキスト ポインターを返しました。
[in, optional] MessageNotifyCallback
呼び出し元が指定したコールバック ルーチンへのポインター。 フィルター マネージャーは、ユーザー モード アプリケーションが FilterSendMessage を呼び出してクライアント ポートを介してミニフィルター ドライバーにメッセージを送信するたびに、IRQL = PASSIVE_LEVELでこのルーチンを呼び出します。 このパラメーターは省略可能であり、 NULL にすることができます。 NULL の場合、ポートにデータを送信するためにユーザー モードから行われた要求は、エラーを受け取ります。
このルーチンは、次のように宣言されています。
typedef NTSTATUS
(*PFLT_MESSAGE_NOTIFY) (
IN PVOID PortCookie,
IN PVOID InputBuffer OPTIONAL,
IN ULONG InputBufferLength,
OUT PVOID OutputBuffer OPTIONAL,
IN ULONG OutputBufferLength,
OUT PULONG ReturnOutputBufferLength
);
PortCookie
このクライアント ポートを一意に識別する情報へのポインター。 この情報は、ミニフィルター ドライバーによって定義されます。 クライアント ポートが作成されると、ミニフィルター ドライバーは ConnectNotifyCallback ルーチンの ConnectionPortCookie パラメーターでこのコンテキスト ポインターを返しました。
InputBuffer
ミニフィルター ドライバーに送信されるメッセージを含む呼び出し元によって割り当てられたバッファーへのポインター。
InputBuffer は、未加工のロック解除されたユーザー モード バッファーへのポインターであることに注意してください。 このポインターは、ユーザー モード プロセスのコンテキストでのみ有効であり、 try/except ブロック内からのみアクセスする必要があります。
フィルター マネージャーは ProbeForRead を呼び出してこのポインターを検証しますが、バッファーが正しく配置されていることを確認しません。 バッファーに配置要件がある構造体が含まれている場合、ミニフィルター ドライバーは必要なアラインメント チェックを実行します。 これを行うには、MiniSpy サンプル ミニフィルター ドライバーに示すように、ミニフィルター ドライバーで IS_ALIGNED マクロを使用できます。
このパラメーターは省略可能であり、 NULL にすることができます。
InputBufferLength
InputBuffer が指すバッファーのサイズ (バイト単位)。 InputBuffer が NULL の場合、このパラメーターは無視されます。
OutputBuffer
ミニフィルター ドライバーから応答 (存在する場合) を受信する呼び出し元によって割り当てられたバッファーへのポインター。
OutputBuffer は、ロックが解除された未加工のユーザー モード バッファーへのポインターであることに注意してください。 このポインターは、ユーザー モード プロセスのコンテキストでのみ有効であり、 try/except ブロック内からのみアクセスする必要があります。
フィルター マネージャーは ProbeForWrite を呼び出してこのポインターを検証しますが、バッファーが正しく配置されていることを確認しません。 バッファーに配置要件がある構造体が含まれている場合、ミニフィルター ドライバーは必要なアラインメント チェックを実行します。 これを行うには、MiniSpy サンプル ミニフィルター ドライバーに示すように、ミニフィルター ドライバーで IS_ALIGNED マクロを使用できます。
このパラメーターは省略可能であり、 NULL にすることができます。
OutputBufferLength
OutputBuffer が指すバッファーのサイズ (バイト単位)。 OutputBuffer が NULL の場合、このパラメーターは無視されます。
ReturnOutputBufferLength
OutputBuffer が指すバッファーで返されるバイト数を受け取る、呼び出し元によって割り当てられた変数へのポインター。
[in] MaxConnections
このサーバー ポートで許可される同時クライアント接続の最大数。 このパラメーターは必須であり、0 より大きくする必要があります。
戻り値
FltCreateCommunicationPort は、次のいずれかのSTATUS_SUCCESSまたは適切な NTSTATUS 値を返します。
| リターン コード | 説明 |
|---|---|
|
指定した フィルター が破棄されています。 これはエラー コードです。 |
|
FltCreateCommunicationPort でプール割り当てエラーが発生しました。 これはエラー コードです。 |
|
同じ名前のミニフィルター ドライバー通信ポートが既に存在します。 ポート名は一意である必要があります。 これはエラー コードです。 |
注釈
ミニフィルター ドライバーは FltCreateCommunicationPort を呼び出して、通信サーバー ポート オブジェクトを作成します。
サーバー ポートが作成されたら、ユーザー モード アプリケーションは FilterConnectCommunicationPort を呼び出してポートに接続できます。 接続すると、ユーザー モード アプリケーションは 、FilterSendMessage、 FilterGetMessage、 FilterReplyMessage などのユーザー モード メッセージング関数を呼び出すことによって、メッセージを送受信できます。
呼び出し元は、FltCreateCommunicationPortの ObjectAttributes パラメーターのOBJ_KERNEL_HANDLE属性フラグを設定する必要があります。 このフラグを設定すると、 FltCreateCommunicationPort の呼び出し元が実行されている可能性があるユーザー モード プロセスでミニフィルター ドライバー通信サーバー ポート ハンドルが使用されなくなります。 このフラグが設定されていない場合、 FltCreateCommunicationPort はSTATUS_INVALID_PARAMETERを返します。
FltCreateCommunicationPort によって作成されたすべてのサーバー ポートは、FltCloseCommunicationPort を呼び出すことによって最終的に閉じる必要があります。 サーバー ポートを閉じると、サーバー ポートへの新しい接続は許可されません。 また、FilterConnectCommunicationPort への呼び出しはすべて失敗します。 ただし、既存の接続は、ユーザー モード アプリケーションまたはミニフィルター ドライバーによって閉じられるまで、またはミニフィルター ドライバーがアンロードされるまで開いたままです。
要件
| 要件 | 値 |
|---|---|
| 対象プラットフォーム | ユニバーサル |
| Header | fltkernel.h (Fltkernel.h を含む) |
| Library | FltMgr.lib |
| [DLL] | Fltmgr.sys |
| IRQL | PASSIVE_LEVEL |
こちらもご覧ください
FilterConnectCommunicationPort
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示