GetTimeFormatEx-Funktion (datetimeapi.h)

  • Artikel

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

Hinweis Die Anwendung sollte diese Funktion vorZug für GetTimeFormat aufrufen, wenn sie nur unter Windows Vista und höher ausgeführt werden soll.

 
Hinweis Diese Funktion kann Daten formatieren, die sich zwischen Releases ändern, z. B. aufgrund eines benutzerdefinierten Gebietsschemas. Wenn Ihre Anwendung Daten beibehalten oder übertragen muss, finden Sie weitere Informationen unter Verwenden persistenter Gebietsschemadaten.
 

Syntax

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

Parameter

[in, optional] lpLocaleName

Zeiger auf einen Gebietsschemanamen oder einen der folgenden vordefinierten Werte.

[in] dwFlags

Flags, die Zeitformatoptionen angeben. Die Anwendung kann eine Kombination aus den folgenden Werten und LOCALE_USE_CP_ACP oder LOCALE_NOUSEROVERRIDE angeben.

Vorsicht Die Verwendung von LOCALE_NOUSEROVERRIDE wird dringend abgeraten, da die Benutzereinstellungen deaktiviert werden.
 
Wert Bedeutung
TIME_NOMINUTESORSECONDS
 Verwenden Sie keine Minuten oder Sekunden.
TIME_NOSECONDS
 Verwenden Sie keine Sekunden.
TIME_NOTIMEMARKER
 Verwenden Sie keine Zeitmarkierung.
TIME_FORCE24HOURFORMAT
 Verwenden Sie immer ein 24-Stunden-Zeitformat.

[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 Zeichen 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 im Puffer abgerufenen Zeichen zurück, die von lpTimeStr angegeben werden. 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

Wenn eine Zeitmarkierung vorhanden ist und das TIME_NOTIMEMARKER-Flag nicht festgelegt ist, lokalisiert die Funktion den Zeitmarker basierend auf dem angegebenen Gebietsschemabezeichner. Beispiele für Zeitmarkierungen sind "AM" und "PM" für Englisch (USA).

Die Von lpTime angegebenen Zeitwerte in der Struktur müssen gültig sein. Die Funktion überprüft jeden Zeitwert, um festzustellen, ob sie sich innerhalb des entsprechenden Wertebereichs befindet. Wenn sich ein Zeitwert außerhalb des richtigen Bereichs befindet, schlägt die Funktion fehl und legt den letzten Fehler auf ERROR_INVALID_PARAMETER fest.

Die Funktion ignoriert die Datumsmember der SYSTEMTIME-Struktur . Dazu gehören: wYear, wMonth, wDayOfWeek und wDay.

Wenn TIME_NOMINUTESORSECONDS oder TIME_NOSECONDS angegeben ist, entfernt die Funktion die Trennzeichen nach den Elementen Minuten und/oder Sekunden.

Wenn TIME_NOTIMEMARKER angegeben ist, entfernt die Funktion die Trennzeichen vor und nach der Zeitmarkierung.

Wenn TIME_FORCE24HOURFORMAT angegeben ist, zeigt die Funktion eine vorhandene Zeitmarkierung an, es sei denn, das flag TIME_NOTIMEMARKER ist ebenfalls festgelegt.

Die Funktion enthält keine Millisekunden als Teil der formatierten Zeitzeichenfolge.

Die Funktion gibt keine Fehler für eine fehlerhafte Formatzeichenfolge zurück, sondern bildet nur die bestmögliche Zeitzeichenfolge. Wenn Bilder im Format von mehr als zwei Stunden, Minuten, Sekunden oder Zeitmarkierungen übergeben werden, wird die Funktion standardmäßig auf zwei festgelegt. Die einzigen gültigen Zeitmarkerbilder sind beispielsweise "t" und "tt". Wenn "ttt" übergeben wird, geht die Funktion von "tt" aus.

Um das Zeitformat ohne tatsächliche Formatierung zu erhalten, sollte die Anwendung die GetLocaleInfoEx-Funktion verwenden und LOCALE_STIMEFORMAT angeben.

Die Anwendung kann die folgenden Elemente verwenden, um eine Formatbildzeichenfolge zu erstellen. Wenn Leerzeichen verwendet werden, um die Elemente in der Formatzeichenfolge zu trennen, werden diese Leerzeichen an derselben Position in der Ausgabezeichenfolge angezeigt. Die Buchstaben müssen groß- oder klein geschrieben sein, z. B. "ss", nicht "SS". Zeichen in der Formatzeichenfolge, die in einzelne Anführungszeichen eingeschlossen sind, werden an derselben Position und unverändert in der Ausgabezeichenfolge angezeigt.

Picture Bedeutung
h Stunden ohne führende Null für einstellige Stunden; 12-Stunden-Uhr
hh Stunden mit führendem Null für einstellige Stunden; 12-Stunden-Uhr
H Stunden ohne führende Null für einstellige Stunden; 24-Stunden-Uhr
HH Stunden mit führendem Null für einstellige Stunden; 24-Stunden-Uhr
m Minuten ohne führende Null für einstellige Minuten
mm Minuten mit führender Null für einstellige Minuten
s Sekunden ohne führende Null für einstellige Sekunden
ss Sekunden mit führender Null für einstellige Sekunden
t Ein zeichenweise Zeitmarkierungszeichenfolge, z. B. A oder P
tt Mehrzeichen-Zeitmarkierungszeichenfolge, z. B. AM oder PM
 

Beispielsweise, um die Zeitzeichenfolge abzurufen

"11:29:40 PM"

Die Anwendung sollte die Bildzeichenfolge verwenden

"hh':'mm':'ss tt"

Diese Funktion kann Daten aus benutzerdefinierten Gebietsschemas abrufen. Es ist nicht garantiert, dass die Daten von Computer zu Computer oder zwischen den Ausführungen einer Anwendung identisch sind. Wenn Ihre Anwendung Daten beibehalten oder übertragen muss, finden Sie weitere Informationen unter Verwenden persistenter Gebietsschemadaten.

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

Anforderungen

   
Unterstützte Mindestversion (Client) Windows Vista [Desktop-Apps | UWP-Apps]
Unterstützte Mindestversion (Server) Windows Server 2008 [Desktop-Apps | UWP-Apps]
Zielplattform Windows
Kopfzeile datetimeapi.h
Bibliothek Kernel32.lib
DLL Kernel32.dll

Siehe auch

GetDateFormatEx

GetLocaleInfoEx

GetTimeFormat

Unterstützung für landessprachliche Sprachen

Unterstützungsfunktionen für nationalsprachliche Sprachen