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