Función GetDurationFormatEx (winnls.h)

Artículo
03/18/2023

Da formato a una duración de tiempo como una cadena de tiempo para una configuración regional especificada por nombre.

Nota La aplicación debe llamar a esta función en preferencia a GetDurationFormat si está diseñada para ejecutarse solo en Windows Vista y versiones posteriores.

Nota Esta función puede dar formato a los datos que cambian entre versiones, por ejemplo, debido a una configuración regional personalizada. Si la aplicación debe conservar o transmitir datos, consulte Uso de datos de configuración regional persistente.

Sintaxis

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
);

Parámetros

[in, optional] lpLocaleName

Puntero a un nombre de configuración regional o uno de los siguientes valores predefinidos.

[in] dwFlags

Marcas que especifican opciones de función. Si lpFormat no está establecido en NULL, este parámetro debe establecerse en 0. Si lpFormat se establece en NULL, la aplicación puede especificar LOCALE_NOUSEROVERRIDE para dar formato a la cadena mediante el formato de duración predeterminado del sistema para la configuración regional especificada.

Precaución Se recomienda encarecidamente el uso de LOCALE_NOUSEROVERRIDE , ya que deshabilita las preferencias del usuario.

[in, optional] lpDuration

Puntero a una estructura SYSTEMTIME que contiene la información de duración de tiempo que se va a dar formato. La aplicación establece este parámetro en NULL si la función es omitirla y usar ullDuration.

[in] ullDuration

Entero sin signo de 64 bits que representa el número de intervalos de 100 nanosegundos en la duración. Si se establecen lpDuration y ullDuration , el parámetro lpDuration tiene prioridad. Si lpDuration se establece en NULL y ullDuration se establece en 0, la duración es 0.

[in, optional] lpFormat

Puntero a la cadena de formato con caracteres como se muestra a continuación. La aplicación puede establecer este parámetro en NULL si la función tiene que dar formato a la cadena según el formato de duración de la configuración regional especificada. Si lpFormat no se establece en NULL, la función usa la configuración regional solo para la información no especificada en la cadena de imagen de formato.

Value	Significado
d	days
h o H	horas
hh o HH	Horas; si es menor que diez, anteponga un cero inicial
m	minutes
mm	Minutos; si es menor que diez, anteponga un cero inicial
s	segundos
ss	Segundos; si es menor que diez, anteponga un cero inicial
f	fracciones de un segundo Nota El carácter "f" puede producirse hasta nueve veces consecutivas (fffffffff), aunque la compatibilidad con temporizadores de frecuencia está limitada a 100 nanosegundos. Por lo tanto, si hay nueve caracteres, los dos últimos dígitos siempre son 0.

[out, optional] lpDurationStr

Puntero al búfer en el que la función recupera la cadena de duración.

Como alternativa, este parámetro recupera NULL si cchDuration está establecido en 0. En este caso, la función devuelve el tamaño necesario para el búfer de cadena de duración.

[in] cchDuration

Tamaño, en caracteres, del búfer indicado por lpDurationStr.

Como alternativa, la aplicación puede establecer este parámetro en 0. En este caso, la función recupera NULL en lpDurationStr y devuelve el tamaño necesario para el búfer de cadena de duración.

Valor devuelto

Devuelve el número de caracteres recuperados en el búfer indicado por lpDurationStr si se ejecuta correctamente. Si lpDurationStr se establece en NULL y cchDuration se establece en 0, la función devuelve el tamaño necesario para el búfer de cadena de duración, incluido el carácter nulo de terminación. Por ejemplo, si se escriben 10 caracteres en el búfer, la función devuelve 11 para incluir el carácter nulo de terminación.

La función devuelve 0 si no se realiza correctamente. Para obtener información de error extendida, la aplicación puede llamar a GetLastError, que puede devolver uno de los siguientes códigos de error:

ERROR_INSUFFICIENT_BUFFER. Un tamaño de búfer proporcionado no era lo suficientemente grande o se estableció incorrectamente en NULL.
ERROR_INVALID_PARAMETER. Cualquiera de los valores de parámetro no era válido.

Observaciones

Esta función se puede usar con aplicaciones multimedia que muestran tiempo de archivo y aplicaciones de eventos deportivos que muestran los tiempos de finalización.

La función omite los tres primeros miembros de la estructura SYSTEMTIME : wYear, wMonth y wDayOfWeek.

Esta función puede recuperar datos de configuraciones regionales personalizadas. No se garantiza que los datos sean los mismos desde el equipo al equipo o entre ejecuciones de una aplicación. Si la aplicación debe conservar o transmitir datos, consulte Uso de datos de configuración regional persistente.

A continuación se muestran las características de las cadenas de formato de duración:

Los caracteres de formato están en minúsculas.
Nota Se realiza una excepción para que (H) sea coherente con GetTimeFormatEx.
Las cadenas de formato de dos dígitos para horas, minutos y segundos anteponen un cero inicial si el valor es menor que 10.
El primer campo de salida no está sujeto a ninguna prueba de límites (horas<24, minutos<60, segundos<60, milisegundos<1000). Los días no están sujetos a pruebas limitadas.
La función supone que todas las cadenas de formato están en tamaño de campo decreciente, por ejemplo, horas, minutos, segundos, milisegundos.
El primer campo que se va a mostrar se normaliza, tal como se define en la cadena de formato. Por ejemplo, si la aplicación especifica 310 segundos y la cadena de formato es m:ss, la salida es 5:10. Sin embargo, si la cadena de formato especifica minutos y segundos, pero la aplicación especifica horas, el campo minutos se ajusta en consecuencia.
Si las fracciones no son el primer campo, el número de caracteres "f" en la cadena de formato indica el número de decimales que se van a mostrar (límite de 9). Si las fracciones son el primer campo, el número de caracteres "f" indica el número de dígitos significativos por debajo de un segundo.
La redondeo se produce por truncamiento, no por la regla de cinco redondeos y cuatro redondeos hacia abajo.
Las comillas simples se usan para escapar caracteres.

A partir de Windows 8: si la aplicación pasa etiquetas de idioma a esta función desde el espacio de nombres Windows.Globalization, primero debe convertir las etiquetas mediante una llamada a ResolveLocaleName.

Ejemplos

A continuación se muestran ejemplos de formatos de duración y salidas correspondientes para las duraciones de tiempo especificadas.

SYSTEMTIME = 14 días, 2 horas, 45 minutos, 12 segundos y 247 milisegundos

Formato	Resultados
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 segundos

Formato	Resultados
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
ss' seconds'	345 segundos

uulDuration = 51234567 (5,1234567 segundos)

Formato	Resultados
s.fff	5.123
s.ffffff	5.123456
s.fffffffffff	5.123456700 (agregar ceros finales)
fff 'ms'	5123 ms
ffffff 'microsegundos'	5123456 microsegundos
fffffffff 'ns'	5123456700 ns

Requisitos


Cliente mínimo compatible	Windows Vista [aplicaciones de escritorio \| Aplicaciones para UWP]
Servidor mínimo compatible	Windows Server 2008 [aplicaciones de escritorio \| Aplicaciones para UWP]
Plataforma de destino	Windows
Encabezado	winnls.h (incluya Windows.h)
Library	Kernel32.lib
Archivo DLL	Kernel32.dll