Função GetTimeFormatEx (datetimeapi.h)

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

Sintaxe

int GetTimeFormatEx(
  [in, optional]  LPCWSTR          lpLocaleName,
  [in]            DWORD            dwFlags,
  [in, optional]  const SYSTEMTIME *lpTime,
  [in, optional]  LPCWSTR          lpFormat,
  [out, optional] LPWSTR           lpTimeStr,
  [in]            int              cchTime
);

Parâmetros

[in, optional] lpLocaleName

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

• LOCALE_NAME_INVARIANT
• LOCALE_NAME_SYSTEM_DEFAULT
• LOCALE_NAME_USER_DEFAULT

[in] dwFlags

Sinalizadores especificando opções de formato de hora. O aplicativo pode especificar uma combinação dos seguintes valores e LOCALE_USE_CP_ACP ou LOCALE_NOUSEROVERRIDE.

[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 formatará 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 tempo 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 caracteres, 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 caracteres 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 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.
• ERROR_OUTOFMEMORY. Não havia armazenamento suficiente disponível para concluir essa operação.

Comentários

Se existir um marcador de tempo e o sinalizador de TIME_NOTIMEMARKER não estiver definido, a função localizará o marcador de tempo com base no identificador de localidade especificado. Exemplos de marcadores de tempo são "AM" e "PM" para inglês (Estados Unidos).

Os valores de tempo na estrutura indicada por lpTime devem ser válidos. A função verifica cada um dos valores de tempo para determinar se está dentro do intervalo apropriado de valores. Se qualquer um dos valores de tempo 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 data da estrutura SYSTEMTIME . Estes incluem: wYear, wMonth, wDayOfWeek e wDay.

Se TIME_NOMINUTESORSECONDS ou TIME_NOSECONDS for especificado, a função removerá os separadores após os membros de minutos e/ou segundos.

Se TIME_NOTIMEMARKER for especificado, a função removerá os separadores anteriores e seguirão o marcador de tempo.

Se TIME_FORCE24HOURFORMAT for especificado, a função exibirá qualquer marcador de tempo existente, a menos que o sinalizador TIME_NOTIMEMARKER também esteja definido.

A função não inclui milissegundos como parte da cadeia de caracteres de tempo formatada.

A função não retorna erros para uma cadeia de caracteres de formato inválido, mas apenas forma a melhor cadeia de caracteres de tempo possível. Se mais de duas horas, minutos, segundos ou imagens de formato de marcador de tempo forem passadas, a função será padronizada como duas. Por exemplo, as únicas imagens de marcador de tempo válidas são "t" e "tt". Se "ttt" for passado, a função assumirá "tt".

Para obter o formato de tempo sem executar nenhuma formatação real, o aplicativo deve usar a função GetLocaleInfoEx , especificando LOCALE_STIMEFORMAT.

O aplicativo pode usar os elementos a seguir para construir uma cadeia de caracteres de imagem de formato. Se os espaços forem usados para separar os elementos na cadeia de caracteres de formato, esses espaços aparecerão no mesmo local na cadeia de caracteres de saída. As letras devem estar em letras maiúsculas ou minúsculas, conforme mostrado, por exemplo, "ss", não "SS". Os caracteres na cadeia de caracteres de formato que estão entre aspas simples aparecem no mesmo local e inalterados na cadeia de caracteres de saída.

Por exemplo, para obter a cadeia de caracteres de tempo

"11:29:40 PM"

o aplicativo deve usar a cadeia de caracteres de imagem

"hh':'mm':'ss tt"

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.

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 em Windows 8: GetTimeFormatEx é declarado em Datetimeapi.h. Antes de Windows 8, ele foi declarado em Winnls.h.

Requisitos

Confira também

GetDateFormatEx

Getlocaleinfoex

Gettimeformat

Suporte à linguagem nacional

Funções de suporte à linguagem nacional