Função GetDateFormatEx (datetimeapi.h)

Artigo
08/23/2023

Formata uma data como uma cadeia de caracteres de data para uma localidade especificada pelo nome. A função formata uma data especificada ou a data do sistema local.

Nota O aplicativo deve chamar essa função em preferência para GetDateFormat se projetado para ser executado somente no Windows Vista e posterior.

Nota Essa função pode formatar dados que são alterados entre versões, por exemplo, devido a uma localidade personalizada. Se o aplicativo precisar persistir ou transmitir dados, consulte Usando dados de localidade persistente.

Sintaxe

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

Ponteiro para um nome de localidade ou um dos seguintes valores predefinidos.

[in] dwFlags

Sinalizadores especificando várias opções de função que podem ser definidas se lpFormat estiver definido como NULL. O aplicativo pode especificar uma combinação dos seguintes valores e LOCALE_USE_CP_ACP ou LOCALE_NOUSEROVERRIDE.

Cuidado O uso de LOCALE_NOUSEROVERRIDE é altamente desencorajado, pois desabilita as preferências do usuário.

Valor	Significado
DATE_AUTOLAYOUT	Windows 7 e posterior: Detecte a necessidade de layout de leitura da direita para a esquerda e da esquerda para a direita usando as informações de localidade e calendário e adicione marcas adequadamente. Esse valor não pode ser usado com DATE_LTRREADING ou DATE_RTLREADING. DATE_AUTOLAYOUT é preferencial em DATE_LTRREADING e DATE_RTLREADING porque usa as localidades e calendários para determinar a adição correta de marcas.
DATE_LONGDATE	Use o formato de data longa. Esse valor não pode ser usado com DATE_MONTHDAY, DATE_SHORTDATE ou DATE_YEARMONTH.
DATE_LTRREADING	Adicione marcas para o layout de leitura da esquerda para a direita. Esse valor não pode ser usado com DATE_RTLREADING.
DATE_RTLREADING	Adicione marcas para o layout de leitura da direita para a esquerda. Esse valor não pode ser usado com DATE_LTRREADING
DATE_SHORTDATE	Use o formato de data curta. Esse é o padrão. Esse valor não pode ser usado com DATE_MONTHDAY, DATE_LONGDATE ou DATE_YEARMONTH.
DATE_USE_ALT_CALENDAR	Use o calendário alternativo, se existir, para formatar a cadeia de caracteres de data. Se esse sinalizador estiver definido, a função usará o formato padrão para esse calendário alternativo, em vez de usar quaisquer substituições de usuário. As substituições de usuário serão usadas somente no caso de não haver um formato padrão para o calendário alternativo especificado.
DATE_YEARMONTH	Windows Vista: Use o formato ano/mês. Esse valor não pode ser usado com DATE_MONTHDAY, DATE_SHORTDATE ou DATE_LONGDATE.
DATE_MONTHDAY	Windows 10: use a combinação de formatos de mês e dia apropriados para a localidade especificada. Esse valor não pode ser usado com DATE_YEARMONTH, DATE_SHORTDATE ou DATE_LONGDATE.

Se o aplicativo não especificar DATE_YEARMONTH, DATE_MONTHDAY, DATE_SHORTDATE ou DATE_LONGDATE e lpFormat for definido como NULL, DATE_SHORTDATE será o padrão.

[in, optional] lpDate

Ponteiro para uma estrutura SYSTEMTIME que contém as informações de data a serem formatadas. O aplicativo poderá definir esse parâmetro como NULL se a função for usar a data atual do sistema local.

[in, optional] lpFormat

Ponteiro para uma cadeia de caracteres de imagem de formato usada para formar a data. Os valores possíveis para a cadeia de caracteres de imagem de formato são definidos em Day, Month, Year e Era Format Pictures.

Por exemplo, para obter a cadeia de caracteres de data "Wed, Aug 31 94", o aplicativo usa a cadeia de caracteres de imagem "ddd',' MMM dd yy".

A função usa a localidade especificada apenas para informações não especificadas na cadeia de caracteres de imagem de formato, por exemplo, os nomes de dia e mês para a localidade. O aplicativo pode definir esse parâmetro como NULL para formatar a cadeia de caracteres de acordo com o formato de data para a localidade especificada.

[out, optional] lpDateStr

Ponteiro para um buffer no qual essa função recupera a cadeia de caracteres de data formatada.

[in] cchDate

Tamanho, em caracteres, do buffer lpDateStr . O aplicativo pode definir esse parâmetro como 0 para retornar o tamanho do buffer necessário para manter a cadeia de caracteres de data formatada. Nesse caso, o buffer indicado por lpDateStr não é usado.

[in, optional] lpCalendar

Reservados; deve definir como NULL.

Retornar valor

Retorna o número de caracteres gravados no buffer lpDateStr se tiver êxito. Se o parâmetro cchDate for definido como 0, a função retornará o número de caracteres necessários para manter a cadeia de caracteres de data formatada, incluindo o caractere nulo de terminação.

Essa função retornará 0 se não for bem-sucedida. Para obter informações de erro estendidas, o aplicativo pode chamar GetLastError, que pode retornar um dos seguintes códigos de erro:

ERROR_INSUFFICIENT_BUFFER. Um tamanho de buffer fornecido não era grande o suficiente ou foi definido incorretamente como NULL.
ERROR_INVALID_FLAGS. Os valores fornecidos para sinalizadores não eram válidos.
ERROR_INVALID_PARAMETER. Qualquer um dos valores de parâmetro era inválido.

Comentários

Nota Essa API está sendo atualizada para dar suporte à alteração da era japonesa de maio de 2019. Se o aplicativo der suporte ao calendário japonês, você deverá validar se ele lida corretamente com a nova era. Confira Preparar seu aplicativo para a alteração da era japonesa para obter mais informações.

A data mais antiga compatível com essa função é 1º de janeiro de 1601.

O nome do dia, o nome do dia abreviado, o nome do mês e o nome do mês abreviado são localizados com base no identificador de localidade.

Os valores de data na estrutura indicada por lpDate devem ser válidos. A função verifica cada um dos valores de data: ano, mês, dia e dia da semana. Se o dia da semana estiver incorreto, a função usará o valor correto e não retornará nenhum erro. Se qualquer um dos outros valores de data estiver fora do intervalo correto, a função falhará e definirá o último erro como ERROR_INVALID_PARAMETER.

A função ignora os membros de tempo da estrutura SYSTEMTIME indicada pelo lpDate. Eles incluem wHour, wMinute, wSecond e wMilliseconds.

Se o parâmetro lpFormat contiver uma cadeia de caracteres de formato inválido, a função não retornará erros, mas apenas forma a melhor cadeia de caracteres de data possível. Por exemplo, as únicas imagens de ano válidas são L"yyyy" e L"yyy", em que "L" indica uma cadeia de caracteres Unicode (caracteres de 16 bits). Se L"y" for passado, a função pressupõe L"yy". Se L"yyy" for passado, a função pressupõe L"yyyy". Se mais de quatro imagens de data (L"dddd") ou quatro meses (L"MMMM") forem passadas, a função usará como padrão L"dddd" ou L"MMMM".

O aplicativo deve incluir qualquer texto que deve permanecer em sua forma exata na cadeia de caracteres de data dentro das aspas simples na imagem de formato de data. A aspa única também pode ser usada como um caractere de escape para permitir que a própria aspa seja exibida na cadeia de caracteres de data. No entanto, a sequência de escape deve ser colocada entre duas aspas simples. Por exemplo, para exibir a data como "Maio '93', a cadeia de caracteres de formato é: L"MMMM ''''yy'". As primeiras e últimas aspas simples são as aspas delimitando. A segunda e a terceira aspas simples são a sequência de escape para permitir que a aspa única seja exibida antes do século.

Quando a imagem de data contém uma forma numérica do dia (d ou dd) e o nome do mês completo (MMMM), a forma congênita do nome do mês é recuperada na cadeia de caracteres de data.

Para obter o formato de data curta e longa padrão sem executar nenhuma formatação real, o aplicativo deve usar GetLocaleInfoEx com a constante LOCALE_SSHORTDATE ou LOCALE_SLONGDATE . Para obter o formato de data de um calendário alternativo, o aplicativo usa GetLocaleInfoEx com a constante LOCALE_IOPTIONALCALENDAR . Para obter o formato de data de um calendário específico, o aplicativo usa GetCalendarInfoEx, passando o Identificador de Calendário apropriado. Ele pode chamar EnumCalendarInfoEx ou EnumDateFormatsEx para recuperar formatos de data para um calendário específico.

Essa função pode recuperar dados de localidades personalizadas. Não há garantia de que os dados sejam iguais de computador para computador ou entre execuções de um aplicativo. Se o aplicativo precisar persistir ou transmitir dados, consulte Usando dados de localidade persistente.

O formato DATE_LONGDATE inclui dois tipos de padrões de data: padrões que incluem o dia da semana e padrões que não incluem o dia da semana. Por exemplo, "Terça-feira, 18 de outubro de 2016" ou "18 de outubro de 2016". Se o aplicativo precisar garantir que as datas usem um desses tipos de padrões e não o outro tipo, seu aplicativo deverá executar as seguintes ações:

Chame a função EnumDateFormatsExEx para obter todos os formatos de data para o formato DATE_LONGDATE.
Procure o primeiro formato de data passado para a função de retorno de chamada que você especificou para EnumDateFormatsExEx que corresponda ao identificador de calendário solicitado e tenha uma cadeia de caracteres de formato de data que corresponda aos requisitos do seu aplicativo. Por exemplo, procure o formato de primeira data que inclui "dddd" se o aplicativo exigir que a data inclua o nome completo do dia da semana ou procure o formato de primeira data que não inclui "ddd" nem "dddd" se o aplicativo exigir que a data inclua nether o nome abreviado nem o nome completo do dia da semana.
Chame a função GetDateFormatEx com o parâmetro lpFormat definido como a cadeia de caracteres de formato de data que você identificou como o formato apropriado na função de retorno de chamada.

Se a presença ou ausência do dia da semana no formato de data longa não for importante para seu aplicativo, seu aplicativo poderá chamar GetDateFormatEx diretamente sem primeiro enumerar todos os formatos de data longos chamando EnumDateFormatsExEx.

Começando no Windows 8: se o aplicativo passar marcas de idioma para essa função do namespace Windows.Globalization, ele deverá primeiro converter as marcas chamando ResolveLocaleName.

Começando no Windows 8: GetDateFormatEx é declarado em Datetimeapi.h. Antes de Windows 8, ele foi declarado em Winnls.h.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows Vista [aplicativos da área de trabalho \| Aplicativos UWP]
Servidor mínimo com suporte	Windows Server 2008 [aplicativos da área de trabalho \| Aplicativos UWP]
Plataforma de Destino	Windows
Cabeçalho	datetimeapi.h
Biblioteca	Kernel32.lib
DLL	Kernel32.dll