Funzione GetDateFormatW (datetimeapi.h)

Articolo
11/20/2024

Formatta una data come stringa di data per le impostazioni locali specificate dall'identificatore delle impostazioni locali. La funzione formatta una data specificata o la data di sistema locale.

Nota Per motivi di interoperabilità, l'applicazione deve preferire la funzione GetDateFormatEx a GetDateFormat perché Microsoft sta eseguendo la migrazione verso l'uso dei nomi delle impostazioni locali anziché degli identificatori delle impostazioni locali per le nuove impostazioni locali. Qualsiasi applicazione che verrà eseguita solo in Windows Vista e versioni successive deve usare GetDateFormatEx.

Sintassi

int GetDateFormatW(
  [in]            LCID             Locale,
  [in]            DWORD            dwFlags,
  [in, optional]  const SYSTEMTIME *lpDate,
  [in, optional]  LPCWSTR          lpFormat,
  [out, optional] LPWSTR           lpDateStr,
  [in]            int              cchDate
);

Parametri

[in] Locale

identificatore delle impostazioni locali che specifica le impostazioni locali per cui questa funzione formatta la stringa di data. È possibile utilizzare la macro MAKELCID per creare un identificatore delle impostazioni locali o usare uno dei valori predefiniti seguenti.

[in] dwFlags

Flag che specificano le opzioni di formato data. Per definizioni dettagliate, vedere il parametro dwFlags di GetDateFormatEx.

[in, optional] lpDate

Puntatore a una struttura SYSTEMTIME che contiene le informazioni sulla data da formattare. L'applicazione imposta questo parametro su NULL se la funzione deve usare la data di sistema locale corrente.

[in, optional] lpFormat

Puntatore a una stringa di formato immagine utilizzata per formare la data. I valori possibili per la stringa di immagine di formato sono definiti in Giorno, Mese, Anno ed Era Immagini in formato.

La funzione usa le impostazioni locali specificate solo per le informazioni non specificate nella stringa di immagine in formato, ad esempio i nomi dei giorni e dei mesi per le impostazioni locali. L'applicazione può impostare questo parametro su NULL per formattare la stringa in base al formato di data per le impostazioni locali specificate.

[out, optional] lpDateStr

Puntatore a un buffer in cui questa funzione recupera la stringa di data formattata.

[in] cchDate

Dimensioni, in caratteri, del buffer lpDateStr. L'applicazione può impostare questo parametro su 0 per restituire le dimensioni del buffer necessarie per contenere la stringa di data formattata. In questo caso, il buffer indicato da lpDateStr non viene utilizzato.

Valore restituito

Restituisce il numero di caratteri scritti nel buffer lpDateStr se ha esito positivo. Se il parametro cchDate è impostato su 0, la funzione restituisce il numero di caratteri necessari per contenere la stringa di data formattata, incluso il carattere Null di terminazione.

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

ERROR_INSUFFICIENT_BUFFER. Le dimensioni del buffer fornite non sono sufficienti o non sono state impostate correttamente su NULL.
ERROR_INVALID_FLAGS. I valori specificati per i flag non sono validi.
ERROR_INVALID_PARAMETER. Uno dei valori dei parametri non è valido.

Osservazioni

Nota Questa API viene aggiornata per supportare la modifica dell'era giapponese di maggio 2019. Se l'applicazione supporta il calendario giapponese, è necessario verificare che gestisca correttamente la nuova era. Per altre informazioni, vedere Preparare l'applicazione per la modifica dell'era giapponese.

Vedere la sezione Osservazioni per GetDateFormatEx.

Quando la versione ANSI di questa funzione viene usata con un identificatore delle impostazioni locali solo Unicode, la funzione può avere esito positivo perché il sistema operativo usa la tabella codici del sistema. Tuttavia, i caratteri non definiti nella tabella codici di sistema vengono visualizzati nella stringa come punto interrogativo ("?").

A partire da Windows 8: GetDateFormat è dichiarato in Datetimeapi.h. Prima di Windows 8, è stato dichiarato in Winnls.h.

Nota

L'intestazione datetimeapi.h definisce GetDateFormat come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice non indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere convenzioni di per i prototipi di funzioni.

Fabbisogno

Requisito	Valore
client minimo supportato	Windows 2000 Professional [solo app desktop]
server minimo supportato	Windows 2000 Server [solo app desktop]
piattaforma di destinazione	Finestre
intestazione	datetimeapi.h
libreria	Kernel32.lib
dll	Kernel32.dll