GetTimeFormatA, fonction (datetimeapi.h)

Article
08/23/2023

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

Note Pour des raisons d’interopérabilité, l’application doit préférer la fonction GetTimeFormatEx à GetTimeFormat , car Microsoft migre 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 GetTimeFormatEx.

Syntaxe

int GetTimeFormatA(
  [in]            LCID             Locale,
  [in]            DWORD            dwFlags,
  [in, optional]  const SYSTEMTIME *lpTime,
  [in, optional]  LPCSTR           lpFormat,
  [out, optional] LPSTR            lpTimeStr,
  [in]            int              cchTime
);

Paramètres

[in] Locale

Identificateur de paramètres régionaux qui spécifie les paramètres régionaux. 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 d’heure. Pour obtenir des définitions détaillées, consultez le paramètre dwFlags de GetTimeFormatEx.

[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 valeurs TCHAR, 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 valeurs TCHAR récupérées dans la mémoire tampon indiquée par lpTimeStr. Si le paramètre cchTime est défini sur 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 suffisamment grande ou 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. L’espace de stockage disponible n’était pas suffisant pour effectuer cette opération.

Remarques

Consultez les remarques relatives à GetTimeFormatEx.

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 ( ?).

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

Notes

L’en-tête datetimeapi.h définit GetTimeFormat en tant qu’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. La combinaison 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.

Configuration requise

Condition requise	Valeur
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

Voir aussi

GetDateFormat

GetLocaleInfo

GetTimeFormatEx

Prise en charge des langues nationales

Fonctions de prise en charge des langues nationales