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

Статья
08/26/2023

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

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

Синтаксис

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

Параметры

[in, optional] lpTimerAttributes

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

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

[in] bManualReset

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

[in, optional] lpTimerName

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Примеры

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

Требования

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