Skip to content

Latest commit

 

History

History
135 lines (100 loc) · 5.23 KB

nf-portcls-pcregisteriotimeout.md

File metadata and controls

135 lines (100 loc) · 5.23 KB
Raw
UID title description old-location tech.root ms.date keywords ms.keywords req.header req.include-header req.target-type req.target-min-winverclnt req.target-min-winversvr req.kmdf-ver req.umdf-ver req.ddi-compliance req.unicode-ansi req.idl req.max-support req.namespace req.assembly req.type-library req.lib req.dll req.irql targetos req.typenames f1_keywords topic_type api_type api_location api_name
NF:portcls.PcRegisterIoTimeout
PcRegisterIoTimeout function (portcls.h)
The PcRegisterIoTimeout function registers a driver-supplied I/O-timer callback routine for a specified device object.
audio\pcregisteriotimeout.htm
audio
05/08/2018
PcRegisterIoTimeout function
PcRegisterIoTimeout, PcRegisterIoTimeout function [Audio Devices], audio.pcregisteriotimeout, audpc-routines_1a63a1fa-c80a-4fe4-87d6-95543e6e2f1d.xml, portcls/PcRegisterIoTimeout
portcls.h
Portcls.h
Universal
The PortCls system driver implements the PcRegisterIoTimeout function in Microsoft Windows 98/Me and in Windows 2000 and later operating systems.
Portcls.lib
PASSIVE_LEVEL
Windows
PcRegisterIoTimeout
portcls/PcRegisterIoTimeout
APIRef
kbSyntax
LibDef
Portcls.lib
Portcls.dll
PcRegisterIoTimeout

PcRegisterIoTimeout function

-description

The PcRegisterIoTimeout function registers a driver-supplied I/O-timer callback routine for a specified device object.

Once registered, the port-class driver calls the timer callback approximately once per second for as long as the device remains active.

Note  This function is deprecated for Windows 8 and later versions of Windows. For Windows on Arm systems, this function is commented out in the PortCls class driver and is inaccessible.
 

-parameters

-param pDeviceObject [in]

Pointer to a device object representing a device on which I/O operations can time out. This parameter must point to a system structure of type DEVICE_OBJECT. When calling the I/O-timer callback routine, the port class driver passes this pointer as the first of two call parameters. For more information, see the following Remarks section.

-param pTimerRoutine [in]

Pointer to the driver-supplied I/O-timer callback routine. For more information, see the following Remarks section.

-param pContext [in]

Pointer to the driver-specific context. When calling the I/O-timer callback routine, the port class driver passes this pointer as the second of two call parameters. For more information, see the following Remarks section.

-returns

PcRegisterIoTimeout returns STATUS_SUCCESS if the call was successful. Otherwise, it returns an appropriate error code. The following table shows some of the possible error codes.

Return code Description
STATUS_INSUFFICIENT_RESOURCES
 Possibly indicates that a memory allocation failed inside the port-class driver.
STATUS_UNSUCCESSFUL
 Possibly indicates that a timer callback with the same combination of device object, I/O-timer callback routine, and context is already registered.

-remarks

An adapter driver calls the PcRegisterIoTimeout function to enable a low-resolution watchdog timer. Drivers use this function primarily to monitor devices that have no means to generate an event themselves if they fail to complete a previously initiated I/O operation within some maximum time interval.

After the driver calls PcRegisterIoTimeout, the port-class driver calls the driver's I/O-timer callback routine approximately once per second for as long as the device remains active. (The device is activated by an IRP_MN_START_DEVICE request and deactivated by an IRP_MN_STOP_DEVICE request.)

The driver can disable the timer by calling PcUnregisterIoTimeout.

Only one timer callback with a particular combination of device object, I/O-timer callback routine, and context can be registered at a time.

The meaning of the pContext parameter is determined by the adapter driver, but the driver typically sets this parameter to point to an object such as the miniport, miniport-stream, or adapter object.

The pTimerRoutine parameter is of type PIO_TIMER_ROUTINE, which is defined in ntddk.h to be

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

The DeviceObject and Context parameters are the same values that the adapter driver previously passed as call parameters to PcRegisterIoTimeout. The port-class driver calls the timer routine at IRQL DISPATCH_LEVEL. The timer routine must not contain pageable code.

-see-also

DEVICE_OBJECT

PcUnregisterIoTimeout