CreateEventExA 関数 (synchapi.h)

名前付きまたは名前のないイベント オブジェクトを作成または開き、オブジェクトへのハンドルを返します。

構文

HANDLE CreateEventExA(
  [in, optional] LPSECURITY_ATTRIBUTES lpEventAttributes,
  [in, optional] LPCSTR                lpName,
  [in]           DWORD                 dwFlags,
  [in]           DWORD                 dwDesiredAccess
);

パラメーター

[in, optional] lpEventAttributes

SECURITY_ATTRIBUTES構造体へのポインター。 lpEventAttributes が NULL の場合、イベント ハンドルは子プロセスによって継承できません。

構造体の lpSecurityDescriptor メンバーは、新しいイベントの セキュリティ記述子 を指定します。 lpEventAttributes が NULL の場合、イベントは既定のセキュリティ記述子を取得します。 イベントの既定のセキュリティ記述子の ACL は、作成者のプライマリ トークンまたは偽装トークンから取得されます。

[in, optional] lpName

イベント オブジェクトの名前です。 名前は MAX_PATH 文字に制限されています。 名前の比較では大文字と小文字が区別されます。

lpName が NULL の場合、イベント オブジェクトは名前なしで作成されます。

lpName が同じ名前空間内の別の種類のオブジェクトの名前 (既存のセマフォ、ミューテックス、待機可能タイマー、ジョブ、ファイル マッピング オブジェクトなど) と一致する場合、関数は失敗し、GetLastError 関数はERROR_INVALID_HANDLEを返します。 これは、これらのオブジェクトが同じ名前空間を共有しているために発生します。

名前には、グローバル名前空間またはセッション名前空間にオブジェクトを明示的に作成するための "Global" または "Local" プレフィックスを付けることができます。 名前の残りの部分には、円記号 (\) を除く任意の文字を含めることができます。 詳細については、「 カーネル オブジェクトの名前空間」を参照してください。 ターミナル サービス セッションを使用して、高速ユーザー切り替えが実装されます。 カーネル オブジェクト名は、アプリケーションが複数のユーザーをサポートできるように、ターミナル サービスに関するガイドラインに従う必要があります。

オブジェクトは、プライベート名前空間に作成できます。 詳細については、「 オブジェクトの名前空間」を参照してください。

[in] dwFlags

このパラメーターには、次の 1 つ以上の値を指定できます。

[in] dwDesiredAccess

イベント オブジェクトのアクセス マスク。 アクセス権の一覧については、「 同期オブジェクトのセキュリティとアクセス権」を参照してください。

戻り値

関数が成功した場合、戻り値はイベント オブジェクトへのハンドルです。 関数呼び出しの前に名前付きイベント オブジェクトが存在する場合、関数は既存のオブジェクトへのハンドルを返し、GetLastError はERROR_ALREADY_EXISTSを返します。

関数が失敗した場合は、返される値は NULL です。 詳細なエラー情報を得るには、GetLastError を呼び出します。

解説

呼び出し元プロセスのスレッドは、 いずれかの待機関数の呼び出しでイベント オブジェクト ハンドルを指定できます。 単一オブジェクト待機関数は、指定されたオブジェクトの状態が通知されると を返します。 複数オブジェクト待機関数は、いずれかの場合、または指定されたすべてのオブジェクトが通知されたときにを返すように指示できます。 待機関数が戻ると、待機中のスレッドが解放され、実行が続行されます。

イベント オブジェクトの初期状態は dwFlags パラメーターによって指定されます。 SetEvent 関数を使用して、イベント オブジェクトの状態を signaled に設定します。 ResetEvent 関数を使用して、イベント オブジェクトの状態を非署名にリセットします。

手動リセット イベント オブジェクトの状態が通知されると、 ResetEvent 関数によって非署名に明示的にリセットされるまで、その状態はシグナル状態のままです。 任意の数の待機中のスレッド、または指定されたイベント オブジェクトの待機操作をその後開始するスレッドは、オブジェクトの状態が通知されている間に解放できます。

複数のプロセスに同じイベント オブジェクトのハンドルを含めることができるため、プロセス間同期に オブジェクトを使用できます。 次のオブジェクト共有メカニズムを使用できます。

• CreateProcess 関数によって作成された子プロセスは、CreateEvent の lpEventAttributes パラメーターで継承が有効になっている場合、イベント オブジェクトへのハンドルを継承できます。
• プロセスでは、 DuplicateHandle 関数の呼び出しでイベント オブジェクト ハンドルを指定して、別のプロセスで使用できる重複するハンドルを作成できます。
• プロセスでは、 OpenEvent または CreateEvent 関数の呼び出しでイベント オブジェクトの名前 を 指定できます。

要件

関連項目

CloseHandle

イベント オブジェクト

オブジェクト名

同期関数