Функция GetDurationFormatEx (winnls.h)

Статья
06/01/2023

Форматирует длительность времени в виде строки времени для языкового стандарта, заданного именем.

Примечание Приложение должно вызывать эту функцию в предпочтительном варианте GetDurationFormat , если оно предназначено для работы только в Windows Vista и более поздних версиях.

Примечание Эта функция может форматировать данные, которые изменяются между выпусками, например из-за пользовательского языкового стандарта. Если приложение должно сохранять или передавать данные, см. статью Использование данных сохраняемого языкового стандарта.

Синтаксис

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
);

Параметры

[in, optional] lpLocaleName

Указатель на имя языкового стандарта или одно из следующих предопределенных значений.

[in] dwFlags

Флаги, указывающие параметры функции. Если для lpFormat не задано значение NULL, этот параметр должен иметь значение 0. Если lpFormat имеет значение NULL, приложение может указать LOCALE_NOUSEROVERRIDE для форматирования строки с использованием системного формата длительности по умолчанию для указанного языкового стандарта.

Осторожностью Использование LOCALE_NOUSEROVERRIDE настоятельно не рекомендуется, так как оно отключает пользовательские настройки.

[in, optional] lpDuration

Указатель на структуру SYSTEMTIME , содержащую сведения о длительности времени для форматирования. Приложение задает этому параметру значение NULL , если функция игнорирует его и использует ullDuration.

[in] ullDuration

64-разрядное целое число без знака, представляющее количество 100-наносекундных интервалов в длительности. Если заданы оба параметра lpDuration и ullDuration , приоритет имеет параметр lpDuration . Если для параметра lpDuration задано значение NULL , а для параметра ullDuration задано значение 0, длительность равно 0.

[in, optional] lpFormat

Указатель на строку формата с символами, как показано ниже. Приложение может задать для этого параметра значение NULL , если функция отформатировать строку в соответствии с форматом длительности для указанного языкового стандарта. Если для lpFormat не задано значение NULL, функция использует языковой стандарт только для сведений, не указанных в строке рисунка формата.

Значение	Значение
d	days
h или H	часы
hh или HH	Часов; если меньше десяти, добавьте начальный ноль
m	minutes
мм	Минут; если меньше десяти, добавьте начальный ноль
s	секунд
ss	Секунд; если меньше десяти, добавьте начальный ноль
f	доли секунды Примечание Символ "f" может встречаться до девяти раз подряд (fffffffff), хотя поддержка таймеров частоты ограничена 100 наносекундами. Таким образом, если имеется девять символов, последние две цифры всегда будут 0.

[out, optional] lpDurationStr

Указатель на буфер, в котором функция извлекает строку длительности.

Кроме того, этот параметр получает значение NULL , если параметр cchDuration имеет значение 0. В этом случае функция возвращает необходимый размер для буфера строк длительности.

[in] cchDuration

Размер буфера в символах, указанный lpDurationStr.

Кроме того, приложение может задать для этого параметра значение 0. В этом случае функция получает значение NULL в lpDurationStr и возвращает необходимый размер для буфера строки длительности.

Возвращаемое значение

Возвращает количество символов, полученных в буфере, указанное lpDurationStr в случае успешного выполнения. Если lpDurationStr имеет значение NULL , а cchDuration — 0, функция возвращает необходимый размер для буфера строки длительности, включая завершающий символ NULL. Например, если в буфер записано 10 символов, функция возвращает 11, чтобы включить завершающий символ NULL.

Функция возвращает значение 0, если не удалось. Чтобы получить расширенные сведения об ошибке, приложение может вызвать Метод GetLastError, который может возвращать один из следующих кодов ошибок:

ERROR_INSUFFICIENT_BUFFER. Указанный размер буфера был недостаточно велик или для него неправильно задано значение NULL.
ERROR_INVALID_PARAMETER. Любое из значений параметров было недопустимым.

Эта функция может извлекать данные из пользовательских языковых стандартов. Данные не обязательно будут одинаковыми с компьютера на компьютер или между запусками приложения. Если приложение должно сохранять или передавать данные, см. статью Использование данных сохраняемого языкового стандарта.

Ниже приведены характеристики строк формата длительности.

Символы форматирования имеют нижний регистр.
Примечание Для (H) создается исключение для согласованности с GetTimeFormatEx.
Двузначные строки формата для часов, минут и секунд в начале нуля, если значение меньше 10.
Первое поле вывода не подлежит проверке границ (часы<24, минуты<60, секунды<60, миллисекунд<1000). Дни не подлежат тестированию с ограничениями.
Функция предполагает, что все строки формата имеют уменьшающийся размер поля, например часы, минуты, секунды, миллисекунд.
Первое отображаемое поле нормализуется в соответствии со строкой формата. Например, если приложение указывает 310 секунд, а строка формата m:ss, выходные данные будут 5:10. Однако если в строке формата указаны минуты и секунды, а в приложении — часы, поле минут корректируется соответствующим образом.
Если дроби не являются первым полем, количество символов "f" в строке формата указывает количество десятичных знаков для отображения (ограничение в 9). Если дроби являются первым полем, число символов "f" указывает на количество значимых цифр ниже одной секунды.
Округление происходит путем усечения, а не по правилу пяти раундов вверх и четырех раундов вниз.
Одинарные кавычки используются для экранирования символов.

Начиная с Windows 8. Если приложение передает языковые теги в эту функцию из пространства имен Windows.Globalization, оно должно сначала преобразовать теги, вызвав ResolveLocaleName.

Примеры

Ниже приведены примеры форматов длительности и соответствующих выходных данных для указанных периодов времени.

SYSTEMTIME = 14 дней, 2 часа, 45 минут, 12 секунд и 247 миллисекунд

Формат	Выходные данные
d:чч:мм:сс	14:02:45:12
чч:мм:сс:ff	338:45:12:24
чч:мм:сс:fff	338:45:12:247
h' h 'mm' m 'ss' s'	338 ч 45 м 12 с

SYSTEMTIME = 345 секунд

Формат	Выходные данные
чч:мм:сс	00:05:45
ч:мм:сс	0:05:45
мм:сс	05:45
m:ss	5:45
mm' m 'ss' s'	05 м 45 с
сс	345
секунды ss'	345 секунд

uulDuration = 51234567 (5,1234567 секунд)

Формат	Выходные данные
s.fff	5.123
s.ffffff	5.123456
s.fffffffffff	5.123456700 (добавление конечных нулей)
fff 'ms'	5123 мс
ffffff 'microseconds'	5123456 микросекунд
fffffffff 'ns'	5123456700 ns

Требования


Минимальная версия клиента	Windows Vista [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows Server 2008 [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	winnls.h (включая Windows.h)
Библиотека	Kernel32.lib
DLL	Kernel32.dll