GetDateFormatEx-Funktion (datetimeapi.h)

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.

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.

• LOCALE_NAME_INVARIANT
• LOCALE_NAME_SYSTEM_DEFAULT
• LOCALE_NAME_USER_DEFAULT

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

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

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:

1. Rufen Sie die EnumDateFormatsExEx-Funktion auf, um alle Datumsformate für das DATE_LONGDATE-Format abzurufen.
2. 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.
3. 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

Siehe auch

Bilder im Tag-, Monats-, Jahres- und Epochenformat

EnumDateFormatsEx

GetCalendarInfoEx

GetDateFormat

NLS: Beispiel für namensbasierte APIs

Unterstützung für landessprachliche Sprachen

Unterstützungsfunktionen für nationalsprachliche Sprachen