Función GetTimeFormatEx (datetimeapi.h)
Da formato a la hora como una cadena de hora para una configuración regional especificada por nombre. La función da formato a una hora especificada o a la hora del sistema local.
Sintaxis
int GetTimeFormatEx(
[in, optional] LPCWSTR lpLocaleName,
[in] DWORD dwFlags,
[in, optional] const SYSTEMTIME *lpTime,
[in, optional] LPCWSTR lpFormat,
[out, optional] LPWSTR lpTimeStr,
[in] int cchTime
);
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 formato de hora. La aplicación puede especificar una combinación de los siguientes valores y LOCALE_USE_CP_ACP o LOCALE_NOUSEROVERRIDE.
[in, optional] lpTime
Puntero a una estructura 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 tiempo. 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 caracteres, 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 caracteres 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.
Comentarios
Si existe un marcador de hora y no se establece la marca de TIME_NOTIMEMARKER, la función localiza el marcador de hora en función del identificador de configuración regional especificado. Algunos ejemplos de marcadores de tiempo son "AM" y "PM" para inglés (Estados Unidos).
Los valores de hora de la estructura indicada por lpTime deben ser válidos. La función comprueba cada uno de los valores de hora para determinar que se encuentra dentro del intervalo de valores adecuado. Si alguno de los valores de hora está fuera del intervalo correcto, se produce un error en la función y establece el último error en ERROR_INVALID_PARAMETER.
La función omite los miembros de fecha de la estructura SYSTEMTIME . Estos incluyen: wYear, wMonth, wDayOfWeek y wDay.
Si se especifica TIME_NOMINUTESORSECONDS o TIME_NOSECONDS, la función quita los separadores después de los miembros de minutos o segundos.
Si se especifica TIME_NOTIMEMARKER, la función quita los separadores anteriores y después del marcador de hora.
Si se especifica TIME_FORCE24HOURFORMAT, la función muestra cualquier marcador de tiempo existente, a menos que también se establezca la marca de TIME_NOTIMEMARKER.
La función no incluye milisegundos como parte de la cadena de tiempo con formato.
La función no devuelve errores para una cadena de formato incorrecto, pero solo forma la mejor cadena de tiempo posible. Si se pasan más de dos imágenes de formato de marcador de hora, minuto, segundo o hora, la función tiene como valor predeterminado dos. Por ejemplo, las únicas imágenes de marcador de tiempo que son válidas son "t" y "tt". Si se pasa "ttt", la función asume "tt".
Para obtener el formato de hora sin realizar ningún formato real, la aplicación debe usar la función GetLocaleInfoEx , especificando LOCALE_STIMEFORMAT.
La aplicación puede usar los siguientes elementos para construir una cadena de imagen de formato. Si los espacios se usan para separar los elementos de la cadena de formato, estos espacios aparecen en la misma ubicación de la cadena de salida. Las letras deben estar en mayúsculas o minúsculas, como se muestra, por ejemplo, "ss", no "SS". Los caracteres de la cadena de formato que se incluyen entre comillas simples aparecen en la misma ubicación y sin cambios en la cadena de salida.
| Imagen | Significado |
|---|---|
| h | Horas sin cero inicial para horas de un solo dígito; Reloj de 12 horas |
| hh | Horas con cero inicial para horas de un solo dígito; Reloj de 12 horas |
| H | Horas sin cero inicial para horas de un solo dígito; Reloj de 24 horas |
| HH | Horas con cero inicial para horas de un solo dígito; Reloj de 24 horas |
| m | Minutos sin cero inicial para minutos de un solo dígito |
| mm | Minutos con cero inicial para minutos de un solo dígito |
| d | Segundos sin cero inicial para segundos de un solo dígito |
| ss | Segundos con cero inicial para segundos de un solo dígito |
| m | Cadena de marcador de tiempo de un carácter, como A o P |
| tt | Cadena de marcador de tiempo de varios caracteres, como AM o PM |
Por ejemplo, para obtener la cadena de tiempo
"11:29:40 PM"
la aplicación debe usar la cadena de imagen.
"hh':'mm':'ss tt"
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 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 llamando a ResolveLocaleName.
A partir de Windows 8: GetTimeFormatEx se declara en Datetimeapi.h. Antes de Windows 8, se declaró en Winnls.h.
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 | datetimeapi.h |
| Library | Kernel32.lib |
| Archivo DLL | Kernel32.dll |