Funzione GetTimeFormatEx (datetimeapi.h)
Formatta l'ora come stringa temporale per le impostazioni locali specificate in base al nome. La funzione formatta un'ora specificata o l'ora del sistema locale.
Sintassi
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
);
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 formato ora. L'applicazione può specificare una combinazione dei valori seguenti e LOCALE_USE_CP_ACP o LOCALE_NOUSEROVERRIDE.
[in, optional] lpTime
Puntatore a una struttura SYSTEMTIME che contiene le informazioni sul tempo da formattare. L'applicazione può impostare questo parametro su NULL se la funzione deve usare l'ora di sistema locale corrente.
[in, optional] lpFormat
Puntatore a un'immagine di formato da usare per formattare la stringa temporale. Se l'applicazione imposta questo parametro su NULL, la funzione formatta la stringa in base al formato ora delle impostazioni locali specificate. Se l'applicazione non imposta il parametro su NULL, la funzione usa le impostazioni locali solo per informazioni non specificate nella stringa di immagine di formato, ad esempio i marcatori temporali specifici delle impostazioni locali. Per informazioni sulla stringa di immagine di formato, vedere la sezione Osservazioni.
[out, optional] lpTimeStr
Puntatore a un buffer in cui questa funzione recupera la stringa di tempo formattata.
[in] cchTime
Dimensioni, in caratteri, per il buffer stringa di tempo indicato da lpTimeStr. In alternativa, l'applicazione può impostare questo parametro su 0. In questo caso, la funzione restituisce le dimensioni necessarie per il buffer stringa di tempo e non usa il parametro lpTimeStr .
Valore restituito
Restituisce il numero di caratteri recuperati nel buffer indicato da lpTimeStr. Se il parametro cchTime è impostato su 0, la funzione restituisce le dimensioni del buffer necessario per contenere la stringa di tempo formattata, incluso un carattere null di terminazione.
Questa 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_FLAGS. I valori forniti per i flag non sono validi.
- ERROR_INVALID_PARAMETER. Uno dei valori dei parametri non è valido.
- ERROR_OUTOFMEMORY. L'archiviazione non è sufficiente per completare questa operazione.
Commenti
Se esiste un indicatore di tempo e il flag di TIME_NOTIMEMARKER non è impostato, la funzione localizza il marcatore temporale in base all'identificatore delle impostazioni locali specificato. Esempi di indicatori temporali sono "AM" e "PM" per l'inglese (Stati Uniti).
I valori di ora nella struttura indicati da lpTime devono essere validi. La funzione controlla ognuno dei valori temporali per determinare che si trova all'interno dell'intervallo appropriato di valori. Se uno dei valori temporali non è compreso nell'intervallo corretto, la funzione ha esito negativo e imposta l'ultimo errore su ERROR_INVALID_PARAMETER.
La funzione ignora i membri della data della struttura SYSTEMTIME . Includono: wYear, wMonth, wDayOfWeek e wDay.
Se viene specificato TIME_NOMINUTESORSECONDS o TIME_NOSECONDS, la funzione rimuove i separatori seguenti i membri minuti e/o secondi.
Se viene specificato TIME_NOTIMEMARKER, la funzione rimuove i separatori precedenti e seguendo il marcatore temporale.
Se viene specificato TIME_FORCE24HOURFORMAT, la funzione visualizza qualsiasi indicatore di tempo esistente, a meno che non sia impostato anche il flag TIME_NOTIMEMARKER.
La funzione non include millisecondi come parte della stringa di tempo formattata.
La funzione non restituisce errori per una stringa di formato non valida, ma forma solo la stringa di tempo migliore possibile. Se vengono passate più di due ore, minuti, secondi o immagini di formato indicatore di tempo, la funzione viene predefinita a due. Ad esempio, l'unico indicatore temporale valido è "t" e "tt". Se "ttt" viene passato, la funzione presuppone "tt".
Per ottenere il formato ora senza eseguire alcuna formattazione effettiva, l'applicazione deve usare la funzione GetLocaleInfoEx , specificando LOCALE_STIMEFORMAT.
L'applicazione può usare gli elementi seguenti per costruire una stringa di immagine di formato. Se gli spazi vengono usati per separare gli elementi nella stringa di formato, questi spazi vengono visualizzati nella stessa posizione nella stringa di output. Le lettere devono essere maiuscole o minuscole, ad esempio "ss", non "SS". I caratteri nella stringa di formato racchiusi tra virgolette singole vengono visualizzati nella stessa posizione e invariati nella stringa di output.
| Immagine | Significato |
|---|---|
| h | Ore senza zero iniziale per ore a cifra singola; Orologio di 12 ore |
| hh | Ore con zero iniziale per ore a cifra singola; Orologio di 12 ore |
| H | Ore senza zero iniziale per ore a cifra singola; Orologio di 24 ore |
| HH | Ore con zero iniziale per ore a cifra singola; Orologio di 24 ore |
| m | Minuti senza zero iniziale per minuti a cifra singola |
| MM | Minuti con zero iniziale per minuti a cifra singola |
| s | Secondi senza zero iniziale per secondi a cifra singola |
| ss | Secondi con zero iniziale per secondi a cifra singola |
| t | Stringa del marcatore di caratteri, ad esempio A o P |
| tt | Stringa di marcatore temporale a più caratteri, ad esempio AM o PM |
Ad esempio, per ottenere la stringa di tempo
"11:29:40 PM"
l'applicazione deve usare la stringa immagine
"hh':'mm':'ss tt"
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.
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.
A partire da Windows 8: GetTimeFormatEx è dichiarato in Datetimeapi.h. Prima di Windows 8, è stato dichiarato in Winnls.h.
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 | datetimeapi.h |
| Libreria | Kernel32.lib |
| DLL | Kernel32.dll |