SetupGetBinaryField-Funktion (setupapi.h)
[Diese Funktion ist für die Verwendung in den betriebssystemen verfügbar, die im Abschnitt "Anforderungen" angegeben sind. Es kann in nachfolgenden Versionen geändert oder entfernt werden. SetupAPI sollte nicht mehr zum Installieren von Anwendungen verwendet werden. Verwenden Sie stattdessen den Windows Installer zum Entwickeln von Installationsprogrammen für Anwendungen. SetupAPI wird weiterhin zum Installieren von Gerätetreibern verwendet.]
Die SetupGetBinaryField-Funktion ruft Binärdaten aus einer Zeile in einem INF-Dateiabschnitt ab, vom angegebenen Feld bis zum Ende der Zeile.
Syntax
WINSETUPAPI BOOL SetupGetBinaryField(
[in] PINFCONTEXT Context,
[in] DWORD FieldIndex,
[in, out] PBYTE ReturnBuffer,
[in] DWORD ReturnBufferSize,
[in, out] LPDWORD RequiredSize
);
Parameter
[in] Context
INF-Kontext für die Zeile.
[in] FieldIndex
Der 1-basierte Index des Startfelds innerhalb der angegebenen Zeile, aus der die Binärdaten abgerufen werden sollen. Die Binärdaten werden aus jedem Feld erstellt, beginnend an diesem Punkt bis zum Ende der Zeile. Jedes Feld entspricht 1 Byte und ist in hexadezimaler Notation. Ein FieldIndex von 0 (null) ist mit dieser Funktion ungültig.
[in, out] ReturnBuffer
Optionaler Zeiger auf einen Puffer, der die Binärdaten empfängt. Stellen Sie sicher, dass der Zielpuffer die gleiche Größe oder größer als der Quellpuffer hat. Sie können die Funktion einmal aufrufen, um die erforderliche Puffergröße abzurufen, den erforderlichen Arbeitsspeicher zuzuweisen und dann die Funktion ein zweites Mal aufzurufen, um die Daten abzurufen. Mit dieser Technik können Sie Fehler vermeiden, die auf eine unzureichende Puffergröße zurückzuführen sind. Weitere Informationen finden Sie im Abschnitt mit den Hinweisen.
[in] ReturnBufferSize
Größe des Puffers, auf den von ReturnBuffer in Zeichen verwiesen wird. Diese Zahl enthält den NULL-Abschlusszeichen .
[in, out] RequiredSize
Optionaler Zeiger auf eine Variable, die die erforderliche Größe für den Puffer empfängt, der auf ReturnBuffer verweist, in Zeichen. Diese Zahl enthält den NULL-Abschlusszeichen . Wenn die erforderliche Größe größer als der von ReturnBufferSize angegebene Wert ist, schlägt die Funktion fehl, und ein Aufruf von GetLastError gibt ERROR_INSUFFICIENT_BUFFER zurück.
Rückgabewert
Wenn die Funktion erfolgreich ist, ist der Rückgabewert ein Wert ungleich null.
Wenn die Funktion fehlerhaft ist, ist der Rückgabewert null. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.
GetLastError gibt ERROR_INVALID_DATA zurück, wenn ein Von SetupGetBinaryField abgerufenes Feld keine gültige Hexadezimalzahl im Bereich 0-FF ist.
Hinweise
Wenn diese Funktion mit einem ReturnBuffer von NULL und einem ReturnBufferSize-Wert von 0 (null) aufgerufen wird, fügt die Funktion die zum Halten der angegebenen Daten erforderliche Puffergröße in die Variable ein, auf die von RequiredSize verwiesen wird. Wenn dies für die Funktion erfolgreich ist, ist der Rückgabewert ein Wert ungleich Null. Andernfalls ist der Rückgabewert null, und erweiterte Fehlerinformationen können durch Aufrufen von GetLastError abgerufen werden.
Um besser zu verstehen, wie diese Funktion funktioniert, sehen Sie sich die folgende Zeile aus einer INF-Datei an.
X=34,FF,00,13
Wenn SetupGetBinaryField in der vorherigen Zeile aufgerufen wurde, werden die Binärwerte 34, FF, 00 und 13 in den von ReturnBuffer angegebenen Puffer eingefügt.
Für die Unicode-Version dieser Funktion werden die Puffergrößen ReturnBufferSize und RequiredSize als Anzahl von Zeichen angegeben. Diese Zahl enthält den NULL-Abschlusszeichen . Für die ANSI-Version dieser Funktion werden die Größen in Byte angegeben.
Wenn diese Funktion mit einem ReturnBuffer von NULL und einem ReturnBufferSize-Wert von 0 (null) aufgerufen wird, fügt die Funktion die zum Halten der angegebenen Daten erforderliche Puffergröße in die Variable ein, auf die von RequiredSize verwiesen wird. Wenn dies für die Funktion erfolgreich ist, ist der Rückgabewert ein Wert ungleich Null. Andernfalls ist der Rückgabewert null, und erweiterte Fehlerinformationen können durch Aufrufen von GetLastError abgerufen werden.
Daher können Sie die Funktion einmal aufrufen, um die erforderliche Puffergröße abzurufen, den erforderlichen Arbeitsspeicher zuzuweisen und dann die Funktion ein zweites Mal aufzurufen, um die Daten abzurufen. Mit dieser Technik können Sie Fehler vermeiden, die auf eine unzureichende Puffergröße zurückzuführen sind.
Anforderungen
| Unterstützte Mindestversion (Client) | Windows XP [nur Desktop-Apps] |
| Unterstützte Mindestversion (Server) | Windows Server 2003 [nur Desktop-Apps] |
| Zielplattform | Windows |
| Kopfzeile | setupapi.h |
| Bibliothek | Setupapi.lib |
| DLL | Setupapi.dll |