Fonction PcRegisterIoTimeout (portcls.h)

Article
08/07/2023

La fonction PcRegisterIoTimeout inscrit une routine de rappel du minuteur d’E/S fournie par le pilote pour un objet d’appareil spécifié.

Une fois inscrit, le pilote de classe de port appelle le rappel du minuteur environ une fois par seconde tant que l’appareil reste actif.

Note Cette fonction est déconseillée pour les versions Windows 8 et ultérieures de Windows. Pour les systèmes Windows sur Arm, cette fonction est commentée dans le pilote de classe PortCls et est inaccessible.

Syntaxe

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

Paramètres

[in] pDeviceObject

Pointeur vers un objet d’appareil représentant un appareil sur lequel les opérations d’E/S peuvent expirer. Ce paramètre doit pointer vers une structure système de type DEVICE_OBJECT. Lors de l’appel de la routine de rappel du minuteur d’E/S, le pilote de classe de port transmet ce pointeur comme premier des deux paramètres d’appel. Pour plus d'informations, consultez la section Notes qui suit.

[in] pTimerRoutine

Pointeur vers la routine de rappel du minuteur d’E/S fournie par le pilote. Pour plus d'informations, consultez la section Notes qui suit.

[in] pContext

Pointeur vers le contexte spécifique au pilote. Lors de l’appel de la routine de rappel du minuteur d’E/S, le pilote de classe de port transmet ce pointeur en tant que deuxième des deux paramètres d’appel. Pour plus d'informations, consultez la section Notes qui suit.

Valeur retournée

PcRegisterIoTimeout retourne STATUS_SUCCESS si l’appel a réussi. Sinon, elle retourne un code d’erreur approprié. Le tableau suivant présente certains des codes d’erreur possibles.

Code de retour	Description
STATUS_INSUFFICIENT_RESOURCES	Indique éventuellement qu’une allocation de mémoire a échoué à l’intérieur du pilote de classe de port.
STATUS_UNSUCCESSFUL	Indique éventuellement qu’un rappel de minuteur avec la même combinaison d’objet d’appareil, de routine de rappel d’E/S et de contexte est déjà inscrit.

Remarques

Un pilote d’adaptateur appelle la fonction PcRegisterIoTimeout pour activer un minuteur de surveillance basse résolution. Les pilotes utilisent cette fonction principalement pour surveiller les appareils qui n’ont aucun moyen de générer eux-mêmes un événement s’ils ne parviennent pas à effectuer une opération d’E/S initiée précédemment dans un intervalle de temps maximal.

Une fois que le pilote a appelé PcRegisterIoTimeout, le pilote de classe de port appelle la routine de rappel du minuteur d’E/S du pilote environ une fois par seconde, tant que l’appareil reste actif. (L’appareil est activé par une demande IRP_MN_START_DEVICE et désactivé par une demande de IRP_MN_STOP_DEVICE.)

Le pilote peut désactiver le minuteur en appelant PcUnregisterIoTimeout.

Un seul rappel du minuteur avec une combinaison particulière d’objet d’appareil, de routine de rappel du minuteur d’E/S et de contexte peut être inscrit à la fois.

La signification du paramètre pContext est déterminée par le pilote de l’adaptateur, mais le pilote définit généralement ce paramètre pour qu’il pointe vers un objet tel que le miniport, le miniport-stream ou l’objet adaptateur.

Le paramètre pTimerRoutine est de type PIO_TIMER_ROUTINE, qui est défini dans ntddk.h pour être

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

Les paramètres DeviceObject et Context sont les mêmes valeurs que celles que le pilote de l’adaptateur a précédemment passées en tant que paramètres d’appel à PcRegisterIoTimeout. Le pilote de classe de port appelle la routine du minuteur au DISPATCH_LEVEL IRQL. La routine du minuteur ne doit pas contenir de code paginable.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Le pilote système PortCls implémente la fonction PcRegisterIoTimeout dans Microsoft Windows 98/Me et dans les systèmes d’exploitation Windows 2000 et ultérieur.
Plateforme cible	Universal
En-tête	portcls.h (include Portcls.h)
Bibliothèque	Portcls.lib
IRQL	PASSIVE_LEVEL

Voir aussi

DEVICE_OBJECT

PcUnregisterIoTimeout