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 pour un jeu d’informations d’appareil. Cet ensemble 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 de SP_DEVINFO_DATA qui spécifie l’élément d’informations sur l’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 de périphérique comme espaces réservés pour les périphériques logiciels créés à la demande.
[in] CreationFlags
Réservé. Doit être zéro.
[out, optional] DeviceInterfaceData
Pointeur vers une structure de 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 le membre cbSize de cette structure sur sizeof(SP_DEVICE_INTERFACE_DATA) avant d’appeler cette fonction. Pour plus d’informations, consultez la section Notes suivante.
Valeur retournée
SetupDiCreateDeviceInterface retourne TRUE si la fonction s’est terminée sans erreur. Si la fonction s’est terminée avec une erreur, elle retourne FALSE 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 en cours d’inscription.
Si cette fonction inscrit correctement une interface pour l’appareil qui correspond à l’élément d’informations sur l’appareil spécifié, elle ajoute également l’interface à la liste d’interface associée à l’élément d’informations sur l’appareil dans le jeu d’informations sur l’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 non volatile 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 FALSE et un appel ultérieur à GetLastError renvoie ERROR_INVALID_USER_BUFFER. Toutefois, la fonction crée et enregistre la nouvelle interface d’appareil.
Notes
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. La combinaison 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.
Configuration requise
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge | Disponible dans Microsoft Windows 2000 et versions ultérieures de Windows. |
| Plateforme cible | Desktop (Expérience utilisateur) |
| En-tête | setupapi.h (inclure Setupapi.h) |
| Bibliothèque | Setupapi.lib |