ZwCreateEvent 関数 (ntifs.h)

[アーティクル]
12/21/2024

ZwCreateEvent ルーチンは、イベントオブジェクトを作成し、イベントの初期状態を指定した値に設定し、指定した目的のアクセス権を持つオブジェクトへのハンドルを開きます。

構文

NTSYSAPI NTSTATUS ZwCreateEvent(
  [out]          PHANDLE            EventHandle,
  [in]           ACCESS_MASK        DesiredAccess,
  [in, optional] POBJECT_ATTRIBUTES ObjectAttributes,
  [in]           EVENT_TYPE         EventType,
  [in]           BOOLEAN            InitialState
);

パラメーター

[out] EventHandle

イベントオブジェクトハンドルを受け取る変数へのポインター。ハンドルには、参照カウントやセキュリティコンテキストなどのブックキーピング情報が含まれます。

[in] DesiredAccess

イベントオブジェクトの目的のアクセスの種類を表す ACCESS_MASK 値。次の表に、イベント固有のACCESS_MASK値を示します。

価値	必要なアクセス
EVENT_QUERY_STATE	イベントオブジェクトの状態を照会します。
EVENT_MODIFY_STATE	イベントオブジェクトの状態を変更します。
EVENT_ALL_ACCESS	イベントオブジェクトに対して可能なすべてのアクセス権。

[in, optional] ObjectAttributes

指定したオブジェクトに使用する呼び出し元によって提供されるオブジェクト属性構造体へのポインター。これらの属性には、たとえば、ObjectName と SECURITY_DESCRIPTORが含まれます。このパラメーターは、InitializeObjectAttributes マクロを呼び出すことによって初期化されます。

[in] EventType

SynchronizationEvent または NotificationEventをできるイベントの種類。これらの値は、ntdef.h ヘッダーファイルで定義されている EVENT_TYPE 列挙体に属します。

[in] InitialState

イベントオブジェクトの初期状態。イベントオブジェクトを Signaled 状態に初期化するには、true をに設定します。イベントオブジェクトを非シグナル状態に初期化するには、FALSE をに設定します。

戻り値

ZwCreateEvent は、STATUS_SUCCESSまたは適切なエラー状態を返します。考えられるエラー状態コードは次のとおりです。

リターンコード	形容
STATUS_INSUFFICIENT_RESOURCES	この関数に必要なリソースを割り当てませんでした。
STATUS_INVALID_PARAMETER	指定された ObjectAttributes 構造体に無効なパラメーター値が含まれていました。
STATUS_INVALID_PARAMETER_4	指定した EventType パラメーターが無効でした。
STATUS_OBJECT_NAME_INVALID	ObjectAttributes パラメーターには、無効な OBJECT_ATTRIBUTES 構造体に ObjectName が含まれていました。
STATUS_OBJECT_PATH_SYNTAX_BAD	ObjectAttributes パラメーターには、RootDirectory メンバーが含まれていませんでしたが、OBJECT_ATTRIBUTES 構造体の ObjectName メンバーが空の文字列であるか、OBJECT_NAME_PATH_SEPARATOR文字が含まれていませんでした。これは、オブジェクトパスの構文が正しく示されていません。
STATUS_PRIVILEGE_NOT_HELD	呼び出し元には、DesiredAccess パラメーターで指定されたアクセス権を持つハンドルを作成するために必要な特権がありませんでした。

備考

ZwCreateEvent イベントオブジェクトを作成し、その初期状態を指定した値に設定し、指定した目的のアクセス権を持つオブジェクトへのハンドルを開きます。

イベントは、実行を調整するために使用されます。イベントは、指定されたイベントが Signaled 状態に設定されるまで、呼び出し元が要求された操作の完了を待機できるように、ファイルシステムドライバーによって使用できます。

ZwCreateEvent は、通知イベントまたは同期イベントを作成できます。

通知イベントを使用して、イベントが発生したことを 1 つ以上の実行スレッドに通知できます。
同期イベントは、他の 2 つの関連のないドライバー間のハードウェアへのアクセスのシリアル化で使用できます。

同期イベントは自動リセットです。同期イベントが Signaled 状態に設定されている場合、イベントの通知を待機していた単一の実行スレッドが解放され、イベントは自動的に Not-Signaled 状態にリセットされます。

同期イベントとは異なり、通知イベントは自動リセットされません。通知イベントが Signaled 状態になると、明示的にリセットされるまで、通知イベントはその状態のままになります。

通知イベントで同期するには:

EventType パラメーターを NotificationEventに設定して、ZwCreateEvent 通知イベントを作成します。
ZwCreateEventによって返される EventHandle を使用して ZwWaitForSingleObject 呼び出して、イベントが通知されるまで待ちます。複数の実行スレッドは、特定の通知イベントが通知されるまで待機できます。ストールではなくポーリングするには、ZwWaitForSingleObjectをする 0 の Timeout を指定します。
イベントへのアクセスが不要になったときに、ZwClose を使用して通知イベントのハンドルを閉じます。

ZwCreateEvent 関数は、InitializeObjectAttributes マクロを使用して、オブジェクトの OBJECT_ATTRIBUTES 構造体に属性を設定した後に呼び出されます。

ZwCreateEventに渡されるオブジェクトの名前指定するには、次の 2 つの方法があります。

完全修飾パス名として、入力 ObjectAttributesの ObjectName メンバーで指定されます。
objectAttributesの入力メンバー RootDirectory 内のハンドルによって表されるディレクトリを基準とするパス名。

イベントを解放するために、ドライバーはイベントハンドル ZwClose を呼び出します。

イベントの詳細については、「イベントオブジェクトの」を参照してください。

手記

ZwCreateEvent ルーチンの呼び出しがユーザーモードで発生する場合は、"ZwCreateEvent" ではなく"NtCreateEvent" という名前を使用する必要があります。

カーネルモードドライバーからの呼び出しの場合、Windows ネイティブシステムサービスルーチンの NtXxx および ZwXxx バージョンは、入力パラメーターを処理および解釈する方法で動作が異なる場合があります。ルーチンの NtXxx と ZwXxx バージョンの間の関係の詳細については、「ネイティブシステムサービスルーチンの Nt および Zw バージョンの使用を参照してください。

必要条件

要件	価値
サポートされる最小クライアント	Windows XP。
ターゲットプラットフォームの	万国
ヘッダー	ntifs.h (Ntifs.h を含む)
ライブラリ	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
DDI コンプライアンス規則をする	HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm)

次の方法で共有

ZwCreateEvent 関数 (ntifs.h)

構文

パラメーター

戻り値

備考

必要条件

関連項目

フィードバック

その他のリソース