Funzione GetDateFormatEx (datetimeapi.h)
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.
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.
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
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 |
Vedere anche
Immagini di formato Day, Month, Year e Era
NLS: Esempio di API basate su nome