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

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

Синтаксис

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

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

• LOCALE_NAME_INVARIANT
• LOCALE_NAME_SYSTEM_DEFAULT
• LOCALE_NAME_USER_DEFAULT

[in] dwFlags

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

[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". Символы в строке формата, заключенные в одинарные кавычки, отображаются в том же месте и без изменений в выходной строке.

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

"11:29:40 PM"

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

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

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

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

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

Требования

См. также

GetDateFormatEx

GetLocaleInfoEx

GetTimeFormat

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

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