GetLocaleInfoW-Funktion (winnls.h)

Artikel
03/04/2024

Ruft Informationen zu einem durch den Bezeichner angegebenen Gebietsschema ab.

Hinweis Aus Interoperabilitätsgründen sollte die Anwendung die GetLocaleInfoEx-Funktion gegenüber GetLocaleInfo vorziehen, da Microsoft zur Verwendung von Gebietsschemanamen anstelle von Gebietsschemabezeichnern für neue Gebietsschemas migriert. Jede Anwendung, die nur unter Windows Vista und höher ausgeführt wird, sollte GetLocaleInfoEx verwenden.

Syntax

int GetLocaleInfoW(
  [in]            LCID   Locale,
  [in]            LCTYPE LCType,
  [out, optional] LPWSTR lpLCData,
  [in]            int    cchData
);

Parameter

[in] Locale

Gebietsschemabezeichner , für den Informationen abgerufen werden sollen. Sie können das MAKELCID-Makro verwenden, um einen Gebietsschemabezeichner zu erstellen oder einen der folgenden vordefinierten Werte zu verwenden.

[in] LCType

Die abzurufenden Gebietsschemainformationen. Ausführliche Definitionen finden Sie im LCType-Parameter von GetLocaleInfoEx.

Hinweis Für GetLocaleInfo ist der Wert LOCALE_USE_CP_ACP nur für die ANSI-Version relevant.

[out, optional] lpLCData

Zeiger auf einen Puffer, in dem diese Funktion die angeforderten Gebietsschemainformationen abruft. Dieser Zeiger wird nicht verwendet, wenn cchData auf 0 festgelegt ist. Weitere Informationen finden Sie im Abschnitt mit Hinweisen.

[in] cchData

Größe des durch lpLCData angegebenen Datenpuffers in TCHAR-Werten. Alternativ kann die Anwendung diesen Parameter auf 0 festlegen. In diesem Fall verwendet die Funktion nicht den lpLCData-Parameter und gibt die erforderliche Puffergröße einschließlich des abschließenden NULL-Zeichens zurück.

Rückgabewert

Gibt die Anzahl der Im Gebietsschemadatenpuffer abgerufenen Zeichen zurück, wenn erfolgreich und cchData ein Wert ungleich null ist. Wenn die Funktion erfolgreich ist, ist cchData ungleich null, und LOCALE_RETURN_NUMBER angegeben wird, entspricht der Rückgabewert der Größe der ganzen Zahl, die im Datenpuffer abgerufen wird. d. h. 2 für die Unicode-Version der Funktion oder 4 für die ANSI-Version. Wenn die Funktion erfolgreich ist und der Wert von cchData 0 ist, entspricht der Rückgabewert der erforderlichen Größe in Zeichen einschließlich eines NULL-Zeichens für den Gebietsschemadatenpuffer.

Die Funktion gibt 0 zurück, wenn sie nicht erfolgreich ist. Um erweiterte Fehlerinformationen zu erhalten, kann die Anwendung GetLastError aufrufen, wodurch einer der folgenden Fehlercodes zurückgegeben werden kann:

ERROR_INSUFFICIENT_BUFFER. Eine angegebene Puffergröße war nicht groß genug, oder sie wurde fälschlicherweise auf NULL festgelegt.
ERROR_INVALID_FLAGS. Die für Flags angegebenen Werte waren ungültig.
ERROR_INVALID_PARAMETER. Jeder der Parameterwerte war ungültig.

Hinweise

Informationen zum Betrieb dieser Funktion finden Sie unter Hinweise zu GetLocaleInfoEx.

Hinweis Selbst wenn der LCType-Parameter als LOCALE_FONTSIGNATURE angegeben wird, sind cchData und die Funktionsrückgabe weiterhin TCHAR-Zählungen. Die Anzahl unterscheidet sich für die ANSI- und Unicode-Versionen der Funktion. Wenn eine Anwendung die generische Version von GetLocaleInfo mit LOCALE_FONTSIGNATURE aufruft, kann cchData sicher als sizeof(LOCALESIGNATURE) / sizeof(TCHAR) angegeben werden.

In den folgenden Beispielen wird die Puffergröße für Nicht-Textwerte ordnungsgemäß verarbeitet:

int   ret;
CALID calid;
DWORD value;

ret = GetLocaleInfo(LOCALE_USER_DEFAULT,
                    LOCALE_ICALENDARTYPE | LOCALE_RETURN_NUMBER,
                    (LPTSTR)&value,
                    sizeof(value) / sizeof(TCHAR) );
calid = value;

LOCALESIGNATURE LocSig;

ret = GetLocaleInfo(LOCALE_USER_DEFAULT,
                    LOCALE_FONTSIGNATURE,
                    (LPWSTR)&LocSig,
                    sizeof(LocSig) / sizeof(TCHAR) );

Die von der ANSI-Version dieser Funktion abgerufene ANSI-Zeichenfolge wird basierend auf der ANSI-Standardcodepage für den Gebietsschemabezeichner aus Unicode in ANSI übersetzt. Wenn jedoch LOCALE_USE_CP_ACP angegeben ist, basiert die Übersetzung auf der standardmäßigen ANSI-Codepage des Systems.

Wenn die ANSI-Version dieser Funktion mit einem reinen Unicode-Gebietsschemabezeichner verwendet wird, kann die Funktion erfolgreich ausgeführt werden, da das Betriebssystem die Systemcodepage verwendet. Jedoch werden Zeichen, die auf der Systemcodepage nicht definiert sind, in der Zeichenfolge als Fragezeichen (?) angezeigt.

Hinweis

Der winnls.h-Header definiert GetLocaleInfo 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 2000 Professional [Desktop-Apps \| UWP-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [Desktop-Apps \| UWP-Apps]
Zielplattform	Windows
Kopfzeile	winnls.h (windows.h einschließen)
Bibliothek	Kernel32.lib
DLL	Kernel32.dll