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

Статья
08/23/2023

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

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

Синтаксис

int GetDateFormatW(
  [in]            LCID             Locale,
  [in]            DWORD            dwFlags,
  [in, optional]  const SYSTEMTIME *lpDate,
  [in, optional]  LPCWSTR          lpFormat,
  [out, optional] LPWSTR           lpDateStr,
  [in]            int              cchDate
);

Параметры

[in] Locale

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

[in] dwFlags

Флаги, указывающие параметры формата даты. Подробные определения см. в параметре dwFlagsобъекта GetDateFormatEx.

[in, optional] lpDate

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

[in, optional] lpFormat

Указатель на строку изображения формата, которая используется для формирования даты. Возможные значения для строки рисунка формата определяются в значениях "День", "Месяц", "Год" и "Эра".

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

[out, optional] lpDateStr

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

[in] cchDate

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

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

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

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

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

Примечание Этот API обновляется для поддержки изменений в японской эре за май 2019 г. Если приложение поддерживает японский календарь, убедитесь, что он правильно обрабатывает новую эру. Дополнительные сведения см. в статье Подготовка приложения к изменению японской эры .

См. примечания для GetDateFormatEx.

Если версия ANSI этой функции используется с идентификатором языкового стандарта только в Юникоде, функция может завершиться успешно, так как операционная система использует системную кодовую страницу. Однако символы, которые не определены на системной кодовой странице, отображаются в строке как вопросительный знак ("?").

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

Примечание

Заголовок datetimeapi.h определяет GetDateFormat в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОДа. Использование псевдонима, не зависящий от кодирования, с кодом, который не является нейтральным для кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или времени выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования


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