FltCreateMailslotFile 関数 (fltkernel.h)
ミニフィルター ドライバーは 、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 | mailslot に関連付けられているアクセス制御リスト ACL と所有権情報を読み取ることができます。 |
| FILE_WRITE_DATA | データは mailslot に書き込むことができます。 |
| FILE_WRITE_ATTRIBUTES | FileAttributes フラグを 書き込むことができます。 |
| FILE_APPEND_DATA | データは mailslot に追加できます。 |
| WRITE_DAC | mailslot に関連付けられている随意アクセス制御リスト DACL を記述できます。 |
| WRITE_OWNER | mailslot に関連付けられている所有権情報を書き込むことができます。 |
| ACCESS_SYSTEM_SECURITY | 呼び出し元は、mailslot の SACL への書き込みアクセス権を持ちます。 |
| SYNCHRONIZE | 呼び出し元は、返された FileHandle が Signaled 状態に設定されるのを待って、I/O 操作の完了を同期できます。 CreateOptions FILE_SYNCHRONOUS_IO_ALERTまたは FILE_SYNCHRONOUS_IO_NONALERT フラグが設定されている場合は、このフラグを設定する必要があります。 |
または、ディレクトリを表さないファイル オブジェクトに対して、次の汎用 ACCESS_MASK フラグの 1 つ以上を指定できます。 (STANDARD_RIGHTS_XXX フラグは、システム オブジェクトにセキュリティを適用するために使用される定義済みのシステム値です)。これらの汎用フラグを、前の表の追加フラグと組み合わせることもできます。
| DesiredAccess to File Values | 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 を作成または開くときに適用されるオプション。
| Flags | 意味 |
|---|---|
| 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 パラメーターで指定された フィルター または インスタンス が破棄されています。 この状態コードは、オープン要求がボリューム・マウント・ポイントを超え、 Instance パラメーターが NULL 以外の場合に受け取ることができます。 これはエラー コードです。 |
| STATUS_OBJECT_PATH_SYNTAX_BAD | ObjectAttributes パラメーターに RootDirectory メンバーが含まれていませんでしたが、OBJECT_ATTRIBUTES構造体の ObjectName メンバーが空の文字列であるか、OBJECT_NAME_PATH_SEPARATOR文字が含まれていませんでした。 このエラー コードは、オブジェクト パスの構文が正しくないことです。 |
注釈
FltCreateMailslotFile 関数を使用すると、ミニフィルター ドライバーで mailslot インスタンスを作成または開くことができるようになります。 これは、仮想メールスロットを作成する場合や、他のいくつかの mailslot に配布する mailslot グループを作成する場合に便利です。
Instance パラメーターは NULL であるか、mailslot ボリュームにアタッチして以前に設定されています。 ボリューム ポインターは、ボリューム名として "\Device\Mailslot" を FltGetVolumeFromName に渡すことによって取得されます。
作成操作の一部として追加の create パラメーター (ECP) を指定するには、FltAllocateExtraCreateParameterList ルーチンを使用して、IO_DRIVER_CREATE_CONTEXT構造体の ExtraCreateParameter メンバーを初期化します。 ECP を使用する場合は、関連付けられているサポート ルーチンを使用して、割り当て、初期化、および解放する必要があります。 FltCreateMailslotFile の呼び出しから戻ると、ECP リストは変更されず、他の作成操作のために FltCreateMailslotFile の追加の呼び出しに渡される場合があります。 ECP リスト構造は自動的に割り当て解除されません。 FltCreateMailslotFile の呼び出し元は、FltFreeExtraCreateParameterList ルーチンを呼び出すことによって、この構造体の割り当てを解除する必要があります。
Instance が NULL でない場合、FltCreateMailslotFile からの作成要求は、指定されたミニフィルター ドライバー インスタンスの下にアタッチされたインスタンスと mailslot ファイル システムにのみ送信されます。 指定したインスタンスとその上にアタッチされたインスタンスは、作成要求を受け取りません。 インスタンスが指定されていない場合、要求はスタックの先頭に移動し、すべてのインスタンスと mailslot ファイル システムによって受信されます。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows 8で使用できます。 |
| 対象プラットフォーム | ユニバーサル |
| Header | fltkernel.h (FltKernel.h を含む) |
| Library | Fltmgr.lib |
| IRQL | PASSIVE_LEVEL |
こちらもご覧ください
FltAllocateExtraCreateParameterList