NdisRegisterProtocol-Funktion (ndis.h)

  • Artikel

Hinweis NDIS 5. x ist veraltet und wird durch NDIS 6 ersetzt. x. Informationen zur Entwicklung neuer NDIS-Treiber finden Sie unter Netzwerktreiber ab Windows Vista. Informationen zum Portieren von NDIS 5. x Treiber für NDIS 6. x, siehe Portieren von NDIS 5.x-Treibern zu NDIS 6.0.

NdisRegisterProtocol registriert die ProtocolXxx-Einstiegspunkte und den Namen eines NDIS-Treibers bei der NDIS-Bibliothek, wenn der Treiber initialisiert.

Syntax

void NdisRegisterProtocol(
  [out] PNDIS_STATUS                   Status,
  [out] PNDIS_HANDLE                   NdisProtocolHandle,
  [in]  PNDIS_PROTOCOL_CHARACTERISTICS ProtocolCharacteristics,
  [in]  UINT                           CharacteristicsLength
);

Parameter

[out] Status

Zeiger auf eine vom Aufrufer bereitgestellte Variable, die einer der folgenden Werte sein kann, wenn von dieser Funktion zurückgegeben wird:

  • NDIS_STATUS_SUCCESS
    Die NDIS-Bibliothek hat den Aufrufer als Protokolltreiber registriert.

  • NDIS_STATUS_BAD_CHARACTERISTICS
    Die CharacteristicsLength ist zu klein für die MajorNdisVersion , die im Puffer unter ProtocolCharacteristics angegeben ist.

  • NDIS_STATUS_BAD_VERSION
    Die im Puffer unter ProtocolCharacteristics angegebene MajorNdisVersion ist ungültig.

  • NDIS_STATUS_RESOURCES
    Ein Mangel an Ressourcen, möglicherweise Arbeitsspeicher, verhinderte, dass die NDIS-Bibliothek den Aufrufer registriert.

[out] NdisProtocolHandle

Zeiger auf eine vom Aufrufer bereitgestellte Variable, in der diese Funktion ein Handle zurückgibt, das den registrierten Treiber darstellt.

[in] ProtocolCharacteristics

Zeiger auf eine NDIS_PROTOCOL_CHARACTERISTICS Struktur, die vom Aufrufer eingerichtet wurde. Die Struktur bei ProtocolCharacteristics ist wie folgt definiert:

        typedef struct _NDIS_PROTOCOL_CHARACTERISTICS {
            UCHAR MajorNdisVersion;
            UCHAR MinorNdisVersion;
            UINT Reserved;
            OPEN_ADAPTER_COMPLETE_HANDLER OpenAdapterCompleteHandler;
            CLOSE_ADAPTER_COMPLETE_HANDLER CloseAdapterCompleteHandler;
            SEND_COMPLETE_HANDLER SendCompleteHandler;
            TRANSFER_DATA_COMPLETE_HANDLER TransferDataCompleteHandler;
            RESET_COMPLETE_HANDLER ResetCompleteHandler;
            REQUEST_COMPLETE_HANDLER RequestCompleteHandler;
            RECEIVE_HANDLER ReceiveHandler;
            RECEIVE_COMPLETE_HANDLER ReceiveCompleteHandler;
            STATUS_HANDLER StatusHandler;
            STATUS_COMPLETE_HANDLER StatusCompleteHandler;
            NDIS_STRING Name;
        //
        // MajorNdisVersion must be set to 0x04 or 0x05
        // with any of the following members.
        //
            RECEIVE_PACKET_HANDLER ReceivePacketHandler;
            BIND_HANDLER BindAdapterHandler;
            UNBIND_HANDLER UnbindAdapterHandler;
            PNP_EVENT_HANDLER PnPEventHandler;
            UNLOAD_PROTOCOL_HANDLER UnloadHandler;
        //
        // MajorNdisVersion must be set to 0x05 
        // with any of the following members.
        //
            CO_SEND_COMPLETE_HANDLER CoSendCompleteHandler;
            CO_STATUS_HANDLER CoStatusHandler;
            CO_RECEIVE_PACKET_HANDLER CoReceivePacketHandler;
            CO_AF_REGISTER_NOTIFY_HANDLER CoAfRegisterNotifyHandler;
        } NDIS_PROTOCOL_CHARACTERISTICS, *PNDIS_PROTOCOL_CHARACTERISTICS;

Der Treiber sollte diese Struktur mit Nullen initialisieren, bevor die folgenden Member eingerichtet werden:

  • MajorNdisVersion
    Gibt die Hauptversion der NDIS-Bibliothek an, die der Treiber verwendet. Der aktuelle Wert ist 0x05, obwohl die NDIS-Bibliothek weiterhin vorhandene Treiber unterstützt, die für NDIS V4.0 entwickelt wurden. NDIS unterstützt keine V3.0-Protokolle mehr.

  • MinorNdisVersion
    Gibt die nebenstehende NDIS-Version an. Der aktuelle Wert ist 0x00.

  • Reserved
    Dieses Element ist für die Systemverwendung reserviert.

  • OpenAdapterCompleteHandler
    Gibt den Einstiegspunkt der ProtocolOpenAdapterComplete-Funktion des Aufrufers an.

  • CloseAdapterCompleteHandler
    Gibt den Einstiegspunkt der ProtocolCloseAdapterComplete-Funktion des Aufrufers an.

  • SendCompleteHandler
    Gibt den Einstiegspunkt der ProtocolSendComplete-Funktion des Aufrufers an, falls vorhanden.

  • TransferDataCompleteHandler
    Gibt den Einstiegspunkt der ProtocolTransferDataComplete-Funktion des Aufrufers an, falls vorhanden.

  • ResetCompleteHandler
    Gibt den Einstiegspunkt der ProtocolResetComplete-Funktion des Aufrufers an.

  • RequestCompleteHandler
    Gibt den Einstiegspunkt der ProtocolRequestComplete-Funktion des Aufrufers an.

  • ReceiveHandler
    Gibt den Einstiegspunkt der ProtocolReceive-Funktion des Aufrufers an, falls vorhanden.

  • ReceiveCompleteHandler
    Gibt den Einstiegspunkt der ProtocolReceiveComplete-Funktion des Aufrufers an.

  • StatusHandler
    Gibt den Einstiegspunkt der ProtocolStatus-Funktion des Aufrufers an, falls vorhanden.

  • StatusCompleteHandler
    Gibt den Einstiegspunkt der ProtocolStatusComplete-Funktion des Aufrufers an.

  • Name
    Ein NDIS_STRING-Typ, der eine vom Aufrufer initialisierte Zählzeichenfolge im Systemstandardzeichensatz enthält, wobei der Treiber benannt wird. Bei Treibern unter Windows 2000 und höher enthält diese Zeichenfolge Unicode-Zeichen. Das heißt, für Windows 2000 und höher definiert NDIS den NDIS_STRING-Typ als UNICODE_STRING-Typ . Diese Zeichenfolge muss mit der in der Registrierung (unter Dienste) angegebenen übereinstimmen, als das Protokoll installiert wurde.

    NdisRegisterProtocol konvertiert die angegebene Zeichenfolge in Großbuchstaben, sodass ein Protokolltreiberschreiber nicht davon ausgehen kann, dass das Ändern der Groß-/Kleinschreibung eines bereits registrierten Protokollnamens einen eindeutigen Namen für den Treiber erzeugt.

  • ReceivePacketHandler
    Gibt den Einstiegspunkt der ProtocolReceivePacket-Funktion des Aufrufers an, falls vorhanden, oder NULL. Protokolle, die an einen beliebigen NIC-Treiber binden, der Multipacket-Empfangsanzeigen unterstützt, sollten eine ProtocolReceivePacket-Funktion bereitstellen, um ihre Leistung zu verbessern. Ein Protokoll, das sich ausschließlich an verbindungsorientierte Miniports bindet, kann diesen Member jedoch auch auf NULL festlegen.

  • BindAdapterHandler
    Gibt den Einstiegspunkt der ProtocolBindAdapter-Funktion des Aufrufers an. Aufrufer, die den Wert im MajorNdisVersion-Member auf 0x05 oder 0x04 festlegen, müssen eine ProtocolBindAdapter-Funktion bereitstellen und Plug & Play unterstützen. NDIS-Zwischentreiber müssen auch eine ProtocolBindAdapter-Funktion bereitstellen, die es diesen Zwischentreibern ermöglicht, NdisIMRegisterLayeredMiniport aufzurufen und die vollständige Treiberinitialisierung zurückzusetzen, bis die zugrunde liegenden NIC-Treiber initialisiert wurden.

  • UnbindAdapterHandler
    Gibt den Einstiegspunkt der ProtocolUnbindAdapter-Funktion des Aufrufers an. NDIS-Treiber, die eine ProtocolBindAdapter-Funktion bereitstellen, müssen auch eine ProtocolUnbindAdapter-Funktion bereitstellen.

  • PnPEventHandler
    Gibt den Einstiegspunkt der ProtocolPnPEvent-Funktion des Aufrufers an, falls vorhanden.

  • UnloadHandler
    Gibt den Einstiegspunkt der ProtocolUnbind-Funktion des Aufrufers an, falls vorhanden, oder NULL.

  • CoSendCompleteHandler
    Gibt den Einstiegspunkt der ProtocolCoSendComplete-Funktion des Aufrufers an, den ein verbindungsorientierter Client oder Anruf-Manager bereitstellen muss. Ein verbindungsorientierter Client stellt eine ProtocolSendComplete-Funktion bereit, wenn er sich auch an verbindungslose Miniports bindet.

  • CoStatusHandlerCoStatusHandler
    Gibt den Einstiegspunkt der ProtocolCoStatus-Funktion des Aufrufers an, den ein verbindungsorientierter Client oder Anruf-Manager bereitstellen muss. Ein verbindungsorientierter Client stellt eine ProtocolStatus-Funktion bereit, wenn er sich auch an verbindungslose Miniports bindet.

  • CoReceivePacketHandler
    Gibt den Einstiegspunkt der ProtocolCoReceivePacket-Funktion des Aufrufers an, den ein verbindungsorientierter Client oder Anruf-Manager bereitstellen muss. Ein verbindungsorientierter Client stellt eine ProtocolReceivePacket-Funktion und/oder ProtocolReceive - und ProtocolTransferDataComplete-Funktionen bereit, wenn er sich auch an verbindungslose Miniports bindet.

  • CoAfRegisterNotifyHandler
    Gibt den Einstiegspunkt der ProtocolAfRegisterNotify-Funktion des Aufrufers an, den ein verbindungsorientierter Client bereitstellen muss.

[in] CharacteristicsLength

Gibt die Größe der Struktur in Bytes unter ProtocolCharacteristics an. Wenn die Builddirektive -DNDIS50=1 oder -DNDIS40=1 in der Quelldatei vor #includeNdis.h angegeben wird, wird die sizeof(NDIS_PROTOCOL_CHARACTERISTICS) automatisch auf den entsprechenden Wert festgelegt. Wenn keine Direktive angegeben ist, geht NDIS davon aus, dass die V3.0-Merkmalsstruktur verwendet wird.

Die werte, die in den Membern MajorNdisVersion und MinorNdisVersion der Merkmalsstruktur festgelegt werden, müssen mit der Builddirektive konsistent sein, oder sie müssen 0x03 bzw. 0x00 sein.

Rückgabewert

Keine

Bemerkungen

Ein Protokolltreiber muss eine MajorNdisVersion von 0x05 (aktuelle Version) oder 0x04 angeben. NDIS unterstützt keine V.30-Protokolle mehr und lädt daher kein Protokoll, das eine MajorNdisVersion von 0x03 angibt.

Alle Protokolle müssen Plug & Play (PnP) fähig sein. Ein Protokoll muss daher Einstiegspunkte für BindAdapterHandler und UnbindAdapterHandler angeben. NDIS lädt kein Protokoll, das NULL für diese Handler angibt.

Um die bestmögliche Leistung zu erzielen, sollte jedes Protokoll, das sich über einem verbindungslosen NIC-Treiber befindet, der Multipacket-Empfangsvorgänge unterstützt, eine ProtocolReceivePacket-Funktion bereitstellen. Ein solcher Protokolltreiber muss auch eine ProtocolReceive-Funktion bereitstellen. Jeder verbindungslose NIC-Treiber, der Multipacket-Sendevorgänge unterstützt, weist wahrscheinlich auch auf Multipacket-Empfang hin.

Alle verbindungsorientierten Protokolle, ob Clients oder Aufruf-Manager, müssen eine ProtocolCoReceivePacket-Funktion registrieren. Clientprotokolle, die sich auch an verbindungslose NIC-Treiber binden, stellen auch ProtocolReceivePacket - und ProtocolReceive-Funktionen bereit. Verbindungsorientierte Protokolle müssen zusätzliche verbindungsorientierte Einstiegspunkte bei NDIS registrieren, indem sie entweder NdisClOpenAddressFamily für Clients oder NdisCmRegisterAddressFamily für Anruf-Manager über ihre ProtocolBindAdapter-Funktionen aufrufen.

Nach einem erfolgreichen Aufruf von NdisRegisterProtocol kann ein Treiber den Satz der bereitgestellten ProtocolXxx-Funktionen nicht ändern.

Ein erfolgreich registrierter Treiber sollte das bei NdisProtocolHandle zurückgegebene Handle speichern. Dies ist ein erforderlicher Parameter für andere NdisXxx-Funktionen , die der Treiber anschließend aufruft.

Nach einem erfolgreichen Aufruf von NdisRegisterProtocol gibt die DriverEntry-Funktion eines PnP-fähigen oder verbindungsorientierten Protokolls die Steuerung zurück, da die ProtocolBindAdapter-Funktion eines solchen Treibers anschließend ein oder mehrmals aufgerufen wird, um Bindungen an zugrunde liegende NIC(s) einzurichten. Andernfalls kann der Protokolltreiber NdisOpenAdapter aufrufen, um eine Bindung an den zugrunde liegenden NIC-Treiber einzurichten oder sich über einen beliebigen NDIS-Treiber zu setzen, der eine Reihe von NDIS MiniportXxx-Funktionen registriert hat.

Anforderungen

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

Weitere Informationen