Freigeben über

NdisMRegisterDevice-Funktion (ndis.h)

  • Artikel

Hinweis NDIS 5. x wurde veraltet und wird von NDIS 6 abgelöst. x. Informationen zur Entwicklung neuer NDIS-Treiber finden Sie unter Netzwerktreiber ab Windows Vista. Informationen zum Portieren von NDIS 5. x-Treiber auf NDIS 6. x, siehe Portieren von NDIS 5.x-Treibern zu NDIS 6.0.

Die NdisMRegisterDevice-Funktion erstellt ein benanntes Geräteobjekt und eine symbolische Verknüpfung zwischen dem Geräteobjekt und einem für den Benutzer sichtbaren Namen für dieses Gerät.

Syntax

NDIS_STATUS NdisMRegisterDevice(
  [in]  NDIS_HANDLE      NdisWrapperHandle,
  [in]  PNDIS_STRING     DeviceName,
  [in]  PNDIS_STRING     SymbolicName,
  [in]  PDRIVER_DISPATCH *MajorFunctions,
  [in]  PDEVICE_OBJECT   *pDeviceObject,
  [out] NDIS_HANDLE      *NdisDeviceHandle
);

Parameter

[in] NdisWrapperHandle

Gibt das von NdisMInitializeWrapper zurückgegebene Handle an.

[in] DeviceName

Zeiger auf einen NDIS_STRING Typ, der eine Unicode-Zeichenfolge mit NULL-Beendigung enthält, die das Geräteobjekt benennt. Die Zeichenfolge muss ein vollständiger Pfadname sein, z. B. \Device\DeviceName. Für Windows 2000 und höher definiert NDIS den NDIS_STRING Typ als UNICODE_STRING Typ.

[in] SymbolicName

Zeiger auf einen NDIS_STRING Typ, der eine Unicode-Zeichenfolge enthält, bei der es sich um den Win32-visible-Namen des registrierten Geräts handelt. In der Regel hat symbolicName das folgende Format: \DosDevices\SymbolicName.

[in] MajorFunctions

Zeiger auf ein Array mit einem oder mehreren Einstiegspunkten für die Dispatchroutinen des Gerätetreibers. Ein Treiber muss so viele separate Dispatcheinstiegspunkte festlegen wie die IRP_MJ_XXX-Codes , die der Treiber für das Geräteobjekt verarbeitet. Jede Dispatchroutine wird wie folgt deklariert:

NTSTATUS
(*PDRIVER_DISPATCH) (
    IN PDEVICE_OBJECT Device Object,
    IN PIRP Irp
)   ;

Ein Treiber darf keine Einstiegspunkte für Plug & Play- oder Energieverwaltungshandler bereitstellen, da das erstellte Geräteobjekt nicht für ein physisches Gerät ist und daher keine Plug & Play oder Energieverwaltungs-IRPs empfängt.

[in] pDeviceObject

Zeiger auf das neu erstellte Geräteobjekt, wenn der Aufruf erfolgreich ist.

[out] NdisDeviceHandle

Zeiger auf eine vom Aufrufer bereitgestellte Variable, in der diese Funktion, wenn sie erfolgreich ist, ein Handle an das Geräteobjekt zurückgibt. Dieses Handle ist ein erforderlicher Parameter für die NdisMDeregisterDevice-Funktion , die der Treiber anschließend aufruft.

Rückgabewert

NdisMRegisterDevice gibt STATUS_SUCCESS zurück, wenn es erfolgreich ist, NDIS_STATUS_NOT_SUPPORTED, wenn der Aufrufer kein NDIS-Miniporttreiber ist, oder einen Fehlercode, wenn er fehlschlägt.

Hinweise

Ein Zwischentreiber oder Miniporttreiber erfordert möglicherweise ein separates eigenständiges Geräteobjekt. Beispielsweise kann ein zwischengeschalteter Miniporttreiber ein eigenständiges Geräteobjekt erfordern, um die status einer zugrunde liegenden NIC zu überwachen, wenn der Miniporttreiber der NIC nicht ausgeführt wird. Um in einem solchen Fall die status der Netzwerkkarte abzurufen, sendet eine Benutzermodusanwendung oder ein Umgebungssubsystem ein IRP an das Geräteobjekt. Der IRP wird vom Zwischentreiber verarbeitet. Ohne das eigenständige Geräteobjekt ist die status der NIC nur verfügbar, wenn der Miniporttreiber der NIC aktiv ist und ausgeführt wird.

Ein Zwischentreiber oder Miniporttreiber erstellt ein Geräteobjekt, indem er NdisMRegisterDevice über seine DriverEntry-Funktion aufruft, nachdem DriverEntryNdisMInitializeWrapper aufgerufen hat. NdisMRegisterDevice erstellt ein benanntes Geräteobjekt und auch eine symbolische Verknüpfung zwischen dem Geräteobjektnamen und einem sichtbaren Benutzernamen für dieses Gerät. Wenn der Aufruf von NdisMRegisterDevice erfolgreich ist, ordnet der E/A-Manager Speicher im nicht ausgelagerten Pool für das Geräteobjekt selbst und für alle anderen Datenstrukturen zu, die dem Geräteobjekt zugeordnet sind, einschließlich der Geräteerweiterung des Treibers. Die Geräteerweiterung für ein mit NdisMRegisterDevice erstelltes Objekt ist für die Verwendung durch NDIS reserviert und kann nicht vom Treiber verwendet werden.

Ein Geräteobjekt, das mit NdisMRegisterDevice-Funktionen auf die gleiche Weise wie ein Geräteobjekt und eine symbolische Verknüpfung erstellt wurde, die mit IoCreateDevice bzw . IoCreateSymbolicLink erstellt wurden. Der Miniporttreiber ist für die Verarbeitung aller IRPs verantwortlich, die er für das Geräteobjekt empfängt. (NDIS verarbeitet alle Plug & Play- und Energieverwaltungs-IRPs, die an das Geräteobjekt gesendet werden.) Der Treiber verarbeitet IRPs, die an das Geräteobjekt gesendet werden, mithilfe von Dispatchroutinen, die er registriert hat, als er den MajorFunctions-Zeiger auf NdisMRegisterDevice bereitgestellt hat. Weitere Informationen zu Geräteobjekten, IRPs und Dispatchroutinen finden Sie unter Geräteobjekte und Gerätestapel, Behandeln von IRPs und Schreiben von Dispatchroutinen.

NDIS-Miniport- und Zwischentreiber sollten niemals IoCreateDevice oder IoCreateSymbolicLink aufrufen. Wenn ein NDIS-Treiber stattdessen ein Geräteobjekt erstellen muss, sollte er NdisMRegisterDevice aufrufen. Miniport- und Zwischentreiber sollten niemals versuchen, das Geräteobjekt über das objekt des physischen Geräts zu stapeln, indem IoAttachDevice aufgerufen wird.

Das mit NdisMRegisterDevice erstellte Geräteobjekt ist kein physisches Geräteobjekt und empfängt daher keine Plug & Play- oder Energieverwaltungs-IRPs. Aufrufer von NdisMRegisterDevice müssen daher Einstiegspunkte für Plug & Play- oder Energieverwaltungshandler in dem Array weglassen, auf das von MajorFunctions verwiesen wird.

Beachten Sie, dass der Treiber, der das Geräteobjekt erstellt hat, nicht entladen werden kann, wenn ein Handle für das Geräteobjekt geöffnet ist, das mit NdisMRegisterDevice erstellt wird. Eine Anwendung im Benutzermodus sollte daher eine der folgenden Aktionen ausführen:

  1. Wenn sich die Anwendung für die Geräteereignisbenachrichtigung auf dem zugrunde liegenden Gerät registriert, indem sie die Funktion RegisterDeviceNotification aufruft, geben Sie einen DBT_DEVTYP_HANDLE Typbenachrichtigungsfilter an. (Weitere Informationen zur Funktion RegisterDeviceNotification finden Sie in der Microsoft Windows SDK-Dokumentation.) Wenn die Anwendung anschließend ein DBT_DEVICEQUERYREMOVE-Ereignis für das Gerät empfängt, sollte die Anwendung das geöffnete Handle schließen.

  2. Wenn die Anwendung sich für die Geräteereignisbenachrichtigung auf dem zugrunde liegenden Gerät registriert, indem sie die Funktion RegisterDeviceNotification aufruft, geben Sie einen DBT_DEVTYP_DEVICEINTERFACE Typbenachrichtigungsfilter und GUID_NDIS_LAN_CLASS als GUID der Schnittstellenklasse an. Wenn die Anwendung anschließend ein DBT_DEVICEREMOVECOMPLETE-Ereignis für die Geräteschnittstelle empfängt, der das Handle entspricht, sollte die Anwendung das geöffnete Handle schließen.

Wenn der Aufruf eines Treibers an NdisMRegisterDevice fehlschlägt, kann der Treiber weiterhin laden oder nicht, je nachdem, wie wichtig das eigenständige Geräteobjekt für den Betrieb des Treibers ist.

  • Zielplattform: Universell
  • Version: Wird für NDIS 6.0-Treiber in Windows Vista nicht unterstützt. Verwenden Sie stattdessen NdisRegisterDeviceEx. Unterstützt für NDIS 5.1-Treiber in Windows Vista und Windows XP.

Anforderungen

Anforderung Wert
Header ndis.h (include Ndis.h)
Bibliothek Ndis.lib
IRQL PASSIVE_LEVEL

Weitere Informationen