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

Статья
08/27/2023

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

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

Синтаксис

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

Параметры

[in] Locale

Идентификатор языкового стандарта, указывающий языковой стандарт, для которого эта функция форматирует длительность. Макрос MAKELCID можно использовать для создания идентификатора языкового стандарта или одного из следующих предопределенных значений.

Windows Vista и более поздних версий: Также поддерживаются следующие пользовательские идентификаторы языкового стандарта.

[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, длительность равна нулю.

[in, optional] lpFormat

Указатель на строку формата. Дополнительные сведения см. в параметре lpFormatметода GetDurationFormatEx.

[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. Любое из значений параметров было недопустимым.

Требования

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