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
로캘 이름 또는 다음 미리 정의된 값 중 하나에 대한 포인터입니다.
[in] dwFlags
시간 형식 옵션을 지정하는 플래그입니다. 애플리케이션은 다음 값과 LOCALE_USE_CP_ACP 또는 LOCALE_NOUSEROVERRIDE 조합을 지정할 수 있습니다.
| 값 | 의미 |
|---|---|
|
분 또는 초를 사용하지 마세요. |
|
초를 사용하지 마세요. |
|
시간 표식을 사용하지 마세요. |
|
항상 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 플래그도 설정되지 않는 한 함수는 기존 시간 표식을 표시합니다.
함수에는 서식이 지정된 시간 문자열의 일부로 밀리초가 포함되지 않습니다.
함수는 잘못된 형식 문자열에 대한 오류를 반환하지 않고 가능한 최상의 시간 문자열을 형성합니다. 2시간, 1분, 2시간 또는 시간 표식 서식 그림이 전달되는 경우 함수는 기본적으로 2로 설정됩니다. 예를 들어 유효한 유일한 시간 표식 그림은 "t" 및 "tt"입니다. "ttt"가 전달되면 함수는 "tt"를 가정합니다.
실제 서식을 수행하지 않고 시간 형식을 가져오려면 애플리케이션에서 GetLocaleInfoEx 함수를 사용하여 LOCALE_STIMEFORMAT 지정해야 합니다.
애플리케이션은 다음 요소를 사용하여 그림 문자열 서식을 생성할 수 있습니다. 공백을 사용하여 서식 문자열의 요소를 구분하는 경우 이러한 공백은 출력 문자열의 동일한 위치에 표시됩니다. 문자는 "SS"가 아닌 "ss"와 같이 대문자 또는 소문자여야 합니다. 작은따옴표로 묶인 형식 문자열의 문자는 동일한 위치에 표시되고 출력 문자열에는 변경되지 않습니다.
| 그림 | 의미 |
|---|---|
| h | 한 자리 시간 동안 앞에 0이 없는 시간; 12시간 시계 |
| hh | 한 자리 시간 동안 앞에 0이 있는 시간; 12시간 시계 |
| H | 한 자리 시간 동안 앞에 0이 없는 시간; 24시간 시계 |
| HH | 한 자리 시간 동안 앞에 0이 있는 시간; 24시간 시계 |
| 분 | 한 자리 분 동안 선행 0이 없는 분 |
| mm | 한 자리 분 동안 앞에 0이 있는 분 |
| 초 | 한 자리 초 동안 선행 0이 없는 초 |
| ss | 한 자리 초 동안 앞에 0이 있는 초 |
| 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 |
| 헤더 | datetimeapi.h |
| 라이브러리 | Kernel32.lib |
| DLL | Kernel32.dll |
참고 항목
피드백
출시 예정: 2024년 내내 콘텐츠에 대한 피드백 메커니즘으로 GitHub 문제를 단계적으로 폐지하고 이를 새로운 피드백 시스템으로 바꿀 예정입니다. 자세한 내용은 다음을 참조하세요. https://aka.ms/ContentUserFeedback
다음에 대한 사용자 의견 제출 및 보기