GetDurationFormatEx-Funktion (winnls.h)

Artikel
03/18/2023

Formatiert eine Zeitdauer als Zeitzeichenfolge für ein gebietsschema, das durch den Namen angegeben ist.

Hinweis Die Anwendung sollte diese Funktion vorZug für GetDurationFormat 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 GetDurationFormatEx(
  [in, optional]  LPCWSTR          lpLocaleName,
  [in]            DWORD            dwFlags,
  [in, optional]  const SYSTEMTIME *lpDuration,
  [in]            ULONGLONG        ullDuration,
  [in, optional]  LPCWSTR          lpFormat,
  [out, optional] LPWSTR           lpDurationStr,
  [in]            int              cchDuration
);

Parameter

[in, optional] lpLocaleName

Zeiger auf einen Gebietsschemanamen oder einen der folgenden vordefinierten Werte.

[in] dwFlags

Flags, die Funktionsoptionen angeben. Wenn lpFormat nicht auf NULL festgelegt ist, muss dieser Parameter auf 0 festgelegt werden. Wenn lpFormat auf NULL festgelegt ist, kann Ihre Anwendung LOCALE_NOUSEROVERRIDE angeben, um die Zeichenfolge mithilfe des Systemstandarddauerformats für das angegebene Gebietsschema zu formatieren.

Vorsicht Die Verwendung von LOCALE_NOUSEROVERRIDE wird dringend abgeraten, da die Benutzereinstellungen deaktiviert werden.

[in, optional] lpDuration

Zeiger auf eine SYSTEMTIME-Struktur , die die zu formatierenden Zeitdauerinformationen enthält. Die Anwendung legt diesen Parameter auf NULL fest, wenn die Funktion ihn ignorieren und ullDuration verwenden soll.

[in] ullDuration

64-Bit-Ganzzahl ohne Vorzeichen, die die Anzahl der Intervalle von 100 Nanosekunden in der Dauer darstellt. Wenn sowohl lpDuration als auch ullDuration festgelegt sind, hat der lpDuration-Parameter Vorrang. Wenn lpDuration auf NULL und ullDuration auf 0 festgelegt ist, ist die Dauer 0.

[in, optional] lpFormat

Zeiger auf die Formatzeichenfolge mit Zeichen wie unten gezeigt. Die Anwendung kann diesen Parameter auf NULL festlegen, wenn die Funktion die Zeichenfolge entsprechend dem Dauerformat für das angegebene Gebietsschema formatieren soll. Wenn lpFormat nicht auf NULL festgelegt ist, verwendet die Funktion das Gebietsschema nur für Informationen, die nicht in der Formatbildzeichenfolge angegeben sind.

Wert	Bedeutung
d	days
h oder H	Stunden
hh oder HH	Stunden; wenn weniger als zehn, einer führenden Null vorangestellt
m	minutes
mm	Minuten; wenn weniger als zehn, einer führenden Null vorangestellt
s	Sekunden
ss	Sekunden; wenn weniger als zehn, einer führenden Null vorangestellt
f	Sekundenbruchteile Hinweis Das Zeichen "f" kann bis zu neun aufeinanderfolgende Male auftreten (fffffffffff), obwohl die Unterstützung für Frequenztimer auf 100 Nanosekunden beschränkt ist. Wenn also neun Zeichen vorhanden sind, sind die letzten beiden Ziffern immer 0.

[out, optional] lpDurationStr

Zeiger auf den Puffer, in dem die Funktion die Dauerzeichenfolge abruft.

Alternativ ruft dieser Parameter NULL ab, wenn cchDuration auf 0 festgelegt ist. In diesem Fall gibt die Funktion die erforderliche Größe für den Dauerzeichenfolgenpuffer zurück.

[in] cchDuration

Größe des Puffers, der von lpDurationStr. angegeben wird, in Zeichen

Alternativ kann die Anwendung diesen Parameter auf 0 festlegen. In diesem Fall ruft die Funktion NULL in lpDurationStr ab und gibt die erforderliche Größe für den Dauerzeichenfolgenpuffer zurück.

Rückgabewert

Gibt die Anzahl der im Puffer abgerufenen Zeichen zurück, die bei erfolgreicher Ausführung von lpDurationStr angegeben wurden. Wenn lpDurationStr auf NULL und cchDuration auf 0 festgelegt ist, gibt die Funktion die erforderliche Größe für den Dauerzeichenfolgenpuffer zurück, einschließlich des beendenden NULL-Zeichens. Wenn beispielsweise 10 Zeichen in den Puffer geschrieben werden, gibt die Funktion 11 zurück, um das beendende NULL-Zeichen einzuschließen.

Die 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_PARAMETER. Jeder der Parameterwerte war ungültig.

Hinweise

Diese Funktion kann mit Multimediaanwendungen verwendet werden, die Dateizeit- und Sportereignisanwendungen anzeigen, die Endzeiten anzeigen.

Die Funktion ignoriert die ersten drei Elemente der SYSTEMTIME-Struktur : wYear, wMonth und wDayOfWeek.

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.

Im Folgenden sind Merkmale von Dauerformatzeichenfolgen aufgeführt:

Formatierungszeichen sind Kleinbuchstaben.
Hinweis Es wird eine Ausnahme für (H) gemacht, um mit GetTimeFormatEx konsistent zu sein.
Zweistellige Formatzeichenfolgen für Stunden, Minuten und Sekunden werden einer führenden Null vorangestellt, wenn der Wert kleiner als 10 ist.
Das erste Ausgabefeld unterliegt keinem Begrenzungstest (Stunden<24, Minuten<60, Sekunden<60, Millisekunden<1000). Tage unterliegen keinen Begrenzungstests.
Die Funktion geht davon aus, dass sich alle Formatzeichenfolgen in abnehmender Feldgröße befinden, z. B. Stunden, Minuten, Sekunden, Millisekunden.
Das erste anzuzeigende Feld ist normalisiert, wie durch die Formatzeichenfolge definiert. Wenn die Anwendung beispielsweise 310 Sekunden angibt und die Formatzeichenfolge m:ss ist, ist die Ausgabe 5:10. Wenn die Formatzeichenfolge jedoch Minuten und Sekunden angibt, die Anwendung Jedoch Stunden angibt, wird das Minutenfeld entsprechend angepasst.
Wenn Brüche nicht das erste Feld sind, gibt die Anzahl der "f"-Zeichen in der Formatzeichenfolge die Anzahl der anzuzeigenden Dezimalstellen an (Grenzwert von 9). Wenn Brüche das erste Feld sind, gibt die Anzahl der "f"-Zeichen die Anzahl der signifikanten Ziffern unter einer Sekunde an.
Die Abrundung erfolgt durch Abschneiden, nicht durch die Regel von fünf Runden und vier Runden nach unten.
Einzelne Anführungszeichen werden verwendet, um Zeichen zu escapen.

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.

Beispiele

Im Folgenden sind Beispiele für Dauerformate und entsprechende Ausgaben für angegebene Zeitdauern aufgeführt.

SYSTEMTIME = 14 Tage, 2 Stunden, 45 Minuten, 12 Sekunden und 247 Millisekunden

Format	Ausgabe
d:hh:mm:ss	14:02:45:12
hh:mm:ss:ff	338:45:12:24
hh:mm:ss:fff	338:45:12:247
h' h 'mm' m 's' s' s'	338 h 45 m 12 s

SYSTEMTIME = 345 Sekunden

Format	Ausgabe
hh:mm:ss	00:05:45
h:mm:ss	0:05:45
mm:ss	05:45
m:ss	5:45
mm' m 's' s' s'	05 m 45 s
ss	345
ss' Sekunden'	345 Sekunden

uulDuration = 51234567 (5,1234567 Sekunden)

Format	Ausgabe
s.fff	5.123
s.ffffff	5.123456
s.fffffffffff	5.123456700 (nachgestellte Nullen hinzufügen)
fff "ms"	5123 ms
ffffff "Microsekunden"	5123456 Mikrosekunden
fffffffffff 'ns'	5123456700 ns

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	winnls.h (einschließlich Windows.h)
Bibliothek	Kernel32.lib
DLL	Kernel32.dll