GetLocaleInfoA-Funktion (winnls.h)

Artikel
11/20/2024

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

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

Hinweis Für die globale Kompatibilität sollte die Anwendung die Unicode-API-Formulare "W" den "A"-Formularen vorziehen. GetLocaleInfoA beschränkt die Zeichendaten und kann zu Ergebnissen führen, die benutzern beschädigt erscheinen, insbesondere in global aktivierten Anwendungen. Für diese API wird GetLocaleInfoEx bevorzugt, da es Unicode ist und auch moderne Gebietsschemanamenstandards unterstützt.

Syntax

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

Parameter

[in] Locale

Gebietsschema-ID, für die 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 "Hinweise".

[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 parameter lpLCData und gibt die erforderliche Puffergröße einschließlich des endenden NULL-Zeichens zurück.

Rückgabewert

Gibt die Anzahl der im Gebietsschemadatenpuffer abgerufenen Zeichen zurück, wenn dies erfolgreich ist, und cchData- ein Wert ungleich Null ist. Wenn die Funktion erfolgreich ausgeführt wird, ist cchData- nicht null, und LOCALE_RETURN_NUMBER angegeben wird, ist der Rückgabewert die Größe der im Datenpuffer abgerufenen ganzzahligen Zahl; 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, 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 zu erhalten, kann die Anwendung GetLastErroraufrufen, wodurch eine 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. Ungültige Parameterwerte.

Bemerkungen

Informationen zum Vorgang dieser Funktion finden Sie in den Hinweisen für GetLocaleInfoEx-.

Hinweis Auch wenn der LCType Parameter als LOCALE_FONTSIGNATURE angegeben wird, cchData- und die Funktionsrückgabe sind weiterhin TCHAR-Anzahl. 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 richtig behandelt:

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 Standard-ANSI-Codeseite für den Gebietsschemabezeichner von Unicode in ANSI übersetzt. Wenn jedoch LOCALE_USE_CP_ACP angegeben wird, basiert die Übersetzung auf der Standardmäßig-ANSI-Codeseite des Systems.

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

Anmerkung

Der winnls.h-Header definiert GetLocaleInfo als Alias, der automatisch die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante 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 2000 Professional [Desktop-Apps \| UWP-Apps]
mindestens unterstützte Server-	Windows 2000 Server [Desktop-Apps \| UWP-Apps]
Zielplattform-	Fenster
Header-	winnls.h (enthalten Windows.h)
Library	Kernel32.lib
DLL-	Kernel32.dll