Función GetTimeFormatA (datetimeapi.h)

Artículo
11/20/2024

Da formato a la hora como una cadena de hora para una configuración regional especificada por identificador. La función da formato a una hora especificada o a la hora del sistema local.

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

Sintaxis

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

Parámetros

[in] Locale

identificador de configuración regional que especifica la configuración regional. Puede usar la macro MAKELCID para crear un identificador de configuración regional o usar uno de los siguientes valores predefinidos.

[in] dwFlags

Marcas que especifican opciones de formato de hora. Para obtener definiciones detalladas, consulte el parámetro dwFlags de de GetTimeFormatEx.

[in, optional] lpTime

Puntero a una estructura de SYSTEMTIME que contiene la información de tiempo que se va a dar formato. La aplicación puede establecer este parámetro en NULL si la función va a usar la hora actual del sistema local.

[in, optional] lpFormat

Puntero a una imagen de formato que se va a usar para dar formato a la cadena de hora. Si la aplicación establece este parámetro en NULL, la función da formato a la cadena según el formato de hora de la configuración regional especificada. Si la aplicación no establece el parámetro en NULL, la función usa la configuración regional solo para la información no especificada en la cadena de imagen de formato, por ejemplo, los marcadores de tiempo específicos de la configuración regional. Para obtener información sobre la cadena de imagen de formato, vea la sección Comentarios.

[out, optional] lpTimeStr

Puntero a un búfer en el que esta función recupera la cadena de tiempo con formato.

[in] cchTime

Tamaño, en valores TCHAR, para el búfer de cadena de tiempo indicado por lpTimeStr. Como alternativa, la aplicación puede establecer este parámetro en 0. En este caso, la función devuelve el tamaño necesario para el búfer de cadena de tiempo y no usa el parámetro lpTimeStr.

Valor devuelto

Devuelve el número de valores TCHAR recuperados en el búfer indicado por lpTimeStr. Si el parámetro cchTime se establece en 0, la función devuelve el tamaño del búfer necesario para contener la cadena de tiempo con formato, incluido un carácter nulo de terminación.

Esta 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_FLAGS. Los valores proporcionados para las marcas no eran válidos.
ERROR_INVALID_PARAMETER. Cualquiera de los valores de parámetro no era válido.
ERROR_OUTOFMEMORY. No había suficiente almacenamiento disponible para completar esta operación.

Observaciones

Consulte los comentarios de GetTimeFormatEx.

Cuando se usa la versión ANSI de esta función con un identificador de configuración regional de solo Unicode, la función puede realizarse correctamente porque el sistema operativo usa la página de códigos del sistema. Sin embargo, los caracteres que no están definidos en la página de códigos del sistema aparecen en la cadena como signo de interrogación (?).

a partir de Windows 8: GetTimeFormat se declara en Datetimeapi.h. Antes de Windows 8, se declaró en Winnls.h.

Nota

El encabezado datetimeapi.h define GetTimeFormat como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutral de codificación con código que no es neutral de codificación puede dar lugar a errores de coincidencia que dan lugar a errores de compilación o tiempo de ejecución. Para obtener más información, vea Conventions for Function Prototypes.

Requisitos

Requisito	Valor
cliente mínimo admitido	Windows 2000 Professional [solo aplicaciones de escritorio]
servidor mínimo admitido	Windows 2000 Server [solo aplicaciones de escritorio]
de la plataforma de destino de	Windows
encabezado de	datetimeapi.h
biblioteca de	Kernel32.lib
DLL de	Kernel32.dll

Consulte también

GetDateFormat

GetLocaleInfo

GetTimeFormatEx

de compatibilidad con idiomas nacionales

funciones de compatibilidad con idiomas nacionales

Compartir a través de