Funzione GetDurationFormatEx (winnls.h)

Articolo
03/18/2023

Formatta una durata di tempo come stringa temporale per le impostazioni locali specificate in base al nome.

Nota L'applicazione deve chiamare questa funzione in preferenza getDurationFormat se progettata per l'esecuzione solo in Windows Vista e versioni successive.

Nota Questa funzione può formattare i dati che cambiano tra le versioni, ad esempio a causa di impostazioni locali personalizzate. Se l'applicazione deve mantenere o trasmettere dati, vedere Uso di dati locali persistenti.

Sintassi

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
);

Parametri

[in, optional] lpLocaleName

Puntatore a un nome delle impostazioni locali o uno dei valori predefiniti seguenti.

[in] dwFlags

Flag che specificano le opzioni di funzione. Se lpFormat non è impostato su NULL, questo parametro deve essere impostato su 0. Se lpFormat è impostato su NULL, l'applicazione può specificare LOCALE_NOUSEROVERRIDE per formattare la stringa usando il formato di durata predefinita del sistema per le impostazioni locali specificate.

Attenzione L'uso di LOCALE_NOUSEROVERRIDE è fortemente sconsigliato perché disabilita le preferenze utente.

[in, optional] lpDuration

Puntatore a una struttura SYSTEMTIME contenente le informazioni sulla durata del tempo da formattare. L'applicazione imposta questo parametro su NULL se la funzione deve ignorarla e usare ullDuration.

[in] ullDuration

Intero senza segno a 64 bit che rappresenta il numero di intervalli a 100 nanosecondi nella durata. Se vengono impostati sia lpDuration che ullDuration , il parametro lpDuration ha la precedenza. Se lpDuration è impostato su NULL e ullDuration è impostato su 0, la durata è 0.

[in, optional] lpFormat

Puntatore alla stringa di formato con caratteri, come illustrato di seguito. L'applicazione può impostare questo parametro su NULL se la funzione deve formattare la stringa in base al formato di durata per le impostazioni locali specificate. Se lpFormat non è impostato su NULL, la funzione usa le impostazioni locali solo per informazioni non specificate nella stringa di immagine di formato.

Valore	Significato
d	days
h o H	ore
hh o HH	Ore; se meno di dieci, prependò uno zero iniziale
m	minutes
mm	Minuti; se meno di dieci, prependò uno zero iniziale
s	secondi
ss	Secondi; se meno di dieci, prependò uno zero iniziale
f	frazioni di un secondo Nota Il carattere "f" può verificarsi fino a nove volte consecutive (fffffffff), anche se il supporto per i timer di frequenza è limitato a 100 nanosecondi. Pertanto, se sono presenti nove caratteri, le ultime due cifre sono sempre 0.

[out, optional] lpDurationStr

Puntatore al buffer in cui la funzione recupera la stringa di durata.

In alternativa, questo parametro recupera NULL se cchDuration è impostato su 0. In questo caso, la funzione restituisce le dimensioni necessarie per il buffer della stringa di durata.

[in] cchDuration

Dimensioni, in caratteri, del buffer indicato da lpDurationStr.

In alternativa, l'applicazione può impostare questo parametro su 0. In questo caso, la funzione recupera NULL in lpDurationStr e restituisce le dimensioni necessarie per il buffer della stringa di durata.

Valore restituito

Restituisce il numero di caratteri recuperati nel buffer indicato da lpDurationStr se ha esito positivo. Se lpDurationStr è impostato su NULL e cchDuration è impostato su 0, la funzione restituisce le dimensioni necessarie per il buffer stringa di durata, incluso il carattere null di terminazione. Se, ad esempio, 10 caratteri vengono scritti nel buffer, la funzione restituisce 11 per includere il carattere Null terminante.

La funzione restituisce 0 se non riesce. Per ottenere informazioni sull'errore estese, l'applicazione può chiamare GetLastError, che può restituire uno dei codici di errore seguenti:

ERROR_INSUFFICIENT_BUFFER. Una dimensione del buffer fornita non è stata sufficiente oppure è stata impostata in modo errato su NULL.
ERROR_INVALID_PARAMETER. Uno dei valori dei parametri non è valido.

Commenti

Questa funzione può essere usata con applicazioni multimediali che visualizzano l'ora di file e le applicazioni di eventi sportivi che visualizzano i tempi di fine.

La funzione ignora i primi tre membri della struttura SYSTEMTIME: wYear, wMonth e wDayOfWeek.

Questa funzione può recuperare i dati dalle impostazioni locali personalizzate. I dati non sono garantiti come uguali da computer a computer o tra esecuzioni di un'applicazione. Se l'applicazione deve mantenere o trasmettere dati, vedere Uso di dati locali persistenti.

Di seguito sono riportate le caratteristiche delle stringhe di formato di durata:

La formattazione dei caratteri è minuscola.
Nota Viene eseguita un'eccezione per la coerenza con GetTimeFormatEx.An exception is made for (H) to be consistent with GetTimeFormatEx.
Stringhe di formato a due cifre per ore, minuti e secondi prepende uno zero iniziale se il valore è minore di 10.
Il primo campo di output non è soggetto a alcun test dei limiti (ore<24, minuti<60, secondi<60, millisecondi<1000). I giorni non sono soggetti ai test dei limiti.
La funzione presuppone che tutte le stringhe di formato siano in riduzione delle dimensioni del campo, ad esempio ore, minuti, secondi, millisecondi.
Il primo campo da visualizzare è normalizzato, come definito dalla stringa di formato. Ad esempio, se l'applicazione specifica 310 secondi e la stringa di formato è m:ss, l'output è 5:10. Tuttavia, se la stringa di formato specifica minuti e secondi, ma l'applicazione specifica ore, il campo minuti viene modificato di conseguenza.
Se le frazioni non sono il primo campo, il numero di caratteri "f" nella stringa di formato indica il numero di decimali da visualizzare (limite di 9). Se le frazioni sono il primo campo, il numero di caratteri "f" indica il numero di cifre significative sotto un secondo.
Il round-off si verifica per troncamento, non per la regola di cinque round up e quattro round down.
Le virgolette singole vengono usate per eseguire l'escape dei caratteri.

A partire da Windows 8: se l'app passa tag di lingua a questa funzione dallo spazio dei nomi Windows.Globalization, deve prima convertire i tag chiamando ResolveLocaleName.

esempi

Di seguito sono riportati esempi di formati di durata e output corrispondenti per le durate di tempo specificate.

SYSTEMTIME = 14 giorni, 2 ore, 45 minuti, 12 secondi e 247 millisecondi

Formato	Output
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 'ss' s'	338 h 45 m 12 s

SYSTEMTIME = 345 secondi

Formato	Output
hh:mm:ss	00:05:45
h:mm:ss	0:05:45
mm:ss	05:45
m:ss	5:45
mm' m 'ss' s'	05 m 45 s
ss	345
secondi di ss'	345 secondi

uulDuration = 51234567 (5,1234567 secondi)

Formato	Output
s.fff	5.123
s.ffffffff	5.123456
s.fffffffff	5.123456700 (aggiunta di zeri finali)
fff 'ms'	5123 ms
ffffff 'microsecondi'	5123456 microsecondi
fffffffff 'ns'	5123456700 ns

Requisiti


Client minimo supportato	Windows Vista [app desktop \| App UWP]
Server minimo supportato	Windows Server 2008 [app desktop \| App UWP]
Piattaforma di destinazione	Windows
Intestazione	winnls.h (include Windows.h)
Libreria	Kernel32.lib
DLL	Kernel32.dll