ZwOpenEvent 関数 (wdm.h)

[アーティクル]
03/05/2024

ZwOpenEvent ルーチンは、指定された目的のアクセス権を持つ既存の名前付きイベントオブジェクトへのハンドルを開きます。

構文

NTSYSCALLAPI NTSTATUS ZwOpenEvent(
  [out] PHANDLE            EventHandle,
  [in]  ACCESS_MASK        DesiredAccess,
  [in]  POBJECT_ATTRIBUTES ObjectAttributes
);

パラメーター

[out] EventHandle

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

[in] DesiredAccess

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

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

[in] ObjectAttributes

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

戻り値

ZwOpenEvent は、STATUS_SUCCESSまたは適切なエラー状態を返します。このルーチンは、次のいずれかのエラー状態コードを返す場合があります。

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

注釈

ZwOpenEvent は、既存の名前付きイベントオブジェクトを開き、指定した目的のアクセス権を持つオブジェクトへのハンドルを作成します。

ZwOpenEvent は、通知イベントまたは同期イベントを開くことができます。

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

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

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

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

要件

要件	値
対象プラットフォーム	ユニバーサル
Header	wdm.h (Wdm.h を含む)
Library	NtosKrnl.lib
[DLL]	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
DDI コンプライアンス規則	HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm)