NdisMRegisterDevice, 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.

La fonction NdisMRegisterDevice crée un objet d’appareil nommé et un lien symbolique entre l’objet d’appareil et un nom visible par l’utilisateur pour cet appareil.

Syntaxe

NDIS_STATUS NdisMRegisterDevice(
  [in]  NDIS_HANDLE      NdisWrapperHandle,
  [in]  PNDIS_STRING     DeviceName,
  [in]  PNDIS_STRING     SymbolicName,
  [in]  PDRIVER_DISPATCH *MajorFunctions,
  [in]  PDEVICE_OBJECT   *pDeviceObject,
  [out] NDIS_HANDLE      *NdisDeviceHandle
);

Paramètres

[in] NdisWrapperHandle

Spécifie le handle retourné par NdisMInitializeWrapper.

[in] DeviceName

Pointeur vers un type NDIS_STRING contenant une chaîne Unicode terminée par null qui nomme l’objet d’appareil. La chaîne doit être un nom de chemin d’accès complet, par exemple, \Device\DeviceName. Pour Windows 2000 et versions ultérieures, NDIS définit le type NDIS_STRING comme un type UNICODE_STRING .

[in] SymbolicName

Pointeur vers un type NDIS_STRING contenant une chaîne Unicode qui est le nom visible win32 de l’appareil en cours d’inscription. En règle générale, symbolName a le format suivant : \DosDevices\SymbolicName.

[in] MajorFunctions

Pointeur vers un tableau d’un ou plusieurs points d’entrée pour les routines de répartition du pilote de périphérique. Un pilote doit définir autant de points d’entrée de répartition distincts que les codes IRP_MJ_XXX que le pilote gère pour l’objet d’appareil. Chaque routine de distribution est déclarée comme suit :

NTSTATUS
(*PDRIVER_DISPATCH) (
    IN PDEVICE_OBJECT Device Object,
    IN PIRP Irp
)   ;

Un pilote ne doit pas fournir de points d’entrée pour les gestionnaires de Plug-and-Play ou de gestion de l’alimentation, car l’objet d’appareil créé n’est pas destiné à un appareil physique et ne reçoit donc pas de Plug-and-Play ou de gestion de l’alimentation.

[in] pDeviceObject

Pointeur vers l’objet d’appareil nouvellement créé si l’appel réussit.

[out] NdisDeviceHandle

Pointeur vers une variable fournie par l’appelant dans laquelle cette fonction, si elle réussit, retourne un handle à l’objet d’appareil. Ce handle est un paramètre obligatoire pour la fonction NdisMDeregisterDevice que le pilote appelle par la suite.

Valeur retournée

NdisMRegisterDevice retourne STATUS_SUCCESS si elle réussit, NDIS_STATUS_NOT_SUPPORTED si l’appelant n’est pas un pilote miniport NDIS, ou un code d’échec en cas d’échec.

Remarques

Un pilote intermédiaire ou un pilote miniport peut nécessiter un objet d’appareil autonome distinct. Par exemple, un pilote de miniport intermédiaire peut nécessiter un objet d’appareil autonome pour surveiller la status d’une carte réseau sous-jacente lorsque le pilote miniport de la carte réseau n’est pas opérationnel. Pour obtenir le status de la carte réseau dans ce cas, une application en mode utilisateur ou un sous-système environnemental envoie un IRP à l’objet d’appareil. L’IRP est traité par le pilote intermédiaire. Sans l’objet d’appareil autonome, la status de la carte réseau est disponible uniquement lorsque le pilote miniport de la carte réseau est opérationnel.

Un pilote intermédiaire ou un pilote miniport crée un objet d’appareil en appelant NdisMRegisterDevice à partir de sa fonction DriverEntry après que DriverEntry a appelé NdisMInitializeWrapper. NdisMRegisterDevice crée un objet d’appareil nommé et un lien symbolique entre le nom de l’objet d’appareil et un nom visible par l’utilisateur pour cet appareil. Si l’appel à NdisMRegisterDevice réussit, le gestionnaire d’E/S alloue le stockage dans le pool non paginé pour l’objet d’appareil lui-même et pour toutes les autres structures de données associées à l’objet d’appareil, y compris l’extension de périphérique du pilote. L’extension d’appareil d’un objet créé avec NdisMRegisterDevice est réservée à une utilisation par NDIS et ne peut pas être utilisée par le pilote.

Un objet d’appareil créé avec NdisMRegisterDevice fonctionne de la même manière qu’un objet d’appareil et un lien symbolique créés avec IoCreateDevice et IoCreateSymbolicLink, respectivement. Le pilote miniport est responsable du traitement de tous les IRP qu’il reçoit pour l’objet d’appareil. (NDIS traite tous les Plug-and-Play et les IIP de gestion de l’alimentation envoyés à l’objet d’appareil.) Le pilote traite les IRP envoyés à l’objet d’appareil à l’aide des routines de répartition qu’il a inscrites lorsqu’il a fourni le pointeur MajorFunctions vers NdisMRegisterDevice. Pour plus d’informations sur les objets d’appareil, les IIP et les routines de répartition, consultez Device Objects and Device Stacks, Handling IRPs et Writing Dispatch Routines.

Les pilotes NDIS miniport et intermédiaires ne doivent jamais appeler IoCreateDevice ou IoCreateSymbolicLink. Au lieu de cela, si un pilote NDIS doit créer un objet d’appareil, il doit appeler NdisMRegisterDevice. Les pilotes miniport et intermédiaires ne doivent jamais tenter d’empiler l’objet d’appareil sur l’objet d’appareil physique en appelant IoAttachDevice.

L’objet d’appareil créé avec NdisMRegisterDevice n’est pas un objet d’appareil physique et ne reçoit donc pas de Plug-and-Play ou de gestion de l’alimentation. Les appelants de NdisMRegisterDevice doivent donc omettre les points d’entrée pour les gestionnaires Plug-and-Play ou Power Management dans le tableau vers lequel est pointé MajorFunctions.

Notez que, si un handle de l’objet d’appareil créé avec NdisMRegisterDevice est ouvert, le pilote qui a créé l’objet d’appareil ne peut pas être déchargé. Une application en mode utilisateur doit donc effectuer l’une des opérations suivantes :

  1. Lorsque l’application s’inscrit pour la notification d’événement d’appareil sur l’appareil sous-jacent en appelant la fonction RegisterDeviceNotification , spécifiez un filtre de notification de type DBT_DEVTYP_HANDLE. (Pour plus d’informations sur la fonction RegisterDeviceNotification, consultez la documentation Microsoft Windows SDK.) Si l’application reçoit par la suite un événement DBT_DEVICEQUERYREMOVE pour l’appareil, l’application doit fermer le handle ouvert.

  2. Lorsque l’application s’inscrit pour la notification d’événement d’appareil sur l’appareil sous-jacent en appelant la fonction RegisterDeviceNotification , spécifiez un filtre de notification de type DBT_DEVTYP_DEVICEINTERFACE et GUID_NDIS_LAN_CLASS comme GUID de classe d’interface. Si l’application reçoit ensuite un événement DBT_DEVICEREMOVECOMPLETE pour l’interface de l’appareil auquel correspond le handle, l’application doit fermer le handle ouvert.

Si l’appel d’un pilote à NdisMRegisterDevice échoue, le pilote peut continuer à charger ou non, en fonction de la critique de l’objet d’appareil autonome pour le fonctionnement du pilote.

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