Méthode IDriverEntry ::OnDeviceAdd (wudfddi.h)

Article
03/01/2024

[Avertissement : UMDF 2 est la dernière version d’UMDF et remplace UMDF 1. Tous les nouveaux pilotes UMDF doivent être écrits à l’aide d’UMDF 2. Aucune nouvelle fonctionnalité n’est ajoutée à UMDF 1 et la prise en charge d’UMDF 1 est limitée sur les versions plus récentes de Windows 10. Les pilotes Windows universels doivent utiliser UMDF 2. Pour plus d’informations, consultez Prise en main avec UMDF.]

La méthode OnDeviceAdd ajoute un nouvel appareil à un système.

Syntaxe

HRESULT OnDeviceAdd(
  [in] IWDFDriver           *pWdfDriver,
  [in] IWDFDeviceInitialize *pWdfDeviceInit
);

Paramètres

[in] pWdfDriver

Pointeur vers l’interface IWDFDriver pour l’objet de pilote parent auquel appartient le nouvel appareil.

[in] pWdfDeviceInit

Pointeur vers l’interface IWDFDeviceInitialize que le pilote utilise pour initialiser l’appareil nouvellement créé.

Valeur retournée

OnDeviceAdd retourne S_OK si l’opération réussit. Sinon, cette méthode retourne l’un des codes d’erreur définis dans Winerror.h. Le pilote ne doit retourner S_OK que s’il a correctement appelé la méthode IWDFDriver ::CreateDevice pour créer l’objet d’appareil framework. Si le pilote retourne un code d’erreur, UMDF détruit toute la pile de périphériques, que le pilote soit un pilote de filtre ou un pilote de fonction.

Remarques

Un nouvel objet d’appareil est créé pour chaque appareil chargé dans le processus hôte du pilote. Lorsqu’un nouvel appareil arrive dans le système, l’infrastructure appelle OnDeviceAdd pour informer le pilote de l’arrivée et passe les interfaces IWDFDriver et IWDFDeviceInitialize dans l’appel. Le pilote peut appeler la méthode IWDFDeviceInitialize ::RetrieveDevicePropertyStore pour rechercher les informations sur l’appareil fournies dans le cadre de l’installation de l’appareil. Le pilote doit appeler la méthode IWDFDriver ::CreateDevice pour configurer et créer l’appareil. Si le pilote n’appelle pas correctement IWDFDriver ::CreateDevice avant qu’il ne retourne S_OK, UMDF détermine que le comportement du pilote est incorrect et met fin au processus hôte.

Tout pilote dont la méthode OnDeviceAdd retourne S_OK recevra par la suite un appel à sa méthode IPnpCallbackHardware ::OnReleaseHardware lorsque l’UMDF déchire la pile des appareils.

N’utilisez pas l’interface IWDFDeviceInitialize vers laquelle pointe le paramètre pWdfDeviceInit après que le pilote a appelé IWDFDriver ::CreateDevice.

Pour plus d’informations, consultez Ajout d’un appareil.