SetupGetStringFieldA-Funktion (setupapi.h)

Artikel
03/01/2024

[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 für die Installation von Anwendungen verwendet werden. Verwenden Sie stattdessen den Windows Installer zum Entwickeln von Anwendungsinstallationsprogrammen. SetupAPI wird weiterhin zum Installieren von Gerätetreibern verwendet.]

Die SetupGetStringField-Funktion ruft eine Zeichenfolge aus dem angegebenen Feld einer Zeile in einer INF-Datei ab.

Syntax

WINSETUPAPI BOOL SetupGetStringFieldA(
  [in]      PINFCONTEXT Context,
  [in]      DWORD       FieldIndex,
  [in, out] PSTR        ReturnBuffer,
  [in]      DWORD       ReturnBufferSize,
  [out]     PDWORD      RequiredSize
);

Parameter

[in] Context

Zeiger auf den Kontext für eine Zeile in einer INF-Datei.

[in] FieldIndex

Der 1-basierte Index des Felds innerhalb der angegebenen Zeile, aus der die Zeichenfolge abgerufen werden soll. Verwenden Sie einen FieldIndex von 0, um einen Zeichenfolgenschlüssel abzurufen, falls vorhanden.

[in, out] ReturnBuffer

Optionaler Zeiger auf einen Puffer, der die null-beendete Zeichenfolge empfängt. Sie sollten sicherstellen, dass der Zielpuffer die gleiche Größe oder größer als der Quellpuffer hat. Dieser Parameter kann NULL sein. Weitere Informationen finden Sie im Abschnitt mit den Hinweisen.

[in] ReturnBufferSize

Größe des Puffers, auf den returnBuffer in Zeichen verweist. Dies schließt den NULL-Abschlussator ein.

[out] RequiredSize

Optionaler Zeiger auf eine Variable, die die erforderliche Größe für den Puffer empfängt, auf den der ReturnBuffer-Parameter in Zeichen verweist. Wenn ReturnBuffer angegeben wird und die tatsächliche erforderliche Größe größer als der von ReturnBufferSize angegebene Wert ist, schlägt die Funktion fehl und speichert die Zeichenfolge nicht im Puffer. In diesem Fall gibt ein Aufruf von GetLastError ERROR_INSUFFICIENT_BUFFER zurück. Für die Unicode-Version dieser Funktion ist die erforderliche Größe in Zeichen. Dies schließt den NULL-Abschlussator ein.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ein Nichtzero-Wert.

Wenn die Funktion fehlerhaft ist, ist der Rückgabewert null. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

Wenn diese Funktion mit einem ReturnBuffer von NULL und einer ReturnBufferSize von null aufgerufen wird, legt die Funktion die Puffergröße, die zum Halten der angegebenen Daten erforderlich ist, in die Variable ein, auf die von RequiredSize verwiesen wird. Wenn die Funktion in dieser Funktion erfolgreich ist, ist der Rückgabewert ein Nonzero-Wert. Andernfalls ist der Rückgabewert null, und erweiterte Fehlerinformationen können durch Aufrufen von GetLastError abgerufen werden.

Sie können die Funktion einmal aufrufen, um die erforderliche Puffergröße abzurufen, den erforderlichen Arbeitsspeicher zuzuweisen und die Funktion dann ein zweites Mal aufzurufen, um die Daten abzurufen. Mit diesem Verfahren können Sie Fehler aufgrund einer unzureichenden Puffergröße vermeiden.

Beachten Sie, dass die maximale Länge einer einzelnen Zeichenfolge, die in einem INF-Zeichenfolgenabschnitt angegeben ist, 512 Zeichen beträgt, einschließlich der beendenden NULL. Wenn die Zeichenfolgenlänge größer als 512 ist, wird sie abgeschnitten, und es wird kein Fehler zurückgegeben. Die maximale Länge einer verketteten Zeichenfolge, die aus einem oder mehreren %strkey%-Token erstellt wird, beträgt 4096 Zeichen.

Hinweis

Der setupapi.h-Header definiert SetupGetStringField als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit nicht codierungsneutralem Code kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen

Anforderung	Wert
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
APIs	ext-ms-win-setupapi-inf-l1-1-1 (eingeführt in Windows 10, Version 10.0.14393)