SetupGetStringFieldA, 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 SetupGetStringField récupère une chaîne à partir du champ spécifié d’une ligne dans un fichier INF.
Syntaxe
WINSETUPAPI BOOL SetupGetStringFieldA(
[in] PINFCONTEXT Context,
[in] DWORD FieldIndex,
[in, out] PSTR ReturnBuffer,
[in] DWORD ReturnBufferSize,
[out] PDWORD RequiredSize
);
Paramètres
[in] Context
Pointeur vers le contexte d’une ligne dans un fichier INF.
[in] FieldIndex
Index de base 1 du champ dans la ligne spécifiée à partir de laquelle la chaîne doit être récupérée. Utilisez un FieldIndex de 0 pour récupérer une clé de chaîne, le cas échéant.
[in, out] ReturnBuffer
Pointeur facultatif vers une mémoire tampon qui reçoit la chaîne null-terminated. Vous devez vous assurer que la mémoire tampon de destination est de la même taille ou supérieure à la mémoire tampon source. Ce paramètre peut être NULL. Consultez la section Remarques.
[in] ReturnBufferSize
Taille de la mémoire tampon pointée par ReturnBuffer , en caractères. Cela inclut la la marque de fin de null.
[out] RequiredSize
Pointeur facultatif vers une variable qui reçoit la taille requise pour la mémoire tampon pointée par le paramètre ReturnBuffer, en caractères. Si ReturnBuffer est spécifié et que la taille réelle nécessaire est supérieure à la valeur spécifiée par ReturnBufferSize, la fonction échoue et ne stocke pas la chaîne dans la mémoire tampon. Dans ce cas, un appel à GetLastError retourne ERROR_INSUFFICIENT_BUFFER. Pour la version Unicode de cette fonction, la taille requise est en caractères. Cela inclut la la marque de fin de null.
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 nécessaire 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.
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.
Notez que la longueur maximale de n’importe quelle chaîne unique spécifiée dans une section Chaînes INF est de 512 caractères, y compris la fin NULL. Si la longueur de la chaîne est supérieure à 512, elle est tronquée et aucune erreur n’est retournée. La longueur maximale de toute chaîne concaténée créée à partir d’un ou plusieurs jetons %strkey% est de 4 096 caractères.
Note
L’en-tête setupapi.h définit SetupGetStringField 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-1 (introduit dans Windows 10, version 10.0.14393) |