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

Статья
11/20/2024

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

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

Синтаксис

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

Параметры

[in, optional] lpTimerAttributes

Указатель на структуру SECURITY_ATTRIBUTES, которая задает дескриптор безопасности для нового объекта таймера и определяет, могут ли дочерние процессы наследовать возвращенный дескриптор.

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

[in] bManualReset

Если этот параметр TRUE, таймер — таймер для сброса уведомлений вручную. В противном случае таймер является таймером синхронизации.

[in, optional] lpTimerName

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

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

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

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

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

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

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

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

Замечания

Дескриптор, возвращаемый CreateWaitableTimer, создается с помощью права доступа TIMER_ALL_ACCESS; его можно использовать в любой функции, требующей дескриптора к объекту таймера, при условии, что вызывающий объект предоставлен доступ. Если таймер создается из службы или потока, олицетворяющего другого пользователя, можно применить дескриптор безопасности к таймеру при его создании или изменить дескриптор безопасности по умолчанию для процесса создания, изменив значение DACL по умолчанию. Дополнительные сведения см. в службы "Безопасность объектов синхронизации и права доступа".

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

Несколько процессов могут иметь дескриптор одного и того же объекта таймера, что позволяет использовать объект для межпроцессной синхронизации.

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

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

Чтобы скомпилировать приложение, использующее эту функцию, определите _WIN32_WINNT как 0x0400 или более поздней версии. Дополнительные сведения см. в разделе Использование заголовков Windows.

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

Примеры

Пример использования CreateWaitableTimerсм. в разделе Использование объектов таймера ожидания.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows XP [классические приложения \| Приложения UWP]
минимальный поддерживаемый сервер	Windows Server 2003 [классические приложения \| Приложения UWP]
целевая платформа	Виндоус
заголовка	synchapi.h (включая Windows.h)
библиотеки	Kernel32.lib
DLL	Kernel32.dll