FltCreateMailslotFile 関数 (fltkernel.h)

[アーティクル]
02/06/2025

ミニフィルタードライバーは、FltCreateMailslotFile 呼び出して、新しいパイプを作成するか、既存の mailslot を開きます。

構文

NTSTATUS FLTAPI FltCreateMailslotFile(
  [in]            PFLT_FILTER               Filter,
  [in, optional]  PFLT_INSTANCE             Instance,
  [out]           PHANDLE                   FileHandle,
  [out, optional] PFILE_OBJECT              *FileObject,
  [in]            ULONG                     DesiredAccess,
  [in]            POBJECT_ATTRIBUTES        ObjectAttributes,
  [out]           PIO_STATUS_BLOCK          IoStatusBlock,
  [in]            ULONG                     CreateOptions,
  [in]            ULONG                     MailslotQuota,
  [in]            ULONG                     MaximumMessageSize,
  [in]            PLARGE_INTEGER            ReadTimeout,
  [in, optional]  PIO_DRIVER_CREATE_CONTEXT DriverContext
);

パラメーター

[in] Filter

呼び出し元の不透明なフィルターポインター。

[in, optional] Instance

作成要求の送信先となるミニフィルタードライバーインスタンスの不透明なインスタンスポインター。インスタンスは、mailslot ファイルシステムのボリュームにアタッチされている必要があります。このパラメーターは省略可能であり、NULL できます。このパラメーターが NULL 場合、要求はボリュームのファイルシステムドライバースタックの上部にあるデバイスオブジェクトに送信されます。 NULL以外の場合、要求は、指定されたインスタンスの下にアタッチされているミニフィルタードライバーインスタンスにのみ送信されます。

[out] FileHandle

FltCreateMailslotFile の呼び出しが成功した場合にファイルハンドル 受け取る呼び出し元によって割り当てられた変数へのポインター。

[out, optional] FileObject

fltCreateMailslotFile の呼び出しが成功した場合にファイルオブジェクトポインター 受け取る呼び出し元によって割り当てられた変数へのポインター。このパラメーターは省略可能であり、NULL できます。

[in] DesiredAccess

呼び出し元がファイルまたはディレクトリに対して必要とするアクセスの種類を指定するフラグのビットマスク。 DesiredAccess フラグ システム定義のセットによって、ファイルオブジェクトに対する次の特定のアクセス権が決まります。

DesiredAccess フラグ	意味
FILE_READ_DATA	名前付き mailslot からデータを読み取ることができます。
FILE_READ_ATTRIBUTES	FileAttributes フラグを読み取ることができます。詳細については、FltCreateFileEx2の FileAttributes パラメーターの有効なフラグ値表を参照してください。
READ_CONTROL	アクセス制御リスト ACL と mailslot に関連付けられている所有権情報を読み取ることができます。
FILE_WRITE_DATA	データは mailslot に書き込むことができます。
FILE_WRITE_ATTRIBUTES	FileAttributes フラグを書き込むことができます。
FILE_APPEND_DATA	データは mailslot に追加できます。
WRITE_DAC	mailslot に関連付けられている DACL 随意アクセス制御リストを記述できます。
WRITE_OWNER	mailslot に関連付けられている所有権情報を書き込むことができます。
ACCESS_SYSTEM_SECURITY	呼び出し元は、mailslot の SACL への書き込みアクセス権を持ちます。
同期	呼び出し元は、返された FileHandle が Signaled 状態に設定されるのを待機することで、I/O 操作の完了を同期できます。このフラグは、CreateOptions FILE_SYNCHRONOUS_IO_ALERT または FILE_SYNCHRONOUS_IO_NONALERT フラグが設定されている場合に設定する必要があります。

または、ディレクトリを表さないファイルオブジェクトに対して、次の汎用 ACCESS_MASK フラグを 1 つ以上指定することもできます。 (STANDARD_RIGHTS_XXX フラグは、システムオブジェクトにセキュリティを適用するために使用される定義済みのシステム値です)。これらの汎用フラグを、前の表の追加フラグと組み合わせることもできます。

DesiredAccess to File の値	DesiredAccess フラグへのマップ
GENERIC_READ	STANDARD_RIGHTS_READ、FILE_READ_DATA、SYNCHRONIZE。
GENERIC_WRITE	STANDARD_RIGHTS_WRITE、FILE_WRITE_DATA、FILE_APPEND_DATA、SYNCHRONIZE。

[in] ObjectAttributes

InitializeObjectAttributesで既に初期化されている不透明な OBJECT_ATTRIBUTES 構造体へのポインター。呼び出し元がシステムプロセスコンテキストで実行されている場合、このパラメーターは NULL できます。それ以外の場合、呼び出し元は、InitializeObjectAttributesへの呼び出しでOBJ_KERNEL_HANDLE属性を設定する必要があります。ファイルオブジェクトのこの構造体のメンバーを次の表に示します。

メンバー	価値
ULONG の長さのをする	ObjectAttributesが指す構造体に含まれるデータのバイト数。この値は、少なくとも `sizeof(OBJECT_ATTRIBUTES)`する必要があります。
PUNICODE_STRING ObjectName	作成または開く mailslot の名前を含む UNICODE_STRING 構造体へのポインター。この名前は、rootDirectory で指定されたディレクトリを基準とするファイルの名前でない限り、完全修飾ファイル指定またはデバイスオブジェクトの名前必要があります。たとえば、"\Device\Mailslot\myslot" や "??\mailslot\myslot" はどちらも有効なファイル仕様である可能性があります。 (注: "??" は、Win32 オブジェクト名前空間の名前として "\DosDevices" を置き換えます。 "\DosDevices" は引き続き機能しますが、"??" はオブジェクトマネージャーによって高速に変換されます。
HANDLE RootDirectory	FltCreateFileEx2の前の呼び出しによって取得ディレクトリへの省略可能なハンドル。この値が NULL 場合、ObjectName メンバーは、ターゲット mailslot への完全パスを含む完全修飾ファイル指定である必要があります。この値が null以外の場合、ObjectName メンバーは、このディレクトリを基準とする mailslot 名を指定します。
PSECURITY_DESCRIPTOR SecurityDescriptor	mailslot に適用する省略可能な SECURITY_DESCRIPTOR。このようなセキュリティ記述子で指定 ACL は、作成時にのみ mailslot に適用されます。 mailslot の作成時に値が null 場合、mailslot に配置される ACL は mailslot ファイルシステムに依存し、クライアントが任意のアクセス権を持つインスタンスを作成できます。
ULONG 属性をする	ファイルオブジェクト属性を制御するフラグのセット。呼び出し元がシステムプロセスコンテキストで実行されている場合、このパラメーターは 0 にすることができます。それ以外の場合、呼び出し元は OBJ_KERNEL_HANDLE フラグを設定する必要があります。呼び出し元は必要に応じて、OBJ_CASE_INSENSITIVE フラグを設定することもできます。これは、完全一致検索を実行するのではなく、名前参照コード ObjectName の大文字と小文字を無視する必要があることを示します。

[out] IoStatusBlock

最終的な完了状態と要求された操作に関する情報を受け取る IO_STATUS_BLOCK 構造体へのポインター。 FltCreateMailslotFile から戻った場合、変数の Information メンバーには、次のいずれかの値が含まれます。

FILE_CREATED
FILE_OPENED

[in] CreateOptions

mailslot を作成または開くときに、次のフラグの互換性のある組み合わせとして適用されるオプション。

フラグ	意味
FILE_WRITE_THROUGH	mailslot にデータを書き込むシステムサービス、ファイルシステム、ドライバーは、要求された書き込み操作が完了したと見なされる前に、実際にデータを mailslot に転送する必要があります。このフラグは、CreateOptions フラグ FILE_NO_INTERMEDIATE_BUFFERINGが設定されている場合に自動的に設定されます。
FILE_SYNCHRONOUS_IO_ALERT	mailslot に対するすべての操作は同期的に実行されます。呼び出し元に代わって待機すると、アラートが早期に終了する可能性があります。また、このフラグにより、I/O システムは mailslot 位置コンテキストを維持します。このフラグを設定する場合は、I/O マネージャーが同期オブジェクトとしてファイルオブジェクトを使用するように、DesiredAccess SYNCHRONIZE フラグも設定する必要があります。
FILE_SYNCHRONOUS_IO_NONALERT	mailslot に対するすべての操作は同期的に実行されます。システムで I/O キューの同期を待機し、完了はアラートの対象になりません。また、このフラグにより、I/O システムはファイル位置コンテキストを維持します。このフラグを設定する場合は、I/O マネージャーが同期オブジェクトとしてファイルオブジェクトを使用するように、DesiredAccess SYNCHRONIZE フラグも設定する必要があります。

[in] MailslotQuota

mailslot への書き込みのバッファーのサイズ (バイト単位)。

[in] MaximumMessageSize

mailslot に書き込むメッセージの最大サイズ (バイト単位)。任意のサイズのメッセージは、値 0 で指定されます。

[in] ReadTimeout

mailslot でメッセージが使用できるようになるまで読み取り操作が待機する時間。既定のタイムアウトは、負の整数として 100 ナノ秒単位で表されます。たとえば、250 ミリ秒は –10*1000*250として指定されます。さらに、次の値には特別な意味があります。

価値	意味
0	メッセージが存在しない場合は直ちに返されます。
-1	メッセージを永久に待機します。

[in, optional] DriverContext

IoInitializeDriverCreateContextによって既に初期化されているIO_DRIVER_CREATE_CONTEXT 構造体への省略可能なポインター。

戻り値

FltCreateMailslotFile 、STATUS_SUCCESSまたは次のいずれかの適切な NTSTATUS 値を返します。

リターンコード	形容
STATUS_FLT_DELETING_OBJECT	Filter または Instance パラメーターで指定されたフィルターまたはインスタンスが取り壊されています。この状態コードは、開いている要求がボリュームマウントポイントを超え、インスタンスパラメーターが nullでない場合に受信できます。これはエラーコードです。
STATUS_OBJECT_PATH_SYNTAX_BAD	ObjectAttributes パラメーターに RootDirectory メンバーが含まれていませんでしたが、OBJECT_ATTRIBUTES構造体の ObjectName メンバーが空の文字列であるか、OBJECT_NAME_PATH_SEPARATOR文字が含まれていませんでした。このエラーコードは、オブジェクトパスの構文が正しく示されていません。

備考

FltCreateMailslotFile 関数を使用すると、ミニフィルタードライバーで mailslot インスタンスを作成または開くことができるようになります。これは、仮想メールスロットを作成する場合や、他のいくつかの mailslot に配布する mailslot グループを作成する場合に便利です。

インスタンス パラメーターは、null するか、mailslot ボリュームにアタッチして以前に設定されています。ボリュームポインターは、FltGetVolumeFromNameにボリューム名として "\Device\Mailslot"渡すことによって取得されます。

作成操作の一部として追加の作成パラメーター (ECP) を指定するには、FltAllocateExtraCreateParameterList ルーチンを使用して、IO_DRIVER_CREATE_CONTEXT 構造体の ExtraCreateParameter メンバーを初期化します。 ECP を使用する場合は、関連付けられているサポートルーチンを使用して、割り当て、初期化、解放する必要があります。 FltCreateMailslotFile 呼び出しから戻ると、ECP リストは変更されず、他の作成操作のために FltCreateMailslotFile 追加の呼び出しに渡すことができます。 ECP リスト構造は自動的に割り当て解除されません。 FltCreateMailslotFile の呼び出し元は、FltFreeExtraCreateParameterList ルーチンを呼び出すことによって、この構造体の割り当てを解除する必要があります。

インスタンス が NULL されていない場合、fltCreateMailslotFile からの作成要求は、指定されたミニフィルタードライバーインスタンスの下に接続されているインスタンスと mailslot ファイルシステムにのみ送信されます。指定されたインスタンスとその上にアタッチされたインスタンスは、作成要求を受け取りません。インスタンスが指定されていない場合、要求はスタックの一番上に送信され、すべてのインスタンスと mailslot ファイルシステムによって受信されます。

必要条件

要件	価値
サポートされる最小クライアント	Windows 8 で使用できます。
ターゲットプラットフォームの	万国
ヘッダー	fltkernel.h (FltKernel.h を含む)
ライブラリ	Fltmgr.lib
IRQL	PASSIVE_LEVEL

次の方法で共有

FltCreateMailslotFile 関数 (fltkernel.h)

構文

パラメーター

戻り値

備考

必要条件

関連項目

フィードバック

その他のリソース