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

Статья
11/20/2024

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

Примечание По соображениям взаимодействия приложение должно предпоч есть функцию 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 Профессиональный [только классические приложения]
минимальный поддерживаемый сервер	Windows 2000 Server [только классические приложения]
целевая платформа	Виндоус
заголовка	datetimeapi.h
библиотеки	Kernel32.lib
DLL	Kernel32.dll