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

このパラメーターには、0 または次のいずれかの値を指定できます。

価値 意味
CREATE_EVENT_INITIAL_SET
0x00000002
 イベント オブジェクトの初期状態はシグナル状態です。それ以外の場合は、非シグナル状態です。
CREATE_EVENT_MANUAL_RESET
0x00000001
 ResetEvent 関数を使用して、イベントを手動でリセットする必要があります。 任意の数の待機中のスレッド、または指定されたイベント オブジェクトの待機操作をその後開始するスレッドは、オブジェクトの状態がシグナル状態である間に解放できます。

このフラグが指定されていない場合、システムは、1 つの待機スレッドを解放した後、イベントを自動的にリセットします。

[in] dwDesiredAccess

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

戻り値

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

関数が失敗した場合、戻り値は NULL。 拡張エラー情報を取得するには、GetLastError呼び出します。

備考

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

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

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

複数のプロセスが同じイベント オブジェクトのハンドルを持つ可能性があり、プロセス間同期にオブジェクトを使用できます。 次のオブジェクト共有メカニズムを使用できます。

  • CreateProcess 関数によって作成された子プロセスは、lpEventAttributes が CreateEvent のパラメーター継承を有効にした場合、イベント オブジェクト ハンドルを継承できます。
  • プロセスでは、DuplicateHandle 関数の呼び出しでイベント オブジェクト ハンドルを指定して、別のプロセスで使用できる重複するハンドルを作成できます。
  • プロセスでは、OpenEvent または CreateEvent 関数の呼び出しでイベント オブジェクトの名前を指定できます。
CloseHandle 関数を使用してハンドルを閉じます。 プロセスが終了すると、システムはハンドルを自動的に閉じます。 イベント オブジェクトは、最後のハンドルが閉じられたときに破棄されます。

手記

synchapi.h ヘッダーは、Unicode プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択するエイリアスとして CreateEventEx を定義します。 エンコードに依存しないエイリアスをエンコードに依存しないコードと組み合わせて使用すると、コンパイルエラーやランタイム エラーが発生する不一致が発生する可能性があります。 詳細については、「関数プロトタイプの 規則」を参照してください。

必要条件

要件 価値
サポートされる最小クライアント Windows Vista [デスクトップ アプリ |UWP アプリ]
サポートされる最小サーバー Windows Server 2008 [デスクトップ アプリ |UWP アプリ]
ターゲット プラットフォーム ウィンドウズ
ヘッダー synchapi.h (Windows 7、Windows Server 2008 Windows Server 2008 R2 の Windows.h を含む)
ライブラリ カーネル32.lib
DLL Kernel32.dll

関連項目

CloseHandle

イベント オブジェクト

オブジェクト名の

同期関数の

  • Last updated on