Función GetDateFormatEx (datetimeapi.h)
Da formato a una fecha como una cadena de fecha para una configuración regional especificada por nombre. La función da formato a una fecha especificada o a la fecha del sistema local.
Sintaxis
int GetDateFormatEx(
[in, optional] LPCWSTR lpLocaleName,
[in] DWORD dwFlags,
[in, optional] const SYSTEMTIME *lpDate,
[in, optional] LPCWSTR lpFormat,
[out, optional] LPWSTR lpDateStr,
[in] int cchDate,
[in, optional] LPCWSTR lpCalendar
);
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 varias opciones de función que se pueden establecer si lpFormat está establecida en NULL. La aplicación puede especificar una combinación de los siguientes valores y LOCALE_USE_CP_ACP o LOCALE_NOUSEROVERRIDE.
Si la aplicación no especifica DATE_YEARMONTH, DATE_MONTHDAY, DATE_SHORTDATE o DATE_LONGDATE, y lpFormat se establece en NULL, DATE_SHORTDATE es el valor predeterminado.
[in, optional] lpDate
Puntero a una estructura SYSTEMTIME que contiene la información de fecha que se va a dar formato. La aplicación puede establecer este parámetro en NULL si la función va a usar la fecha actual del sistema local.
[in, optional] lpFormat
Puntero a una cadena de imagen de formato que se usa para formar la fecha. Los valores posibles para la cadena de imagen de formato se definen en Imágenes de formato Day, Month, Year y Era.
Por ejemplo, para obtener la cadena de fecha "Wed, ago 31 94", la aplicación usa la cadena de imagen "ddd',' MMM dd yy".
La función usa la configuración regional especificada solo para la información no especificada en la cadena de imagen de formato, por ejemplo, los nombres de día y mes para la configuración regional. La aplicación puede establecer este parámetro en NULL para dar formato a la cadena según el formato de fecha de la configuración regional especificada.
[out, optional] lpDateStr
Puntero a un búfer en el que esta función recupera la cadena de fecha con formato.
[in] cchDate
Tamaño, en caracteres, del búfer lpDateStr . La aplicación puede establecer este parámetro en 0 para devolver el tamaño del búfer necesario para contener la cadena de fecha con formato. En este caso, no se usa el búfer indicado por lpDateStr .
[in, optional] lpCalendar
Reservados; debe establecerse en NULL.
Valor devuelto
Devuelve el número de caracteres escritos en el búfer lpDateStr si se ejecuta correctamente. Si el parámetro cchDate se establece en 0, la función devuelve el número de caracteres necesarios para contener la cadena de fecha con formato, incluido el 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.
Comentarios
El nombre del día, el nombre abreviado del día, el nombre del mes y el nombre del mes abreviado se localizan en función del identificador de configuración regional.
Los valores de fecha de la estructura indicada por lpDate deben ser válidos. La función comprueba cada uno de los valores de fecha: año, mes, día y día de la semana. Si el día de la semana es incorrecto, la función usa el valor correcto y no devuelve ningún error. Si alguno de los demás valores de fecha 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 hora de la estructura SYSTEMTIME indicada por lpDate. Estos incluyen wHour, wMinute, wSecond y wMilliseconds.
Si el parámetro lpFormat contiene una cadena de formato incorrecto, la función no devuelve ningún error, pero solo forma la mejor cadena de fecha posible. Por ejemplo, las únicas imágenes de año válidas son L"aaaa" y L"yy", donde "L" indica una cadena Unicode (caracteres de 16 bits). Si se pasa L"y", la función asume L"yy". Si se pasa L"yyy", la función asume L"aaaa". Si se pasan más de cuatro imágenes de fecha (L"dddd") o de cuatro meses (L"MMMM"), la función tiene como valor predeterminado L"dddd" o L"MMMM".
La aplicación debe incluir cualquier texto que debe permanecer en su forma exacta en la cadena de fecha entre comillas simples en la imagen de formato de fecha. La comilla simple también se puede usar como carácter de escape para permitir que se muestren las comillas simples en la cadena de fecha. Sin embargo, la secuencia de escape debe ir entre comillas simples. Por ejemplo, para mostrar la fecha como "may '93", la cadena de formato es: L"MMMM ''''yy". Las comillas primera y última son las comillas envolventes. Las comillas simples segunda y tercera son la secuencia de escape para permitir que se muestren las comillas simples antes del siglo.
Cuando la imagen de fecha contiene una forma numérica del día (d o dd) y el nombre de mes completo (MMMM), la forma genitiva del nombre del mes se recupera en la cadena de fecha.
Para obtener el formato de fecha corta y larga predeterminado sin realizar ningún formato real, la aplicación debe usar GetLocaleInfoEx con la constante LOCALE_SSHORTDATE o LOCALE_SLONGDATE . Para obtener el formato de fecha de un calendario alternativo, la aplicación usa GetLocaleInfoEx con la constante LOCALE_IOPTIONALCALENDAR . Para obtener el formato de fecha de un calendario determinado, la aplicación usa GetCalendarInfoEx, pasando el identificador de calendario adecuado. Puede llamar a EnumCalendarInfoEx o EnumDateFormatsEx para recuperar formatos de fecha para un calendario determinado.
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.
El formato DATE_LONGDATE incluye dos tipos de patrones de fecha: patrones que incluyen el día de la semana y patrones que no incluyen el día de la semana. Por ejemplo, "Martes, 18 de octubre de 2016" o "18 de octubre de 2016". Si la aplicación necesita asegurarse de que las fechas usen uno de estos tipos de patrones y no el otro tipo, la aplicación debe realizar las siguientes acciones:
- Llame a la función EnumDateFormatsExEx para obtener todos los formatos de fecha para el formato DATE_LONGDATE.
- Busque el primer formato de fecha pasado a la función de devolución de llamada que especificó para EnumDateFormatsEx que coincida con el identificador de calendario solicitado y tenga una cadena de formato de fecha que coincida con los requisitos de la aplicación. Por ejemplo, busque el primer formato de fecha que incluya "dd" si la aplicación requiere que la fecha incluya el nombre completo del día de la semana, o busque el primer formato de fecha que no incluya "d" ni "dddd" si la aplicación requiere que la fecha incluya nether el nombre abreviado ni el nombre completo del día de la semana.
- Llame a la función GetDateFormatEx con el parámetro lpFormat establecido en la cadena de formato de fecha que identificó como el formato adecuado en la función de devolución de llamada.
Si la presencia o ausencia del día de la semana en el formato de fecha larga no importa a la aplicación, la aplicación puede llamar directamente a GetDateFormatEx sin enumerar primero todos los formatos de fecha larga llamando a EnumDateFormatsExEx.
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: GetDateFormatEx se declara en Datetimeapi.h. Antes de Windows 8, se declaró en Winnls.h.
Requisitos
| Requisito | Value |
|---|---|
| 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 |
Vea también
Imágenes con formato día, mes, año y era
NLS: ejemplo de API basadas en nombres