CreateWaitableTimerW-Funktion (synchapi.h)

Artikel
11/20/2024

Erstellt oder öffnet ein wartebares Timerobjekt.

Um ein Zugriffsformat für das Objekt anzugeben, verwenden Sie die CreateWaitableTimerEx--Funktion.

Syntax

HANDLE CreateWaitableTimerW(
  [in, optional] LPSECURITY_ATTRIBUTES lpTimerAttributes,
  [in]           BOOL                  bManualReset,
  [in, optional] LPCWSTR               lpTimerName
);

Parameter

[in, optional] lpTimerAttributes

Ein Zeiger auf eine SECURITY_ATTRIBUTES-Struktur, die einen Sicherheitsdeskriptor für das neue Timerobjekt angibt und bestimmt, ob untergeordnete Prozesse den zurückgegebenen Handle erben können.

Wenn lpTimerAttributes-NULL-ist, ruft das Timerobjekt einen Standardsicherheitsdeskriptor ab, und der Handle kann nicht geerbt werden. Die ACLs im Standardsicherheitsdeskriptor für einen Timer stammen aus dem primären oder Identitätswechseltoken des Erstellers.

[in] bManualReset

Wenn dieser Parameter TRUEist, handelt es sich beim Timer um einen Zeitgeber für die manuelle Zurücksetzung von Benachrichtigungen. Andernfalls ist der Timer ein Synchronisierungszeitgeber.

[in, optional] lpTimerName

Der Name des Timerobjekts. Der Name ist auf MAX_PATH Zeichen beschränkt. Bei dem Namensvergleich wird die Groß-/Kleinschreibung beachtet.

Wenn lpTimerName-NULL-ist, wird das Timerobjekt ohne Namen erstellt.

Wenn lpTimerName- mit dem Namen eines vorhandenen Ereignisses, Semaphor, Mutex, Auftrag oder Dateizuordnungsobjekts übereinstimmt, schlägt die Funktion fehl, und GetLastError gibt ERROR_INVALID_HANDLEzurück. Dies geschieht, da diese Objekte denselben Namespace gemeinsam nutzen.

Der Name kann ein Präfix "Global" oder "Local" aufweisen, um das Objekt explizit im globalen oder Sitzungsnamespace zu erstellen. Der Rest des Namens kann ein beliebiges Zeichen mit Ausnahme des umgekehrten Schrägstrichs (\) enthalten. Weitere Informationen finden Sie unter Kernel Object Namespaces. Schnelle Benutzerumschaltung wird mithilfe von Terminaldienstesitzungen implementiert. Kernelobjektnamen müssen den Richtlinien für Terminaldienste entsprechen, damit Anwendungen mehrere Benutzer unterstützen können.

Das Objekt kann in einem privaten Namespace erstellt werden. Weitere Informationen finden Sie unter Object Namespaces.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ein Handle für das Timerobjekt. Wenn das benannte Timerobjekt vor dem Funktionsaufruf vorhanden ist, gibt die Funktion ein Handle an das vorhandene Objekt zurück und GetLastError gibt ERROR_ALREADY_EXISTSzurück.

Wenn die Funktion fehlschlägt, ist der Rückgabewert NULL-. Rufen Sie GetLastErrorauf, um erweiterte Fehlerinformationen zu erhalten.

Bemerkungen

Das von CreateWaitableTimer zurückgegebene Handle wird mit dem TIMER_ALL_ACCESS Zugriffsrecht erstellt; sie kann in jeder Funktion verwendet werden, die ein Handle für ein Timerobjekt erfordert, vorausgesetzt, der Aufrufer wurde Zugriff gewährt. Wenn ein Timer aus einem Dienst oder Thread erstellt wird, der die Identität eines anderen Benutzers angibt, können Sie entweder einen Sicherheitsdeskriptor auf den Timer anwenden, wenn Sie ihn erstellen, oder den Standardsicherheitsdeskriptor für den Erstellungsprozess ändern, indem Sie die standardmäßige DACL ändern. Weitere Informationen finden Sie unter Sync Object Security and Access Rights.

Jeder Thread des aufrufenden Prozesses kann das Timerobjekthandle in einem Aufruf einer der Wait-Funktionenangeben.

Mehrere Prozesse können Überhandles an dasselbe Timerobjekt verfügen, wodurch die Verwendung des Objekts für die Interprocess-Synchronisierung ermöglicht wird.

Ein prozess, der von der CreateProcess--Funktion erstellt wurde, kann ein Handle an ein Timerobjekt erben, wenn der lpTimerAttributes Parameter von CreateWaitableTimer die Vererbung ermöglicht.
Ein Prozess kann das Timerobjekthandle in einem Aufruf der DuplicateHandle--Funktion angeben. Der resultierende Handle kann von einem anderen Prozess verwendet werden.
Ein Prozess kann den Namen eines Timerobjekts in einem Aufruf des OpenWaitableTimer- oder CreateWaitableTimer--Funktion angeben.

Verwenden Sie die CloseHandle--Funktion, um den Handle zu schließen. Das System schließt das Handle automatisch, wenn der Prozess beendet wird. Das Timerobjekt wird zerstört, wenn der letzte Handle geschlossen wurde.

Um eine Anwendung zu kompilieren, die diese Funktion verwendet, definieren Sie _WIN32_WINNT als 0x0400 oder höher. Weitere Informationen finden Sie unter Verwenden der Windows-Header.

Um einem Fenster einen Timer zuzuordnen, verwenden Sie die SetTimer--Funktion.

Beispiele

Ein Beispiel, das CreateWaitableTimer-verwendet, finden Sie unter Using Waitable Timer Objects.

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Windows XP [Desktop-Apps \| UWP-Apps]
mindestens unterstützte Server-	Windows Server 2003 [Desktop-Apps \| UWP-Apps]
Zielplattform-	Fenster
Header-	synchapi.h (enthalten Windows.h)
Library	Kernel32.lib
DLL-	Kernel32.dll