Funzione GetDateFormatEx (datetimeapi.h)

Articolo
08/23/2023

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

Nota L'applicazione deve chiamare questa funzione in preferenza a GetDateFormat 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 GetDateFormatEx(
  [in, optional]  LPCWSTR          lpLocaleName,
  [in]            DWORD            dwFlags,
  [in, optional]  const SYSTEMTIME *lpDate,
  [in, optional]  LPCWSTR          lpFormat,
  [out, optional] LPWSTR           lpDateStr,
  [in]            int              cchDate,
  [in, optional]  LPCWSTR          lpCalendar
);

Parametri

[in, optional] lpLocaleName

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

[in] dwFlags

Flag che specificano varie opzioni di funzione che possono essere impostate se lpFormat è impostato su NULL. L'applicazione può specificare una combinazione dei valori seguenti e LOCALE_USE_CP_ACP o LOCALE_NOUSEROVERRIDE.

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

Valore	Significato
DATE_AUTOLAYOUT	Windows 7 e versioni successive: Rilevare la necessità di un layout di lettura da destra a sinistra e da sinistra usando le impostazioni locali e le informazioni sul calendario e aggiungere i segni di conseguenza. Questo valore non può essere usato con DATE_LTRREADING o DATE_RTLREADING. DATE_AUTOLAYOUT è preferibile per DATE_LTRREADING e DATE_RTLREADING perché usa le impostazioni locali e i calendari per determinare l'aggiunta corretta di segni.
DATE_LONGDATE	Usare il formato di data lunga. Questo valore non può essere usato con DATE_MONTHDAY, DATE_SHORTDATE o DATE_YEARMONTH.
DATE_LTRREADING	Aggiungere segni per il layout di lettura da sinistra a destra. Questo valore non può essere usato con DATE_RTLREADING.
DATE_RTLREADING	Aggiungere segni per il layout di lettura da destra a sinistra. Questo valore non può essere usato con DATE_LTRREADING
DATE_SHORTDATE	Usare il formato di data breve. Questo è il valore predefinito. Questo valore non può essere usato con DATE_MONTHDAY, DATE_LONGDATE o DATE_YEARMONTH.
DATE_USE_ALT_CALENDAR	Usare il calendario alternativo, se presente, per formattare la stringa di data. Se questo flag è impostato, la funzione usa il formato predefinito per tale calendario alternativo, anziché usare eventuali overridi utente. Gli overridi utente verranno usati solo nel caso in cui non sia presente alcun formato predefinito per il calendario alternativo specificato.
DATE_YEARMONTH	Windows Vista: Usare il formato anno/mese. Questo valore non può essere usato con DATE_MONTHDAY, DATE_SHORTDATE o DATE_LONGDATE.
DATE_MONTHDAY	Windows 10: usare la combinazione di formati mese e giorno appropriati per le impostazioni locali specificate. Questo valore non può essere usato con DATE_YEARMONTH, DATE_SHORTDATE o DATE_LONGDATE.

Se l'applicazione non specifica DATE_YEARMONTH, DATE_MONTHDAY, DATE_SHORTDATE o DATE_LONGDATE e lpFormat è impostata su NULL, DATE_SHORTDATE è l'impostazione predefinita.

[in, optional] lpDate

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

[in, optional] lpFormat

Puntatore a una stringa di immagine di formato usata per formare la data. I valori possibili per la stringa di immagine di formato sono definiti in Day , Month, Year e Era Format Pictures.

Ad esempio, per ottenere la stringa di data "Wed, August 31 94", l'applicazione usa la stringa di immagine "ddd',' MMM dd y".

La funzione usa le impostazioni locali specificate solo per informazioni non specificate nella stringa di immagine di formato, ad esempio i nomi giorno e mese per le impostazioni locali. L'applicazione può impostare questo parametro su NULL per formattare la stringa in base al formato 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 usato.

[in, optional] lpCalendar

Riservati; deve impostare su NULL.

Valore restituito

Restituisce il numero di caratteri scritti nel buffer lpDateStr se riuscito. 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.

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.

Commenti

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 .

La data più recente supportata da questa funzione è il 1° gennaio 1601.

Il nome del giorno, il nome abbreviato del giorno, il nome del mese e il nome del mese abbreviato sono tutti localizzati in base all'identificatore delle impostazioni locali.

I valori di data nella struttura indicati da lpDate devono essere validi. La funzione controlla ognuno dei valori di data: anno, mese, giorno e giorno della settimana. Se il giorno della settimana non è corretto, la funzione usa il valore corretto e non restituisce alcun errore. Se uno degli altri valori di data non rientra nell'intervallo corretto, la funzione ha esito negativo e imposta l'ultimo errore su ERROR_INVALID_PARAMETER.

La funzione ignora i membri temporali della struttura SYSTEMTIME indicati da lpDate. Questi includono wHour, wMinute, wSecond e wMilliseconds.

Se il parametro lpFormat contiene una stringa di formato non valida, la funzione non restituisce errori, ma forma solo la stringa di data migliore possibile. Ad esempio, le uniche immagini dell'anno valide sono L"y" e L"yy", dove "L" indica una stringa Unicode (caratteri a 16 bit). Se L"y" viene passato, la funzione presuppone L"yy". Se L"yyy" viene passato, la funzione presuppone L"yy". Se più di quattro date (L"dddd") o quattro mesi (L"MMMM") le immagini vengono passate, la funzione viene predefinita su L"dd" o L"MMMM".

L'applicazione deve racchiudere qualsiasi testo che deve rimanere nel formato esatto nella stringa di data all'interno di virgolette singole nell'immagine del formato data. La virgoletta singola può essere usata anche come carattere di escape per consentire la visualizzazione della virgoletta singola nella stringa di data. Tuttavia, la sequenza di escape deve essere racchiusa tra due virgolette singole. Ad esempio, per visualizzare la data come "Maggio '93", la stringa di formato è: L"MMMM ''''y". La prima e l'ultima virgolette singole sono le virgolette racchiuse. La seconda e la terza virgolette singole sono la sequenza di escape per consentire la visualizzazione della virgoletta singola prima del secolo.

Quando l'immagine di data contiene sia una forma numerica del giorno (d o dd) che il nome del mese completo (MMMM), la forma genitiva del nome del mese viene recuperata nella stringa di data.

Per ottenere il formato di data breve e lunga predefinito senza eseguire alcuna formattazione effettiva, l'applicazione deve usare GetLocaleInfoEx con la costante LOCALE_SSHORTDATE o LOCALE_SLONGDATE . Per ottenere il formato data per un calendario alternativo, l'applicazione usa GetLocaleInfoEx con la costante LOCALE_IOPTIONALCALENDAR . Per ottenere il formato data per un calendario specifico, l'applicazione usa GetCalendarInfoEx, passando l'identificatore di calendario appropriato. Può chiamare EnumCalendarInfoEx o EnumDateFormatsEx per recuperare i formati di data per un determinato calendario.

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.

Il formato DATE_LONGDATE include due tipi di modelli di data: modelli che includono il giorno della settimana e i modelli che non includono il giorno della settimana. Ad esempio, "Martedì, 18 ottobre 2016" o "18 ottobre 2016". Se l'applicazione deve assicurarsi che le date usino uno di questi tipi di modelli e non l'altro tipo, l'applicazione deve eseguire le azioni seguenti:

Chiamare la funzione EnumDateFormatsExEx per ottenere tutti i formati di data per il formato DATE_LONGDATE.
Cercare il primo formato di data passato alla funzione callback specificata per EnumDateFormatsExEx che corrisponde all'identificatore del calendario richiesto e ha una stringa di formato data corrispondente ai requisiti dell'applicazione. Ad esempio, cercare il primo formato di data che include "dddd" se l'applicazione richiede che la data includa il nome completo del giorno della settimana o cercare il primo formato data che include né "d" né "d" se l'applicazione richiede che la data includa il nome abbreviato né il nome completo del giorno della settimana.
Chiamare la funzione GetDateFormatEx con il parametro lpFormat impostato sulla stringa di formato data identificata come formato appropriato nella funzione callback.

Se la presenza o l'assenza del giorno della settimana nel formato di data lunga non è importante per l'applicazione, l'applicazione può chiamare direttamente GetDateFormatEx senza prima enumerare tutti i formati di data prolungata chiamando EnumDateFormatsExEx.

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: GetDateFormatEx è dichiarato in Datetimeapi.h. Prima di Windows 8, è stato dichiarato in Winnls.h.

Requisiti

Requisito	Valore
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