SHGetFileInfoW 함수(shellapi.h)
파일, 폴더, 디렉터리 또는 드라이브 루트와 같은 파일 시스템의 개체에 대한 정보를 검색합니다.
구문
DWORD_PTR SHGetFileInfoW(
[in] LPCWSTR pszPath,
DWORD dwFileAttributes,
[in, out] SHFILEINFOW *psfi,
UINT cbFileInfo,
UINT uFlags
);
매개 변수
[in] pszPath
형식: LPCTSTR
경로 및 파일 이름을 포함하는 최대 길이 MAX_PATH null로 끝나는 문자열에 대한 포인터입니다. 절대 경로와 상대 경로는 모두 유효합니다.
uFlags 매개 변수에 SHGFI_PIDL 플래그가 포함된 경우 이 매개 변수는 Shell의 네임스페이스 내에서 파일을 고유하게 식별하는 항목 식별자 목록을 포함하는 PIDL(ITEMIDLIST) 구조체의 주소여야 합니다. PIDL은 정규화된 PIDL이어야 합니다. 상대 PIDL은 허용되지 않습니다.
uFlags 매개 변수에 SHGFI_USEFILEATTRIBUTES 플래그가 포함된 경우 이 매개 변수는 유효한 파일 이름이 아니어야 합니다. 함수는 지정된 이름과 dwFileAttributes 매개 변수에 전달된 파일 특성을 사용하여 파일이 있는 것처럼 진행됩니다. 이렇게 하면 pszPath에 대한 확장명만 전달하고 dwFileAttributes에서 FILE_ATTRIBUTE_NORMAL 전달하여 파일 형식에 대한 정보를 얻을 수 있습니다.
이 문자열은 짧은 파일 이름(8.3 형식) 또는 긴 파일 이름을 사용할 수 있습니다.
dwFileAttributes
형식:DWORD
하나 이상의 파일 특성 플래그 (Winnt.h에 정의된 값 FILE_ATTRIBUTE_)의 조합입니다. uFlags에SHGFI_USEFILEATTRIBUTES 플래그가 포함되지 않으면 이 매개 변수는 무시됩니다.
[in, out] psfi
형식: SHFILEINFO*
파일 정보를 수신하는 SHFILEINFO 구조체에 대한 포인터입니다.
cbFileInfo
형식: UINT
psfi 매개 변수가 가리키는 SHFILEINFO 구조체의 크기(바이트)입니다.
uFlags
형식: UINT
검색할 파일 정보를 지정하는 플래그입니다. 이 매개 변수는 다음 값의 조합일 수 있습니다.
SHGFI_ADDOVERLAYS(0x000000020)
버전 5.0. 파일의 아이콘에 적절한 오버레이를 적용합니다. SHGFI_ICON 플래그도 설정해야 합니다.
SHGFI_ATTR_SPECIFIED(0x000020000)
psfi에서 SHFILEINFO 구조체의 dwAttributes 멤버에 원하는 특정 특성이 포함되어 있음을 나타내도록 SHGFI_ATTRIBUTES 수정합니다. 이러한 특성은 IShellFolder::GetAttributesOf에 전달됩니다. 이 플래그를 지정하지 않으면 0xFFFFFFFF IShellFolder::GetAttributesOf에 전달되어 모든 특성을 요청합니다. 이 플래그는 SHGFI_ICON 플래그로 지정할 수 없습니다.
SHGFI_ATTRIBUTES(0x000000800)
항목 특성을 검색합니다. 특성은 psfi 매개 변수에 지정된 구조체의 dwAttributes 멤버에 복사됩니다. 이러한 특성은 IShellFolder::GetAttributesOf에서 가져온 것과 동일한 특성입니다.
SHGFI_DISPLAYNAME(0x000000200)
파일의 표시 이름을 검색합니다. 이 이름은 Windows Explorer 표시되는 이름입니다. 이름은 psfi에 지정된 구조체의 szDisplayName 멤버에 복사됩니다. 반환된 표시 이름은 파일 이름의 8.3 형식이 아닌 긴 파일 이름(있는 경우)을 사용합니다. 표시 이름은 확장이 표시되는지 여부와 같은 설정의 영향을 받을 수 있습니다.
SHGFI_EXETYPE(0x000002000)
pszPath가 실행 파일을 식별하는 경우 실행 파일의 형식을 검색합니다. 정보는 반환 값으로 압축됩니다. 이 플래그는 다른 플래그로 지정할 수 없습니다.
SHGFI_ICON(0x000000100)
시스템 이미지 목록 내의 아이콘의 파일 및 인덱스를 나타내는 아이콘에 대한 핸들을 검색합니다. 핸들은 psfi로 지정된 구조체의 hIcon 멤버에 복사되고 인덱스는 iIcon 멤버에 복사됩니다.
SHGFI_ICONLOCATION(0x000001000)
파일 아이콘 처리기의 IExtractIcon::GetIconLocation 메서드에서 반환한 대로 pszPath에서 지정한 파일을 나타내는 아이콘이 포함된 파일의 이름을 검색합니다. 또한 해당 파일 내에서 아이콘 인덱스도 검색합니다. 아이콘이 포함된 파일의 이름은 psfi로 지정된 구조체의 szDisplayName 멤버에 복사됩니다. 아이콘의 인덱스가 해당 구조체의 iIcon 멤버에 복사됩니다.
SHGFI_LARGEICON(0x000000000)
SHGFI_ICON 수정하여 함수가 파일의 큰 아이콘을 검색합니다. SHGFI_ICON 플래그도 설정해야 합니다.
SHGFI_LINKOVERLAY(0x000008000)
SHGFI_ICON 수정하여 함수가 파일 아이콘에 링크 오버레이를 추가합니다. SHGFI_ICON 플래그도 설정해야 합니다.
SHGFI_OPENICON(0x000000002)
SHGFI_ICON 수정하여 함수가 파일의 열린 아이콘을 검색합니다. 또한 SHGFI_SYSICONINDEX 수정하는 데 사용되어 함수가 파일의 작은 열린 아이콘이 포함된 시스템 이미지 목록으로 핸들을 반환합니다. 컨테이너 개체는 열린 아이콘을 표시하여 컨테이너가 열려 있음을 나타냅니다. SHGFI_ICON 및/또는 SHGFI_SYSICONINDEX 플래그도 설정해야 합니다.
SHGFI_OVERLAYINDEX(0x000000040)
버전 5.0. 오버레이 아이콘의 인덱스 반환 오버레이 인덱스의 값은 psfi로 지정된 구조체의 iIcon 멤버의 상위 8비트에서 반환됩니다. 이 플래그를 사용하려면 SHGFI_ICON 설정해야 합니다.
SHGFI_PIDL(0x000000008)
pszPath가 경로 이름이 아닌 ITEMIDLIST 구조체의 주소임을 나타냅니다.
SHGFI_SELECTED(0x000010000)
SHGFI_ICON 수정하여 함수가 파일의 아이콘을 시스템 강조 색과 혼합합니다. SHGFI_ICON 플래그도 설정해야 합니다.
SHGFI_SHELLICONSIZE(0x000000004)
SHGFI_ICON 수정하여 함수가 셸 크기 아이콘을 검색합니다. 이 플래그를 지정하지 않으면 함수는 시스템 메트릭 값에 따라 아이콘의 크기를 조정합니다. SHGFI_ICON 플래그도 설정해야 합니다.
SHGFI_SMALLICON(0x000000001)
SHGFI_ICON 수정하여 함수가 파일의 작은 아이콘을 검색합니다. 또한 SHGFI_SYSICONINDEX 수정하는 데 사용되어 함수가 작은 아이콘 이미지가 포함된 시스템 이미지 목록으로 핸들을 반환합니다. SHGFI_ICON 및/또는 SHGFI_SYSICONINDEX 플래그도 설정해야 합니다.
SHGFI_SYSICONINDEX(0x000004000)
시스템 이미지 목록 아이콘의 인덱스 검색 성공하면 인덱스가 psfi의 iIcon 멤버에 복사됩니다. 반환 값은 시스템 이미지 목록에 대한 핸들입니다. 인덱스가 iIcon 에 성공적으로 복사된 이미지만 유효합니다. 시스템 이미지 목록의 다른 이미지에 액세스하려고 하면 정의되지 않은 동작이 발생합니다.
SHGFI_TYPENAME(0x000000400)
파일의 형식을 설명하는 문자열을 검색합니다. 문자열은 psfi에 지정된 구조체의 szTypeName 멤버에 복사됩니다.
SHGFI_USEFILEATTRIBUTES(0x000000010)
함수가 pszPath로 지정된 파일에 액세스하려고 시도해서는 안 됨을 나타냅니다. 대신 pszPath 에 지정된 파일이 dwFileAttributes에 전달된 파일 특성과 함께 있는 것처럼 작동해야 합니다. 이 플래그는 SHGFI_ATTRIBUTES, SHGFI_EXETYPE 또는 SHGFI_PIDL 플래그와 결합할 수 없습니다.
반환 값
형식: DWORD_PTR
의미가 uFlags 매개 변수에 따라 달라지는 값을 반환합니다.
uFlags에 SHGFI_EXETYPE 또는 SHGFI_SYSICONINDEX 포함되지 않은 경우 반환 값은 성공하면 0이 아니고, 그렇지 않으면 0이 됩니다.
uFlags에SHGFI_EXETYPE 플래그가 포함된 경우 반환 값은 실행 파일의 형식을 지정합니다. 다음 값 중 하나가 됩니다.
| 반환 코드 | 설명 |
|---|---|
|
사용할 수 없는 파일 또는 오류 조건입니다. |
|
Windows 애플리케이션. |
|
MS-DOS .exe 또는 .com 파일 |
|
콘솔 애플리케이션 또는 .bat 파일 |
설명
백그라운드 스레드에서 이 함수를 호출해야 합니다. 이렇게 하지 않으면 UI의 응답이 중지될 수 있습니다.
SHGetFileInfo가 psfi가 가리키는 SHFILEINFO 구조체의 hIcon 멤버에서 아이콘 핸들을 반환하는 경우 더 이상 필요하지 않을 때 DestroyIcon을 사용하여 해제해야 합니다.
Windows 애플리케이션에서 SHGFI_EXETYPE 플래그를 사용하는 경우 Windows 버전의 실행 파일은 반환 값의 HIWORD에 제공됩니다. 이 버전은 16진수 값으로 반환됩니다. 이 값을 특정 Windows 버전과 동일시하는 방법에 대한 자세한 내용은 Windows 헤더 사용을 참조하세요.
예제
다음 코드 예제에서는 SHGetFileInfo 를 사용하여 PIDL로 식별된 휴지통의 표시 이름을 검색합니다.
LPITEMIDLIST pidl = NULL;
hr = SHGetFolderLocation(NULL, CSIDL_BITBUCKET, NULL, 0, &pidl);
if (SUCCEEDED(hr))
{
SHFILEINFOW sfi = {0};
hr = SHGetFileInfo((LPCTSTR)pidl,
-1,
&sfi,
sizeof(sfi),
SHGFI_PIDL | SHGFI_DISPLAYNAME)
if (SUCCEEDED(hr))
{
// The display name is now held in sfi.szDisplayName.
}
}
ILFree(pidl);
참고
shellapi.h 헤더는 UNICODE 전처리기 상수의 정의에 따라 이 함수의 ANSI 또는 유니코드 버전을 자동으로 선택하는 별칭으로 SHGetFileInfo를 정의합니다. 인코딩 중립 별칭을 인코딩 중립이 아닌 코드와 혼합하면 컴파일 또는 런타임 오류가 발생하는 불일치가 발생할 수 있습니다. 자세한 내용은 함수 프로토타입에 대한 규칙을 참조하세요.
요구 사항
| 요구 사항 | 값 |
|---|---|
| 지원되는 최소 클라이언트 | Windows XP [데스크톱 앱만 해당] |
| 지원되는 최소 서버 | Windows 2000 Server[데스크톱 앱만] |
| 대상 플랫폼 | Windows |
| 헤더 | shellapi.h |
| 라이브러리 | Shell32.lib |
| DLL | Shell32.dll(버전 4.0 이상) |