Функция CreateWaitableTimerExW (synchapi.h)

Статья
08/26/2023

Создает или открывает объект таймера с возможностью ожидания и возвращает дескриптор объекту .

Синтаксис

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

Параметры

[in, optional] lpTimerAttributes

Указатель на структуру SECURITY_ATTRIBUTES . Если этот параметр имеет значение NULL, дескриптор таймера не может наследоваться дочерними процессами.

Если lpTimerAttributes имеет значение NULL, объект таймера получает дескриптор безопасности по умолчанию и дескриптор не может быть унаследован. Списки ACL в дескрипторе безопасности по умолчанию для таймера поступают из основного маркера или токена олицетворения создателя.

[in, optional] lpTimerName

Имя объекта таймера. Имя ограничено MAX_PATH символами. Сравнение имен учитывает регистр.

Если lpTimerName имеет значение NULL, объект таймера создается без имени.

Если lpTimerName соответствует имени существующего объекта события, семафора, мьютекса, задания или сопоставления файлов, функция завершается ошибкой и GetLastError возвращает ERROR_INVALID_HANDLE. Это происходит потому, что эти объекты используют одно и то же пространство имен.

Имя может иметь префикс "Global" или "Local" для явного создания объекта в глобальном пространстве имен или пространстве имен сеанса. Оставшаяся часть имени может содержать любой символ, кроме символа обратной косой черты (\). Дополнительные сведения см. в разделе Пространства имен объектов ядра. Быстрое переключение пользователей реализуется с помощью сеансов служб терминалов. Имена объектов ядра должны соответствовать рекомендациям, описанным для служб терминалов, чтобы приложения могли поддерживать нескольких пользователей.

Объект можно создать в частном пространстве имен. Дополнительные сведения см. в разделе Пространства имен объектов.

[in] dwFlags

Этот параметр может иметь значение 0 или следующие значения.

Значение	Значение
CREATE_WAITABLE_TIMER_MANUAL_RESET 0x00000001	Таймер необходимо сбросить вручную. В противном случае система автоматически сбрасывает таймер после выпуска одного потока ожидания.
CREATE_WAITABLE_TIMER_HIGH_RESOLUTION 0x00000002	Создает таймер с высоким разрешением. Используйте это значение для критически важных по времени ситуаций, когда короткие задержки истечения срока действия порядка нескольких миллисекундах неприемлемы. Это значение поддерживается в Windows 10 версии 1803 и более поздних версиях.

Значение

CREATE_WAITABLE_TIMER_MANUAL_RESET
0x00000001

Таймер необходимо сбросить вручную. В противном случае система автоматически сбрасывает таймер после выпуска одного потока ожидания.

CREATE_WAITABLE_TIMER_HIGH_RESOLUTION
0x00000002

Создает таймер с высоким разрешением. Используйте это значение для критически важных по времени ситуаций, когда короткие задержки истечения срока действия порядка нескольких миллисекундах неприемлемы. Это значение поддерживается в Windows 10 версии 1803 и более поздних версиях.

[in] dwDesiredAccess

Маска доступа для объекта таймера. Список прав доступа см. в разделе Безопасность объектов синхронизации и права доступа.

Возвращаемое значение

Если функция выполняется успешно, возвращаемое значение является дескриптором для объекта таймера. Если именованный объект таймера существует до вызова функции, функция возвращает дескриптор существующему объекту, а GetLastError возвращает ERROR_ALREADY_EXISTS.

Если функция завершается сбоем, возвращается значение NULL. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.

Процесс, созданный функцией CreateProcess, может наследовать дескриптор объекта таймера, если параметр lpTimerAttributesэлемента CreateWaitableTimerEx включает наследование.
Процесс может указать дескриптор объекта таймера в вызове функции DuplicateHandle . Результирующий дескриптор может использоваться другим процессом.
Процесс может указать имя объекта таймера при вызове функции OpenWaitableTimer или CreateWaitableTimerEx .

Используйте функцию CloseHandle , чтобы закрыть дескриптор. Система автоматически закрывает дескриптор при завершении процесса. Объект таймера уничтожается при закрытии последнего дескриптора.

Чтобы связать таймер с окном, используйте функцию SetTimer .

Требования


Минимальная версия клиента	Windows Vista [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows Server 2008 [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	synchapi.h (включая Windows.h)
Библиотека	Kernel32.lib
DLL	Kernel32.dll

См. также

CloseHandle

Функции синхронизации

Объекты таймера для ожидания