GetLocaleInfoEx-Funktion (winnls.h)

Artikel
03/21/2023
3 Minuten Lesedauer

Ruft Informationen zu einem gebietsschema ab, das nach Dem Namen angegeben wird.

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

Hinweis Diese Funktion kann Daten abrufen, die sich zwischen Versionen ändern, z. B. aufgrund eines benutzerdefinierten Gebietsschemas. Wenn Ihre Anwendung Daten beibehalten oder übertragen muss, finden Sie unter Verwenden von persistenten 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 Gebietsschemainformationen, die abgerufen werden sollen. Mögliche Werte finden Sie im Abschnitt "Konstanten, die im LCType-Parameter von GetLocaleInfo, GetLocaleInfoEx und SetLocaleInfo" in Gebietsschemainformationskonstanten verwendet werden. Beachten Sie, dass nur eine Gebietsschemainformation pro Anruf angegeben werden kann.

Die Anwendung kann den binären OR-Operator verwenden, um LOCALE_RETURN_NUMBER mit jeder anderen zulässigen Konstante 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 sein, der 2 ist.

Vorsicht Es ist auch möglich , LOCALE_NOUSEROVERRIDE mit jeder anderen Konstante zu kombinieren. Die Verwendung dieser Konstante ist jedoch stark entmutigt. (Auch ohne Verwendung des aktuellen Benutzers überschreiben kann sich die Daten von Computer zu Computer unterscheiden, und benutzerdefinierte Gebietsschemas können die Daten ändern. Beispielsweise unterliegen sogar Monats- oder Tagnamen 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 LOCALE_ILANGUAGE imLCType-Parameter nicht verwenden, um Fehler oder Abrufen unerwarteter Daten zu vermeiden. Stattdessen wird es für Ihre Anwendungen empfohlen, GetLocaleInfoEx aufzurufen.

[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 in Zeichen des Datenpuffers, der von lpLCData angegeben ist. 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 terminierenden Nullzeichens.

Rückgabewert

Gibt die Anzahl der im Gebietsschemadatenpuffer abgerufenen Zeichen zurück, wenn erfolgreich und cchData ein Nichtzero-Wert ist. Wenn die Funktion erfolgreich ist, ist cchData nicht zero, und LOCALE_RETURN_NUMBER angegeben wird, ist der Rückgabewert die Größe der im Datenpuffer abgerufenen ganzzahl, 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 eines Nullzeichens, für den Gebietsschemadatenpuffer.

Die Funktion gibt 0 zurück, wenn sie nicht erfolgreich ist. Um erweiterte Fehlerinformationen abzurufen, kann die Anwendung GetLastError aufrufen, die einen der folgenden Fehlercodes zurückgeben kann:

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

Bemerkungen

Diese Funktion ruft normalerweise Informationen im Textformat ab. Wenn die Informationen ein numerischer Wert sind 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 angeben. 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 aus 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 Zeichenanzahl. Wenn eine Anwendung GetLocaleInfoEx mit LCType als LOCALE_FONTSIGNATURE angegeben aufruft, kann cchData sicher als Sizeof(LOCALESIGNATURE) / sizeof(WCHAR) angegeben werden.

In den folgenden Beispielen wird die Puffergröße für Nichttextwerte korrekt 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. Daten sind nicht garantiert, dass sie von Computer zu Computer oder zwischen Ausführung einer Anwendung identisch sind. Wenn Ihre Anwendung Daten beibehalten oder übertragen muss, finden Sie unter Verwenden von persistenten Gebietsschemadaten.

Beginnend in Windows 8: Wenn Ihre App Sprachtags an diese Funktion aus dem Windows.Globalization-Namespace übergeben, muss sie zuerst die Tags konvertieren, indem Sie ResolveLocaleName aufrufen.

Beispiele

Beispiele für die Verwendung dieser Funktion finden Sie in NLS: Beispiel für namebasierte APIs und NLS:Internationalized Domain Name (IDN) Mitigation Sample.

Anforderungen


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 (enthalten Windows.h)
Bibliothek	Kernel32.lib
DLL	Kernel32.dll