CreateWaitableTimerW-Funktion (synchapi.h)

Artikel
08/26/2023

Erstellt oder öffnet ein wartebares Timerobjekt.

Um eine Zugriffsmaske für das Objekt anzugeben, verwenden Sie die Funktion CreateWaitableTimerEx .

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 das zurückgegebene Handle erben können.

Wenn lpTimerAttributesNULL ist, erhält das Timerobjekt einen Standardsicherheitsdeskriptor, und das Handle kann nicht geerbt werden. Die ACLs im Standardsicherheitsdeskriptor für einen Timer stammen aus dem primären Token oder dem Identitätswechseltoken des Erstellers.

[in] bManualReset

Wenn dieser Parameter TRUE ist, ist der Timer ein Benachrichtigungstimer, der manuell zurückgesetzt wird. Andernfalls ist der Timer ein Synchronisierungszeitgeber.

[in, optional] lpTimerName

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

Wenn lpTimerNameNULL ist, wird das Timerobjekt ohne Namen erstellt.

Wenn lpTimerName mit dem Namen eines vorhandenen Ereignisses, Semaphore, Mutex, Auftrags oder Dateizuordnungsobjekts übereinstimmt, schlägt die Funktion fehl, und GetLastError gibt ERROR_INVALID_HANDLE zurück. Dies tritt auf, weil diese Objekte denselben Namespace verwenden.

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 Kernelobjektnamespaces. Der schnelle Benutzerwechsel wird mithilfe von Terminaldienstesitzungen implementiert. Kernelobjektnamen müssen den für Terminaldienste beschriebenen Richtlinien entsprechen, damit Anwendungen mehrere Benutzer unterstützen können.

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

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_EXISTS zurück.

Wenn bei der Funktion ein Fehler auftritt, ist der Rückgabewert NULL. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

Das von CreateWaitableTimer zurückgegebene Handle wird mit dem zugriffsrecht TIMER_ALL_ACCESS erstellt. Sie kann in jeder Funktion verwendet werden, die ein Handle für ein Zeitgeberobjekt erfordert, vorausgesetzt, dem 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 Standard-DACL ändern. Weitere Informationen finden Sie unter Synchronisierungsobjektsicherheit und Zugriffsrechte.

Jeder Thread des aufrufenden Prozesses kann das Timerobjekthandle in einem Aufruf einer der Wartefunktionen angeben.

Mehrere Prozesse können Über Handles für dasselbe Timerobjekt verfügen, wodurch die Verwendung des Objekts für die Interprozesssynchronisierung ermöglicht wird.

Ein von der CreateProcess-Funktion erstellter Prozess kann ein Handle an ein Timerobjekt erben, wenn der lpTimerAttributes-Parameter von CreateWaitableTimer die Vererbung aktiviert.
Ein Prozess kann das Timerobjekthandle in einem Aufruf der DuplicateHandle-Funktion angeben. Das resultierende Handle kann von einem anderen Prozess verwendet werden.
Ein Prozess kann den Namen eines Timerobjekts in einem Aufruf der OpenWaitableTimer- oder CreateWaitableTimer-Funktion angeben.

Verwenden Sie die CloseHandle-Funktion , um das Handle zu schließen. Das System schließt den Handle automatisch, wenn der Prozess beendet wird. Das Timerobjekt wird zerstört, wenn das 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.

Verwenden Sie die SetTimer-Funktion , um einen Timer einem Fenster zuzuordnen.

Beispiele

Ein Beispiel, das CreateWaitableTimer verwendet, finden Sie unter Using Waitable Timer Objects.For an example that using CreateWaitableTimer, see Using Waitable Timer Objects.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows XP [Desktop-Apps \| UWP-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [Desktop-Apps \| UWP-Apps]
Zielplattform	Windows
Kopfzeile	synchapi.h (einschließlich Windows.h)
Bibliothek	Kernel32.lib
DLL	Kernel32.dll