SetupGetLineTextA, fonction (setupapi.h)
[Cette fonction est disponible pour une utilisation dans les systèmes d’exploitation indiqués dans la section Configuration requise. Il peut être modifié ou indisponible dans les versions ultérieures. SetupAPI ne doit plus être utilisé pour installer des applications. Utilisez plutôt Windows Installer pour développer des programmes d’installation d’applications. SetupAPI continue d’être utilisé pour installer des pilotes de périphérique.]
La fonction SetupGetLineText retourne le contenu d’une ligne dans un fichier INF dans un formulaire compact. La ligne à récupérer peut être spécifiée par une structure INFCONTEXT retournée à partir d’une fonction SetupFindLineXXX, ou en passant explicitement le handle INF, la section et la clé de la ligne souhaitée.
Syntaxe
WINSETUPAPI BOOL SetupGetLineTextA(
[in] PINFCONTEXT Context,
[in] HINF InfHandle,
[in] PCSTR Section,
[in] PCSTR Key,
[in, out] PSTR ReturnBuffer,
[in] DWORD ReturnBufferSize,
[in, out] PDWORD RequiredSize
);
Paramètres
[in] Context
Contexte d’une ligne dans un fichier INF dont le texte doit être récupéré. Ce paramètre peut être NULL. Si context est NULL, InfHandle, Sectionet Clé doivent tous être spécifiés.
[in] InfHandle
Gérez le fichier INF à interroger. Ce paramètre peut être NULL. Ce paramètre n’est utilisé que si contexte est NULL. Si context est NULL, InfHandle, Sectionet Clé doivent tous être spécifiés.
[in] Section
Pointeur vers une chaîne null-terminated qui spécifie la section qui contient le nom de clé de la ligne dont le texte doit être récupéré. Ce paramètre peut être NULL. Ce paramètre n’est utilisé que si contexte est NULL. Si de contexte est NULL, InfHandle, Sectionet clé doivent être spécifiées.
[in] Key
Pointeur vers une chaîne null-terminated qui contient le nom de clé dont la chaîne associée doit être récupérée. Ce paramètre peut être NULL. Ce paramètre n’est utilisé que si contexte est NULL. Si de contexte est NULL, InfHandle, Sectionet clé doivent être spécifiées.
[in, out] ReturnBuffer
Si ce n'NULL, ReturnBuffer pointe vers une mémoire tampon dans laquelle cette fonction retourne le contenu de la ligne. La chaîne null-terminated ne doit pas dépasser la taille de la mémoire tampon de destination. Vous pouvez appeler la fonction une fois pour obtenir la taille de mémoire tampon requise, allouer la mémoire nécessaire, puis appeler la fonction une deuxième fois pour récupérer les données. Cette technique vous permet d’éviter les erreurs en raison d’une taille de mémoire tampon insuffisante. Consultez la section Remarques. Ce paramètre peut être NULL.
[in] ReturnBufferSize
Taille de la mémoire tampon pointée par le paramètre ReturnBuffer, en caractères. Cela inclut la la marque de fin de null.
[in, out] RequiredSize
S’il n'pasNULL, pointe vers une variable dans laquelle cette fonction retourne la taille requise pour la mémoire tampon pointée par le paramètre ReturnBuffer, en caractères. Cela inclut la la marque de fin de null. Si returnBuffer est spécifié et que la taille requise est supérieure à la valeur spécifiée dans le paramètre ReturnBufferSize, la fonction échoue et ne stocke pas les données dans la mémoire tampon.
Valeur de retour
Si la fonction réussit, la valeur de retour est une valeur différente de zéro.
Si la fonction échoue, la valeur de retour est égale à zéro. Pour obtenir des informations d’erreur étendues, appelez GetLastError.
Remarques
Si cette fonction est appelée avec un ReturnBuffer de NULL et un ReturnBufferSize de zéro, la fonction place la taille de mémoire tampon requise pour contenir les données spécifiées dans la variable pointée par RequiredSize. Si la fonction réussit dans ce cas, la valeur de retour est une valeur différente de zéro. Sinon, la valeur de retour est zéro et les informations d’erreur étendues peuvent être obtenues en appelant GetLastError.
Cette fonction retourne le contenu d’une ligne dans un format compact. Tous les espaces blancs superflus sont supprimés et les valeurs à plusieurs lignes sont converties en une seule chaîne contiguë. Par exemple, cette ligne :
HKLM, , PointerClass0, 1 \
; This is a comment
01, 02, 03
est retourné comme suit :
HKLM,,PointerClass0,1,01,02,03
Note
L’en-tête setupapi.h définit SetupGetLineText comme 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 | Windows XP [applications de bureau uniquement] |
| serveur minimum pris en charge | Windows Server 2003 [applications de bureau uniquement] |
| plateforme cible | Windows |
| d’en-tête | setupapi.h |
| bibliothèque | Setupapi.lib |
| DLL | Setupapi.dll |
| ensemble d’API | ext-ms-win-setupapi-inf-l1-1-0 (introduit dans Windows 8) |