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

Статья
11/20/2024

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

Синтаксис

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

Параметры

[in, optional] lpTimerAttributes

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

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

[in, optional] lpTimerName

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

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

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

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

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

[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]
целевая платформа	Виндоус
заголовка	synchapi.h (включая Windows.h)
библиотеки	Kernel32.lib
DLL	Kernel32.dll

См. также

CloseHandle

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

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

Поделиться через