Función GetDateFormatEx (datetimeapi.h)

Artículo
08/23/2023

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.

Nota La aplicación debe llamar a esta función en preferencia a GetDateFormat si está diseñada para ejecutarse solo en Windows Vista y versiones posteriores.

Nota Esta función puede dar formato a los datos que cambian entre versiones, por ejemplo, debido a una configuración regional personalizada. Si la aplicación debe conservar o transmitir datos, consulte Uso de datos de configuración regional persistente.

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.

Precaución El uso de LOCALE_NOUSEROVERRIDE no se recomienda, ya que deshabilita las preferencias del usuario.

Valor	Significado
DATE_AUTOLAYOUT	Windows 7 y versiones posteriores: Detecte la necesidad de un diseño de lectura de derecha a izquierda y de izquierda a derecha mediante la configuración regional y la información del calendario, y agregue marcas en consecuencia. Este valor no se puede usar con DATE_LTRREADING o DATE_RTLREADING. DATE_AUTOLAYOUT se prefiere sobre DATE_LTRREADING y DATE_RTLREADING porque usa las configuraciones regionales y los calendarios para determinar la adición correcta de marcas.
DATE_LONGDATE	Use el formato de fecha larga. Este valor no se puede usar con DATE_MONTHDAY, DATE_SHORTDATE o DATE_YEARMONTH.
DATE_LTRREADING	Agregue marcas para el diseño de lectura de izquierda a derecha. Este valor no se puede usar con DATE_RTLREADING.
DATE_RTLREADING	Agregue marcas para el diseño de lectura de derecha a izquierda. Este valor no se puede usar con DATE_LTRREADING
DATE_SHORTDATE	Use el formato de fecha corta. Este es el valor predeterminado. Este valor no se puede usar con DATE_MONTHDAY, DATE_LONGDATE o DATE_YEARMONTH.
DATE_USE_ALT_CALENDAR	Use el calendario alternativo, si existe, para dar formato a la cadena de fecha. Si se establece esta marca, la función usa el formato predeterminado para ese calendario alternativo, en lugar de usar invalidaciones de usuario. Las invalidaciones de usuario solo se usarán en caso de que no haya ningún formato predeterminado para el calendario alternativo especificado.
DATE_YEARMONTH	Windows Vista: Use el formato año/mes. Este valor no se puede usar con DATE_MONTHDAY, DATE_SHORTDATE o DATE_LONGDATE.
DATE_MONTHDAY	Windows 10: use la combinación de formatos de mes y día adecuados para la configuración regional especificada. Este valor no se puede usar con DATE_YEARMONTH, DATE_SHORTDATE o DATE_LONGDATE.

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

Nota Esta API se está actualizando para admitir el cambio en la era japonesa de mayo de 2019. Si la aplicación admite el calendario japonés, debe validar que controla correctamente la nueva era. Consulte Preparación de la aplicación para el cambio en la era japonesa para obtener más información.

La fecha más antigua admitida por esta función es el 1 de enero de 1601.

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