Fonction GetDateFormatEx (datetimeapi.h)

Article
08/23/2023

Met en forme une date en tant que chaîne de date pour un paramètre régional spécifié par nom. La fonction met en forme une date spécifiée ou la date système locale.

Note L’application doit appeler cette fonction de préférence à GetDateFormat si elle est conçue pour s’exécuter uniquement sur Windows Vista et versions ultérieures.

Note Cette fonction peut mettre en forme des données qui changent d’une version à l’autre, par exemple, en raison d’un paramètre régional personnalisé. Si votre application doit conserver ou transmettre des données, consultez Utilisation des données de paramètres régionaux persistants.

Syntaxe

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
);

Paramètres

[in, optional] lpLocaleName

Pointeur vers un nom de paramètres régionaux ou l’une des valeurs prédéfinies suivantes.

[in] dwFlags

Indicateurs spécifiant différentes options de fonction qui peuvent être définies si lpFormat a la valeur NULL. L’application peut spécifier une combinaison des valeurs suivantes et LOCALE_USE_CP_ACP ou LOCALE_NOUSEROVERRIDE.

Attention L’utilisation de LOCALE_NOUSEROVERRIDE est fortement déconseillée, car elle désactive les préférences utilisateur.

Valeur	Signification
DATE_AUTOLAYOUT	Windows 7 et versions ultérieures : Détectez la nécessité d’une disposition de lecture de droite à gauche et de gauche à droite à l’aide des paramètres régionaux et des informations de calendrier, et ajoutez des marques en conséquence. Cette valeur ne peut pas être utilisée avec DATE_LTRREADING ou DATE_RTLREADING. DATE_AUTOLAYOUT est préférable à DATE_LTRREADING et DATE_RTLREADING, car il utilise les paramètres régionaux et les calendriers pour déterminer l’ajout correct des marques.
DATE_LONGDATE	Utilisez le format de date long. Cette valeur ne peut pas être utilisée avec DATE_MONTHDAY, DATE_SHORTDATE ou DATE_YEARMONTH.
DATE_LTRREADING	Ajoutez des marques pour la disposition de lecture de gauche à droite. Cette valeur ne peut pas être utilisée avec DATE_RTLREADING.
DATE_RTLREADING	Ajoutez des marques pour la disposition de lecture de droite à gauche. Cette valeur ne peut pas être utilisée avec DATE_LTRREADING
DATE_SHORTDATE	Utilisez le format de date court. Il s’agit de la valeur par défaut. Cette valeur ne peut pas être utilisée avec DATE_MONTHDAY, DATE_LONGDATE ou DATE_YEARMONTH.
DATE_USE_ALT_CALENDAR	Utilisez l’autre calendrier, le cas échéant, pour mettre en forme la chaîne de date. Si cet indicateur est défini, la fonction utilise le format par défaut pour ce calendrier de remplacement, plutôt que d’utiliser des remplacements d’utilisateur. Les remplacements utilisateur seront utilisés uniquement dans le cas où il n’existe pas de format par défaut pour le calendrier de remplacement spécifié.
DATE_YEARMONTH	Windows Vista : Utilisez le format année/mois. Cette valeur ne peut pas être utilisée avec DATE_MONTHDAY, DATE_SHORTDATE ou DATE_LONGDATE.
DATE_MONTHDAY	Windows 10 : utilisez la combinaison des formats mois et jour appropriés pour les paramètres régionaux spécifiés. Cette valeur ne peut pas être utilisée avec DATE_YEARMONTH, DATE_SHORTDATE ou DATE_LONGDATE.

Si l’application ne spécifie pas DATE_YEARMONTH, DATE_MONTHDAY, DATE_SHORTDATE ou DATE_LONGDATE, et si lpFormat a la valeur NULL, DATE_SHORTDATE est la valeur par défaut.

[in, optional] lpDate

Pointeur vers une structure SYSTEMTIME qui contient les informations de date à mettre en forme. L’application peut définir ce paramètre sur NULL si la fonction doit utiliser la date actuelle du système local.

[in, optional] lpFormat

Pointeur vers une chaîne d’image de format utilisée pour former la date. Les valeurs possibles pour la chaîne d’image de format sont définies dans Jour, Mois, Année et Images au format Era.

Par exemple, pour obtenir la chaîne de date « Wed, Aug 31 94 », l’application utilise la chaîne d’image « ddd',' MMM jj yy ».

La fonction utilise les paramètres régionaux spécifiés uniquement pour les informations qui ne sont pas spécifiées dans la chaîne d’image de format, par exemple, les noms des jours et des mois pour les paramètres régionaux. L’application peut définir ce paramètre sur NULL pour mettre en forme la chaîne en fonction du format de date pour les paramètres régionaux spécifiés.

[out, optional] lpDateStr

Pointeur vers une mémoire tampon dans laquelle cette fonction récupère la chaîne de date mise en forme.

[in] cchDate

Taille, en caractères, de la mémoire tampon lpDateStr . L’application peut définir ce paramètre sur 0 pour renvoyer la taille de mémoire tampon requise pour contenir la chaîne de date mise en forme. Dans ce cas, la mémoire tampon indiquée par lpDateStr n’est pas utilisée.

[in, optional] lpCalendar

Réservés au; doit avoir la valeur NULL.

Valeur retournée

Retourne le nombre de caractères écrits dans la mémoire tampon lpDateStr en cas de réussite. Si le paramètre cchDate a la valeur 0, la fonction retourne le nombre de caractères requis pour contenir la chaîne de date mise en forme, y compris le caractère null de fin.

Cette fonction retourne 0 si elle ne réussit pas. Pour obtenir des informations d’erreur étendues, l’application peut appeler GetLastError, qui peut retourner l’un des codes d’erreur suivants :

ERROR_INSUFFICIENT_BUFFER. Une taille de mémoire tampon fournie n’était pas assez grande ou elle a été incorrectement définie sur NULL.
ERROR_INVALID_FLAGS. Les valeurs fournies pour les indicateurs n’étaient pas valides.
ERROR_INVALID_PARAMETER. L’une des valeurs de paramètre n’était pas valide.

Remarques

Note Cette API est mise à jour pour prendre en charge le changement d’ère japonaise de mai 2019. Si votre application prend en charge le calendrier japonais, vous devez vérifier qu’elle gère correctement la nouvelle ère. Pour plus d’informations, consultez Préparer votre application pour le changement d’ère japonaise .

La date la plus ancienne prise en charge par cette fonction est le 1er janvier 1601.

Le nom du jour, le nom du jour abrégé, le nom du mois et le nom du mois abrégé sont tous localisés en fonction de l’identificateur des paramètres régionaux.

Les valeurs de date dans la structure indiquée par lpDate doivent être valides. La fonction vérifie chacune des valeurs de date : année, mois, jour et jour de la semaine. Si le jour de la semaine est incorrect, la fonction utilise la valeur correcte et ne retourne aucune erreur. Si l’une des autres valeurs de date se trouve en dehors de la plage correcte, la fonction échoue et définit la dernière erreur sur ERROR_INVALID_PARAMETER.

La fonction ignore les membres de temps de la structure SYSTEMTIME indiqués par lpDate. Il s’agit notamment de wHour, wMinute, wSecond et wMillisecondes.

Si le paramètre lpFormat contient une chaîne de format incorrect, la fonction ne retourne aucune erreur, mais forme simplement la meilleure chaîne de date possible. Par exemple, les seules images d’année valides sont L"aaaa » et L"yyy », où le « L » indique une chaîne Unicode (caractères 16 bits). Si L"y » est passé, la fonction suppose L"yy ». Si L"yyyy » est transmis, la fonction suppose L"yyyyy ». Si plus de quatre images de date (L"dddd ») ou quatre mois (L"MMMM ») sont transmises, la fonction par défaut est L"dddd » ou L"MMMM ».

L’application doit inclure tout texte qui doit rester dans sa forme exacte dans la chaîne de date entre guillemets simples dans l’image au format de date. Le guillemet unique peut également être utilisé comme caractère d’échappement pour permettre l’affichage du guillemet unique lui-même dans la chaîne de date. Toutefois, la séquence d’échappement doit être placée entre deux guillemets simples. Par exemple, pour afficher la date sous la forme « May '93 », la chaîne de format est : L"MMMM ''''yy ». Le premier et le dernier guillemet unique sont les guillemets englobants. Les deuxième et troisième guillemets simples sont la séquence d’échappement permettant d’afficher le guillemet unique avant le siècle.

Lorsque l’image de date contient à la fois une forme numérique du jour (d ou dd) et le nom complet du mois (MMMM), la forme génitive du nom du mois est récupérée dans la chaîne de date.

Pour obtenir le format de date court et long par défaut sans effectuer de mise en forme réelle, l’application doit utiliser GetLocaleInfoEx avec la constante LOCALE_SSHORTDATE ou LOCALE_SLONGDATE . Pour obtenir le format de date d’un autre calendrier, l’application utilise GetLocaleInfoEx avec la constante LOCALE_IOPTIONALCALENDAR . Pour obtenir le format de date d’un calendrier particulier, l’application utilise GetCalendarInfoEx, en passant l’identificateur de calendrier approprié. Il peut appeler EnumCalendarInfoEx ou EnumDateFormatsEx pour récupérer les formats de date d’un calendrier particulier.

Cette fonction peut récupérer des données à partir de paramètres régionaux personnalisés. Il n’est pas garanti que les données soient identiques d’un ordinateur à l’autre ou entre les exécutions d’une application. Si votre application doit conserver ou transmettre des données, consultez Utilisation des données de paramètres régionaux persistants.

Le format DATE_LONGDATE comprend deux types de modèles de date : les modèles qui incluent le jour de la semaine et les modèles qui n’incluent pas le jour de la semaine. Par exemple, « mardi 18 octobre 2016 » ou « 18 octobre 2016 ». Si votre application doit s’assurer que les dates utilisent l’un de ces types de modèles et non l’autre type, votre application doit effectuer les actions suivantes :

Appelez la fonction EnumDateFormatsExEx pour obtenir tous les formats de date pour le format DATE_LONGDATE.
Recherchez le premier format de date passé à la fonction de rappel que vous avez spécifiée pour EnumDateFormatsExEx qui correspond à l’identificateur de calendrier demandé et qui a une chaîne de format de date qui correspond aux exigences de votre application. Par exemple, recherchez le premier format de date qui inclut « dddd » si votre application exige que la date inclue le nom complet du jour de la semaine, ou recherchez le premier format de date qui n’inclut ni « dddd » ni « dddd » si votre application exige que la date inclue le nom abrégé ou le nom complet du jour de la semaine.
Appelez la fonction GetDateFormatEx avec le paramètre lpFormat défini sur la chaîne de format de date que vous avez identifiée comme format approprié dans la fonction de rappel.

Si la présence ou l’absence du jour de la semaine dans le format de date longue n’a pas d’importance pour votre application, votre application peut appeler GetDateFormatEx directement sans énumérer au préalable tous les formats de date longs en appelant EnumDateFormatsExEx.

À compter de Windows 8 : si votre application transmet des balises de langue à cette fonction à partir de l’espace de noms Windows.Globalization, elle doit d’abord convertir les balises en appelant ResolveLocaleName.

À compter de Windows 8 : GetDateFormatEx est déclaré dans Datetimeapi.h. Avant Windows 8, elle était déclarée dans Winnls.h.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows Vista [applications de bureau \| applications UWP]
Serveur minimal pris en charge	Windows Server 2008 [applications de bureau \| applications UWP]
Plateforme cible	Windows
En-tête	datetimeapi.h
Bibliothèque	Kernel32.lib
DLL	Kernel32.dll