CreateWaitableTimer

HANDLE CreateWaitableTimer( LPSECURITY_ATTRIBUTES lpTimerAttributes, BOOL bManualReset, LPCTSTR lpTimerName );

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

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

Аргументы

0. lpTimerAttributes — указатель на объект структуры SECURITY_ATTRIBUTES, содержащий дескриптор безопасности нового объекта таймера и определяющий может ли дочерний процесс наследовать возвращённый дескриптор. Если данный аргумент имеет нулевое значение, объекту таймера сопоставляется дескриптор безопасности, используемый по умолчанию, и возвращённый дескриптор не может наследоваться.

1. bManualReset — определяет тип таймера. Если данный аргумент имеет значение TRUE, то создаётся управляемый таймер извещения. В противном случае создаётся таймер синхронизации.

2. lpTimerName — указатель на заканчивающуюся нулём строку, определяющую имя объекта таймера. Размер имени объекта таймера не может превышать значения константы MAX_PATH и может содержать любые символы кроме косой черты, используемой при задании пути файла (\). При сравнении имён учитывается регистр составляющих их символов.

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

4. Если аргумент lpTimerName имеет нулевое значение, то создаётся неименованный объект таймера.

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

Примечание

Функция CreateWaitableTimer создаёт "ждущий" объект таймера.

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

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

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

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

• Процесс может передать дескриптор объекта таймера в качестве аргумента функции DuplicateHandle. Полученный в результате вызова данной функции дескриптор может использоваться процессом.

• Процесс может использовать имя объекта таймера при вызове функций OpenWaitableTimer и CreateWaitableTimer.

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

Описание данной функции содержится в файле заголовка winbase.h. При работе с данной функцией следует включить в проект библиотеку kernel32.lib.