ZwCreateEvent 関数 (ntifs.h)

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

指定したオブジェクトに使用する呼び出し元によって提供されるオブジェクト属性構造体へのポインター。 たとえば、これらの属性には ObjectNameSECURITY_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 状態になると、通知イベントは明示的にリセットされるまでその状態のままになります。

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

  1. EventType パラメーターが NotificationEvent に設定された ZwCreateEvent通知イベントを作成します。

  2. ZwCreateEvent によって返される EventHandle を使用して ZwWaitForSingleObject を呼び出して、イベントが通知されるまで待ちます。 複数の実行スレッドは、特定の通知イベントが通知されるまで待機できます。 ストールの代わりにポーリングするには、ZwWaitForSingleObject に 0 のタイムアウトを指定します。

  3. イベントへのアクセスが不要になったら、通知イベントのハンドルを ZwClose で閉じます。

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

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

  • 完全修飾パス名として、入力 ObjectAttributesObjectName メンバーで指定されます。

  • 入力 ObjectAttributesRootDirectory メンバーのハンドルによって表されるディレクトリを基準とするパス名。

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

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

注意

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

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

要件

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

こちらもご覧ください

ACCESS_MASK

InitializeObjectAttributes

IoCreateNotificationEvent

IoCreateSynchronizationEvent

KeClearEvent

KeResetEvent

KeSetEvent

KeWaitForSingleObject

Nt および Zw バージョンのネイティブ システム サービス ルーチンの使用

ZwClose

ZwSetEvent

ZwWaitForSingleObject