GetDateFormatA-Funktion (datetimeapi.h)

Artikel
08/23/2023

Formatiert ein Datum als Datumszeichenfolge für ein durch den Gebietsschemabezeichner angegebenes Gebietsschema. Die Funktion formatiert entweder ein angegebenes Datum oder das lokale Systemdatum.

Hinweis Aus Interoperabilitätsgründen sollte die Anwendung die GetDateFormatEx-Funktion gegenüber GetDateFormat vorziehen, da Microsoft zur Verwendung von Gebietsschemanamen anstelle von Gebietsschemabezeichnern für neue Gebietsschemas migriert. Jede Anwendung, die nur unter Windows Vista und höher ausgeführt wird, sollte GetDateFormatEx verwenden.

Syntax

int GetDateFormatA(
  [in]            LCID             Locale,
  [in]            DWORD            dwFlags,
  [in, optional]  const SYSTEMTIME *lpDate,
  [in, optional]  LPCSTR           lpFormat,
  [out, optional] LPSTR            lpDateStr,
  [in]            int              cchDate
);

Parameter

[in] Locale

Gebietsschemabezeichner , der das Gebietsschema angibt, für das diese Funktion die Datumszeichenfolge formatiert. Sie können das MAKELCID-Makro verwenden, um einen Gebietsschemabezeichner zu erstellen oder einen der folgenden vordefinierten Werte zu verwenden.

[in] dwFlags

Flags, die Datumsformatoptionen angeben. Ausführliche Definitionen finden Sie im dwFlags-Parameter von GetDateFormatEx.

[in, optional] lpDate

Zeiger auf eine SYSTEMTIME-Struktur , die die zu formatierenden Datumsinformationen enthält. Die Anwendung legt diesen Parameter auf NULL fest, 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.

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.

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.

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

Weitere Informationen finden Sie unter Hinweise zu GetDateFormatEx.

Wenn die ANSI-Version dieser Funktion mit einem reinen Unicode-Gebietsschemabezeichner verwendet wird, kann die Funktion erfolgreich ausgeführt werden, da das Betriebssystem die Systemcodepage verwendet. Jedoch werden Zeichen, die auf der Systemcodepage nicht definiert sind, in der Zeichenfolge als Fragezeichen ("?") angezeigt.

Ab Windows 8: GetDateFormat wird in Datetimeapi.h deklariert. Vor Windows 8 wurde es in Winnls.h deklariert.

Hinweis

Der datetimeapi.h-Header definiert GetDateFormat als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch 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


Unterstützte Mindestversion (Client)	Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	datetimeapi.h
Bibliothek	Kernel32.lib
DLL	Kernel32.dll