GetTimeFormatW-Funktion (datetimeapi.h)

Artikel
08/23/2023

Formatiert zeit als Zeitzeichenfolge für ein gebietsschema, das durch den Bezeichner angegeben wird. Die Funktion formatiert entweder eine angegebene Zeit oder die lokale Systemzeit.

Hinweis Aus Interoperabilitätsgründen sollte die Anwendung die GetTimeFormatEx-Funktiongegenüber GetTimeFormat 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 GetTimeFormatEx verwenden.

Syntax

int GetTimeFormatW(
  [in]            LCID             Locale,
  [in]            DWORD            dwFlags,
  [in, optional]  const SYSTEMTIME *lpTime,
  [in, optional]  LPCWSTR          lpFormat,
  [out, optional] LPWSTR           lpTimeStr,
  [in]            int              cchTime
);

Parameter

[in] Locale

Gebietsschemabezeichner , der das Gebietsschema angibt. Sie können das MAKELCID-Makro verwenden, um einen Gebietsschemabezeichner zu erstellen oder einen der folgenden vordefinierten Werte zu verwenden.

[in] dwFlags

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

[in, optional] lpTime

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

[in, optional] lpFormat

Zeiger auf ein Formatbild, das zum Formatieren der Zeitzeichenfolge verwendet werden soll. Wenn die Anwendung diesen Parameter auf NULL festlegt, formatiert die Funktion die Zeichenfolge entsprechend dem Zeitformat des angegebenen Gebietsschemas. Wenn die Anwendung den Parameter nicht auf NULL festlegt, verwendet die Funktion das Gebietsschema nur für Informationen, die nicht in der Formatbildzeichenfolge angegeben sind, z. B. die gebietsschemaspezifischen Zeitmarkierungen. Informationen zur Formatbildzeichenfolge finden Sie im Abschnitt Hinweise.

[out, optional] lpTimeStr

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

[in] cchTime

Größe in TCHAR-Werten für den Zeitzeichenfolgenpuffer, der von lpTimeStr angegeben wird. Alternativ kann die Anwendung diesen Parameter auf 0 festlegen. In diesem Fall gibt die Funktion die erforderliche Größe für den Zeitzeichenfolgenpuffer zurück und verwendet nicht den lpTimeStr-Parameter .

Rückgabewert

Gibt die Anzahl der abgerufenen TCHAR-Werte im Puffer zurück, der von lpTimeStr angegeben wird. Wenn der cchTime-Parameter auf 0 festgelegt ist, gibt die Funktion die Größe des Puffers zurück, die erforderlich ist, um die formatierte Zeitzeichenfolge zu enthalten, einschließlich eines beendenden NULL-Zeichens.

Diese Funktion gibt 0 zurück, wenn sie nicht erfolgreich ist. Um erweiterte Fehlerinformationen abzurufen, 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.
ERROR_OUTOFMEMORY. Für diesen Vorgang war nicht genügend Speicher verfügbar.

Hinweise

Weitere Informationen finden Sie unter Hinweise zu GetTimeFormatEx.

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

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

Hinweis

Der header datetimeapi.h definiert GetTimeFormat 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 nicht codierungsneutralem Code 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
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