GetTimeFormatA-Funktion (datetimeapi.h)

Artikel
11/20/2024

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

Hinweis Aus Interoperabilitätsgründen sollte die Anwendung die GetTimeFormatEx--Funktion vorziehen, um GetTimeFormat- 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 GetTimeFormatExverwenden.

Syntax

int GetTimeFormatA(
  [in]            LCID             Locale,
  [in]            DWORD            dwFlags,
  [in, optional]  const SYSTEMTIME *lpTime,
  [in, optional]  LPCSTR           lpFormat,
  [out, optional] LPSTR            lpTimeStr,
  [in]            int              cchTime
);

Parameter

[in] Locale

Gebietsschema-ID, die 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

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

[in, optional] lpFormat

Zeigen Sie 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 durch lpTimeStrangegebenen Zeitzeichenfolgenpuffer. 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 parameter lpTimeStr.

Rückgabewert

Gibt die Anzahl der im Puffer abgerufenen TCHAR-Werte zurück, die durch lpTimeStrangegeben sind. Wenn der cchTime--Parameter auf 0 festgelegt ist, gibt die Funktion die Größe des Puffers zurück, der zum Speichern der formatierten Zeitzeichenfolge erforderlich ist, einschließlich eines endenden Nullzeichens.

Diese 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.
ERROR_OUTOFMEMORY. Nicht genügend Speicher war verfügbar, um diesen Vorgang abzuschließen.

Bemerkungen

Siehe Hinweise für GetTimeFormatEx.

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: GetTimeFormat- wird in Datetimeapi.h deklariert. Vor Windows 8 wurde sie in Winnls.h deklariert.

Anmerkung

Der datetimeapi.h-Header definiert GetTimeFormat 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

Siehe auch

Freigeben über