SetupGetBinaryField, fonction (setupapi.h)
[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 SetupGetBinaryField récupère les données binaires d’une ligne dans une section de fichier INF, du champ spécifié jusqu’à la fin de la ligne.
Syntaxe
WINSETUPAPI BOOL SetupGetBinaryField(
[in] PINFCONTEXT Context,
[in] DWORD FieldIndex,
[in, out] PBYTE ReturnBuffer,
[in] DWORD ReturnBufferSize,
[in, out] LPDWORD RequiredSize
);
Paramètres
[in] Context
Contexte INF pour la ligne.
[in] FieldIndex
Index de base 1 du champ de départ dans la ligne spécifiée à partir de laquelle les données binaires doivent être récupérées. Les données binaires sont générées à partir de chaque champ, en commençant à ce stade jusqu’à la fin de la ligne. Chaque champ correspond à 1 octet et est en notation hexadécimale. Un FieldIndex de zéro n’est pas valide avec cette fonction.
[in, out] ReturnBuffer
Pointeur facultatif vers une mémoire tampon qui reçoit les données binaires. Vous devez vous assurer que la mémoire tampon de destination est de la même taille ou plus grande que la mémoire tampon source. 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.
[in] ReturnBufferSize
Taille de la mémoire tampon pointée par ReturnBuffer, en caractères. Ce nombre inclut la marque de fin Null .
[in, out] RequiredSize
Pointeur facultatif vers une variable qui reçoit la taille requise pour la mémoire tampon pointée vers ReturnBuffer, en caractères. Ce nombre inclut la marque de fin Null . Si la taille nécessaire est supérieure à la valeur spécifiée par ReturnBufferSize, la fonction échoue et un appel à GetLastError retourne ERROR_INSUFFICIENT_BUFFER.
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.
GetLastError retourne ERROR_INVALID_DATA si un champ récupéré par SetupGetBinaryField n’est pas un nombre hexadécimal valide dans la plage 0-FF.
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 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 des informations d’erreur étendues peuvent être obtenues en appelant GetLastError.
Pour mieux comprendre le fonctionnement de cette fonction, considérez la ligne suivante à partir d’un fichier INF.
X=34,FF,00,13
Si SetupGetBinaryField a été appelé sur la ligne précédente, les valeurs binaires 34, FF, 00 et 13 sont placées dans la mémoire tampon spécifiée par ReturnBuffer.
Pour la version Unicode de cette fonction, les tailles de mémoire tampon ReturnBufferSize et RequiredSize sont spécifiées en nombre de caractères. Ce nombre inclut la marque de fin Null . Pour la version ANSI de cette fonction, les tailles sont spécifiées en nombre d’octets.
Si cette fonction est appelée avec un ReturnBuffernull 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 des informations d’erreur étendues peuvent être obtenues en appelant GetLastError.
Ainsi, vous pouvez appeler la fonction une seule 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.
Configuration requise
| 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 |