GetDateFormatA-Funktion (datetimeapi.h)

Artikel
11/20/2024

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

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

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

Zeigen Sie 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

Zeigen Sie auf eine Formatbildzeichenfolge, die verwendet wird, um das Datum zu bilden. Mögliche Werte für die Formatbildzeichenfolge werden in Tag, Monat, Jahr und Era Format Bilderdefiniert.

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

[out, optional] lpDateStr

Zeigen Sie 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 erforderlich ist, um die formatierte Datumszeichenfolge zu speichern. In diesem Fall wird der durch lpDateStr angegebene Puffer nicht verwendet.

Rückgabewert

Gibt die Anzahl der Zeichen zurück, die in den lpDateStr Puffer geschrieben werden, wenn dies erfolgreich ist. 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 endenden Nullzeichens.

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

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

Siehe Hinweise für GetDateFormatEx.

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.

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

Anmerkung

Der datetimeapi.h-Header definiert GetDateFormat 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 [nur Desktop-Apps]
mindestens unterstützte Server-	Windows 2000 Server [nur Desktop-Apps]
Zielplattform-	Fenster
Header-	datetimeapi.h
Library	Kernel32.lib
DLL-	Kernel32.dll