SetupDiRegisterDeviceInfo, fonction (setupapi.h)

La fonction SetupDiRegisterDeviceInfo est le gestionnaire par défaut pour la requête DIF_REGISTERDEVICE .

Syntaxe

WINSETUPAPI BOOL SetupDiRegisterDeviceInfo(
  [in]            HDEVINFO           DeviceInfoSet,
  [in, out]       PSP_DEVINFO_DATA   DeviceInfoData,
  [in]            DWORD              Flags,
  [in, optional]  PSP_DETSIG_CMPPROC CompareProc,
  [in, optional]  PVOID              CompareContext,
  [out, optional] PSP_DEVINFO_DATA   DupDeviceInfoData
);

Paramètres

[in] DeviceInfoSet

Handle d’un jeu d’informations d’appareil qui contient un élément d’informations sur l’appareil qui représente l’appareil à inscrire. Le jeu d’informations sur l’appareil ne doit pas contenir d’éléments distants.

[in, out] DeviceInfoData

Pointeur vers une structure de SP_DEVINFO_DATA qui spécifie l’élément d’informations sur l’appareil dans DeviceInfoSet. Il s’agit d’un paramètre IN-OUT, car DeviceInfoData.DevInst peut être mis à jour avec une nouvelle valeur de handle lors du retour.

[in] Flags

Valeur d’indicateur qui contrôle la façon dont l’appareil est inscrit, qui peut être zéro ou la valeur suivante :

SPRDI_FIND_DUPS

Recherchez un appareil existant précédemment instance qui correspond à l’appareil représenté par DeviceInfoData. Si cet indicateur n’est pas spécifié, l’appareil instance est inscrit, qu’un appareil instance existe déjà pour lui.

Si l’appelant fournit CompareProc, l’appelant doit également définir cet indicateur.

[in, optional] CompareProc

Pointeur vers une fonction de rappel de comparaison à utiliser dans la détection des doublons. Ce paramètre est facultatif et peut être NULL. Si ce paramètre est spécifié, la fonction de rappel est appelée pour chaque appareil instance de la même classe que l’appareil instance en cours d’inscription. Le prototype de la fonction de rappel est le suivant :

typedef  DWORD (CALLBACK* PSP_DETSIG_CMPPROC) (
    IN HDEVINFO  DeviceInfoSet,
    IN PSP_DEVINFO_DATA  NewDeviceData,
    IN PSP_DEVINFO_DATA  ExistingDeviceData,
    IN PVOID  CompareContextOPTIONAL
    );

La fonction compare doit retourner ERROR_DUPLICATE_FOUND si elle constate que les deux appareils sont des doublons. Sinon, elle doit retourner NO_ERROR. Si une autre erreur se produit, la fonction de rappel doit retourner le code ERROR_* approprié pour indiquer l’échec.

Si CompareProc n’est pas spécifié et que la détection de duplication est demandée, un comportement de comparaison par défaut est utilisé. La valeur par défaut consiste à comparer la signature de détection du nouvel appareil avec la signature de détection de tous les autres appareils de la classe . La signature de détection est contenue dans le descripteur de ressource spécifique à la classe de la configuration du journal de démarrage de l’appareil.

[in, optional] CompareContext

Pointeur vers une mémoire tampon de contexte fournie par l’appelant qui est passée à la fonction de rappel. Ce paramètre est ignoré si CompareProc n’est pas spécifié.

[out, optional] DupDeviceInfoData

Pointeur vers une structure de SP_DEVINFO_DATA pour recevoir des informations sur un appareil en double instance, le cas échéant, découvert à la suite d’une tentative d’inscription de cet appareil. Ce paramètre est facultatif et peut être NULL. Si ce paramètre est spécifié, l’appelant doit définir DupDeviceInfoData.cbSize à sizeof(SP_DEVINFO_DATA). Cette valeur est renseignée si la fonction retourne FALSE et si GetLastError retourne ERROR_DUPLICATE_FOUND. Cet élément d’informations sur l’appareil est ajouté en tant que membre du DeviceInfoSet spécifié, s’il n’est pas déjà membre. Si DupDeviceInfoData n’est pas spécifié, le doublon n’est pas ajouté à l’ensemble d’informations de l’appareil.

Si vous appelez cette fonction lors de la gestion d’une demande de DIF_REGISTERDEVICE , le paramètre DupDeviceInfoData doit être NULL.

Valeur retournée

La fonction retourne TRUE si elle réussit. Sinon, elle retourne FALSE et l’erreur journalisée peut être récupérée avec un appel à GetLastError.

Remarques

SetupDiRegisterDeviceInfo est principalement conçu pour inscrire un appareil non PnP auprès du gestionnaire Plug-and-Play (PnP) sur un ordinateur local. Bien que SetupDiRegisterDeviceInfo n’échoue pas si le jeu d’informations d’appareil est destiné à un ordinateur distant, le résultat est d’une utilisation limitée, car le jeu d’informations sur l’appareil ne peut pas être utilisé ultérieurement avec des demandes d’installation DIF_Xxx ou des fonctions SetupDiXxx qui ne prennent pas en charge les opérations sur un ordinateur distant. Par exemple, l’appel de SetupDiCreateDevRegKey pour exécuter une section INF pour un appareil nouvellement inscrit sur un ordinateur distant échoue.

N’appelez pas directement cette fonction pour les instances d’appareil PnP. Les instances d’appareil PnP sont automatiquement inscrites par le système d’exploitation. Toutefois, vous devez inscrire des instances d’appareil non PnP de l’une des manières suivantes :

1. Si votre application d’installation utilise une demande de DIF_DETECT pour détecter correctement un appareil, elle doit également utiliser une demande DIF_REGISTERDEVICE pour inscrire l’appareil instance. La demande doit être gérée de la manière par défaut. (Par défaut, SetupDiCallClassInstaller appelle d’abord le programme d’installation de classe et les co-programmes d’installation de classe pour effectuer la détection des doublons et inscrire l’appareil instance. Si ces programmes d’installation n’inscrivent pas l’appareil instance, SetupDiCallClassInstaller appelle SetupDiRegisterDeviceInfo pour effectuer la détection des doublons et inscrire l’appareil instance.)
2. Si votre application d’installation crée un instance d’appareil (par exemple, en appelant SetupDiCreateDeviceInfo) mais qu’elle n’effectue pas de détection des doublons, votre application d’installation doit utiliser une demande de DIF_REGISTERDEVICE pour inscrire l’appareil instance. La demande doit être gérée par défaut comme décrit précédemment.
3. Si votre application d’installation crée un appareil et effectue une détection des doublons, votre application d’installation doit utiliser une demande de DIF_REGISTERDEVICE mais doit empêcher SetupDiCallClassInstaller d’appeler SetupDiRegisterDeviceInfo. Pour empêcher SetupDiCallClassInstaller d’appeler SetupDiRegisterDeviceInfo, définissez l’indicateur DI_NODI_DEFAULTACTION dans le membre Flags de la structure SP_DEVINSTALL_PARAMS de l’appareil instance.

   Si SetupDiCallClassInstaller retourne TRUE pour la demande de DIF_REGISTERDEVICE, le programme d’installation de classe ou les co-programmes d’installation de classe ont inscrit l’appareil instance. Dans ce cas, l’application d’installation peut continuer à installer l’appareil.

   Si SetupDiCallClassInstaller retourne FALSE pour la demande de DIF_REGISTERDEVICE, le programme d’installation de classe ou les co-programmes d’installation de classe n’ont pas inscrit l’appareil instance. Dans ce cas, l’application d’installation doit effectuer l’une des opérations suivantes, en fonction de la dernière erreur retournée par GetLastError pour la requête :

   • Si la dernière erreur est ERROR_DI_DO_DEFAULT, l’application d’installation peut appeler directement SetupDiRegisterDeviceInfo et fournir un CompareProc pour effectuer la détection des doublons. Si cet appel réussit et qu’aucun doublon n’est trouvé, l’installation de l’appareil peut continuer. Si un doublon est trouvé, SetupDiRegisterDeviceInfo retourne FALSE, et l’application d’installation doit arrêter l’installation de l’appareil.
   • Si la dernière erreur n’est pas ERROR_DI_DO_DEFAULT, l’application d’installation doit mettre fin à l’installation de l’appareil.
   L’appelant de SetupDiRegisterDeviceInfo doit être membre du groupe Administrateurs.

Configuration requise

Voir aussi

DIF_REGISTERDEVICE

SP_DEVINFO_DATA

SP_DEVINSTALL_PARAMS