GetLocaleInfoEx-Funktion (winnls.h)

Artikel
03/06/2024

Ruft Informationen zu einem gebietsschema ab, das durch den Namen angegeben wird.

Hinweis Die Anwendung sollte diese Funktion für GetLocaleInfo aufrufen, wenn sie nur unter Windows Vista und höher ausgeführt werden soll.

Hinweis Diese Funktion kann Daten abrufen, die sich zwischen Releases ändern, z. B. aufgrund eines benutzerdefinierten Gebietsschemas. Wenn Ihre Anwendung Daten beibehalten oder übertragen muss, finden Sie weitere Informationen unter Verwenden persistenter Gebietsschemadaten.

Syntax

int GetLocaleInfoEx(
  [in, optional]  LPCWSTR lpLocaleName,
  [in]            LCTYPE  LCType,
  [out, optional] LPWSTR  lpLCData,
  [in]            int     cchData
);

Parameter

[in, optional] lpLocaleName

Zeiger auf einen Gebietsschemanamen oder einen der folgenden vordefinierten Werte.

[in] LCType

Die abzurufenden Gebietsschemainformationen. Mögliche Werte finden Sie im Abschnitt "Konstanten, die im LCType-Parameter von GetLocaleInfo, GetLocaleInfoEx und SetLocaleInfo verwendet werden" unter Gebietsschemainformationskonstanten. Beachten Sie, dass pro Aufruf nur ein Teil der Gebietsschemainformationen angegeben werden kann.

Die Anwendung kann den binären OR-Operator verwenden, um LOCALE_RETURN_NUMBER mit jeder anderen zulässigen Konstanten zu kombinieren. In diesem Fall ruft die Funktion den Wert als Zahl anstelle einer Zeichenfolge ab. Der Puffer, der den Wert empfängt, muss mindestens die Länge eines DWORD-Werts aufweisen, der 2 ist.

Vorsicht Es ist auch möglich, LOCALE_NOUSEROVERRIDE mit jeder anderen Konstante zu kombinieren. Von der Verwendung dieser Konstante wird jedoch dringend abgeraten. (Auch ohne Verwendung der aktuellen Benutzerüberschreibung können sich die Daten von Computer zu Computer unterscheiden, und benutzerdefinierte Gebietsschemas können die Daten ändern. Beispielsweise unterliegen auch Monats- oder Tagesnamen Rechtschreibreformen.)

Wenn LCType auf LOCALE_IOPTIONALCALENDAR festgelegt ist, ruft die Funktion nur den ersten alternativen Kalender ab.

Hinweis Um alle alternativen Kalender abzurufen, sollte die Anwendung EnumCalendarInfoEx verwenden.

Ab Windows Vista sollten Ihre Anwendungen keine LOCALE_ILANGUAGE im LCType-Parameter verwenden, um fehler oder das Abrufen unerwarteter Daten zu vermeiden. Stattdessen wird empfohlen, dass Ihre Anwendungen GetLocaleInfoEx aufrufen.

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

[in] cchData

Größe des von lpLCData angegebenen Datenpuffers in Zeichen. 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 zurück, einschließlich des beendenden NULL-Zeichens.

Rückgabewert

Gibt die Anzahl der im Gebietsschemadatenpuffer abgerufenen Zeichen zurück, wenn erfolgreich und cchData ein Nonzero-Wert ist. Wenn die Funktion erfolgreich ist, cchData nonzero ist und LOCALE_RETURN_NUMBER angegeben ist, ist der Rückgabewert die Größe der ganzen Zahl, die im Datenpuffer abgerufen wird, d. h. 2. Wenn die Funktion erfolgreich ist und der Wert von cchData 0 ist, ist der Rückgabewert die erforderliche Größe in Zeichen, einschließlich NULL-Zeichen, für den Gebietsschemadatenpuffer.

Die Funktion gibt 0 zurück, wenn sie nicht erfolgreich ist. Um erweiterte Fehlerinformationen abzurufen, 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

Diese Funktion ruft normalerweise Informationen im Textformat ab. Wenn es sich bei den Informationen um einen numerischen Wert handelt und der Wert von LCTypeLOCALE_ILANGUAGE oder LOCALE_IDEFAULTLANGUAGE ist, ruft diese Funktion Zeichenfolgen ab, die Hexadezimalzahlen enthalten. Andernfalls ist der abgerufene Text für numerische Informationen eine Dezimalzahl.

Für diese Regel gelten zwei Ausnahmen: Zunächst kann die Anwendung numerische Werte als ganze Zahlen abrufen, indem sie LOCALE_RETURN_NUMBER im LCType-Parameter angibt. Die zweite Ausnahme besteht darin, dass sich LOCALE_FONTSIGNATURE anders verhält als alle anderen Gebietsschemainformationskonstanten. Die Anwendung muss einen Datenpuffer von mindestens sizeof(LOCALESIGNATURE)-Bytes bereitstellen. Bei erfolgreicher Rückgabe von der Funktion wird der Puffer als LOCALESIGNATURE-Struktur ausgefüllt.

Hinweis Selbst wenn der LCType-Parameter als LOCALE_FONTSIGNATURE angegeben wird, sind cchData und die Funktionsrückgabe weiterhin Zeichenanzahlen. Wenn eine Anwendung GetLocaleInfoEx aufruft, wobei LCType als LOCALE_FONTSIGNATURE angegeben ist, kann cchData sicher als sizeof(LOCALESIGNATURE) / sizeof(WCHAR) angegeben werden.

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

int   ret;
CALID calid;
DWORD value;

ret = GetLocaleInfoEx(LOCALE_NAME_USER_DEFAULT,
                      LOCALE_ICALENDARTYPE | LOCALE_RETURN_NUMBER,
                      (LPWSTR)&value,
                      sizeof(value) / sizeof(WCHAR) );
calid = value;

LOCALESIGNATURE LocSig;

ret = GetLocaleInfoEx(LOCALE_NAME_USER_DEFAULT,
                      LOCALE_FONTSIGNATURE,
                      (LPWSTR)&LocSig,
                      sizeof(LocSig) / sizeof(WCHAR) );

Diese Funktion kann Daten aus benutzerdefinierten Gebietsschemas abrufen. Es ist nicht garantiert, dass die Daten von Computer zu Computer oder zwischen den Ausführungen einer Anwendung identisch sind. Wenn Ihre Anwendung Daten beibehalten oder übertragen muss, finden Sie weitere Informationen unter Verwenden persistenter Gebietsschemadaten.

Ab Windows 8: Wenn Ihre App Sprachtags aus dem Windows.Globalization-Namespace an diese Funktion übergibt, muss sie zuerst die Tags konvertieren, indem ResolveLocaleName aufgerufen wird.

Beispiele

Beispiele für die Verwendung dieser Funktion finden Sie unter NLS: Name-based APIs Sample and NLS: Internationalized Domain Name (IDN) Mitigation Sample.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows Vista [Desktop-Apps \| UWP-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 [Desktop-Apps \| UWP-Apps]
Zielplattform	Windows
Kopfzeile	winnls.h (einschließlich Windows.h)
Bibliothek	Kernel32.lib
DLL	Kernel32.dll