Funzione CreateWaitableTimerExW (synchapi.h)

Articolo
11/20/2024

Crea o apre un oggetto timer waitable e restituisce un handle all'oggetto .

Sintassi

HANDLE CreateWaitableTimerExW(
  [in, optional] LPSECURITY_ATTRIBUTES lpTimerAttributes,
  [in, optional] LPCWSTR               lpTimerName,
  [in]           DWORD                 dwFlags,
  [in]           DWORD                 dwDesiredAccess
);

Parametri

[in, optional] lpTimerAttributes

Puntatore a una struttura SECURITY_ATTRIBUTES. Se questo parametro è NULL, l'handle timer non può essere ereditato dai processi figlio.

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 di rappresentazione o primario dell'autore.

[in, optional] lpTimerName

Nome dell'oggetto timer. Il nome è limitato ai caratteri MAX_PATH. 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 dell'oggetto kernel . Il passaggio rapido dell'utente viene implementato usando le sessioni di Servizi terminal. I nomi degli oggetti del 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 .

[in] dwFlags

Questo parametro può essere 0 o i valori seguenti.

Valore	Significato
CREATE_WAITABLE_TIMER_MANUAL_RESET 0x00000001	Il timer deve essere reimpostato manualmente. In caso contrario, il sistema reimposta automaticamente il timer dopo il rilascio di un singolo thread in attesa.
CREATE_WAITABLE_TIMER_HIGH_RESOLUTION 0x00000002	Crea un timer ad alta risoluzione. Usare questo valore per situazioni critiche quando i ritardi di scadenza brevi nell'ordine di pochi millisecondi sono inaccettabili. Questo valore è supportato in Windows 10, versione 1803 e successive.

[in] dwDesiredAccess

Maschera di accesso per l'oggetto timer. Per un elenco dei diritti di accesso, vedere Synchronization Object Security and Access Rights.

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 ottenere informazioni estese sull'errore, chiamare GetLastError.

Osservazioni

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 interprocesso.

Un processo creato dalla funzione CreateProcess può ereditare un handle a un oggetto timer se il parametro lpTimerAttributes di CreateWaitableTimerEx 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 OpenWaitableTimer o funzione CreateWaitableTimerEx.

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 associare un timer a una finestra, usare la funzione SetTimer.

Fabbisogno

Requisito	Valore
client minimo supportato	Windows Vista [app desktop \| App UWP]
server minimo supportato	Windows Server 2008 [app desktop \| App UWP]
piattaforma di destinazione	Finestre
intestazione	synchapi.h (include Windows.h)
libreria	Kernel32.lib
dll	Kernel32.dll

Vedere anche

CloseHandle

funzioni di sincronizzazione

oggetti timer waitable

Condividi tramite