Função GetTimeFormatA (datetimeapi.h)

Artigo
02/28/2024

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

Nota Por motivos de interoperabilidade, o aplicativo deve preferir a função GetTimeFormatEx a GetTimeFormat 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 GetTimeFormatEx.

Sintaxe

int GetTimeFormatA(
  [in]            LCID             Locale,
  [in]            DWORD            dwFlags,
  [in, optional]  const SYSTEMTIME *lpTime,
  [in, optional]  LPCSTR           lpFormat,
  [out, optional] LPSTR            lpTimeStr,
  [in]            int              cchTime
);

Parâmetros

[in] Locale

Identificador de localidade que especifica a localidade. 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 hora. Para obter definições detalhadas, consulte o parâmetro dwFlags de GetTimeFormatEx.

[in, optional] lpTime

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

[in, optional] lpFormat

Ponteiro para uma imagem de formato a ser usada para formatar a cadeia de caracteres de tempo. Se o aplicativo definir esse parâmetro como NULL, a função formata a cadeia de caracteres de acordo com o formato de hora da localidade especificada. Se o aplicativo não definir o parâmetro como NULL, a função usará a localidade somente para informações não especificadas na cadeia de caracteres de imagem de formato, por exemplo, os marcadores de hora específicos da localidade. Para obter informações sobre a cadeia de caracteres de imagem de formato, consulte a seção Comentários.

[out, optional] lpTimeStr

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

[in] cchTime

Tamanho, em valores TCHAR, para o buffer de cadeia de caracteres de tempo indicado por lpTimeStr. Como alternativa, o aplicativo pode definir esse parâmetro como 0. Nesse caso, a função retorna o tamanho necessário para o buffer de cadeia de caracteres de tempo e não usa o parâmetro lpTimeStr .

Retornar valor

Retorna o número de valores TCHAR recuperados no buffer indicado por lpTimeStr. Se o parâmetro cchTime for definido como 0, a função retornará o tamanho do buffer necessário para manter a cadeia de caracteres de tempo formatada, incluindo um 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 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.
ERROR_OUTOFMEMORY. Não havia armazenamento suficiente disponível para concluir esta operação.

Comentários

Consulte Comentários para GetTimeFormatEx.

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, os caracteres indefinidos na página de código do sistema aparecem na cadeia de caracteres como um ponto de interrogação (?).

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

Observação

O cabeçalho datetimeapi.h define GetTimeFormat 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

Requisito	Valor
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