SHGetFileInfoA 함수(shellapi.h)

아티클
11/20/2024

파일, 폴더, 디렉터리 또는 드라이브 루트와 같은 파일 시스템의 개체에 대한 정보를 검색합니다.

통사론

DWORD_PTR SHGetFileInfoA(
  [in]      LPCSTR      pszPath,
            DWORD       dwFileAttributes,
  [in, out] SHFILEINFOA *psfi,
            UINT        cbFileInfo,
            UINT        uFlags
);

매개 변수

[in] pszPath

형식: LPCTSTR

경로 및 파일 이름을 포함하는 최대 길이 MAX_PATH null종결 문자열에 대한 포인터입니다. 절대 경로와 상대 경로는 모두 유효합니다.

uFlags 매개 변수에 SHGFI_PIDL 플래그가 포함된 경우 이 매개 변수는 셸의 네임스페이스 내에서 파일을 고유하게 식별하는 항목 식별자 목록을 포함하는 PIDL(ITEMIDLIST) 구조체의 주소여야 합니다. PIDL은 정규화된 PIDL이어야 합니다. 상대 PIDL은 허용되지 않습니다.

uFlags 매개 변수에 SHGFI_USEFILEATTRIBUTES 플래그가 포함된 경우 이 매개 변수는 유효한 파일 이름이 아니어야 합니다. 지정된 이름과 dwFileAttributes 매개 변수에 전달된 파일 특성이 있는 것처럼 함수가 진행됩니다. 이렇게 하면 pszPath 대한 확장명만 전달하고 dwFileAttributesFILE_ATTRIBUTE_NORMAL 전달하여 파일 형식에 대한 정보를 가져올 수 있습니다.

이 문자열은 짧은(8.3 형식) 또는 긴 파일 이름을 사용할 수 있습니다.

dwFileAttributes

형식: DWORD

하나 이상의 파일 특성 플래그가(Winnt.h에 정의된 대로 FILE_ATTRIBUTE_ 값)의 조합입니다. uFlagsSHGFI_USEFILEATTRIBUTES 플래그를 포함하지 않으면 이 매개 변수는 무시됩니다.

[in, out] psfi

형식: SHFILEINFO*

파일 정보를 수신하는 SHFILEINFO 구조체에 대한 포인터입니다.

cbFileInfo

형식: UINT

psfi 매개 변수가 가리키는 SHFILEINFO 구조체의 크기(바이트)입니다.

uFlags

형식: UINT

검색할 파일 정보를 지정하는 플래그입니다. 이 매개 변수는 다음 값의 조합일 수 있습니다.

SHGFI_ADDOVERLAYS(0x000000020)

버전 5.0. 파일의 아이콘에 적절한 오버레이를 적용합니다. SHGFI_ICON 플래그도 설정해야 합니다.

SHGFI_ATTR_SPECIFIED(0x000020000)

psfiSHFILEINFO 구조체의 dwAttributes 멤버에 원하는 특정 특성이 포함되어 있음을 나타내도록 SHGFI_ATTRIBUTES 수정합니다. 이러한 특성은 IShellFolder::GetAttributesOf전달됩니다. 이 플래그를 지정하지 않으면 0xFFFFFFFF 모든 특성을 요청하는 IShellFolder::GetAttributesOf전달됩니다. 이 플래그는 SHGFI_ICON 플래그로 지정할 수 없습니다.

SHGFI_ATTRIBUTES(0x000000800)

항목 특성을 검색합니다. 특성은 psfi 매개 변수에 지정된 구조체의 dwAttributes 멤버에 복사됩니다. 이러한 특성은 IShellFolder::GetAttributesOf가져온 것과 동일한 특성입니다.

SHGFI_DISPLAYNAME(0x000000200)

파일의 표시 이름을 검색합니다. 이 이름은 Windows 탐색기에 표시되는 이름입니다. 이름은 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)

시스템 이미지 목록 아이콘의 인덱스 검색 성공하면 인덱스가 psfiiIcon 멤버에 복사됩니다. 반환 값은 시스템 이미지 목록에 대한 핸들입니다. 인덱스가 iIcon 성공적으로 복사된 이미지만 유효합니다. 시스템 이미지 목록의 다른 이미지에 액세스하려고 하면 정의되지 않은 동작이 발생합니다.

SHGFI_TYPENAME(0x000000400)

파일의 형식을 설명하는 문자열을 검색합니다. 문자열은 psfi지정된 구조체의 szTypeName 멤버에 복사됩니다.

SHGFI_USEFILEATTRIBUTES(0x000000010)

함수가 pszPath지정된 파일에 액세스하려고 시도해서는 안 됨을 나타냅니다. 대신 pszPath 지정한 파일이 dwFileAttributes전달된 파일 특성과 함께 있는 것처럼 작동해야 합니다. 이 플래그는 SHGFI_ATTRIBUTES, SHGFI_EXETYPE또는 SHGFI_PIDL 플래그와 결합할 수 없습니다.

반환 값

형식: DWORD_PTR

uFlags 매개 변수에 따라 의미가 달라지는 값을 반환합니다.

uFlagsSHGFI_EXETYPE 또는 SHGFI_SYSICONINDEX포함하지 않는 경우 반환 값은 성공하면 0이 아니고, 그렇지 않으면 0입니다.

uFlagsSHGFI_EXETYPE 플래그가 포함된 경우 반환 값은 실행 파일의 형식을 지정합니다. 다음 값 중 하나가 됩니다.

반환 코드	묘사
0	사용할 수 없는 파일 또는 오류 조건입니다.
LOWORD = NE 또는 PE 및 HIWORD = Windows 버전	Windows 애플리케이션.
LOWORD = MZ 및 HIWORD = 0	파일 MS-DOS .exe 또는 .com
LOWORD = PE 및 HIWORD = 0	콘솔 애플리케이션 또는 .bat 파일

발언

백그라운드 스레드에서 이 함수를 호출해야 합니다. 이렇게 하지 않으면 UI의 응답이 중지될 수 있습니다.

SHGetFileInfopsfi가리키는 SHFILEINFO 구조의 hIcon 멤버에서 아이콘 핸들을 반환하는 경우 더 이상 필요하지 않은 경우 DestroyIcon 사용하여 해제해야 합니다.

참고 시스템 이미지 목록에 대한 핸들이 있으면 이미지 목록 API 사용하여 다른 이미지 목록처럼 조작할 수 있습니다. 시스템 이미지 목록은 프로세스별로 생성되므로 읽기 전용 개체로 처리해야 합니다. 시스템 이미지 목록에 쓰면 시스템 이미지 중 하나를 덮어쓰거나 삭제할 수 있으므로 프로세스의 나머지 부분에서는 사용할 수 없거나 올바르지 않습니다.

SHGetFileInfo호출하기 전에 CoInitialize 사용하거나 OleInitialize 사용하여 COM(구성 요소 개체 모델)을 초기화해야 합니다.

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 이상)

참고 항목

fileIconInit

다음을 통해 공유