SetupGetStringFieldA-Funktion (setupapi.h)
[Diese Funktion steht für die Verwendung in den im Abschnitt "Anforderungen" angegebenen Betriebssystemen zur Verfügung. Sie kann in nachfolgenden Versionen geändert oder nicht verfügbar sein. 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 für die Installation 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
Zeigen Sie 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 ein FieldIndex- von 0, um einen Zeichenfolgenschlüssel abzurufen, falls vorhanden.
[in, out] ReturnBuffer
Optionaler Zeiger auf einen Puffer, der die null-terminated string empfängt. Stellen Sie sicher, dass der Zielpuffer die gleiche Größe oder größer als der Quellpuffer ist. Dieser Parameter kann NULL-sein. Weitere Informationen finden Sie im Abschnitt "Hinweise".
[in] ReturnBufferSize
Die Größe des Puffers, auf den ReturnBuffer-in Zeichen verweist. Dies schließt den null Terminator 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 ist und die tatsächliche Größe größer als der von ReturnBufferSizeangegebene 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 enthalten. Dies schließt den null Terminator ein.
Rückgabewert
Wenn die Funktion erfolgreich ist, ist der Rückgabewert ein Wert ungleich Null.
Wenn die Funktion fehlschlägt, ist der Rückgabewert null. Rufen Sie GetLastErrorauf, um erweiterte Fehlerinformationen zu erhalten.
Bemerkungen
Wenn diese Funktion mit einer ReturnBuffer- von NULL- und einer ReturnBufferSize- null aufgerufen wird, fügt die Funktion die Puffergröße ein, die zum Halten der angegebenen Daten in die Variable erforderlich ist, auf die RequiredSizeverweist. Wenn die Funktion in diesem Fall erfolgreich ausgeführt wird, ist der Rückgabewert ein Wert ungleich Null. Andernfalls ist der Rückgabewert null und erweiterte Fehlerinformationen können durch Aufrufen von GetLastErrorabgerufen werden.
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. Mithilfe dieser Technik 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 umfasst, einschließlich der endenden NULL-. Wenn die Zeichenfolgenlänge größer als 512 ist, wird sie abgeschnitten, und es wird kein Fehler zurückgegeben. Die maximale Länge aller verketteten Zeichenfolgen, die aus einem oder mehreren %strkey% Token erstellt wurden, beträgt 4096 Zeichen.
Anmerkung
Der Header setupapi.h 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 Code, der nicht codierungsneutral ist, 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 |
|---|---|
| mindestens unterstützte Client- | Windows XP [nur Desktop-Apps] |
| mindestens unterstützte Server- | Windows Server 2003 [Nur Desktop-Apps] |
| Zielplattform- | Fenster |
| Header- | setupapi.h |
| Library | Setupapi.lib |
| DLL- | Setupapi.dll |
| API-Satz | ext-ms-win-setupapi-inf-l1-1-1 (eingeführt in Windows 10, Version 10.0.14393) |