Función GetDurationFormat (winnls.h)

Artículo
03/08/2023

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

Nota Por motivos de interoperabilidad, la aplicación debe preferir la función GetDurationFormatEx a GetDurationFormat porque Microsoft está migrando hacia el uso de nombres de configuración regional en lugar de identificadores de configuración regional para las nuevas configuraciones regionales. Cualquier aplicación que se ejecute solo en Windows Vista y versiones posteriores debe usar GetDurationFormatEx.

Sintaxis

int GetDurationFormat(
  [in]            LCID             Locale,
  [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] Locale

Identificador de configuración regional que especifica la configuración regional para la que esta función da formato a la duración. Puede usar la macro MAKELCID para crear un identificador de configuración regional o usar uno de los siguientes valores predefinidos.

Windows Vista y versiones posteriores: También se admiten los siguientes identificadores de configuración regional personalizados.

[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. Si este puntero es NULL, la función omite este parámetro y usa ullDuration.

[in] ullDuration

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

[in, optional] lpFormat

Puntero a la cadena de formato. Para obtener más información, consulte el parámetro lpFormat de GetDurationFormatEx.

[out, optional] lpDurationStr

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

Como alternativa, este parámetro puede contener 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 de terminación NULL. 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.

Comentarios

Vea Comentarios para GetDurationFormatEx.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows Vista [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2008 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	winnls.h (incluye Windows.h)
Library	Kernel32.lib
Archivo DLL	Kernel32.dll