SetupGetLineTextA, fonction (setupapi.h)

Article
03/01/2024

[Cette fonction peut être utilisée dans les systèmes d’exploitation indiqués dans la section Configuration requise. Il sera 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 les pilotes de périphérique.]

La fonction SetupGetLineText retourne le contenu d’une ligne dans un fichier INF sous forme compacte. 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, la section et la clé INF 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 a la valeur NULL, InfHandle, Section et Key doivent tous être spécifiés.

[in] InfHandle

Gérez le fichier INF à interroger. Ce paramètre peut être NULL. Ce paramètre est utilisé uniquement si Context a la valeur NULL. Si Context a la valeur NULL, InfHandle, Section et Key doivent tous être spécifiés.

[in] Section

Pointeur vers une chaîne terminée par null 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 est utilisé uniquement si Context a la valeur NULL. Si Context a la valeur NULL, InfHandle, Section et Key doivent être spécifiés.

[in] Key

Pointeur vers une chaîne terminée par null 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 est utilisé uniquement si Context a la valeur NULL. Si Context a la valeur NULL, InfHandle, Section et Key doivent être spécifiés.

[in, out] ReturnBuffer

Si ce n’est pas null, ReturnBuffer pointe vers une mémoire tampon dans laquelle cette fonction retourne le contenu de la ligne. La chaîne terminée par null 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. À l’aide de cette technique, vous pouvez éviter les erreurs dues à une taille de mémoire tampon insuffisante. Consultez la section Notes. Ce paramètre peut être NULL.

[in] ReturnBufferSize

Taille de la mémoire tampon vers laquelle pointe le paramètre ReturnBuffer , en caractères. Cela inclut la marque de fin null .

[in, out] RequiredSize

Si ce n’est pas NULL, 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 marque de fin 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 retournée

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étaillées sur l’erreur, appelez GetLastError.

Remarques

Si cette fonction est appelée avec un ReturnBuffernull 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 des 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 multilignes sont converties en une seule chaîne contiguë. Par exemple, cette ligne :

HKLM, , PointerClass0, 1 \
; This is a comment
01, 02, 03

serait retourné comme suit :

HKLM,,PointerClass0,1,01,02,03

Notes

L’en-tête setupapi.h définit SetupGetLineText 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	Windows XP [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau uniquement]
Plateforme cible	Windows
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)