GetDateFormatEx 함수(datetimeapi.h)

아티클
08/23/2023

날짜 형식을 이름으로 지정된 로캘의 날짜 문자열로 지정합니다. 함수는 지정된 날짜 또는 로컬 시스템 날짜의 형식을 지정합니다.

참고 Windows Vista 이상에서만 실행되도록 설계된 경우 애플리케이션은 GetDateFormat 을 기본 설정으로 이 함수를 호출해야 합니다.

참고 이 함수는 예를 들어 사용자 지정 로캘로 인해 릴리스 간에 변경되는 데이터의 서식을 지정할 수 있습니다. 애플리케이션이 데이터를 유지하거나 전송해야 하는 경우 영구 로캘 데이터 사용을 참조하세요.

구문

int GetDateFormatEx(
  [in, optional]  LPCWSTR          lpLocaleName,
  [in]            DWORD            dwFlags,
  [in, optional]  const SYSTEMTIME *lpDate,
  [in, optional]  LPCWSTR          lpFormat,
  [out, optional] LPWSTR           lpDateStr,
  [in]            int              cchDate,
  [in, optional]  LPCWSTR          lpCalendar
);

매개 변수

[in, optional] lpLocaleName

로캘 이름 또는 다음 미리 정의된 값 중 하나에 대한 포인터입니다.

[in] dwFlags

lpFormat이 NULL로 설정된 경우 설정할 수 있는 다양한 함수 옵션을 지정하는 플래그입니다. 애플리케이션은 다음 값과 LOCALE_USE_CP_ACP 또는 LOCALE_NOUSEROVERRIDE 조합을 지정할 수 있습니다.

주의LOCALE_NOUSEROVERRIDE 사용하는 것은 사용자 기본 설정을 사용하지 않도록 설정하기 때문에 권장되지 않습니다.

값	의미
DATE_AUTOLAYOUT	Windows 7 이상: 로캘 및 일정 정보를 사용하여 오른쪽에서 왼쪽 및 왼쪽에서 오른쪽 읽기 레이아웃의 필요성을 감지하고 그에 따라 표시를 추가합니다. 이 값은 DATE_LTRREADING 또는 DATE_RTLREADING 사용할 수 없습니다. DATE_AUTOLAYOUT 로캘 및 달력을 사용하여 올바른 표시 추가를 결정하기 때문에 DATE_LTRREADING 및 DATE_RTLREADING 선호됩니다.
DATE_LONGDATE	긴 날짜 형식을 사용합니다. 이 값은 DATE_MONTHDAY, DATE_SHORTDATE 또는 DATE_YEARMONTH 사용할 수 없습니다.
DATE_LTRREADING	왼쪽에서 오른쪽 읽기 레이아웃에 대한 표시를 추가합니다. 이 값은 DATE_RTLREADING 사용할 수 없습니다.
DATE_RTLREADING	오른쪽에서 왼쪽 읽기 레이아웃에 대한 표시를 추가합니다. 이 값은 DATE_LTRREADING 사용할 수 없습니다.
DATE_SHORTDATE	짧은 날짜 형식을 사용합니다. 이것이 기본값입니다. 이 값은 DATE_MONTHDAY, DATE_LONGDATE 또는 DATE_YEARMONTH 사용할 수 없습니다.
DATE_USE_ALT_CALENDAR	대체 달력(있는 경우)을 사용하여 날짜 문자열의 서식을 지정합니다. 이 플래그가 설정된 경우 함수는 사용자 재정의를 사용하는 대신 해당 대체 일정의 기본 형식을 사용합니다. 사용자 재정의는 지정된 대체 일정에 대한 기본 형식이 없는 경우에만 사용됩니다.
DATE_YEARMONTH	Windows Vista: 연도/월 형식을 사용합니다. 이 값은 DATE_MONTHDAY, DATE_SHORTDATE 또는 DATE_LONGDATE 사용할 수 없습니다.
DATE_MONTHDAY	Windows 10: 지정된 로캘에 적합한 월 및 일 형식의 조합을 사용합니다. 이 값은 DATE_YEARMONTH, DATE_SHORTDATE 또는 DATE_LONGDATE 사용할 수 없습니다.

애플리케이션이 DATE_YEARMONTH, DATE_MONTHDAY, DATE_SHORTDATE 또는 DATE_LONGDATE 지정하지 않고 lpFormat 이 NULL로 설정된 경우 DATE_SHORTDATE 기본값입니다.

[in, optional] lpDate

서식을 지정할 날짜 정보가 포함된 SYSTEMTIME 구조체에 대한 포인터입니다. 함수가 현재 로컬 시스템 날짜를 사용하는 경우 애플리케이션은 이 매개 변수를 NULL 로 설정할 수 있습니다.

[in, optional] lpFormat

날짜를 형성하는 데 사용되는 서식 그림 문자열에 대한 포인터입니다. 그림 문자열 서식에 대한 가능한 값은 일, 월, 연도 및 Era 서식 그림에 정의됩니다.

예를 들어 날짜 문자열 "Wed,8월 31일 94"을 가져오기 위해 애플리케이션은 그림 문자열 "ddd',' MMM dd yy"를 사용합니다.

함수는 그림 문자열 형식에 지정되지 않은 정보(예: 로캘의 날짜 및 월 이름)에만 지정된 로캘을 사용합니다. 애플리케이션은 이 매개 변수를 NULL 로 설정하여 지정된 로캘의 날짜 형식에 따라 문자열의 서식을 지정할 수 있습니다.

[out, optional] lpDateStr

이 함수가 형식이 지정된 날짜 문자열을 검색하는 버퍼에 대한 포인터입니다.

[in] cchDate

lpDateStr 버퍼의 크기(문자)입니다. 애플리케이션은 서식이 지정된 날짜 문자열을 보유하는 데 필요한 버퍼 크기를 반환하기 위해 이 매개 변수를 0으로 설정할 수 있습니다. 이 경우 lpDateStr 로 표시된 버퍼는 사용되지 않습니다.

[in, optional] lpCalendar

예약; 은 NULL로 설정해야 합니다.

반환 값

성공하면 lpDateStr 버퍼에 기록된 문자 수를 반환합니다. cchDate 매개 변수가 0으로 설정된 경우 함수는 종료 null 문자를 포함하여 형식이 지정된 날짜 문자열을 보유하는 데 필요한 문자 수를 반환합니다.

이 함수는 성공하지 못하면 0을 반환합니다. 확장 오류 정보를 가져오기 위해 애플리케이션은 GetLastError를 호출할 수 있으며, 다음 오류 코드 중 하나를 반환할 수 있습니다.

ERROR_INSUFFICIENT_BUFFER. 제공된 버퍼 크기가 충분히 크지 않거나 NULL로 잘못 설정되었습니다.
ERROR_INVALID_FLAGS. 플래그에 제공된 값이 잘못되었습니다.
ERROR_INVALID_PARAMETER. 매개 변수 값이 잘못되었습니다.

설명

참고 이 API는 2019년 5월 일본 시대 변화를 지원하도록 업데이트되고 있습니다. 애플리케이션에서 일본어 달력을 지원하는 경우 새 시대를 제대로 처리하고 있는지 확인해야 합니다. 자세한 내용은 일본 시대 변경에 대한 애플리케이션 준비를 참조하세요 .

이 함수에서 지원하는 가장 빠른 날짜는 1601년 1월 1일입니다.

일 이름, 축약된 일 이름, 월 이름 및 약식 월 이름은 모두 로캘 식별자를 기반으로 지역화됩니다.

lpDate로 표시된 구조체의 날짜 값은 유효해야 합니다. 함수는 각 날짜 값(연도, 월, 일 및 요일)을 확인합니다. 요일이 올바르지 않으면 함수는 올바른 값을 사용하고 오류를 반환하지 않습니다. 다른 날짜 값이 올바른 범위를 벗어나면 함수가 실패하고 마지막 오류를 ERROR_INVALID_PARAMETER 설정합니다.

함수는 lpDate로 표시된 SYSTEMTIME 구조체의 시간 멤버를 무시합니다. 여기에는 wHour, wMinute, wSecond 및 wMilliseconds가 포함됩니다.

lpFormat 매개 변수에 잘못된 형식 문자열이 포함된 경우 함수는 오류를 반환하지 않고 가능한 최상의 날짜 문자열을 형성합니다. 예를 들어 유효한 유일한 연도 그림은 L"yyyy" 및 L"yy"입니다. 여기서 "L"은 유니코드(16비트 문자) 문자열을 나타냅니다. L"y"가 전달되면 함수는 L"yy"를 가정합니다. L"yyy"가 전달되면 함수는 L"yyyy"를 가정합니다. 4개 이상의 날짜(L"dddd") 또는 4개월(L"MMMM") 그림이 전달되는 경우 함수는 기본적으로 L"dddd" 또는 L"MMMM"으로 설정됩니다.

애플리케이션은 날짜 서식 그림의 작은따옴표 안에 날짜 문자열의 정확한 형식으로 유지되어야 하는 텍스트를 묶어야 합니다. 작은따옴표는 단일 따옴표 자체를 날짜 문자열에 표시할 수 있도록 이스케이프 문자로 사용할 수도 있습니다. 그러나 이스케이프 시퀀스는 작은따옴표로 묶어야 합니다. 예를 들어 날짜를 "5월 93일"로 표시하려면 형식 문자열은 L"MMMM ''''yyy"입니다. 첫 번째 및 마지막 작은따옴표는 묶은 따옴표입니다. 두 번째와 세 번째 작은따옴표는 세기 이전에 작은따옴표를 표시할 수 있도록 하는 이스케이프 시퀀스입니다.

날짜 그림에 일의 숫자 형식(d 또는 dd)과 MMMM(전체 월 이름)이 모두 포함된 경우 날짜 문자열에서 월 이름의 genitive 형식이 검색됩니다.

실제 서식을 수행하지 않고 기본 짧고 긴 날짜 형식을 가져오려면 애플리케이션은 LOCALE_SSHORTDATE 또는 LOCALE_SLONGDATE 상수와 함께 GetLocaleInfoEx를 사용해야 합니다. 대체 일정의 날짜 형식을 가져오기 위해 애플리케이션은 LOCALE_IOPTIONALCALENDAR 상수와 함께 GetLocaleInfoEx를 사용합니다. 특정 일정의 날짜 형식을 가져오기 위해 애플리케이션은 GetCalendarInfoEx를 사용하여 적절한 일정 식별자를 전달합니다. EnumCalendarInfoEx 또는 EnumDateFormatsEx를 호출하여 특정 일정의 날짜 형식을 검색할 수 있습니다.

이 함수는 사용자 지정 로캘에서 데이터를 검색할 수 있습니다. 데이터가 컴퓨터에서 컴퓨터로 또는 애플리케이션 실행 간에 동일하지는 않습니다. 애플리케이션이 데이터를 유지하거나 전송해야 하는 경우 영구 로캘 데이터 사용을 참조하세요.

DATE_LONGDATE 형식에는 요일을 포함하는 패턴과 요일을 포함하지 않는 패턴의 두 가지 날짜 패턴이 포함됩니다. 예를 들어 "2016년 10월 18일 화요일" 또는 "2016년 10월 18일"입니다. 애플리케이션에서 날짜가 다른 종류의 패턴이 아닌 이러한 종류의 패턴 중 하나를 사용하도록 해야 하는 경우 애플리케이션은 다음 작업을 수행해야 합니다.

EnumDateFormatsEx 함수를 호출하여 DATE_LONGDATE 형식에 대한 모든 날짜 형식을 가져옵니다.
요청한 일정 식별자와 일치하고 애플리케이션의 요구 사항과 일치하는 날짜 형식 문자열이 있는 EnumDateFormatsExEx 에 대해 지정한 콜백 함수에 전달된 첫 번째 날짜 형식을 찾습니다. 예를 들어 애플리케이션에서 날짜에 요일의 전체 이름을 포함해야 하는 경우 "dddd"를 포함하는 첫 번째 날짜 형식을 찾거나 애플리케이션에서 날짜에 축약된 이름이나 요일의 전체 이름을 포함해야 하는 경우 "ddd" 또는 "dddd"를 포함하지 않는 첫 번째 날짜 형식을 찾습니다.
lpFormat 매개 변수가 콜백 함수에서 적절한 형식으로 식별된 날짜 형식 문자열로 설정된 GetDateFormatEx 함수를 호출합니다.

긴 날짜 형식의 요일의 존재 또는 부재가 애플리케이션에 중요하지 않은 경우 애플리케이션은 EnumDateFormatsEx를 호출하여 모든 긴 날짜 형식을 먼저 열거하지 않고 GetDateFormatEx를 직접 호출할 수 있습니다.

Windows 8 시작: 앱이Windows.Globalization 네임스페이스에서 이 함수에 언어 태그를 전달하는 경우 먼저 ResolveLocaleName을 호출하여 태그를 변환해야 합니다.

Windows 8 시작: GetDateFormatEx는 Datetimeapi.h에서 선언됩니다. Windows 8 전에 Winnls.h에서 선언되었습니다.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows Vista [데스크톱 앱 \| UWP 앱]
지원되는 최소 서버	Windows Server 2008 [데스크톱 앱 \| UWP 앱]
대상 플랫폼	Windows
헤더	datetimeapi.h
라이브러리	Kernel32.lib
DLL	Kernel32.dll