Compartilhar via

Função GetCalendarDateFormatEx

  • Artigo

Preterido. Recupera uma cadeia de caracteres de data formatada corretamente para a localidade especificada usando a data e o calendário especificados. O usuário pode especificar o formato de data curta, o formato de data longa, o formato de mês do ano ou um padrão de formato personalizado.

Observação

Essa função pode recuperar 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

BOOL GetCalendarDateFormatEx(
  _In_        LPCWSTR       lpszLocale,
  _In_        DWORD         dwFlags,
  _In_  const LPCALDATETIME lpCalDateTime,
  _In_        LPCWSTR       lpFormat,
  _Out_       LPWSTR        lpDateStr,
  _In_        int           cchDate
);

Parâmetros

lpszLocale [in]

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

dwFlags [in]

Sinalizadores especificando opções de formato de data. Se lpFormat não estiver definido como NULL, esse parâmetro deverá ser definido como 0. Se lpFormat estiver definido como NULL, o aplicativo poderá especificar uma combinação dos seguintes valores e LOCALE_NOUSEROVERRIDE.

Valor Significado
DATE_SHORTDATE
 Use o formato de data curta. Esse é o padrão. Esse valor não pode ser usado com DATE_LONGDATE ou DATE_YEARMONTH.
DATE_LONGDATE
 Use o formato de data longa. Esse valor não pode ser usado com DATE_SHORTDATE ou DATE_YEARMONTH.
DATE_YEARMONTH
 Use o formato ano/mês. Esse valor não pode ser usado com DATE_SHORTDATE ou DATE_LONGDATE.
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

 

lpCalDateTime [in]

Ponteiro para uma estrutura CALDATETIME que contém as informações de data e calendário a serem formatadas.

lpFormat [in]

Ponteiro para uma cadeia de caracteres de imagem de formato usada para formar a cadeia de caracteres de 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.

A cadeia de caracteres de imagem de formato deve ser terminada em nulo. A função usa a localidade apenas para informações não especificadas na cadeia de caracteres de imagem de formato, por exemplo, os nomes de dia e mês da localidade. O aplicativo define esse parâmetro como NULL se a função usar o formato de data da localidade especificada.

lpDateStr [out]

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

cchDate [in]

Tamanho, em caracteres, do buffer lpDateStr . Como alternativa, o aplicativo pode definir esse parâmetro como 0. Nesse caso, a função retorna o número de caracteres necessários para manter a cadeia de caracteres de data formatada e o parâmetro lpDateStr não é usado.

Valor retornado

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_DATE_OUT_OF_RANGE. A data especificada estava fora do intervalo.
  • 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

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

Essa função não tem um arquivo de cabeçalho ou arquivo de biblioteca associado. O aplicativo pode chamar LoadLibrary com o nome DLL (Kernel32.dll) para obter um identificador de módulo. Em seguida, ele pode chamar GetProcAddress com esse identificador de módulo e o nome dessa função para obter o endereço da função.

Requisitos

Requisito Valor
Cliente mínimo com suporte
 Windows Vista [somente aplicativos da área de trabalho]
Servidor mínimo com suporte
 Windows Server 2008 [somente aplicativos da área de trabalho]
DLL
Kernel32.dll

Confira também

Suporte à linguagem nacional

Funções de suporte à linguagem nacional

Imagens de formato dia, mês, ano e era

NLS: exemplo de APIs baseadas em nome

EnumDateFormatsExEx

Getdateformat

GetDateFormatEx

CALDATETIME