MINIPORT_ADD_DEVICE fonction de rappel (ndis.h)

Article
08/07/2023

La fonction MiniportAddDevice permet à un pilote miniport d’établir une zone de contexte pour un appareil ajouté.

Note Vous devez déclarer la fonction à l’aide du type MINIPORT_ADD_DEVICE . Pour plus d’informations, consultez la section Exemples suivante.

Syntaxe

MINIPORT_ADD_DEVICE MiniportAddDevice;

NDIS_STATUS MiniportAddDevice(
  [in] NDIS_HANDLE NdisMiniportHandle,
  [in] NDIS_HANDLE MiniportDriverContext
)
{...}

Paramètres

[in] NdisMiniportHandle

Un handle NDIS qui identifie l’adaptateur miniport que le gestionnaire de Plug-and-Play (PnP) ajoute. NDIS transmet également ce handle au Fonction MiniportInitializeEx .

[in] MiniportDriverContext

Handle vers une zone de contexte allouée par le pilote où le pilote conserve les informations d’état et de configuration. Le pilote miniport a passé cette zone de contexte au Fonction NdisMRegisterMiniportDriver .

Valeur retournée

MiniportAddDevice retourne l’une des valeurs suivantes :

Code de retour	Description
NDIS_STATUS_SUCCESS	Le pilote miniport a correctement alloué les ressources dont il a besoin pour ajouter l’appareil.
NDIS_STATUS_RESOURCES	Le pilote miniport n’a pas pu allouer les ressources requises.
NDIS_STATUS_FAILURE	MiniportAddDevice a échoué pour des raisons autres que des ressources insuffisantes.

Si MiniportAddDevice échoue, NDIS n’appellera pas la fonction MiniportInitializeEx pour initialiser l’adaptateur miniport.

Remarques

La fonction MiniportAddDevice est une fonction facultative. Les pilotes miniports qui prennent en charge MSI-X doivent spécifier un point d’entrée pour cette fonction dans le NDIS_MINIPORT_PNP_CHARACTERISTICS structure.

MiniportAddDevice peut allouer une zone de contexte pour la gestion IRP_MN_FILTER_RESOURCE_REQUIREMENTS Paquets de demandes d’E/S (IRPs) qui sont Poignées de fonction MiniportFilterResourceRequirements . Les pilotes miniport spécifient la zone de contexte en initialisant un NDIS_MINIPORT_ADD_DEVICE_REGISTRATION_ATTRIBUTES structure, puis en appelant le Fonction NdisMSetMiniportAttributes . NDIS fournit ultérieurement ce handle de contexte au MiniportRemoveDevice, Fonctions MiniportFilterResourceRequirements, MiniportStartDevice et MiniportInitializeEx . Pour MiniportInitializeEx, le handle de contexte est passé dans le membre MiniportAddDeviceContext du NDIS_MINIPORT_INIT_PARAMETERS structure vers laquelle pointe le paramètre MiniportInitParameters .

Si le pilote miniport échoue à l’appel MiniportAddDevice après avoir alloué la zone de contexte, le pilote doit libérer la zone de contexte avant de revenir de MiniportAddDevice.

Les pilotes Miniport doivent utiliser une autre zone de contexte pour le membre MiniportAddDeviceContext de la structure NDIS_MINIPORT_ADD_DEVICE_REGISTRATION_ATTRIBUTES et le membre MiniportAdapterContext de la structure NDIS_MINIPORT_INIT_PARAMETERS . Des zones de contexte distinctes garantissent que les informations de la zone de contexte ne sont pas réinitialisées, ce qui peut se produire dans la fonction MiniportInitializeEx si l’adaptateur miniport est arrêté et réinitialisé.

Lorsque le gestionnaire PnP demande que NDIS supprime l’appareil, NDIS appelle la fonction MiniportRemoveDevice pour annuler les opérations effectuées par MiniportAddDevice .

NDIS appelle MiniportAddDevice à IRQL = PASSIVE_LEVEL.

Exemples

Pour définir une fonction MiniportAddDevice , vous devez d’abord fournir une déclaration de fonction qui identifie le type de fonction que vous définissez. Windows fournit un ensemble de types de fonctions pour les pilotes. La déclaration d’une fonction à l’aide des types de fonction permet à l’analyse du code pour les pilotes, le vérificateur de pilotes statique (SDV) et d’autres outils de vérification de trouver les erreurs, et il s’agit d’une exigence pour l’écriture de pilotes pour le système d’exploitation Windows.

Par exemple, pour définir une fonction MiniportAddDevice nommée « MyAddDevice », utilisez le type MINIPORT_ADD_DEVICE comme indiqué dans cet exemple de code :

MINIPORT_ADD_DEVICE MyAddDevice;

Ensuite, implémentez votre fonction comme suit :

_Use_decl_annotations_
NDIS_STATUS
 MyAddDevice(
    NDIS_HANDLE  NdisMiniportHandle,
    NDIS_HANDLE  MiniportDriverContext
    )
  {...}

Le type de fonction MINIPORT_ADD_DEVICE est défini dans le fichier d’en-tête Ndis.h. Pour identifier plus précisément les erreurs lors de l’exécution des outils d’analyse du code, veillez à ajouter l’annotation Use_decl_annotations à votre définition de fonction. L’annotation Use_decl_annotations garantit que les annotations appliquées au type de fonction MINIPORT_ADD_DEVICE dans le fichier d’en-tête sont utilisées. Pour plus d’informations sur la configuration requise pour les déclarations de fonction, consultez Déclaration de fonctions à l’aide de types de rôles de fonction pour les pilotes NDIS.

Pour plus d’informations sur Use_decl_annotations, consultez Annotating Function Behavior.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Pris en charge dans NDIS 6.0 et versions ultérieures.
Plateforme cible	Windows
En-tête	ndis.h (inclure Ndis.h)
IRQL	PASSIVE_LEVEL