Fonction PcAddAdapterDevice (portcls.h)
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 |