Función GetDurationFormatEx (winnls.h)

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

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.

• LOCALE_NAME_INVARIANT
• LOCALE_NAME_SYSTEM_DEFAULT
• LOCALE_NAME_USER_DEFAULT

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

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

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

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

SYSTEMTIME = 345 segundos

uulDuration = 51234567 (5,1234567 segundos)

Requisitos

Vea también

GetDateFormatEx

GetDurationFormat

GetLocaleInfoEx

GetTimeFormatEx

Compatibilidad con idiomas nacionales

Funciones de compatibilidad con idiomas nacionales