SetupDiCreateDeviceInterfaceA, fonction (setupapi.h)
La fonction SetupDiCreateDeviceInterface inscrit une interface d’appareil sur un système local ou un système distant.
Syntaxe
WINSETUPAPI BOOL SetupDiCreateDeviceInterfaceA(
[in] HDEVINFO DeviceInfoSet,
[in] PSP_DEVINFO_DATA DeviceInfoData,
[in] const GUID *InterfaceClassGuid,
[in, optional] PCSTR ReferenceString,
[in] DWORD CreationFlags,
[out, optional] PSP_DEVICE_INTERFACE_DATA DeviceInterfaceData
);
Paramètres
[in] DeviceInfoSet
Handle vers un jeu d’informations d’appareil . Ce jeu contient un élément d’informations sur l’appareil qui représente l’appareil pour lequel inscrire une interface. Ce handle est généralement retourné par SetupDiGetClassDevs.
[in] DeviceInfoData
Pointeur vers une structure SP_DEVINFO_DATA qui spécifie l’élément d’informations d’appareil dans DeviceInfoSet.
[in] InterfaceClassGuid
Pointeur vers un GUID de classe qui spécifie la classe d’interface pour la nouvelle interface.
[in, optional] ReferenceString
Pointeur vers une chaîne terminée par NULL qui fournit une chaîne de référence. Ce pointeur est facultatif et peut être NULL. Les chaînes de référence sont utilisées uniquement par quelques pilotes de bus qui utilisent des interfaces d’appareil comme espaces réservés pour les appareils logiciels créés à la demande.
[in] CreationFlags
Réservé. Doit être égal à zéro.
[out, optional] DeviceInterfaceData
Pointeur vers une structure d'SP_DEVICE_INTERFACE_DATA initialisée par l’appelant pour recevoir des informations sur la nouvelle interface d’appareil. Ce pointeur est facultatif et peut être NULL. Si la structure est fournie, l’appelant doit définir la cbSize membre de cette structure sur sizeof(SP_DEVICE_INTERFACE_DATA) avant d’appeler cette fonction. Pour plus d’informations, consultez la section suivante Remarques.
Valeur de retour
SetupDiCreateDeviceInterface retourne TRUE si la fonction s’est terminée sans erreur. Si la fonction s’est terminée avec une erreur, elle retourne faux et le code d’erreur de l’échec peut être récupéré en appelant GetLastError.
Remarques
L’appelant de cette fonction doit être membre du groupe Administrateurs.
SetupDiCreateDeviceInterface inscrit une interface pour un appareil. Si un appareil a plusieurs interfaces, appelez cette fonction une fois pour chaque interface inscrite.
Si cette fonction inscrit correctement une interface pour l’appareil qui correspond à l’élément d’informations d’appareil spécifié, elle ajoute également l’interface à la liste d’interfaces associée à l’élément d’informations de l’appareil dans le jeu d’informations d’appareil spécifié.
Avant qu’une interface inscrite puisse être utilisée par les applications et d’autres composants système, l’interface doit être activée par le pilote de l’appareil.
Cette fonction crée une clé de Registre pour la nouvelle interface d’appareil. Les appelants de cette fonction peuvent accéder au stockage nonvolatile sous cette clé à l’aide de SetupDiOpenDeviceInterfaceRegKey.
Si SetupDiCreateDeviceInterface crée correctement une interface d’appareil, mais que la mémoire tampon fournie par l’appelant dans le paramètre DeviceInterfaceData n’est pas valide, cette fonction retourne FAUX et un appel ultérieur à GetLastError retourne ERROR_INVALID_USER_BUFFER. Toutefois, la fonction crée et inscrit la nouvelle interface d’appareil.
Note
L’en-tête setupapi.h définit SetupDiCreateDeviceInterface en tant qu’alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. Le mélange de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.
Exigences
| Exigence | Valeur |
|---|---|
| client minimum pris en charge | Disponible dans Microsoft Windows 2000 et versions ultérieures de Windows. |
| plateforme cible | Bureau |
| d’en-tête | setupapi.h (include Setupapi.h) |
| bibliothèque | Setupapi.lib |