NdisRegisterProtocol, fonction (ndis.h)

  • Article

Note NDIS 5. x a été déconseillé et est remplacé par NDIS 6. x. Pour le développement de nouveaux pilotes NDIS, consultez Pilotes réseau à partir de Windows Vista. Pour plus d’informations sur le portage de NDIS 5. x pilotes dans NDIS 6. x, consultez Portage des pilotes NDIS 5.x vers NDIS 6.0.

NdisRegisterProtocol inscrit le nom et les points d’entrée ProtocolXxx d’un pilote NDIS auprès de la bibliothèque NDIS lors de l’initialisation du pilote.

Syntaxe

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

Paramètres

[out] Status

Pointeur vers une variable fournie par l’appelant qui peut être l’une des valeurs suivantes au retour de cette fonction :

  • NDIS_STATUS_SUCCESS
    La bibliothèque NDIS a inscrit l’appelant en tant que pilote de protocole.

  • NDIS_STATUS_BAD_CHARACTERISTICS
    La valeur CharacteristicsLength est trop petite pour la MajorNdisVersion spécifiée dans la mémoire tampon à l’emplacement ProtocolCharacteristics.

  • NDIS_STATUS_BAD_VERSION
    Le MajorNdisVersion spécifié dans la mémoire tampon sur ProtocolCharacteristics n’est pas valide.

  • NDIS_STATUS_RESOURCES
    Une pénurie de ressources, éventuellement de mémoire, a empêché la bibliothèque NDIS d’inscrire l’appelant.

[out] NdisProtocolHandle

Pointeur vers une variable fournie par l’appelant dans laquelle cette fonction retourne un handle représentant le pilote inscrit.

[in] ProtocolCharacteristics

Pointeur vers une structure NDIS_PROTOCOL_CHARACTERISTICS configurée par l’appelant. La structure de ProtocolCharacteristics est définie comme suit :

        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;

Le pilote doit initialiser cette structure avec des zéros avant de configurer les membres suivants :

  • MajorNdisVersion
    Spécifie la version principale de la bibliothèque NDIS que le pilote utilise. La valeur actuelle est 0x05, bien que la bibliothèque NDIS continue de prendre en charge les pilotes existants développés pour NDIS V4.0. NDIS ne prend plus en charge les protocoles V3.0.

  • MinorNdisVersion
    Spécifie la version mineure de NDIS. La valeur actuelle est 0x00.

  • Reserved
    Ce membre est réservé à l’utilisation du système.

  • OpenAdapterCompleteHandler
    Spécifie le point d’entrée de la fonction ProtocolOpenAdapterComplete de l’appelant.

  • CloseAdapterCompleteHandler
    Spécifie le point d’entrée de la fonction ProtocolCloseAdapterComplete de l’appelant .

  • SendCompleteHandler
    Spécifie le point d’entrée de la fonction ProtocolSendComplete de l’appelant, le cas échéant.

  • TransferDataCompleteHandler
    Spécifie le point d’entrée de la fonction ProtocolTransferDataComplete de l’appelant, le cas échéant.

  • ResetCompleteHandler
    Spécifie le point d’entrée de la fonction ProtocolResetComplete de l’appelant.

  • RequestCompleteHandler
    Spécifie le point d’entrée de la fonction ProtocolRequestComplete de l’appelant.

  • ReceiveHandler
    Spécifie le point d’entrée de la fonction ProtocolReceive de l’appelant, le cas échéant.

  • ReceiveCompleteHandler
    Spécifie le point d’entrée de la fonction ProtocolReceiveComplete de l’appelant.

  • StatusHandler
    Spécifie le point d’entrée de la fonction ProtocolStatus de l’appelant, le cas échéant.

  • StatusCompleteHandler
    Spécifie le point d’entrée de la fonction ProtocolStatusComplete de l’appelant.

  • Nom
    Un NDIS_STRING type contenant une chaîne comptée initialisée de l’appelant, dans le jeu de caractères par défaut du système, nommant le pilote. Pour les pilotes Windows 2000 et versions ultérieures, cette chaîne contient des caractères Unicode. Autrement dit, pour Windows 2000 et versions ultérieures, NDIS définit le type NDIS_STRING comme un type UNICODE_STRING . Cette chaîne doit correspondre à celle spécifiée dans le Registre (sous Services) lorsque le protocole a été installé.

    NdisRegisterProtocol convertit la chaîne fournie en majuscules. Par conséquent, un enregistreur de pilote de protocole ne peut pas supposer que la modification de la casse d’un nom de protocole déjà inscrit crée un nom unique pour le pilote.

  • ReceivePacketHandler
    Spécifie le point d’entrée de la fonction ProtocolReceivePacket de l’appelant, le cas échéant, ou NULL. Les protocoles qui se lient à n’importe quel pilote de carte réseau prenant en charge les indications de réception multipacket doivent fournir une fonction ProtocolReceivePacket pour améliorer leurs performances. Toutefois, un protocole qui se lie exclusivement à des miniports orientés connexion peut également définir ce membre sur NULL.

  • BindAdapterHandler
    Spécifie le point d’entrée de la fonction ProtocolBindAdapter de l’appelant. Les appelants qui définissent la valeur dans le membre MajorNdisVersion sur 0x05 ou 0x04 doivent fournir une fonction ProtocolBindAdapter et prendre en charge Plug-and-Play. Les pilotes intermédiaires NDIS doivent également fournir une fonction ProtocolBindAdapter , qui permet à ces pilotes intermédiaires d’appeler NdisIMRegisterLayeredMiniport et de différer l’initialisation complète du pilote jusqu’à ce que les pilotes NIC sous-jacents aient été initialisés.

  • UnbindAdapterHandler
    Spécifie le point d’entrée de la fonction ProtocolUnbindAdapter de l’appelant. Les pilotes NDIS qui fournissent une fonction ProtocolBindAdapter doivent également fournir une fonction ProtocolUnbindAdapter .

  • PnPEventHandler
    Spécifie le point d’entrée de la fonction ProtocolPnPEvent de l’appelant, le cas échéant.

  • UnloadHandler
    Spécifie le point d’entrée de la fonction ProtocolUnbind de l’appelant, le cas échéant, ou NULL.

  • CoSendCompleteHandler
    Spécifie le point d’entrée de la fonction ProtocolCoSendComplete de l’appelant, qu’un client orienté connexion ou un gestionnaire d’appels doit fournir. Un client orienté connexion fournit une fonction ProtocolSendComplete s’il se lie également à des miniports sans connexion.

  • CoStatusHandlerCoStatusHandler
    Spécifie le point d’entrée de la fonction ProtocolCoStatus de l’appelant, qu’un client orienté connexion ou un gestionnaire d’appels doit fournir. Un client orienté connexion fournit une fonction ProtocolStatus s’il se lie également à des miniports sans connexion.

  • CoReceivePacketHandler
    Spécifie le point d’entrée de la fonction ProtocolCoReceivePacket de l’appelant, qu’un client orienté connexion ou un gestionnaire d’appels doit fournir. Un client orienté connexion fournit une fonction ProtocolReceivePacket et/ou des fonctions ProtocolReceive et ProtocolTransferDataComplete s’il se lie également à des miniports sans connexion.

  • CoAfRegisterNotifyHandler
    Spécifie le point d’entrée de la fonction ProtocolAfRegisterNotify de l’appelant, qu’un client orienté connexion doit fournir.

[in] CharacteristicsLength

Spécifie la taille en octets de la structure dans ProtocolCharacteristics. Si la directive de build -DNDIS50=1 ou -DNDIS40=1 est spécifiée dans le fichier source avant #includeNdis.h , la valeur sizeof(NDIS_PROTOCOL_CHARACTERISTICS) est automatiquement définie sur la valeur appropriée. Si aucune directive n’est spécifiée, NDIS suppose que la structure des caractéristiques V3.0 est utilisée.

Les valeurs définies dans les membres MajorNdisVersion et MinorNdisVersion de la structure des caractéristiques doivent être cohérentes avec la directive de build, ou elles doivent être 0x03 et 0x00, respectivement.

Valeur de retour

None

Remarques

Un pilote de protocole doit spécifier une MajorNdisVersion de 0x05 (la version actuelle) ou 0x04. NDIS ne prend plus en charge les protocoles V.30 et ne charge donc pas de protocole qui spécifie une MajorNdisVersion de 0x03.

Tous les protocoles doivent être compatibles Plug-and-Play (PnP). Un protocole doit donc spécifier des points d’entrée pour BindAdapterHandler et UnbindAdapterHandler. NDIS ne charge pas de protocole qui spécifie la valeur NULL pour ces gestionnaires.

Pour des performances optimales, tout protocole qui se superpose au-dessus d’un pilote de carte réseau sans connexion qui prend en charge les réceptions multipacket doit fournir une fonction ProtocolReceivePacket . Ce pilote de protocole doit également fournir une fonction ProtocolReceive . Tout pilote de carte réseau sans connexion qui prend en charge les envois multipacket est également susceptible d’indiquer des réceptions multipacket.

Tous les protocoles orientés connexion, qu’il s’agisse de clients ou de gestionnaires d’appels, doivent inscrire une fonction ProtocolCoReceivePacket . Les protocoles clients qui se lient eux-mêmes à des pilotes de carte réseau sans connexion fournissent également des fonctions ProtocolReceivePacket et ProtocolReceive . Les protocoles orientés connexion doivent inscrire des points d’entrée supplémentaires orientés connexion auprès de NDIS en appelant NdisClOpenAddressFamily pour les clients ou NdisCmRegisterAddressFamily pour les gestionnaires d’appels à partir de leurs fonctions ProtocolBindAdapter .

Après un appel réussi à NdisRegisterProtocol, un pilote ne peut pas modifier l’ensemble des fonctions ProtocolXxx qu’il a fournies.

Un pilote correctement inscrit doit enregistrer le handle retourné dans NdisProtocolHandle. Il s’agit d’un paramètre obligatoire pour d’autres fonctions NdisXxx que le pilote appelle par la suite.

Après un appel réussi à NdisRegisterProtocol, la fonction DriverEntry d’un protocole compatible PnP ou orienté connexion retourne le contrôle, car la fonction ProtocolBindAdapter d’un tel pilote sera appelée ultérieurement une ou plusieurs fois pour configurer les liaisons aux cartes réseau sous-jacentes. Sinon, le pilote de protocole peut appeler NdisOpenAdapter pour configurer une liaison au pilote de carte réseau sous-jacent ou pour se superposer au-dessus de tout pilote NDIS qui a inscrit un ensemble de fonctions NDIS MiniportXxx .

  • Plateforme cible : Universelle
  • Version : non pris en charge pour les pilotes NDIS 6.0 dans Windows Vista. Utilisez NdisRegisterProtocolDriverà la place. Pris en charge pour les pilotes NDIS 5.1 dans Windows Vista et Windows XP.

Configuration requise

Condition requise Valeur
En-tête ndis.h (inclure Ndis.h)
Bibliothèque Ndis.lib
IRQL PASSIVE_LEVEL

Voir aussi