NdisIMInitializeDeviceInstanceEx, fonction (ndis.h)

Article
03/01/2024

La fonction NdisIMInitializeDeviceInstanceEx lance l’opération d’initialisation d’un miniport virtuel et configure éventuellement des informations d’état sur le miniport virtuel pour les pilotes de protocole liés ultérieurs.

Syntaxe

NDIS_STATUS NdisIMInitializeDeviceInstanceEx(
  [in]           NDIS_HANDLE  DriverHandle,
  [in]           PNDIS_STRING DriverInstance,
  [in, optional] NDIS_HANDLE  DeviceContext
);

Paramètres

[in] DriverHandle

Le pilote miniport gère que le La fonction NdisMRegisterMiniportDriver retourne dans NdisMiniportDriverHandle .

[in] DriverInstance

Pointeur vers un type NDIS_STRING qui décrit une chaîne comptée initialisée par l’appelant dans le jeu de caractères par défaut du système. La chaîne contient le nom de la clé de Registre dans laquelle le pilote stocke des informations sur un miniport virtuel et, éventuellement, des informations spécifiques à la liaison. Pour les pilotes Microsoft 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 .

[in, optional] DeviceContext

Pointeur vers la mémoire fournie par l’appelant à configurer avec des informations de contexte d’appareil définies par le pilote sur le miniport virtuel, que les pilotes de protocole de niveau supérieur qui se lient par la suite à ce miniport virtuel peuvent utiliser. Ce paramètre peut avoir la valeur NULL si le pilote intermédiaire n’a pas de zone de contexte d’appareil de ce type.

Valeur retournée

NdisIMInitializeDeviceInstanceEx peut retourner l’un des éléments suivants :

Code de retour	Description
NDIS_STATUS_SUCCESS	NDIS a lancé l’opération d’initialisation pour le miniport virtuel du pilote intermédiaire.
NDIS_STATUS_NOT_ACCEPTED	NdisIMInitializeDeviceInstanceEx a échoué, car l’appareil spécifié par DriverHandle a déjà été initialisé.

Remarques

Un pilote intermédiaire NDIS doit appeler NdisIMInitializeDeviceInstanceEx à partir de sa fonction ProtocolBindAdapterEx . L’échec de l’appel de NdisIMInitializeDeviceInstanceEx à partir d’un pilote intermédiaire NDIS empêche effectivement ce pilote de se charger correctement.

Avant d’appeler NdisIMInitializeDeviceInstanceEx, la fonction ProtocolBindAdapterEx du pilote intermédiaire doit être liée à tous les pilotes miniports sous-jacents requis pour le fonctionnement du pilote intermédiaire. La fonction ProtocolBindAdapterEx peut également allouer une zone sur DeviceContext , éventuellement la configurer avec des informations intermédiaires déterminées par le pilote sur les fonctionnalités de l’adaptateur miniport sous-jacent et qui ont été collectées par ProtocolBindAdapterEx. La fonction MiniportInitializeEx du pilote intermédiaire peut utiliser ces informations par la suite pour configurer cette zone de contexte avec des informations sur le miniport virtuel du pilote.

L’appel du pilote intermédiaire à NdisIMInitializeDeviceInstanceEx amène NDIS à appeler la fonction MiniportInitializeEx du pilote intermédiaire, si NDIS reçoit une IRP_MN_START_DEVICE IRP pour démarrer l’appareil. Si NDIS ne reçoit pas un tel IRP, NDIS n’appelle pas la fonction MiniportInitializeEx du pilote intermédiaire.

L’appel à MiniportInitializeEx peut se produire ultérieurement et n’est donc pas nécessairement dans le contexte de l’appel à NdisIMInitializeDeviceInstanceEx. Si NDIS n’appelle jamais MiniportInitializeEx pour le miniport virtuel référencé dans un appel à NdisIMInitializeDeviceInstanceEx et que le pilote intermédiaire n’a plus besoin du miniport virtuel, le pilote intermédiaire doit appeler le Fonction NdisIMCancelInitializeDeviceInstance pour annuler l’initialisation du miniport virtuel. Par exemple, supposons qu’un pilote intermédiaire crée un miniport virtuel en réponse à une liaison réussie à un adaptateur miniport sous-jacent. Si cette liaison est supprimée avant que NDIS appelle MiniportInitializeEx, le pilote intermédiaire doit appeler NdisIMCancelInitializeDeviceInstance pour annuler l’initialisation du miniport virtuel.

MiniportInitializeEx alloue toutes les ressources dont le pilote a besoin pour effectuer des opérations d’E/S réseau, telles que l’appel du Fonction NdisMSetMiniportAttributes et pour initialiser la miniport virtuelle du pilote à un état opérationnel. Ensuite, les pilotes de protocole de niveau supérieur peuvent se lier à son miniport virtuel lorsque l’initialisation du pilote intermédiaire est terminée avec succès.

Une fois que MiniportInitializeEx retourne le contrôle, la zone de contexte de périphérique du pilote intermédiaire, le cas échéant, peut contenir des données définies par le pilote intermédiaire qui permettent ensuite à tous les pilotes de protocole de niveau supérieur qui sont liés au même miniport virtuel d’accéder aux informations de cette zone de contexte. Un tel pilote de protocole de niveau supérieur peut interroger le contexte d’appareil fourni par le pilote intermédiaire avec le Fonction NdisIMGetBindingContext .

Avant que NDIS appelle la fonction MiniportInitializeEx d’un pilote intermédiaire, le pilote peut appeler NdisIMCancelInitializeDeviceInstance pour annuler l’opération d’initialisation.

Une fois que NDIS appelle la fonction MiniportInitializeEx d’un pilote intermédiaire, le pilote doit appeler NdisIMDeInitializeDeviceInstance pour inverser l’opération d’initialisation.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Pris en charge pour les pilotes NDIS 6.0 et NDIS 5.1 (voir NdisIMInitializeDeviceInstanceEx (NDIS 5.1)) dans Windows Vista. Pris en charge pour les pilotes NDIS 5.1 (consultez NdisIMInitializeDeviceInstanceEx (NDIS 5.1)) dans Windows XP.
Plateforme cible	Desktop (Expérience utilisateur)
En-tête	ndis.h (inclure Ndis.h)
Bibliothèque	Ndis.lib
IRQL	PASSIVE_LEVEL
Règles de conformité DDI	Irql_IM_Function(ndis)