Функция PcRegisterIoTimeout (portcls.h)

  • Статья

Функция PcRegisterIoTimeout регистрирует подпрограмму обратного вызова таймера ввода-вывода, предоставляемую драйвером, для указанного объекта устройства.

После регистрации драйвер класса port вызывает обратный вызов таймера примерно один раз в секунду, пока устройство остается активным.

Примечание Эта функция не рекомендуется использовать для Windows 8 и более поздних версий Windows. Для систем Windows в Arm эта функция закомментирована в драйвере класса PortCls и недоступна.
 

Синтаксис

PORTCLASSAPI NTSTATUS PcRegisterIoTimeout(
  [in] PDEVICE_OBJECT    pDeviceObject,
  [in] PIO_TIMER_ROUTINE pTimerRoutine,
  [in] PVOID             pContext
);

Параметры

[in] pDeviceObject

Указатель на объект устройства, представляющий устройство, на котором может истекать время ожидания операций ввода-вывода. Этот параметр должен указывать на системную структуру типа DEVICE_OBJECT. При вызове подпрограммы обратного вызова таймера ввода-вывода драйвер класса портов передает этот указатель в качестве первого из двух параметров вызова. Дополнительные сведения см. в разделе "Примечания".

[in] pTimerRoutine

Указатель на подпрограмму обратного вызова таймера ввода-вывода, предоставляемую драйвером. Дополнительные сведения см. в разделе "Примечания".

[in] pContext

Указатель на контекст, зависящий от драйвера. При вызове подпрограммы обратного вызова таймера ввода-вывода драйвер класса порта передает этот указатель в качестве второго из двух параметров вызова. Дополнительные сведения см. в разделе "Примечания".

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

PcRegisterIoTimeout возвращает STATUS_SUCCESS, если вызов был выполнен успешно. В противном случае возвращается соответствующий код ошибки. В следующей таблице показаны некоторые возможные коды ошибок.

Код возврата Описание
STATUS_INSUFFICIENT_RESOURCES
 Возможно, указывает на то, что в драйвере класса порта произошел сбой выделения памяти.
STATUS_UNSUCCESSFUL
 Возможно, указывает, что обратный вызов таймера с тем же сочетанием объекта устройства, подпрограммы обратного вызова таймера ввода-вывода и контекста уже зарегистрирован.

Комментарии

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

После того как драйвер вызывает PcRegisterIoTimeout, драйвер класса port вызывает подпрограмму обратного вызова таймера ввода-вывода драйвера примерно один раз в секунду, пока устройство остается активным. (Устройство активируется запросом IRP_MN_START_DEVICE и деактивируется запросом IRP_MN_STOP_DEVICE.)

Драйвер может отключить таймер, вызвав PcUnregisterIoTimeout.

Одновременно можно зарегистрировать только один обратный вызов таймера с определенным сочетанием объекта устройства, подпрограммы обратного вызова таймера ввода-вывода и контекста.

Значение параметра pContext определяется драйвером адаптера, но драйвер обычно задает этот параметр так, чтобы он указывал на объект, например miniport, miniport-stream или объект адаптера.

Параметр pTimerRoutine имеет тип PIO_TIMER_ROUTINE, который определен в ntddk.h как

  VOID
    (*PIO_TIMER_ROUTINE)(
      IN PDEVICE_OBJECT  DeviceObject,
      IN PVOID  Context
      );

Параметры DeviceObject и Context являются теми же значениями, которые драйвер адаптера ранее передал в качестве параметров вызова в PcRegisterIoTimeout. Драйвер класса портов вызывает подпрограмму таймера в DISPATCH_LEVEL IRQL. Подпрограмма таймера не должна содержать страничный код.

Требования

Требование Значение
Минимальная версия клиента Системный драйвер PortCls реализует функцию PcRegisterIoTimeout в Microsoft Windows 98/Me, а также в операционных системах Windows 2000 и более поздних версий.
Целевая платформа Универсальное
Верхняя часть portcls.h (включая Portcls.h)
Библиотека Portcls.lib
IRQL PASSIVE_LEVEL

См. также раздел

DEVICE_OBJECT

PcUnregisterIoTimeout