Função GetDateFormatW (datetimeapi.h)

Artigo
08/23/2023

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

Nota Por motivos de interoperabilidade, o aplicativo deve preferir a função GetDateFormatEx a GetDateFormat porque a Microsoft está migrando para o uso de nomes de localidade em vez de identificadores de localidade para novas localidades. Qualquer aplicativo que será executado somente no Windows Vista e posterior deve usar GetDateFormatEx.

Sintaxe

int GetDateFormatW(
  [in]            LCID             Locale,
  [in]            DWORD            dwFlags,
  [in, optional]  const SYSTEMTIME *lpDate,
  [in, optional]  LPCWSTR          lpFormat,
  [out, optional] LPWSTR           lpDateStr,
  [in]            int              cchDate
);

Parâmetros

[in] Locale

Identificador de localidade que especifica a localidade para a qual essa função formata a cadeia de caracteres de data. Você pode usar a macro MAKELCID para criar um identificador de localidade ou usar um dos valores predefinidos a seguir.

[in] dwFlags

Sinalizadores que especificam opções de formato de data. Para obter definições detalhadas, consulte o parâmetro dwFlags de GetDateFormatEx.

[in, optional] lpDate

Ponteiro para uma estrutura SYSTEMTIME que contém as informações de data a serem formatadas. O aplicativo define esse parâmetro como NULL se a função deve 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.

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.

Valor retornado

Retorna o número de caracteres gravados no buffer lpDateStr se tiver êxito. Se o parâmetro cchDate estiver 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.

A 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 estava 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.

Consulte Comentários para GetDateFormatEx.

Quando a versão ANSI dessa função é usada com um identificador de localidade somente Unicode, a função pode ser bem-sucedida porque o sistema operacional usa a página de código do sistema. No entanto, caracteres indefinidos na página de código do sistema aparecem na cadeia de caracteres como um ponto de interrogação ("?").

A partir do Windows 8: GetDateFormat é declarado em Datetimeapi.h. Antes do Windows 8, ele era declarado em Winnls.h.

Observação

O cabeçalho datetimeapi.h define GetDateFormat como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

Requisitos


Cliente mínimo com suporte	Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	datetimeapi.h
Biblioteca	Kernel32.lib
DLL	Kernel32.dll