SHGetFileInfoA-Funktion (shellapi.h)

Ruft Informationen zu einem Objekt im Dateisystem ab, z. B. eine Datei, einen Ordner, ein Verzeichnis oder ein Laufwerkstamm.

Syntax

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

Parameter

[in] pszPath

Typ: LPCTSTR

Ein Zeiger auf eine NULL-Zeichenfolge mit maximaler Länge MAX_PATH, die den Pfad und den Dateinamen enthält. Sowohl absolute als auch relative Pfade sind gültig.

Wenn der uFlags-Parameter das SHGFI_PIDL-Flag enthält, muss dieser Parameter die Adresse einer ITEMIDLIST-Struktur (PIDL) sein, die die Liste der Elementbezeichner enthält, die die Datei im Namespace der Shell eindeutig identifiziert. Die PIDL muss eine vollqualifizierte PIDL sein. Relative PIDLs sind nicht zulässig.

Wenn der uFlags-Parameter das SHGFI_USEFILEATTRIBUTES-Flag enthält, muss dieser Parameter kein gültiger Dateiname sein. Die Funktion wird so ausgeführt, als ob die Datei mit dem angegebenen Namen und mit den Dateiattributen vorhanden ist, die im dwFileAttributes-Parameter übergeben werden. Dadurch können Sie Informationen zu einem Dateityp abrufen, indem Sie nur die Erweiterung für pszPath übergeben und FILE_ATTRIBUTE_NORMAL in dwFileAttributes übergeben.

Diese Zeichenfolge kann entweder kurze (das 8.3-Formular) oder lange Dateinamen verwenden.

dwFileAttributes

Art: DWORD

Eine Kombination aus mindestens einem Dateiattributeflag (FILE_ATTRIBUTE_ Werte, die in Winnt.h definiert sind). Wenn uFlags das SHGFI_USEFILEATTRIBUTES-Flag nicht enthält, wird dieser Parameter ignoriert.

[in, out] psfi

Typ: SHFILEINFO*

Zeiger auf eine SHFILEINFO-Struktur , um die Dateiinformationen zu erhalten.

cbFileInfo

Typ: UINT

Die Größe der SHFILEINFO-Struktur in Bytes, auf die der psfi-Parameter verweist.

uFlags

Typ: UINT

Die Flags, die die abzurufenden Dateiinformationen angeben. Für diesen Parameter ist eine Kombination der folgenden Werte gültig.

SHGFI_ADDOVERLAYS (0x000000020)

Version 5.0. Wenden Sie die entsprechenden Überlagerungen auf das Symbol der Datei an. Das SHGFI_ICON-Flag muss ebenfalls festgelegt werden.

SHGFI_ATTR_SPECIFIED (0x000020000)

Ändern Sie SHGFI_ATTRIBUTES , um anzugeben, dass das dwAttributes-Element der SHFILEINFO-Struktur bei psfi die gewünschten spezifischen Attribute enthält. Diese Attribute werden an IShellFolder::GetAttributesOf übergeben. Wenn dieses Flag nicht angegeben wird, wird 0xFFFFFFFF an IShellFolder::GetAttributesOf übergeben, um alle Attribute anzufordern. Dieses Flag kann nicht mit dem SHGFI_ICON-Flag angegeben werden.

SHGFI_ATTRIBUTES (0x000000800)

Rufen Sie die Elementattribute ab. Die Attribute werden in das dwAttributes-Element der im psfi-Parameter angegebenen Struktur kopiert. Dies sind dieselben Attribute, die von IShellFolder::GetAttributesOf abgerufen werden.

SHGFI_DISPLAYNAME (0x000000200)

Rufen Sie den Anzeigenamen für die Datei ab. Dabei handelt es sich um den Namen, der in Windows Explorer angezeigt wird. Der Name wird in das element szDisplayName der in psfi angegebenen Struktur kopiert. Der zurückgegebene Anzeigename verwendet den langen Dateinamen, falls vorhanden, und nicht die Form 8.3 des Dateinamens. Beachten Sie, dass der Anzeigename durch Einstellungen beeinflusst werden kann, z. B. ob Erweiterungen angezeigt werden.

SHGFI_EXETYPE (0x000002000)

Rufen Sie den Typ der ausführbaren Datei ab, wenn pszPath eine ausführbare Datei identifiziert. Die Informationen werden in den Rückgabewert gepackt. Dieses Flag kann nicht mit anderen Flags angegeben werden.

SHGFI_ICON (0x000000100)

Rufen Sie das Handle zum Symbol ab, das die Datei und den Index des Symbols in der Systembildliste darstellt. Das Handle wird in das hIcon-Element der von psfi angegebenen Struktur kopiert, und der Index wird in das iIcon-Element kopiert.

SHGFI_ICONLOCATION (0x000001000)

Rufen Sie den Namen der Datei ab, die das Symbol enthält, das die von pszPath angegebene Datei darstellt, wie von der IExtractIcon::GetIconLocation-Methode des Symbolhandlers der Datei zurückgegeben wird. Rufen Sie auch den Symbolindex in dieser Datei ab. Der Name der Datei, die das Symbol enthält, wird in das element szDisplayName der von psfi angegebenen Struktur kopiert. Der Index des Symbols wird in das iIcon-Element dieser Struktur kopiert.

SHGFI_LARGEICON (0x000000000)

Ändern Sie SHGFI_ICON, sodass die Funktion das große Symbol der Datei abruft. Das SHGFI_ICON-Flag muss ebenfalls festgelegt werden.

SHGFI_LINKOVERLAY (0x000008000)

Ändern Sie SHGFI_ICON, sodass die Funktion dem Symbol der Datei die Linküberlagerung hinzufügt. Das SHGFI_ICON-Flag muss ebenfalls festgelegt werden.

SHGFI_OPENICON (0x000000002)

Ändern Sie SHGFI_ICON, sodass die Funktion das geöffnete Symbol der Datei abruft. Wird auch verwendet, um SHGFI_SYSICONINDEX zu ändern, wodurch die Funktion das Handle an die Systemimageliste zurückgibt, die das kleine geöffnete Symbol der Datei enthält. Ein Containerobjekt zeigt ein geöffnetes Symbol an, um anzugeben, dass der Container geöffnet ist. Das SHGFI_ICON - und/oder SHGFI_SYSICONINDEX-Flag muss ebenfalls festgelegt werden.

SHGFI_OVERLAYINDEX (0x000000040)

Version 5.0. Gibt den Index des Überlagerungssymbols zurück. Der Wert des Überlagerungsindexes wird in den oberen acht Bits des iIcon-Elements der von psfi angegebenen Struktur zurückgegeben. Dieses Flag erfordert, dass auch die SHGFI_ICON festgelegt werden.

SHGFI_PIDL (0x000000008)

Geben Sie an, dass pszPath die Adresse einer ITEMIDLIST-Struktur und nicht ein Pfadname ist.

SHGFI_SELECTED (0x000010000)

Ändern Sie SHGFI_ICON, sodass die Funktion das Symbol der Datei mit der Systemmarkierungsfarbe verschmilzt. Das SHGFI_ICON-Flag muss ebenfalls festgelegt werden.

SHGFI_SHELLICONSIZE (0x000000004)

Ändern Sie SHGFI_ICON, sodass die Funktion ein Shell-großes Symbol abruft. Wenn dieses Flag nicht angegeben wird, wird das Symbol von der Funktion entsprechend den Systemmetrikwerten groß. Das SHGFI_ICON-Flag muss ebenfalls festgelegt werden.

SHGFI_SMALLICON (0x000000001)

Ändern Sie SHGFI_ICON, sodass die Funktion das kleine Symbol der Datei abruft. Wird auch verwendet, um SHGFI_SYSICONINDEX zu ändern, wodurch die Funktion das Handle an die Systembildliste zurückgibt, die kleine Symbolbilder enthält. Das SHGFI_ICON - und/oder SHGFI_SYSICONINDEX-Flag muss ebenfalls festgelegt werden.

SHGFI_SYSICONINDEX (0x000004000)

Rufen Sie den Index eines Systembildlistensymbols ab. Bei erfolgreicher Ausführung wird der Index in das iIcon-Element von psfi kopiert. Der Rückgabewert ist ein Handle für die Systemimageliste. Nur Bilder, deren Indizes erfolgreich in iIcon kopiert wurden, sind gültig. Der Versuch, auf andere Images in der Systemimageliste zuzugreifen, führt zu einem nicht definierten Verhalten.

SHGFI_TYPENAME (0x000000400)

Rufen Sie die Zeichenfolge ab, die den Dateityp beschreibt. Die Zeichenfolge wird in das szTypeName-Element der in psfi angegebenen Struktur kopiert.

SHGFI_USEFILEATTRIBUTES (0x000000010)

Gibt an, dass die Funktion nicht versuchen sollte, auf die von pszPath angegebene Datei zuzugreifen. Es sollte vielmehr so handeln, als ob die von pszPath angegebene Datei mit den dateiattributen vorhanden ist, die in dwFileAttributes übergeben werden. Dieses Flag kann nicht mit den SHGFI_ATTRIBUTES-, SHGFI_EXETYPE- oder SHGFI_PIDL-Flags kombiniert werden.

Rückgabewert

Typ: DWORD_PTR

Gibt einen Wert zurück, dessen Bedeutung vom uFlags-Parameter abhängt.

Wenn uFlags keine SHGFI_EXETYPE oder SHGFI_SYSICONINDEX enthält, ist der Rückgabewert bei erfolgreicher Ausführung ungleich null, andernfalls null.

Wenn uFlags das flag SHGFI_EXETYPE enthält, gibt der Rückgabewert den Typ der ausführbaren Datei an. Es wird einer der folgenden Werte sein.

Hinweise

Sie sollten diese Funktion aus einem Hintergrundthread aufrufen. Andernfalls reagiert die Benutzeroberfläche möglicherweise nicht mehr.

Wenn SHGetFileInfo ein Symbolhandle im hIcon-Member der SHFILEINFO-Struktur zurückgibt, auf die von psfi verwiesen wird, sind Sie dafür verantwortlich, es mit DestroyIcon frei zu geben, wenn Sie es nicht mehr benötigen.

Wenn Sie das flag SHGFI_EXETYPE mit einer Windows-Anwendung verwenden, wird die Windows-Version der ausführbaren Datei im HIWORD des Rückgabewerts angegeben. Diese Version wird als Hexadezimalwert zurückgegeben. Ausführliche Informationen zum Gleichsetzen dieses Werts mit einer bestimmten Windows-Version finden Sie unter Verwenden der Windows-Header.

Beispiele

Im folgenden Codebeispiel wird SHGetFileInfo verwendet, um den Anzeigenamen des Papierkorbs abzurufen, der durch seine PIDL identifiziert wird.

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);

Anforderungen

Weitere Informationen

FileIconInit