Funzione CreateWaitableTimerW (synchapi.h)

Articolo
03/05/2024

Crea o apre un oggetto timer waitable.

Per specificare una maschera di accesso per l'oggetto, utilizzare la funzione CreateWaitableTimerEx .

Sintassi

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

Parametri

[in, optional] lpTimerAttributes

Puntatore a una struttura SECURITY_ATTRIBUTES che specifica un descrittore di sicurezza per il nuovo oggetto timer e determina se i processi figlio possono ereditare l'handle restituito.

Se lpTimerAttributes è NULL, l'oggetto timer ottiene un descrittore di sicurezza predefinito e l'handle non può essere ereditato. Gli ACL nel descrittore di sicurezza predefinito per un timer provengono dal token primario o di rappresentazione del creatore.

[in] bManualReset

Se questo parametro è TRUE, il timer è un timer di notifica di reimpostazione manuale. In caso contrario, il timer è un timer di sincronizzazione.

[in, optional] lpTimerName

Nome dell'oggetto timer. Il nome è limitato a MAX_PATH caratteri. Il confronto tra nomi fa distinzione tra maiuscole e minuscole.

Se lpTimerName è NULL, l'oggetto timer viene creato senza un nome.

Se lpTimerName corrisponde al nome di un evento esistente, semaforo, mutex, processo o oggetto di mapping di file, la funzione ha esito negativo e GetLastError restituisce ERROR_INVALID_HANDLE. Ciò si verifica perché questi oggetti condividono lo stesso spazio dei nomi.

Il nome può avere un prefisso "Global" o "Local" per creare in modo esplicito l'oggetto nello spazio dei nomi globale o sessione. Il resto del nome può contenere qualsiasi carattere ad eccezione del carattere barra rovesciata (\). Per altre informazioni, vedere Spazi dei nomi degli oggetti kernel. Il passaggio rapido degli utenti viene implementato usando le sessioni di Servizi terminal. I nomi degli oggetti kernel devono seguire le linee guida descritte per Servizi terminal in modo che le applicazioni possano supportare più utenti.

L'oggetto può essere creato in uno spazio dei nomi privato. Per altre informazioni, vedere Spazi dei nomi degli oggetti.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è un handle per l'oggetto timer. Se l'oggetto timer denominato esiste prima della chiamata di funzione, la funzione restituisce un handle all'oggetto esistente e GetLastError restituisce ERROR_ALREADY_EXISTS.

Se la funzione ha esito negativo, il valore restituito è NULL. Per informazioni dettagliate sull'errore, chiamare GetLastError.

Commenti

L'handle restituito da CreateWaitableTimer viene creato con il diritto di accesso TIMER_ALL_ACCESS ; può essere usato in qualsiasi funzione che richiede un handle per un oggetto timer, a condizione che al chiamante sia stato concesso l'accesso. Se un timer viene creato da un servizio o da un thread che rappresenta un utente diverso, è possibile applicare un descrittore di sicurezza al timer quando lo si crea oppure modificare il descrittore di sicurezza predefinito per il processo di creazione modificando il relativo DACL predefinito. Per altre informazioni, vedere Synchronization Object Security and Access Rights.For more information, see Synchronization Object Security and Access Rights.

Qualsiasi thread del processo chiamante può specificare l'handle dell'oggetto timer in una chiamata a una delle funzioni di attesa.

Più processi possono avere handle per lo stesso oggetto timer, consentendo l'uso dell'oggetto per la sincronizzazione tra processi.

Un processo creato dalla funzione CreateProcess può ereditare un handle a un oggetto timer se il parametro lpTimerAttributes di CreateWaitableTimer abilita l'ereditarietà.
Un processo può specificare l'handle dell'oggetto timer in una chiamata alla funzione DuplicateHandle . L'handle risultante può essere usato da un altro processo.
Un processo può specificare il nome di un oggetto timer in una chiamata alla funzione OpenWaitableTimer o CreateWaitableTimer .

Usare la funzione CloseHandle per chiudere l'handle. Il sistema chiude automaticamente l'handle al termine del processo. L'oggetto timer viene eliminato definitivamente quando l'ultimo handle è stato chiuso.

Per compilare un'applicazione che usa questa funzione, definire _WIN32_WINNT come 0x0400 o versione successiva. Per altre informazioni, vedere Uso delle intestazioni di Windows.

Per associare un timer a una finestra, usare la funzione SetTimer .

Esempio

Per un esempio che usa CreateWaitableTimer, vedere Using Waitable Timer Objects.For an example that using CreateWaitableTimer, see Using Waitable Timer Objects.

Requisiti

Requisito	Valore
Client minimo supportato	Windows XP [app desktop \| App UWP]
Server minimo supportato	Windows Server 2003 [app desktop \| App UWP]
Piattaforma di destinazione	Windows
Intestazione	synchapi.h (include Windows.h)
Libreria	Kernel32.lib
DLL	Kernel32.dll