GetDateFormatW, fonction (datetimeapi.h)

Article
11/20/2024

Met en forme une date sous forme de chaîne de date pour les paramètres régionaux spécifiés par l’identificateur de paramètres régionaux. La fonction met en forme une date spécifiée ou la date du système local.

Remarque Pour des raisons d’interopérabilité, l’application doit préférer la fonction GetDateFormatEx à GetDateFormat, car Microsoft migre vers l’utilisation de noms de paramètres régionaux au lieu des identificateurs de paramètres 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 GetDateFormatW(
  [in]            LCID             Locale,
  [in]            DWORD            dwFlags,
  [in, optional]  const SYSTEMTIME *lpDate,
  [in, optional]  LPCWSTR          lpFormat,
  [out, optional] LPWSTR           lpDateStr,
  [in]            int              cchDate
);

Paramètres

[in] Locale

identificateur de paramètres régionaux qui spécifie les paramètres régionaux dont 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 système locale actuelle.

[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 Format d’images.

La fonction utilise les paramètres régionaux spécifiés uniquement pour les informations non spécifiées dans la chaîne d’image de format, par exemple les noms de jour et de 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 des 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 retourner 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 de retour

Retourne le nombre de caractères écrits dans la mémoire tampon lpDateStr en cas de réussite. Si le paramètre cchDate est défini sur 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 suffisamment grande, ou elle était 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’est pas valide.

Remarques

Remarque Cette API est mise à jour pour prendre en charge le changement de l’è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 la modification de l’ère japonaise.

Consultez les 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 codes système. Toutefois, les caractères qui ne sont pas définis dans la page de codes système apparaissent dans la chaîne sous la forme d’un point d’interrogation (« ? »).

à partir de Windows 8 : GetDateFormat est déclaré dans Datetimeapi.h. Avant Windows 8, il a été déclaré dans Winnls.h.

Note

L’en-tête datetimeapi.h définit GetDateFormat comme 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.

Exigences

Exigence	Valeur
client minimum pris en charge	Windows 2000 Professionnel [applications de bureau uniquement]
serveur minimum pris en charge	Windows 2000 Server [applications de bureau uniquement]
plateforme cible	Windows
d’en-tête	datetimeapi.h
bibliothèque	Kernel32.lib
DLL	Kernel32.dll