Função GetDurationFormat (winnls.h)

Artigo
08/27/2023

Formata uma duração de tempo como uma cadeia de caracteres de tempo para uma localidade especificada pelo identificador.

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

Sintaxe

int GetDurationFormat(
  [in]            LCID             Locale,
  [in]            DWORD            dwFlags,
  [in, optional]  const SYSTEMTIME *lpDuration,
  [in]            ULONGLONG        ullDuration,
  [in, optional]  LPCWSTR          lpFormat,
  [out, optional] LPWSTR           lpDurationStr,
  [in]            int              cchDuration
);

Parâmetros

[in] Locale

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

Windows Vista e posterior: Também há suporte para os seguintes identificadores de localidade personalizados.

[in] dwFlags

Sinalizadores especificando opções de função. Se lpFormat não estiver definido como NULL, esse parâmetro deverá ser definido como 0. Se lpFormat estiver definido como NULL, seu aplicativo poderá especificar LOCALE_NOUSEROVERRIDE para formatar a cadeia de caracteres usando o formato de duração padrão do sistema para a localidade especificada.

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

[in, optional] lpDuration

Ponteiro para uma estrutura SYSTEMTIME que contém as informações de duração do tempo a serem formatadas. Se esse ponteiro for NULL, a função ignorará esse parâmetro e usará ullDuration.

[in] ullDuration

Inteiro sem sinal de 64 bits que representa o número de intervalos de 100 nanossegundos na duração. Se lpDuration e ullDuration estiverem presentes, lpDuration terá precedência. Se lpDuration for definido como NULL e ullDuration for definido como 0, a duração será zero.

[in, optional] lpFormat

Ponteiro para a cadeia de caracteres de formato. Para obter detalhes, consulte o parâmetro lpFormat de GetDurationFormatEx.

[out, optional] lpDurationStr

Ponteiro para o buffer no qual a função recupera a cadeia de caracteres de duração.

Como alternativa, esse parâmetro poderá conter NULL se cchDuration estiver definido como 0. Nesse caso, a função retorna o tamanho necessário para o buffer de cadeia de caracteres de duração.

[in] cchDuration

Tamanho, em caracteres, do buffer indicado por lpDurationStr.

Como alternativa, o aplicativo pode definir esse parâmetro como 0. Nesse caso, a função recupera NULL em lpDurationStr e retorna o tamanho necessário para o buffer de cadeia de caracteres de duração.

Retornar valor

Retorna o número de caracteres recuperados no buffer indicado por lpDurationStr se tiver êxito. Se lpDurationStr estiver definido como NULL e cchDuration estiver definido como 0, a função retornará o tamanho necessário para o buffer de cadeia de caracteres de duração, incluindo o caractere de terminação nulo. Por exemplo, se 10 caracteres forem gravados no buffer, a função retornará 11 para incluir 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 foi definido incorretamente como NULL.
ERROR_INVALID_PARAMETER. Qualquer um dos valores de parâmetro era inválido.

Comentários

Consulte Comentários para GetDurationFormatEx.

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]
Plataforma de Destino	Windows
Cabeçalho	winnls.h (inclua Windows.h)
Biblioteca	Kernel32.lib
DLL	Kernel32.dll