GetDurationFormatEx, fonction (winnls.h)

Article
03/18/2023

Met en forme une durée de temps sous forme de chaîne de temps pour un paramètre régional spécifié par nom.

Note L’application doit appeler cette fonction de préférence à GetDurationFormat 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 GetDurationFormatEx(
  [in, optional]  LPCWSTR          lpLocaleName,
  [in]            DWORD            dwFlags,
  [in, optional]  const SYSTEMTIME *lpDuration,
  [in]            ULONGLONG        ullDuration,
  [in, optional]  LPCWSTR          lpFormat,
  [out, optional] LPWSTR           lpDurationStr,
  [in]            int              cchDuration
);

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 fonction. Si lpFormat n’est pas défini sur NULL, ce paramètre doit avoir la valeur 0. Si lpFormat a la valeur NULL, votre application peut spécifier LOCALE_NOUSEROVERRIDE pour mettre en forme la chaîne à l’aide du format de durée par défaut du système pour les paramètres régionaux spécifiés.

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

[in, optional] lpDuration

Pointeur vers une structure SYSTEMTIME qui contient les informations de durée à mettre en forme. L’application définit ce paramètre sur NULL si la fonction doit l’ignorer et utiliser ullDuration.

[in] ullDuration

Entier non signé 64 bits qui représente le nombre d’intervalles de 100 nanosecondes dans la durée. Si lpDuration et ullDuration sont définis, le paramètre lpDuration est prioritaire. Si lpDuration a la valeur NULL et ullDuration a la valeur 0, la durée est 0.

[in, optional] lpFormat

Pointeur vers la chaîne de format avec des caractères comme indiqué ci-dessous. L’application peut définir ce paramètre sur NULL si la fonction doit mettre en forme la chaîne en fonction du format de durée pour les paramètres régionaux spécifiés. Si lpFormat n’est pas défini 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.

Valeur	Signification
d	jours
h ou H	heures
hh ou HH	Heures; s’il est inférieur à dix, prépendez un zéro de début
m	minutes
mm	Minutes; s’il est inférieur à dix, prépendez un zéro de début
s	secondes
ss	Secondes; s’il est inférieur à dix, prépendez un zéro de début
f	fractions d’une seconde Note Le caractère « f » peut se produire jusqu’à neuf fois consécutives (fffffffff), bien que la prise en charge des minuteurs de fréquence soit limitée à 100 nanosecondes. Ainsi, si neuf caractères sont présents, les deux derniers chiffres sont toujours 0.

[out, optional] lpDurationStr

Pointeur vers la mémoire tampon dans laquelle la fonction récupère la chaîne de durée.

Ce paramètre récupère également la valeur NULL si cchDuration a la valeur 0. Dans ce cas, la fonction retourne la taille requise pour la mémoire tampon de chaîne de durée.

[in] cchDuration

Taille, en caractères, de la mémoire tampon indiquée par lpDurationStr.

L’application peut également définir ce paramètre sur 0. Dans ce cas, la fonction récupère NULL dans lpDurationStr et retourne la taille requise pour la mémoire tampon de chaîne de durée.

Valeur retournée

Retourne le nombre de caractères récupérés dans la mémoire tampon indiqué par lpDurationStr en cas de réussite. Si lpDurationStr a la valeur NULL et que cchDuration a la valeur 0, la fonction retourne la taille requise pour la mémoire tampon de chaîne de durée, y compris le caractère null de fin. Par exemple, si 10 caractères sont écrits dans la mémoire tampon, la fonction retourne 11 pour inclure 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_PARAMETER. L’une des valeurs de paramètre n’était pas valide.

Remarques

Cette fonction peut être utilisée avec des applications multimédias qui affichent l’heure du fichier et des applications d’événements sportifs qui affichent les heures de fin.

La fonction ignore les trois premiers membres de la structure SYSTEMTIME : wYear, wMonth et wDayOfWeek.

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.

Voici les caractéristiques des chaînes de format de durée :

Les caractères de mise en forme sont minuscules.
Note Une exception est faite pour que (H) soit cohérent avec GetTimeFormatEx.
Les chaînes de format à deux chiffres pendant des heures, des minutes et des secondes précédent un zéro de début si la valeur est inférieure à 10.
Le premier champ de sortie n’est soumis à aucun test de limites (heures<24, minutes<60, secondes<60, millisecondes<1000). Les jours ne sont pas soumis à un test de limites.
La fonction suppose que toutes les chaînes de format sont de taille de champ décroissante, par exemple, heures, minutes, secondes, millisecondes.
Le premier champ à afficher est normalisé, tel que défini par la chaîne de format. Par exemple, si l’application spécifie 310 secondes et que la chaîne de format est m:ss, la sortie est 5:10. Toutefois, si la chaîne de format spécifie des minutes et des secondes, mais que l’application spécifie des heures, le champ minutes est ajusté en conséquence.
Si les fractions ne sont pas le premier champ, le nombre de caractères « f » dans la chaîne de format indique le nombre de décimales à afficher (limite de 9). Si les fractions sont le premier champ, le nombre de caractères « f » indique le nombre de chiffres significatifs inférieurs à une seconde.
L’arrondi se produit par troncation, et non par la règle de cinq arrondis vers le haut et de quatre arrondis vers le bas.
Des guillemets uniques sont utilisés pour les caractères d’échappement.

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

Exemples

Voici des exemples de formats de durée et de sorties correspondants pour des durées spécifiées.

SYSTEMTIME = 14 jours, 2 heures, 45 minutes, 12 secondes et 247 millisecondes

Format	Output
d:hh:mm:ss	14:02:45:12
hh:mm:ss:ff	338:45:12:24
hh:mm:ss:fff	338:45:12:247
h' h 'mm' m 'ss' s'	338 h 45 m 12 s

SYSTEMTIME = 345 secondes

Format	Output
hh:mm:ss	00:05:45
h:mm:ss	0:05:45
mm:ss	05:45
m:ss	5:45
mm' m 'ss' s'	05 m 45 s
ss	345
secondes ss'	345 secondes

uulDuration = 51234567 (5,1234567 secondes)

Format	Output
s.fff	5.123
s.ffffff	5.123456
s.fffffffff	5.123456700 (ajouter des zéros de fin)
fff 'ms'	5123 ms
ffffff 'microsecondes'	5123456 microsecondes
fffffffff 'ns'	5123456700 ns

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	winnls.h (inclure Windows.h)
Bibliothèque	Kernel32.lib
DLL	Kernel32.dll