NdisIMRegisterLayeredMiniport, fonction (ndis.h)

Article
03/10/2023

Note NDIS 5. x a été déprécié 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 vers NDIS 6. x, consultez Portage des pilotes NDIS 5.x vers NDIS 6.0.

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

Syntaxe

NDIS_STATUS NdisIMRegisterLayeredMiniport(
  [in]  NDIS_HANDLE                    NdisWrapperHandle,
  [in]  PNDIS_MINIPORT_CHARACTERISTICS MiniportCharacteristics,
  [in]  UINT                           CharacteristicsLength,
  [out] PNDIS_HANDLE                   DriverHandle
);

Paramètres

[in] NdisWrapperHandle

Spécifie le handle retourné par NdisMInitializeWrapper.

[in] MiniportCharacteristics

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

        typedef struct _NDIS_MINIPORT_CHARACTERISTICS {
            UCHAR MajorNdisVersion;
            UCHAR MinorNdisVersion;
            UINT Reserved;
            W_CHECK_FOR_HANG_HANDLER CheckForHangHandler;
            W_DISABLE_INTERRUPT_HANDLER DisableInterruptHandler;
            W_ENABLE_INTERRUPT_HANDLER  EnableInterruptHandler;
            W_HALT_HANDLER HaltHandler;
            W_HANDLE_INTERRUPT_HANDLER  HandleInterruptHandler;
            W_INITIALIZE_HANDLER InitializeHandler;
            W_ISR_HANDLER ISRHandler;
            W_QUERY_INFORMATION_HANDLER QueryInformationHandler;
            W_RECONFIGURE_HANDLER ReconfigureHandler;
            W_RESET_HANDLER ResetHandler;
            W_SEND_HANDLER SendHandler; 
            W_SET_INFORMATION_HANDLER SetInformationHandler;
            W_TRANSFER_DATA_HANDLER TransferDataHandler;
        //
        // Version used is V4.0 or V5.0
        // with following members
        //
            W_RETURN_PACKET_HANDLER ReturnPacketHandler;
            W_SEND_PACKETS_HANDLER SendPacketsHandler;
            W_ALLOCATE_COMPLETE_HANDLER AllocateCompleteHandler;
        //
        // Version used is V5.0 with the following members
        //
            W_CO_CREATE_VC_HANDLER CoCreateVcHandler;
            W_CO_DELETE_VC_HANDLER CoDeleteVcHandler;
            W_CO_ACTIVATE_VC_HANDLER CoActivateVcHandler;
            W_CO_DEACTIVATE_VC_HANDLER CoDeactivateVcHandler;
            W_CO_SEND_PACKETS_HANDLER CoSendPacketsHandler;
            W_CO_REQUEST_HANDLER CoRequestHandler;
        //
        // Version used is V5.1 with the following members
        //
            W_CANCEL_SEND_PACKETS_HANDLER CancelSendPacketsHandler;
            W_MINIPORT_PNPEVENTNOTIFY_HANDLER PnPEventNotifyHandler;
            W_MINIPORT_SHUTDOWN_HANDLER AdapterShutdownHandler;
        } NDIS_MINIPORT_CHARACTERISTICS, *PNDIS_MINIPORT_CHARACTERISTICS;

Un pilote intermédiaire NDIS doit initialiser cette structure avec des zéros avant de configurer l’un des membres suivants :

MajorNdisVersion
Spécifie la version principale de la bibliothèque NDIS utilisée par le pilote. La valeur actuelle est 0x05, bien que la bibliothèque NDIS continue de prendre en charge les pilotes de miniport existants développés pour NDIS 4.0.
MinorNdisVersion
Spécifie la version mineure de la bibliothèque NDIS utilisée par le pilote. La valeur actuelle est 0x00, bien que NDIS continue de prendre en charge les pilotes existants.
Reserved
Ce membre est réservé à l’utilisation du système.
CheckForHangHandler
Spécifie le point d’entrée de la fonction MiniportCheckForHang de l’appelant, le cas échéant, ou NULL.
DisableInterruptHandler
Spécifie NULL.
EnableInterruptHandler
Spécifie NULL.
HaltHandler
Spécifie le point d’entrée de la fonction MiniportHalt de l’appelant.
HandleInterruptHandler
Spécifie NULL.
InitializeHandler
Spécifie le point d’entrée de la fonction MiniportInitialize de l’appelant.
ISRHandler
Spécifie NULL.
QueryInformationHandler
Spécifie le point d’entrée de la fonction MiniportQueryInformation de l’appelant.
ReconfigureHandler
Spécifie NULL.
ResetHandler
Spécifie le point d’entrée de la fonction MiniportReset de l’appelant.
SendHandler
Spécifie le point d’entrée de la fonction MiniportSend de l’appelant, de la fonction MiniportWanSend ou null si l’appelant fournit une fonction MiniportSendPackets .

Si le pilote prend en charge les envois multipacket ou les informations spécifiques au média, il définit le membre SendPacketsHandler à la place et définit ce membre sur NULL.
SetInformationHandler Spécifie le point d’entrée de la fonction MiniportSetInformation de l’appelant.
TransferDataHandler
Spécifie le point d’entrée de la fonction MiniportTransferData de l’appelant, le cas échéant, ou NULL. Cette fonction de pilote miniport est requise, sauf si l’appelant est le pilote d’une carte réseau WAN ou que l’appelant prend en charge les réceptions multipacket et, par conséquent, fournit le point d’entrée de sa fonction MiniportReturnPacket dans ReturnPacketHandler.
ReturnPacketHandler
Spécifie le point d’entrée de la fonction MiniportReturnPacket de l’appelant, le cas échéant, ou NULL.
SendPacketsHandler
Spécifie le point d’entrée de la fonction MiniportSendPackets de l’appelant, le cas échéant, ou NULL.
AllocateCompleteHandler
Spécifie NULL.
CoCreateVcHandler
Spécifie NULL.
CoDeleteVcHandler
Spécifie NULL.
CoActivateVcHandler
Spécifie NULL.
CoDeactivateVcHandler
Spécifie NULL.
CoSendPacketsHandler
Spécifie NULL.
CoRequestHandler
Spécifie NULL.
CancelSendPacketsHandler
Spécifie le point d’entrée de la fonction MiniportCancelSendPackets de l’appelant, le cas échéant, ou NULL. Les pilotes intermédiaires qui envoient des paquets en file d’attente pendant plus d’une seconde doivent inscrire une fonction MiniportCancelSendPackets .
PnPEventNotifyHandler
Spécifie le point d’entrée de la fonction MiniportPnPEventNotify de l’appelant. Les pilotes miniport NDIS 5.1 doivent inscrire une fonction MiniportPnPEventNotify . Les pilotes miniport « » qui ont un bord inférieur WDM doivent inscrire une fonction MiniportPnPEventNotify .
AdapterShutdownHandler
Spécifie le point d’entrée de la fonction MiniportShutdown de l’appelant, le cas échéant, ou NULL. Les pilotes intermédiaires NDIS 5.1 doivent inscrire une fonction MiniportShutdown . Les pilotes intermédiaires NDIS 5.1 doivent inscrire une fonction MiniportShutdown en appelant NdisIMRegisterLayeredMiniport- et non en appelant NdisMRegisterAdapterShutdownHandler.

[in] CharacteristicsLength

Spécifie la longueur en octets de la mémoire tampon des caractéristiques fournies par l’appelant. Selon la valeur de MajorNdisVersion, ce paramètre doit être sizeof(NDIS50_MINIPORT_CHARACTERISTICS) si le pilote fournit une structure NDIS50_MINIPORT_CHARACTERISTICS ou sizeof(NDIS40_MINIPORT_CHARACTERISTICS) si le pilote fournit une structure NDIS40_MINIPORT_CHARACTERISTICS.

Si le pilote inclut l’instruction de build NDIS50_MINIPORT (ou NDIS40_MINIPORT, le cas échéant) dans ses sources ou si l’enregistreur de pilotes utilise -NDIS50_MINIPORT (ou .. Commutateur de compilateur 40..), ce paramètre est défini lors de la génération du pilote.

[out] DriverHandle

Pointeur vers une variable dans laquelle NdisIMRegisterLayeredMiniport, si cet appel réussit, retourne un handle que l’appelant doit enregistrer. L’appelant doit ensuite passer ce handle à NdisIMInitializeDeviceInstance, généralement à partir de sa fonction ProtocolBindAdapter .

Valeur retournée

NdisIMRegisterLayeredMiniport retourne NDIS_STATUS_SUCCESS s’il a inscrit l’appelant en tant que pilote miniport, ou il peut retourner l’une des valeurs de status suivantes :

Code de retour	Description
NDIS_STATUS_BAD_CHARACTERISTICS	La valeur CharacteristicsLength est trop petite pour la MajorNdisVersion spécifiée dans la mémoire tampon sur MiniportCharacteristics.
NDIS_STATUS_BAD_VERSION	La MajorNdisVersion ou MajorNdisVersion spécifiée dans la structure des caractéristiques 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 en tant que pilote miniport.
NDIS_STATUS_FAILURE	Il s’agit d’une erreur par défaut status, retournée quand aucune des erreurs précédentes n’a provoqué l’échec de l’inscription. Par exemple, si la bibliothèque NDIS ne peut pas charger l’image du pilote et la verrouiller dans la mémoire système, elle retourne cette erreur.

Remarques

Tout pilote intermédiaire NDIS qui exporte à la fois les fonctions MiniportXxx et ProtocolXxx configure une structure de caractéristiques et appelle NdisIMRegisterLayeredMiniport à partir de sa fonction DriverEntry après que DriverEntry a appelé NdisMInitializeWrapper. Cette structure est copiée dans la requête NdisIMRegisterLayeredMiniport vers le stockage interne de la bibliothèque NDIS. Ainsi, une fois inscrit, un tel pilote ne peut pas modifier ses fonctions de gestionnaire.

Une fois qu’un tel pilote intermédiaire NDIS a appelé NdisIMRegisterLayeredMiniport avec succès, il doit appeler NdisRegisterProtocol pour inscrire ses fonctions ProtocolXxx auprès de la bibliothèque NDIS. Un tel pilote dispose généralement des fonctions ProtocolBindAdapter et ProtocolUnbindAdapter . Sa fonction ProtocolBindAdapter sera appelée ensuite lorsque le pilote de carte réseau sous-jacent aura été initialisé avec succès. ProtocolBindAdapter peut ensuite établir une liaison à ce pilote de carte réseau avec NdisOpenAdapter.

Un pilote intermédiaire NDIS doit avoir une fonction MiniportSendPackets si un pilote de carte réseau sous-jacente peut prendre en charge le multipacket envoie ou consomme des informations spécifiques au média, telles que les priorités de paquets, envoyées dans un tableau de paquets à partir d’un protocole de niveau supérieur. Un pilote intermédiaire NDIS doit avoir une fonction MiniportReturnPacket si un pilote de carte réseau sous-jacente peut prendre en charge des indications de réception multipacket ou indiquer des tableaux de paquets contenant des informations spécifiques au média. La bibliothèque NDIS gère les tableaux de paquets transférés entre un pilote de carte réseau sous-jacent et un protocole de niveau supérieur qui prend en charge uniquement les transferts de paquets uniques pour le compte d’un tel pilote intermédiaire.

Plateforme cible : universelle
Version : non pris en charge pour les pilotes NDIS 6.0 dans Windows Vista. Utilisez NdisMRegisterMiniportDriverà 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