GetDateFormatA, fonction (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 l’identificateur de paramètres régionaux. La fonction met en forme une date spécifiée ou la date système locale.

Note Pour des raisons d’interopérabilité, l’application doit préférer la fonction GetDateFormatEx à GetDateFormat , car Microsoft effectue une migration vers l’utilisation de noms de paramètres régionaux au lieu d’identificateurs régionaux pour les nouveaux paramètres régionaux. Toute application qui sera exécutée uniquement sur Windows Vista et versions ultérieures doit utiliser GetDateFormatEx.

Syntaxe

int GetDateFormatA(
  [in]            LCID             Locale,
  [in]            DWORD            dwFlags,
  [in, optional]  const SYSTEMTIME *lpDate,
  [in, optional]  LPCSTR           lpFormat,
  [out, optional] LPSTR            lpDateStr,
  [in]            int              cchDate
);

Paramètres

[in] Locale

Identificateur de paramètres régionaux pour lequel cette fonction met en forme la chaîne de date. Vous pouvez utiliser la macro MAKELCID pour créer un identificateur de paramètres régionaux ou utiliser l’une des valeurs prédéfinies suivantes.

[in] dwFlags

Indicateurs spécifiant les options de format de date. Pour obtenir des définitions détaillées, consultez le paramètre dwFlags de GetDateFormatEx.

[in, optional] lpDate

Pointeur vers une structure SYSTEMTIME qui contient les informations de date à mettre en forme. L’application définit 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.

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.

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.

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

Notes

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 .

Consultez Remarques pour GetDateFormatEx.

Lorsque la version ANSI de cette fonction est utilisée avec un identificateur de paramètres régionaux Unicode uniquement, la fonction peut réussir, car le système d’exploitation utilise la page de code système. Toutefois, les caractères qui ne sont pas définis dans la page de code système apparaissent dans la chaîne sous forme de point d’interrogation (« ? »).

À compter de Windows 8 : GetDateFormat est déclaré dans Datetimeapi.h. Avant Windows 8, il était déclaré dans Winnls.h.

Notes

L’en-tête datetimeapi.h définit GetDateFormat comme un alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. Le mélange de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.

Spécifications


Client minimal pris en charge	Windows 2000 Professionnel [applications de bureau uniquement]
Serveur minimal pris en charge	Windows 2000 Server [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	datetimeapi.h
Bibliothèque	Kernel32.lib
DLL	Kernel32.dll