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.

• LOCALE_NAME_INVARIANT
• LOCALE_NAME_SYSTEM_DEFAULT
• LOCALE_NAME_USER_DEFAULT

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

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

Vedere anche

GetDateFormatEx

GetLocaleInfoEx

GetTimeFormat

Supporto per la lingua nazionale

Funzioni di supporto del linguaggio nazionale