Fonction GetTimeFormatEx (datetimeapi.h)

Article
04/06/2023

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

Note L’application doit appeler cette fonction de préférence à GetTimeFormat 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 GetTimeFormatEx(
  [in, optional]  LPCWSTR          lpLocaleName,
  [in]            DWORD            dwFlags,
  [in, optional]  const SYSTEMTIME *lpTime,
  [in, optional]  LPCWSTR          lpFormat,
  [out, optional] LPWSTR           lpTimeStr,
  [in]            int              cchTime
);

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 les options de format de temps. 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
TIME_NOMINUTESORSECONDS	N’utilisez pas de minutes ou de secondes.
TIME_NOSECONDS	N’utilisez pas de secondes.
TIME_NOTIMEMARKER	N’utilisez pas de marqueur de temps.
TIME_FORCE24HOURFORMAT	Utilisez toujours un format d’heure de 24 heures.

[in, optional] lpTime

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

[in, optional] lpFormat

Pointeur vers une image de format à utiliser pour mettre en forme la chaîne de temps. Si l’application définit ce paramètre sur NULL, la fonction met en forme la chaîne en fonction du format d’heure des paramètres régionaux spécifiés. Si l’application ne définit pas le paramètre sur NULL, la fonction utilise les paramètres régionaux uniquement pour les informations non spécifiées dans la chaîne d’image de format, par exemple, les marqueurs de temps spécifiques aux paramètres régionaux. Pour plus d’informations sur la chaîne d’image de format, consultez la section Remarques.

[out, optional] lpTimeStr

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

[in] cchTime

Taille, en caractères, pour la mémoire tampon de chaîne de temps indiquée par lpTimeStr. L’application peut également définir ce paramètre sur 0. Dans ce cas, la fonction retourne la taille requise pour la mémoire tampon de chaîne de temps et n’utilise pas le paramètre lpTimeStr .

Valeur retournée

Retourne le nombre de caractères récupérés dans la mémoire tampon indiquée par lpTimeStr. Si le paramètre cchTime a la valeur 0, la fonction retourne la taille de la mémoire tampon requise pour contenir la chaîne de temps mise en forme, y compris un 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.
ERROR_OUTOFMEMORY. Le stockage disponible n’était pas suffisant pour effectuer cette opération.

Notes

S’il existe un marqueur d’heure et que l’indicateur TIME_NOTIMEMARKER n’est pas défini, la fonction localise le marqueur d’heure en fonction de l’identificateur de paramètres régionaux spécifié. Des exemples de marqueurs d’heure sont « AM » et « PM » pour l’anglais (États-Unis).

Les valeurs d’heure de la structure indiquées par lpTime doivent être valides. La fonction vérifie chacune des valeurs de temps pour déterminer qu’elle se trouve dans la plage de valeurs appropriée. Si l’une des valeurs de temps 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 date de la structure SYSTEMTIME . Il s’agit notamment de wYear, wMonth, wDayOfWeek et wDay.

Si TIME_NOMINUTESORSECONDS ou TIME_NOSECONDS est spécifié, la fonction supprime les séparateurs après les membres minutes et/ou secondes.

Si TIME_NOTIMEMARKER est spécifié, la fonction supprime les séparateurs qui précèdent et suivent le marqueur d’heure.

Si TIME_FORCE24HOURFORMAT est spécifié, la fonction affiche n’importe quel marqueur d’heure existant, sauf si l’indicateur TIME_NOTIMEMARKER est également défini.

La fonction n’inclut pas de millisecondes dans la chaîne de temps mise en forme.

La fonction ne retourne aucune erreur pour une chaîne de format incorrect, mais forme simplement la meilleure chaîne de temps possible. Si plus de deux images au format d’heure, de minute, de seconde ou de marqueur d’heure sont transmises, la fonction est définie par défaut sur deux. Par exemple, les seules images de marqueur d’heure valides sont « t » et « tt ». Si « ttt » est transmis, la fonction suppose « tt ».

Pour obtenir le format d’heure sans effectuer de mise en forme réelle, l’application doit utiliser la fonction GetLocaleInfoEx , en spécifiant LOCALE_STIMEFORMAT.

L’application peut utiliser les éléments suivants pour construire une chaîne d’image de format. Si des espaces sont utilisés pour séparer les éléments dans la chaîne de format, ces espaces apparaissent au même emplacement dans la chaîne de sortie. Les lettres doivent être en majuscules ou minuscules, comme indiqué, par exemple, « ss », et non « SS ». Les caractères de la chaîne de format qui sont placés entre guillemets simples apparaissent au même emplacement et inchangés dans la chaîne de sortie.

Image	Signification
h	Heures sans zéro de début pour les heures à un chiffre ; Horloge de 12 heures
hh	Heures avec zéro en tête pour les heures à un chiffre ; Horloge de 12 heures
H	Heures sans zéro de début pour les heures à un chiffre ; Horloge 24 heures
HH	Heures avec zéro en tête pour les heures à un chiffre ; Horloge 24 heures
m	Minutes sans zéro de début pour les minutes à un chiffre
mm	Minutes avec zéro de début pour les minutes à un chiffre
s	Secondes sans zéro de début pour les secondes à un chiffre
ss	Secondes avec zéro en tête pour les secondes à un chiffre
t	Chaîne de marqueur de temps de caractère, telle que A ou P
tt	Chaîne de marqueur de temps à plusieurs caractères, telle que AM ou PM

Par exemple, pour obtenir la chaîne de temps

"11:29:40 PM"

l’application doit utiliser la chaîne d’image

"hh':'mm':'ss tt"

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.

À 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 : GetTimeFormatEx est déclaré dans Datetimeapi.h. Avant Windows 8, elle était déclarée dans Winnls.h.

Spécifications


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