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 | アクセス制御リスト 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 |
関連項目
FltAllocateExtraCreateParameterListの
FltFreeExtraCreateParameterListをする
InitializeObjectAttributesの
IoInitializeDriverCreateContextの