GetDateFormatEx-Funktion (datetimeapi.h)

Artikel
08/23/2023

Formatiert ein Datum als Datumszeichenfolge für ein gebietsschema, das durch den Namen angegeben wird. Die Funktion formatiert entweder ein angegebenes Datum oder das lokale Systemdatum.

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

Hinweis Diese Funktion kann Daten formatieren, 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 GetDateFormatEx(
  [in, optional]  LPCWSTR          lpLocaleName,
  [in]            DWORD            dwFlags,
  [in, optional]  const SYSTEMTIME *lpDate,
  [in, optional]  LPCWSTR          lpFormat,
  [out, optional] LPWSTR           lpDateStr,
  [in]            int              cchDate,
  [in, optional]  LPCWSTR          lpCalendar
);

Parameter

[in, optional] lpLocaleName

Zeiger auf einen Gebietsschemanamen oder einen der folgenden vordefinierten Werte.

[in] dwFlags

Flags, die verschiedene Funktionsoptionen angeben, die festgelegt werden können, wenn lpFormat auf NULL festgelegt ist. Die Anwendung kann eine Kombination der folgenden Werte und LOCALE_USE_CP_ACP oder LOCALE_NOUSEROVERRIDE angeben.

Vorsicht Die Verwendung von LOCALE_NOUSEROVERRIDE wird dringend abgeraten, da benutzereinstellungen deaktiviert werden.

Wert	Bedeutung
DATE_AUTOLAYOUT	Windows 7 und höher: Erkennen Sie die Notwendigkeit eines Leselayouts von rechts nach links und von links nach rechts anhand der Gebietsschema- und Kalenderinformationen, und fügen Sie entsprechend Markierungen hinzu. Dieser Wert kann nicht mit DATE_LTRREADING oder DATE_RTLREADING verwendet werden. DATE_AUTOLAYOUT wird gegenüber DATE_LTRREADING und DATE_RTLREADING bevorzugt, da die Gebietsschemas und Kalender verwendet werden, um das richtige Hinzufügen von Markierungen zu bestimmen.
DATE_LONGDATE	Verwenden Sie das Lange Datumsformat. Dieser Wert kann nicht mit DATE_MONTHDAY, DATE_SHORTDATE oder DATE_YEARMONTH verwendet werden.
DATE_LTRREADING	Fügen Sie Markierungen für das Leselayout von links nach rechts hinzu. Dieser Wert kann nicht mit DATE_RTLREADING verwendet werden.
DATE_RTLREADING	Fügen Sie Markierungen für das Leselayout von rechts nach links hinzu. Dieser Wert kann nicht mit DATE_LTRREADING
DATE_SHORTDATE	Verwenden Sie das kurze Datumsformat. Dies ist die Standardoption. Dieser Wert kann nicht mit DATE_MONTHDAY, DATE_LONGDATE oder DATE_YEARMONTH verwendet werden.
DATE_USE_ALT_CALENDAR	Verwenden Sie den alternativen Kalender, sofern vorhanden, um die Datumszeichenfolge zu formatieren. Wenn dieses Flag festgelegt ist, verwendet die Funktion anstelle von Benutzerüberschreibungen das Standardformat für diesen alternativen Kalender. Die Benutzerüberschreibungen werden nur verwendet, wenn kein Standardformat für den angegebenen alternativen Kalender vorhanden ist.
DATE_YEARMONTH	Windows Vista: Verwenden Sie das Format Jahr/Monat. Dieser Wert kann nicht mit DATE_MONTHDAY, DATE_SHORTDATE oder DATE_LONGDATE verwendet werden.
DATE_MONTHDAY	Windows 10: Verwenden Sie die Kombination aus Monats- und Tagesformaten, die für das angegebene Gebietsschema geeignet sind. Dieser Wert kann nicht mit DATE_YEARMONTH, DATE_SHORTDATE oder DATE_LONGDATE verwendet werden.

Wenn die Anwendung DATE_YEARMONTH, DATE_MONTHDAY, DATE_SHORTDATE oder DATE_LONGDATE nicht angibt und lpFormat auf NULL festgelegt ist, ist DATE_SHORTDATE die Standardeinstellung.

[in, optional] lpDate

Zeiger auf eine SYSTEMTIME-Struktur , die die zu formatierenden Datumsinformationen enthält. Die Anwendung kann diesen Parameter auf NULL festlegen, wenn die Funktion das aktuelle lokale Systemdatum verwenden soll.

[in, optional] lpFormat

Zeiger auf eine Formatbildzeichenfolge, die zum Bilden des Datums verwendet wird. Mögliche Werte für die Formatbildzeichenfolge sind in Bildern im Tag-, Monats-, Jahres- und Era-Format definiert.

Um beispielsweise die Datumszeichenfolge "Wed, Aug 31 94" abzurufen, verwendet die Anwendung die Bildzeichenfolge "ddd',' MMM tt jj".

Die Funktion verwendet das angegebene Gebietsschema nur für Informationen, die nicht in der Formatbildzeichenfolge angegeben sind, z. B. den Tag- und Monatsnamen für das Gebietsschema. Die Anwendung kann diesen Parameter auf NULL festlegen, um die Zeichenfolge entsprechend dem Datumsformat für das angegebene Gebietsschema zu formatieren.

[out, optional] lpDateStr

Zeiger auf einen Puffer, in dem diese Funktion die formatierte Datumszeichenfolge abruft.

[in] cchDate

Größe des lpDateStr-Puffers in Zeichen. Die Anwendung kann diesen Parameter auf 0 festlegen, um die Puffergröße zurückzugeben, die für die formatierte Datumszeichenfolge erforderlich ist. In diesem Fall wird der durch lpDateStr angegebene Puffer nicht verwendet.

[in, optional] lpCalendar

Reserviert; muss auf NULL festgelegt werden.

Rückgabewert

Gibt die Anzahl der Zeichen zurück, die bei erfolgreicher Ausführung in den puffer lpDateStr geschrieben werden. Wenn der cchDate-Parameter auf 0 festgelegt ist, gibt die Funktion die Anzahl der Zeichen zurück, die zum Speichern der formatierten Datumszeichenfolge erforderlich sind, einschließlich des abschließenden NULL-Zeichens.

Diese 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

Hinweis Diese API wird aktualisiert, um die Änderung der japanischen Ära vom Mai 2019 zu unterstützen. Wenn Ihre Anwendung den japanischen Kalender unterstützt, sollten Sie überprüfen, ob die neue Ära ordnungsgemäß behandelt wird. Weitere Informationen finden Sie unter Vorbereiten Ihrer Anwendung für die Änderung der japanischen Ära .

Das früheste von dieser Funktion unterstützte Datum ist der 1. Januar 1601.

Der Tagname, der abgekürzte Tagname, der Name des Monats und der abgekürzte Monatsname werden alle basierend auf dem Gebietsschemabezeichner lokalisiert.

Die Datumswerte in der durch lpDate angegebenen Struktur müssen gültig sein. Die Funktion überprüft jeden der Datumswerte: Jahr, Monat, Tag und Wochentag. Wenn der Wochentag falsch ist, verwendet die Funktion den richtigen Wert und gibt keinen Fehler zurück. Wenn einer der anderen Datumswerte außerhalb des richtigen Bereichs liegt, schlägt die Funktion fehl und legt den letzten Fehler auf ERROR_INVALID_PARAMETER fest.

Die Funktion ignoriert die Zeitmember der SYSTEMTIME-Struktur , die durch lpDate angegeben wird. Dazu gehören wHour, wMinute, wSecond und wMilliseconds.

Wenn der lpFormat-Parameter eine ungültige Formatzeichenfolge enthält, gibt die Funktion keine Fehler zurück, sondern bildet nur die bestmögliche Datumszeichenfolge. Beispielsweise sind die einzigen Jahresbilder, die gültig sind, L"jjjj" und L"yy", wobei "L" eine Unicode-Zeichenfolge (16-Bit-Zeichen) angibt. Wenn L"y" übergeben wird, geht die Funktion von L"jj" aus. Wenn L"yyy" übergeben wird, geht die Funktion von L"jjjj" aus. Wenn mehr als vier Datumsbilder (L"dddd") oder vier Monatsbilder (L"MMMM") übergeben werden, wird die Funktion standardmäßig auf L"dddd" oder L"MMMM" festgelegt.

Die Anwendung sollte jeden Text, der in seiner exakten Form erhalten bleiben soll, in der Datumszeichenfolge in einfache Anführungszeichen im Datumsformatbild einschließen. Das einfache Anführungszeichen kann auch als Escapezeichen verwendet werden, damit das einfache Anführungszeichen selbst in der Datumszeichenfolge angezeigt werden kann. Die Escapesequenz muss jedoch in zwei einfache Anführungszeichen eingeschlossen werden. Um beispielsweise das Datum als "Mai '93" anzuzeigen, lautet die Formatzeichenfolge: L"MMMM '''yy". Die ersten und letzten einfachen Anführungszeichen sind die einschließenden Anführungszeichen. Das zweite und dritte einfache Anführungszeichen sind die Escapesequenz, damit das einfache Anführungszeichen vor dem Jahrhundert angezeigt werden kann.

Wenn das Datumsbild sowohl eine numerische Form des Tages (d oder dd) als auch den vollständigen Monatsnamen (MMMM) enthält, wird die Genitivform des Monatsnamens in der Datumszeichenfolge abgerufen.

Um das Standardformat für kurze und lange Datumsinformationen zu erhalten, ohne eine tatsächliche Formatierung auszuführen, sollte die Anwendung GetLocaleInfoEx mit der LOCALE_SSHORTDATE oder LOCALE_SLONGDATE Konstante verwenden. Um das Datumsformat für einen alternativen Kalender abzurufen, verwendet die Anwendung GetLocaleInfoEx mit der LOCALE_IOPTIONALCALENDAR Konstanten. Zum Abrufen des Datumsformats für einen bestimmten Kalender verwendet die Anwendung GetCalendarInfoEx und übergibt den entsprechenden Kalenderbezeichner. Sie kann EnumCalendarInfoEx oder EnumDateFormatsEx aufrufen, um Datumsformate für einen bestimmten Kalender abzurufen.

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

Das DATE_LONGDATE-Format enthält zwei Arten von Datumsmustern: Muster, die den Wochentag enthalten, und Muster, die den Wochentag nicht enthalten. Beispiel: "Dienstag, 18. Oktober 2016" oder "18. Oktober 2016". Wenn Ihre Anwendung sicherstellen muss, dass Datumsangaben eines dieser Muster und nicht die andere Art verwenden, sollte Ihre Anwendung die folgenden Aktionen ausführen:

Rufen Sie die EnumDateFormatsExEx-Funktion auf, um alle Datumsformate für das DATE_LONGDATE-Format abzurufen.
Suchen Sie nach dem ersten Datumsformat, das an die Rückruffunktion übergeben wurde, die Sie für EnumDateFormatsExEx angegeben haben, das mit dem angeforderten Kalenderbezeichner übereinstimmt und eine Datumsformatzeichenfolge aufweist, die den Anforderungen Ihrer Anwendung entspricht. Suchen Sie beispielsweise nach dem ersten Datumsformat, das "dddd" enthält, wenn Ihre Anwendung erfordert, dass das Datum den vollständigen Namen des Wochentags enthält, oder suchen Sie nach dem ersten Datumsformat, das weder "ddd" noch "dddd" enthält, wenn Ihre Anwendung erfordert, dass das Datum den gekürzten Namen oder den vollständigen Namen des Wochentags enthält.
Rufen Sie die GetDateFormatEx-Funktion auf, wobei der lpFormat-Parameter auf die Datumsformatzeichenfolge festgelegt ist, die Sie in der Rückruffunktion als geeignetes Format identifiziert haben.

Wenn das Vorhandensein oder Fehlen des Wochentags im langen Datumsformat für Ihre Anwendung keine Rolle spielt, kann Ihre Anwendung GetDateFormatEx direkt aufrufen, ohne zuerst alle langen Datumsformate aufzuzählen, indem EnumDateFormatsEx aufgerufen wird.

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.

Ab Windows 8: GetDateFormatEx wird in Datetimeapi.h deklariert. Vor Windows 8 wurde sie in Winnls.h deklariert.

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	datetimeapi.h
Bibliothek	Kernel32.lib
DLL	Kernel32.dll