SetupGetLineTextA-Funktion (setupapi.h)

Artikel
03/04/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 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 SetupGetLineText-Funktion gibt den Inhalt einer Zeile in einer INF-Datei in kompakter Form zurück. Die abzurufende Zeile kann durch eine INFCONTEXT-Struktur angegeben werden, die von einer SetupFindLineXXX-Funktion zurückgegeben wird, oder durch explizite Übergabe des INF-Handles, -Abschnitts und -Schlüssels der gewünschten Zeile.

Syntax

WINSETUPAPI BOOL SetupGetLineTextA(
  [in]      PINFCONTEXT Context,
  [in]      HINF        InfHandle,
  [in]      PCSTR       Section,
  [in]      PCSTR       Key,
  [in, out] PSTR        ReturnBuffer,
  [in]      DWORD       ReturnBufferSize,
  [in, out] PDWORD      RequiredSize
);

Parameter

[in] Context

Kontext für eine Zeile in einer INF-Datei, deren Text abgerufen werden soll. Dieser Parameter kann NULL sein. Wenn Contextden Wert NULL aufweist, müssen InfHandle, Section und Key angegeben werden.

[in] InfHandle

Handle für die abzufragende INF-Datei. Dieser Parameter kann NULL sein. Dieser Parameter wird nur verwendet, wenn Contextnull ist. Wenn Contextden Wert NULL aufweist, müssen InfHandle, Section und Key angegeben werden.

[in] Section

Zeiger auf eine NULL-endende Zeichenfolge, die den Abschnitt angibt, der den Schlüsselnamen der Zeile enthält, deren Text abgerufen werden soll. Dieser Parameter kann NULL sein. Dieser Parameter wird nur verwendet, wenn Contextnull ist. Wenn ContextNULL ist, müssen InfHandle, Section und Key angegeben werden.

[in] Key

Zeiger auf eine NULL-endende Zeichenfolge, die den Schlüsselnamen enthält, dessen zugeordnete Zeichenfolge abgerufen werden soll. Dieser Parameter kann NULL sein. Dieser Parameter wird nur verwendet, wenn Contextnull ist. Wenn ContextNULL ist, müssen InfHandle, Section und Key angegeben werden.

[in, out] ReturnBuffer

Wenn nicht NULL, zeigt ReturnBuffer auf einen Puffer, in dem diese Funktion den Inhalt der Zeile zurückgibt. Die Zeichenfolge mit NULL-Termin darf die Größe des Zielpuffers nicht überschreiten. 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. Dieser Parameter kann NULL sein.

[in] ReturnBufferSize

Größe des Puffers, auf den der ReturnBuffer-Parameter in Zeichen verweist. Dies schließt den NULL-Abschlusszeichen ein.

[in, out] RequiredSize

Wenn nicht NULL, zeigt auf eine Variable, in der diese Funktion die erforderliche Größe für den Puffer zurückgibt, auf den der ReturnBuffer-Parameter verweist, in Zeichen. Dies schließt den NULL-Abschlusszeichen ein. Wenn ReturnBuffer angegeben ist und die erforderliche Größe größer als der im ReturnBufferSize-Parameter angegebene Wert ist, schlägt die Funktion fehl und speichert keine Daten im Puffer.

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.

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.

Diese Funktion gibt den Inhalt einer Zeile in einem kompakten Format zurück. Alle überflüssigen Leerzeichen werden entfernt, und mehrzeilige Werte werden in eine einzelne zusammenhängende Zeichenfolge konvertiert. Beispiel:

HKLM, , PointerClass0, 1 \
; This is a comment
01, 02, 03

wird wie folgt zurückgegeben:

HKLM,,PointerClass0,1,01,02,03

Hinweis

Der Header setupapi.h definiert SetupGetLineText 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
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-0 (eingeführt in Windows 8)