GetDurationFormatEx-Funktion (winnls.h)

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

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.

• LOCALE_NAME_INVARIANT
• LOCALE_NAME_SYSTEM_DEFAULT
• LOCALE_NAME_USER_DEFAULT

[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.

[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.

[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.

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

SYSTEMTIME = 345 Sekunden

uulDuration = 51234567 (5,1234567 Sekunden)

Anforderungen

Siehe auch

GetDateFormatEx

GetDurationFormat

GetLocaleInfoEx

GetTimeFormatEx

Unterstützung für nationale Sprachen

Nationale Sprachunterstützungsfunktionen