CreateEventA 関数 (synchapi.h)
名前付きまたは名前のないイベント オブジェクトを作成または開きます。
オブジェクトのアクセス マスクを指定するには、 CreateEventEx 関数を使用します。
構文
HANDLE CreateEventA(
[in, optional] LPSECURITY_ATTRIBUTES lpEventAttributes,
[in] BOOL bManualReset,
[in] BOOL bInitialState,
[in, optional] LPCSTR lpName
);
パラメーター
[in, optional] lpEventAttributes
SECURITY_ATTRIBUTES構造体へのポインター。 このパラメーターが NULL の場合、ハンドルは子プロセスによって継承できません。
構造体の lpSecurityDescriptor メンバーは、新しいイベントの セキュリティ記述子 を指定します。 lpEventAttributes が NULL の場合、イベントは既定のセキュリティ記述子を取得します。 イベントの既定のセキュリティ記述子の ACL は、作成者のプライマリ トークンまたは偽装トークンから取得されます。
[in] bManualReset
このパラメーターが TRUE の場合、この関数は手動リセット イベント オブジェクトを作成します。そのためには、 ResetEvent 関数を使用してイベントの状態を非署名に設定する必要があります。 このパラメーターが FALSE の場合、この関数は自動リセット イベント オブジェクトを作成し、1 つの待機スレッドが解放された後にイベント状態を自動的に非署名にリセットします。
[in] bInitialState
このパラメーターが TRUE の場合、イベント オブジェクトの初期状態が通知されます。それ以外の場合は、非署名です。
[in, optional] lpName
イベント オブジェクトの名前です。 名前は MAX_PATH 文字に制限されています。 名前の比較では大文字と小文字が区別されます。
lpName が既存の名前付きイベント オブジェクトの名前と一致する場合、この関数はEVENT_ALL_ACCESSアクセス権を要求します。 この場合、 bManualReset パラメーターと bInitialState パラメーターは、作成プロセスによって既に設定されているため、無視されます。 lpEventAttributes パラメーターが NULL でない場合、ハンドルを継承できるかどうかを判断しますが、そのセキュリティ記述子メンバーは無視されます。
lpName が NULL の場合、イベント オブジェクトは名前なしで作成されます。
lpName が同じ名前空間内の別の種類のオブジェクトの名前 (既存のセマフォ、ミューテックス、待機可能タイマー、ジョブ、ファイル マッピング オブジェクトなど) と一致する場合、関数は失敗し、GetLastError 関数はERROR_INVALID_HANDLEを返します。 これは、これらのオブジェクトが同じ名前空間を共有しているために発生します。
名前には、グローバル名前空間またはセッション名前空間にオブジェクトを明示的に作成するための "Global" または "Local" プレフィックスを付けることができます。 名前の残りの部分には、円記号 (\) を除く任意の文字を含めることができます。 詳細については、「 カーネル オブジェクトの名前空間」を参照してください。 ターミナル サービス セッションを使用して、高速ユーザー切り替えが実装されます。 カーネル オブジェクト名は、アプリケーションが複数のユーザーをサポートできるように、ターミナル サービスに関するガイドラインに従う必要があります。
オブジェクトは、プライベート名前空間に作成できます。 詳細については、「 オブジェクトの名前空間」を参照してください。
戻り値
関数が成功した場合、戻り値はイベント オブジェクトへのハンドルです。 関数呼び出しの前に名前付きイベント オブジェクトが存在する場合、関数は既存のオブジェクトへのハンドルを返し、GetLastError はERROR_ALREADY_EXISTSを返します。
関数が失敗した場合は、返される値は NULL です。 詳細なエラー情報を得るには、GetLastError を呼び出します。
解説
CreateEvent によって返されるハンドルには、EVENT_ALL_ACCESSアクセス権があります。呼び出し元にアクセス権が付与されている場合は、イベント オブジェクトへのハンドルを必要とする任意の関数で使用できます。 別のユーザーを偽装しているサービスまたはスレッドからイベントが作成された場合は、イベントの作成時にセキュリティ記述子を適用するか、既定の DACL を変更して作成プロセスの既定のセキュリティ記述子を変更できます。 詳細については、「 同期オブジェクトのセキュリティとアクセス権」を参照してください。
呼び出し元プロセスのスレッドは、 いずれかの待機関数の呼び出しでイベント オブジェクト ハンドルを指定できます。 単一オブジェクト待機関数は、指定されたオブジェクトの状態が通知されると を返します。 複数オブジェクト待機関数は、いずれかの場合、または指定されたすべてのオブジェクトが通知されたときにを返すように指示できます。 待機関数が戻ると、待機中のスレッドが解放され、実行が続行されます。
イベント オブジェクトの初期状態は、 bInitialState パラメーターによって指定されます。 SetEvent 関数を使用して、イベント オブジェクトの状態を signaled に設定します。 ResetEvent 関数を使用して、イベント オブジェクトの状態を非署名にリセットします。
手動リセット イベント オブジェクトの状態が通知されると、 ResetEvent 関数によって非署名に明示的にリセットされるまで、その状態はシグナル状態のままです。 任意の数の待機中のスレッド、または指定されたイベント オブジェクトの待機操作をその後開始するスレッドは、オブジェクトの状態が通知されている間に解放できます。
自動リセット イベント オブジェクトの状態が通知されると、1 つの待機中のスレッドが解放されるまで通知されたままになります。その後、システムは状態を非署名に自動的にリセットします。 待機しているスレッドがない場合でも、イベント オブジェクトの状態はシグナルのままです。
複数のプロセスに同じイベント オブジェクトのハンドルを含めることができるため、プロセス間同期に オブジェクトを使用できます。 次のオブジェクト共有メカニズムを使用できます。
- CreateProcess 関数によって作成された子プロセスは、CreateEvent の lpEventAttributes パラメーターで継承が有効になっている場合、イベント オブジェクトへのハンドルを継承できます。
- プロセスでは、 DuplicateHandle 関数の呼び出しでイベント オブジェクト ハンドルを指定して、別のプロセスで使用できる重複するハンドルを作成できます。
- プロセスでは、 OpenEvent または CreateEvent 関数の呼び出しでイベント オブジェクトの名前 を 指定できます。
例
CreateEvent を使用する例については、「イベント オブジェクトの使用」を参照してください。
注意
synchapi.h ヘッダーは、CreateEvent をエイリアスとして定義し、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択します。 encoding-neutral エイリアスの使用を encoding-neutral ではないコードと混在すると、コンパイル エラーまたはランタイム エラーが発生する不一致が発生する可能性があります。 詳細については、「 関数プロトタイプの規則」を参照してください。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows XP [デスクトップ アプリ | UWP アプリ] |
| サポートされている最小のサーバー | Windows Server 2003 [デスクトップ アプリのみ | UWP アプリ] |
| 対象プラットフォーム | Windows |
| ヘッダー | synchapi.h (Windows Server 2003、Windows Vista、Windows 7、Windows Server 2008 Windows Server 2008 R2 の Windows.h を含む) |
| Library | Kernel32.lib |
| [DLL] | Kernel32.dll |