Função GetDurationFormatEx (winnls.h)

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

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.

• LOCALE_NAME_INVARIANT
• LOCALE_NAME_SYSTEM_DEFAULT
• LOCALE_NAME_USER_DEFAULT

[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.

[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.

[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.

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

SYSTEMTIME = 345 segundos

uulDuration = 51234567 (5,1234567 segundos)

Requisitos

Confira também

GetDateFormatEx

GetDurationFormat

Getlocaleinfoex

GetTimeFormatEx

Suporte a idiomas nacionais

Funções de suporte à linguagem nacional