SetupGetBinaryField-Funktion (setupapi.h)

Artikel
08/26/2023

[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.

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