NdisIMInitializeDeviceInstanceEx, fonction (ndis.h)
La fonction NdisIMInitializeDeviceInstanceEx lance l’opération d’initialisation pour un miniport virtuel et configure éventuellement des informations d’état sur le miniport virtuel pour les pilotes de protocole liés ultérieurement.
Syntaxe
NDIS_STATUS NdisIMInitializeDeviceInstanceEx(
[in] NDIS_HANDLE DriverHandle,
[in] PNDIS_STRING DriverInstance,
[in, optional] NDIS_HANDLE DeviceContext
);
Paramètres
[in] DriverHandle
Le pilote miniport que le fonction NdisMRegisterMiniportDriver retourne à 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 en tant que type UNICODE_STRING.
[in, optional] DeviceContext
Pointeur vers la mémoire fournie par l’appelant à configurer avec des informations de contexte de périphérique définies par le pilote sur le miniport virtuel, qui restent des pilotes de protocole de niveau supérieur qui se lient par la suite à ce miniport virtuel peuvent utiliser. Ce paramètre peut être NULL si le pilote intermédiaire n’a pas de zone de contexte de périphérique de ce type.
Valeur de retour
NdisIMInitializeDeviceInstanceEx peut retourner l’une des opérations suivantes :
| Retourner le code | Description |
|---|---|
|
NDIS a lancé l’opération d’initialisation pour le miniport virtuel du pilote intermédiaire. |
|
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. Un échec d’appel NdisIMInitializeDeviceInstanceEx d’un pilote intermédiaire NDIS empêche efficacement le chargement de ce pilote.
Avant d’appeler NdisIMInitializeDeviceInstanceEx, la fonction ProtocolBindAdapterEx du pilote intermédiaire doit être liée à tous les pilotes miniports sous-jacents requis pour que le pilote intermédiaire fonctionne. La fonction ProtocolBindAdapterEx peut allouer une zone à DeviceContext également, é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 a été collectée 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 un IRP IRP_MN_START_DEVICE pour démarrer l’appareil. Si NDIS ne reçoit pas d’IRP de ce type, 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 ne nécessite plus le miniport virtuel, le pilote intermédiaire doit appeler le pilote intermédiaire NdisIMCancelInitializeDeviceInstance fonction pour annuler l’initialisation du miniport virtuel. Par exemple, supposons qu’un pilote intermédiaire crée une miniport virtuelle 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 de la NdisMSetMiniportAttributes fonction et pour initialiser le miniport virtuel 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.
Après MiniportInitializeEx retourne le contrôle, la zone de contexte du périphérique du pilote intermédiaire, le cas échéant, peut contenir des données définies par un pilote intermédiaire qui permettent par la suite à tous les pilotes de protocole de niveau supérieur 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 d’appeler 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.