Fonction PcAddAdapterDevice (portcls.h)

Article
08/07/2023

La fonction PcAddAdapterDevice ajoute un périphérique adaptateur à la pile de périphériques WDM.

Syntaxe

PORTCLASSAPI NTSTATUS PcAddAdapterDevice(
  [in] PDRIVER_OBJECT   DriverObject,
  [in] PDEVICE_OBJECT   PhysicalDeviceObject,
  [in] PCPFNSTARTDEVICE StartDevice,
  [in] ULONG            MaxObjects,
  [in] ULONG            DeviceExtensionSize
);

Paramètres

[in] DriverObject

Pointeur vers l’objet pilote. Ce pointeur est passé en tant que paramètre au gestionnaire AddDevice de l’adaptateur. L’objet driver est une structure système de type DRIVER_OBJECT.

[in] PhysicalDeviceObject

Pointeur vers l’objet d’appareil physique (PDO) de l’appareil. PortCls transmet ce pointeur en tant que paramètre d’appel au gestionnaire AddDevice de l’adaptateur. L’AOP est une structure système de type DEVICE_OBJECT.

[in] StartDevice

Pointeur vers la fonction que le système d’exploitation appelle pour démarrer l’appareil. Pour plus d’informations, consultez la section Notes suivante.

[in] MaxObjects

Spécifie le nombre maximal de sous-appareils à inscrire par les appels à PcRegisterSubdevice. Ce nombre définit la limite supérieure au nombre total d’objets miniport que le pilote de l’adaptateur peut instancier.

[in] DeviceExtensionSize

Spécifie la taille de l’extension d’appareil. Utilisez zéro pour la taille par défaut. Consultez la section Remarques suivante pour connaître les tailles d’extension fournies par l’utilisateur.

Valeur retournée

PcAddAdapterDevice retourne STATUS_SUCCESS si l’appel a réussi. Sinon, elle retourne un code d’erreur approprié.

Remarques

Cette fonction effectue la plupart du travail que le gestionnaire AddDevice du pilote de l’adaptateur audio doit effectuer. PcAddAdapterDevice crée l’objet d’appareil, initialise le contexte de l’appareil et l’attache à la pile d’appareils.

Un pilote d’adaptateur appelle PcAddAdapterDevice lorsqu’il reçoit un appel à son gestionnaire AddDevice . Le pilote de l’adaptateur installe généralement le gestionnaire AddDevice en appelant PcInitializeAdapterDriver, bien que le pilote puisse également installer le gestionnaire par d’autres moyens. PcAddAdapterDevice crée l’objet d’appareil fonctionnel (FDO) pour le PDO qui a été passé au gestionnaire AddDevice .

DeviceExtensionSize est généralement égal à zéro. Certains pilotes d’adaptateur peuvent avoir besoin de réserver de l’espace supplémentaire dans l’extension de périphérique, auquel cas ils doivent spécifier une valeur DeviceExtensionSize supérieure à PORT_CLASS_DEVICE_EXTENSION_SIZE, qui est la taille par défaut. Toute valeur supérieure à zéro et inférieure à PORT_CLASS_DEVICE_EXTENSION_SIZE est illégale. Les pilotes d’adaptateur sont libres d’utiliser n’importe quelle partie de l’extension de périphérique après le décalage PORT_CLASS_DEVICE_EXTENSION_SIZE. Ils sont également libres d’utiliser des octets dans la plage de décalage de 16 à 31 inclus dans un système avec un adressage 32 bits et des octets dans la plage de décalage de 32 à 63 dans un système avec adressage 64 bits. Si l’extension est considérée comme un tableau de ULONG_PTR, les éléments de tableau quatre à sept peuvent être utilisés par le pilote de l’adaptateur.

Le paramètre StartDevice pointe vers une fonction de type PCPFNSTARTDEVICE, que le fichier d’en-tête portcls.h définit comme suit :

  NTSTATUS
    (*PCPFNSTARTDEVICE)(
      IN PDEVICE_OBJECT  DeviceObject,
      IN PIRP  Irp,
      IN PRESOURCELIST  ResourceList
      );

Pour plus d’informations sur PcAddAdapterDevice et les routines de démarrage de périphérique et d’AddDevice du pilote de l’adaptateur, consultez Séquence de démarrage.

L’exemple de code suivant montre comment un pilote d’adaptateur peut utiliser le paramètre DeviceExtensionSize pour ajouter 64 octets de données d’extension spécifiques au périphérique à la fin du bloc de stockage que PortCls alloue pour le contexte de périphérique :

  #define MY_EXTENSION_SIZE  64
  NTSTATUS  ntstatus = PcAddAdapterDevice(DriverObject, PhysicalDeviceObject,
                                          MyStartDevice, MAX_MINIPORTS,
                                          MY_EXTENSION_SIZE + PORT_CLASS_DEVICE_EXTENSION_SIZE);

L’appel PcAddAdapterDevice ci-dessus est similaire à l’exemple de la séquence de démarrage, sauf que le dernier paramètre passé à PcAddAdapterDevice est différent de zéro.

Le pilote de l’adaptateur peut ensuite accéder aux données d’extension spécifiques au périphérique, comme indiqué dans le fragment de code suivant :

  PVOID  pMyExtensionData = (PVOID)((PCHAR)FunctionalDeviceObject->DeviceExtension +
                                              PORT_CLASS_DEVICE_EXTENSION_SIZE);

La variable FunctionalDeviceObject est un pointeur vers le FDO de la carte audio, et pMyExtensionData est un pointeur temporaire vers les données d’extension. Évitez de confondre le FDO avec le PDO, qui appartient au pilote de bus PCI. Le pilote d’adaptateur ne doit pas modifier les données dans le PDO, car cela endommage la mémoire détenue par le pilote de bus PCI et peut provoquer un blocage du système.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Disponible à partir de Windows 2000.
Plateforme cible	Universal
En-tête	portcls.h (include Portcls.h)
Bibliothèque	Portcls.lib
IRQL	PASSIVE_LEVEL

Voir aussi