ZwCreateEvent 関数 (ntifs.h)

[アーティクル]
07/11/2023

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 パラメーターには、無効な objectName がOBJECT_ATTRIBUTES構造体に含まれていました。
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 のタイムアウトを指定します。
イベントへのアクセスが不要になったら、通知イベントへのハンドルを ZwClose で閉じます。

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

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

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

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

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

注意

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

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

要件

要件	値
サポートされている最小のクライアント	Windows XP。
対象プラットフォーム	ユニバーサル
Header	ntifs.h (Ntifs.h を含む)
Library	NtosKrnl.lib
[DLL]	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
DDI コンプライアンス規則	HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm)