PcAddAdapterDevice-Funktion (portcls.h)

Artikel
08/07/2023

Die PcAddAdapterDevice-Funktion fügt dem WDM-Gerätestapel ein Adaptergerät hinzu.

Syntax

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

Parameter

[in] DriverObject

Zeiger auf das Treiberobjekt. Dieser Zeiger wird als Parameter an den AddDevice-Handler des Adapters übergeben. Das Driver-Objekt ist eine Systemstruktur vom Typ DRIVER_OBJECT.

[in] PhysicalDeviceObject

Zeiger auf das Objekt des physischen Geräts (PDO) des Geräts. PortCls übergibt diesen Zeiger als Aufrufparameter an den AddDevice-Handler des Adapters. Die PDO ist eine Systemstruktur vom Typ DEVICE_OBJECT.

[in] StartDevice

Zeiger auf die Funktion, die das Betriebssystem aufruft, um das Gerät zu starten. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise" .

[in] MaxObjects

Gibt die maximale Anzahl von Untergeräte an, die durch Aufrufe von PcRegisterSubdevice registriert werden sollen. Diese Anzahl legt die Obergrenze auf die Gesamtanzahl von Miniportobjekten fest, die der Adaptertreiber instanziieren kann.

[in] DeviceExtensionSize

Gibt die Größe der Geräteerweiterung an. Verwenden Sie 0 (null) für die Standardgröße. Informationen zu den vom Benutzer bereitgestellten Erweiterungsgrößen finden Sie im folgenden Abschnitt "Hinweise ".

Rückgabewert

PcAddAdapterDevice gibt STATUS_SUCCESS zurück, wenn der Aufruf erfolgreich war. Andernfalls wird ein geeigneter Fehlercode zurückgegeben.

Hinweise

Diese Funktion übernimmt den größten Teil der Arbeit, die der AddDevice-Handler des Audioadaptertreibers ausführen muss. PcAddAdapterDevice erstellt das Geräteobjekt, initialisiert den Gerätekontext und fügt das Geräteobjekt an den Gerätestapel an.

Ein Adaptertreiber ruft PcAddAdapterDevice auf, wenn er einen Aufruf des AddDevice-Handlers empfängt. Der Adaptertreiber installiert den AddDevice-Handler in der Regel durch Aufrufen von PcInitializeAdapterDriver, obwohl der Treiber den Handler auch auf andere Wege installieren kann. PcAddAdapterDevice erstellt das funktionale Geräteobjekt (Functional Device Object, FDO) für die PDO, die an den AddDevice-Handler übergeben wurde.

DeviceExtensionSize ist in der Regel null. Einige Adaptertreiber müssen möglicherweise zusätzlichen Speicherplatz in der Geräteerweiterung reservieren. In diesem Fall sollten sie eine DeviceExtensionSize-Größe angeben, die größer als PORT_CLASS_DEVICE_EXTENSION_SIZE ist. Dies ist die Standardgröße. Jeder Wert größer als null und kleiner als PORT_CLASS_DEVICE_EXTENSION_SIZE ist unzulässig. Adaptertreiber können alle Teile der Geräteerweiterung nach dem Offset PORT_CLASS_DEVICE_EXTENSION_SIZE verwenden. Sie können auch Bytes im Offsetbereich von 16 bis einschließlich 31 in einem System mit 32-Bit-Adressierung und Bytes im Offsetbereich von 32 bis 63 in einem System mit 64-Bit-Adressierung verwenden. Wenn die Erweiterung als Array von ULONG_PTR betrachtet wird, stehen die Arrayelemente vier bis sieben zur Verwendung durch den Adaptertreiber zur Verfügung.

Der StartDevice-Parameter verweist auf eine Funktion vom Typ PCPFNSTARTDEVICE, die die Headerdatei portcls.h als definiert:

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

Weitere Informationen zu PcAddAdapterDevice und den Gerätestart- und AddDevice-Routinen des Adaptertreibers finden Sie unter Startsequenz.

Der folgende Beispielcode zeigt, wie ein Adaptertreiber den Parameter DeviceExtensionSize verwenden kann, um 64 Byte gerätespezifischer Erweiterungsdaten an das Ende des Speicherblocks anzufügen, den PortCls für den Gerätekontext zuweist:

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

Der obige PcAddAdapterDevice-Aufruf ähnelt dem Beispiel in Der Startsequenz, mit der Ausnahme, dass der letzte Parameter, der an PcAddAdapterDevice übergeben wird, ungleich null ist.

Der Adaptertreiber kann dann auf die gerätespezifischen Erweiterungsdaten zugreifen, wie im folgenden Codefragment gezeigt:

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

Die Variable FunctionalDeviceObject ist ein Zeiger auf die FDO des Audioadapters, und pMyExtensionData ist ein temporärer Zeiger auf die Erweiterungsdaten. Vermeiden Sie es, die FDO mit der PDO zu verwechseln, die zum PCI-Bustreiber gehört. Der Adaptertreiber darf keine Daten in der PDO ändern, da dadurch der Arbeitsspeicher des PCI-Bustreibers beschädigt wird und das System abstürzt.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Verfügbar ab Windows 2000.
Zielplattform	Universell
Header	portcls.h (portcls.h einschließen)
Bibliothek	Portcls.lib
IRQL	PASSIVE_LEVEL

Weitere Informationen