Функция GetTimeFormatEx (datetimeapi.h)

  • Статья

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

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

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

Синтаксис

int GetTimeFormatEx(
  [in, optional]  LPCWSTR          lpLocaleName,
  [in]            DWORD            dwFlags,
  [in, optional]  const SYSTEMTIME *lpTime,
  [in, optional]  LPCWSTR          lpFormat,
  [out, optional] LPWSTR           lpTimeStr,
  [in]            int              cchTime
);

Параметры

[in, optional] lpLocaleName

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

[in] dwFlags

Флаги, указывающие параметры формата времени. Приложение может указать сочетание следующих значений и LOCALE_USE_CP_ACP или LOCALE_NOUSEROVERRIDE.

Осторожностью Использование LOCALE_NOUSEROVERRIDE настоятельно не рекомендуется, так как оно отключает пользовательские настройки.
 
Значение Значение
TIME_NOMINUTESORSECONDS
 Не используйте минуты или секунды.
TIME_NOSECONDS
 Не используйте секунды.
TIME_NOTIMEMARKER
 Не используйте метку времени.
TIME_FORCE24HOURFORMAT
 Всегда используйте 24-часовой формат времени.

[in, optional] lpTime

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

[in, optional] lpFormat

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

[out, optional] lpTimeStr

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

[in] cchTime

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

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

Возвращает количество символов, полученных в буфере, на который указывает lpTimeStr. Если параметр cchTime имеет значение 0, функция возвращает размер буфера, необходимый для хранения отформатируемой строки времени, включая завершающий символ NULL.

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

  • ERROR_INSUFFICIENT_BUFFER. Указанный размер буфера был недостаточно велик или для него неправильно задано значение NULL.
  • ERROR_INVALID_FLAGS. Значения, указанные для флагов, были недопустимыми.
  • ERROR_INVALID_PARAMETER. Любое из значений параметров было недопустимым.
  • ERROR_OUTOFMEMORY. Недостаточно места для выполнения этой операции.

Комментарии

Если маркер времени существует, а флаг TIME_NOTIMEMARKER не установлен, функция локализует маркер времени на основе указанного идентификатора языкового стандарта. Примерами меток времени являются "AM" и "PM" для английского языка (США).

Значения времени в структуре, указанной lpTime, должны быть допустимыми. Функция проверяет каждое из значений времени, чтобы определить, находится ли оно в соответствующем диапазоне значений. Если какое-либо из значений времени выходит за пределы правильного диапазона, функция завершается ошибкой и задает для последней ошибки значение ERROR_INVALID_PARAMETER.

Функция игнорирует элементы даты в структуре SYSTEMTIME . К ним относятся : wYear, wMonth, wDayOfWeek и wDay.

Если указан TIME_NOMINUTESORSECONDS или TIME_NOSECONDS, функция удаляет разделители, следующие за элементами минут и секунд.

Если указан TIME_NOTIMEMARKER, функция удаляет разделители, предшествующие маркеру времени и следующие за ними.

Если указан TIME_FORCE24HOURFORMAT, функция отображает любой существующий маркер времени, если не установлен флаг TIME_NOTIMEMARKER.

Функция не включает миллисекунда в отформатированную строку времени.

Функция не возвращает ошибок для строки неправильного формата, а просто формирует наилучшую строку времени. Если передается более двух часов, минут, секунд или рисунков в формате меток времени, функция по умолчанию использует значение два. Например, единственными допустимыми рисунками меток времени являются "t" и "tt". Если передается "ttt", функция предполагает "tt".

Чтобы получить формат времени без фактического форматирования, приложение должно использовать функцию GetLocaleInfoEx , указав LOCALE_STIMEFORMAT.

Приложение может использовать следующие элементы для создания строки рисунка формата. Если для разделения элементов в строке формата используются пробелы, эти пробелы отображаются в том же расположении в выходной строке. Буквы должны быть в верхнем или нижнем регистре, как показано, например "ss", а не "SS". Символы в строке формата, заключенные в одинарные кавычки, отображаются в том же месте и без изменений в выходной строке.

Picture Значение
h Часы без нуля в начале для однозначных часов; 12-часовые часы
hh Часы с нулем в начале для однозначных часов; 12-часовые часы
H Часы без нуля в начале для однозначных часов; 24-часовые часы
HH Часы с нулем в начале для однозначных часов; 24-часовые часы
m Минуты без нуля в начале для однозначных минут
ММ Минуты с нулем в начале для однозначных минут
s Секунды без нуля в начале для однозначных секунд
сс Секунды с нулем в начале для однозначных секунд
t Строка маркера времени для одного символа, например A или P
tt Строка многосимвого маркера времени, например AM или PM
 

Например, чтобы получить строку времени

"11:29:40 PM"

приложение должно использовать строку рисунка

"hh':'mm':'ss tt"

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

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

Начиная с Windows 8: GetTimeFormatEx объявляется в файле Datetimeapi.h. До Windows 8 он был объявлен в Winnls.h.

Требования

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

См. также

GetDateFormatEx

GetLocaleInfoEx

GetTimeFormat

Поддержка национальных языков

Функции поддержки национальных языков