Função GetDurationFormatEx (winnls.h)

Artigo
03/08/2023

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

Nota O aplicativo deve chamar essa função em preferência para GetDurationFormat se projetado para ser executado somente no Windows Vista e posterior.

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

int GetDurationFormatEx(
  [in, optional]  LPCWSTR          lpLocaleName,
  [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, optional] lpLocaleName

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

[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. O aplicativo define esse parâmetro como NULL se a função for ignorá-lo 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 definidos, o parâmetro lpDuration terá precedência. Se lpDuration for definido como NULL e ullDuration for definido como 0, a duração será 0.

[in, optional] lpFormat

Ponteiro para a cadeia de caracteres de formato com caracteres, conforme mostrado abaixo. O aplicativo poderá definir esse parâmetro como NULL se a função for formatar a cadeia de caracteres de acordo com o formato de duração da localidade especificada. Se lpFormat não estiver definido como NULL, a função usará a localidade somente para informações não especificadas na cadeia de caracteres de imagem de formato.

Valor	Significado
d	dias
h ou H	horas
hh ou HH	Horas; se menor que dez, preenviar um zero à esquerda
m	minutes
mm	Minutos; se menor que dez, preenviar um zero à esquerda
s	segundos
ss	Segundos; se menor que dez, preenviar um zero à esquerda
f	frações de um segundo Nota O caractere "f" pode ocorrer até nove vezes consecutivas (fffffffff), embora o suporte para temporizadores de frequência seja limitado a 100 nanossegundos. Portanto, se nove caracteres estiverem presentes, os dois últimos dígitos serão sempre 0.

[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 recuperará 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 nulo de terminação. 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

Essa função pode ser usada com aplicativos multimídia que exibem a hora do arquivo e os aplicativos de eventos esportivos que exibem os horários de término.

A função ignora os três primeiros membros da estrutura SYSTEMTIME : wYear, wMonth e wDayOfWeek.

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.

Veja a seguir as características das cadeias de caracteres de formato de duração:

Os caracteres de formatação são minúsculos.
Nota Uma exceção é feita para que (H) seja consistente com GetTimeFormatEx.
Cadeias de caracteres de formato de dois dígitos por horas, minutos e segundos acrescentam um zero à esquerda se o valor for menor que 10.
O primeiro campo de saída não está sujeito a nenhum teste de limites (horas<24, minutos<60, segundos<60, milissegundos<1000). Os dias não estão sujeitos a testes de limites.
A função pressupõe que todas as cadeias de caracteres de formato estejam em tamanho de campo decrescente, por exemplo, horas, minutos, segundos, milissegundos.
O primeiro campo a ser exibido é normalizado, conforme definido pela cadeia de caracteres de formato. Por exemplo, se o aplicativo especificar 310 segundos e a cadeia de caracteres de formato for m:ss, a saída será 5:10. No entanto, se a cadeia de caracteres de formato especificar minutos e segundos, mas o aplicativo especificar horas, o campo de minutos será ajustado adequadamente.
Se frações não forem o primeiro campo, o número de caracteres "f" na cadeia de caracteres de formato indicará o número de decimais a serem mostrados (limite de 9). Se frações forem o primeiro campo, o número de caracteres "f" indicará o número de dígitos significativos abaixo de um segundo.
O arredondamento ocorre por truncamento, não pela regra de cinco rounds para cima e quatro rodadas para baixo.
Aspas simples são usadas para escapar de caracteres.

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.

Exemplos

A seguir estão exemplos de formatos de duração e saídas correspondentes para durações de tempo especificadas.

SYSTEMTIME = 14 dias, 2 horas, 45 minutos, 12 segundos e 247 milissegundos

Formatar	Saída
d:hh:mm:ss	14:02:45:12
hh:mm:ss:ff	338:45:12:24
hh:mm:ss:fff	338:45:12:247
h' h 'mm' m 'ss' s'	338 h 45 m 12 s

SYSTEMTIME = 345 segundos

Formatar	Saída
hh:mm:ss	00:05:45
h:mm:ss	0:05:45
mm:ss	05:45
m:ss	5:45
mm' m 'ss' s'	05 m 45 s
ss	345
ss'seconds'	345 segundos

uulDuration = 51234567 (5,1234567 segundos)

Formatar	Saída
s.fff	5.123
s.ffffff	5.123456
s.fffffffff	5.123456700 (adicionar zeros à direita)
fff 'ms'	5123 ms
ffffff 'microssegundos'	5123456 microssegundos
fffffffff 'ns'	5123456700 ns

Requisitos


Cliente mínimo com suporte	Windows Vista [aplicativos da área de trabalho \| Aplicativos UWP]
Servidor mínimo com suporte	Windows Server 2008 [aplicativos da área de trabalho \| Aplicativos UWP]
Plataforma de Destino	Windows
Cabeçalho	winnls.h (inclua Windows.h)
Biblioteca	Kernel32.lib
DLL	Kernel32.dll