次の方法で共有

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

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

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

  1. EventType パラメーターを NotificationEvent に設定して、ZwCreateEvent で通知イベントを作成します。

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

  3. イベントへのアクセスが不要になったら、通知イベントへのハンドルを 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)

こちらもご覧ください

ACCESS_MASK

InitializeObjectAttributes

IoCreateNotificationEvent

IoCreateSynchronizationEvent

KeClearEvent

KeResetEvent

KeSetEvent

KeWaitForSingleObject

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

ZwClose

ZwSetEvent

ZwWaitForSingleObject