SHGetFileInfoA-Funktion (shellapi.h)
Ruft Informationen zu einem Objekt im Dateisystem ab, z. B. eine Datei, einen Ordner, ein Verzeichnis oder einen 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-terminated string of maximum length MAX_PATH that contains the path and file name. 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- (PIDL)-Struktur 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 fortgesetzt, als ob die Datei mit dem angegebenen Namen und mit den Dateiattributen vorhanden ist, die im dwFileAttributes Parameter übergeben werden. Auf diese Weise 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
Typ: DWORD-
Eine Kombination aus einem oder mehreren Datei-Attributkennzeichnungen (FILE_ATTRIBUTE_ Werte, wie in Winnt.h definiert). Wenn uFlags- das SHGFI_USEFILEATTRIBUTES Flag nicht enthält, wird dieser Parameter ignoriert.
[in, out] psfi
Typ: SHFILEINFO-*
Zeigen Sie 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. Dieser Parameter kann eine Kombination aus den folgenden Werten sein.
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 so, dass das dwAttributes Mitglied der SHFILEINFO- Struktur bei psfi- die gewünschten Attribute enthält. Diese Attribute werden an IShellFolder::GetAttributesOfübergeben. Wenn dieses Flag nicht angegeben ist, wird 0xFFFFFFFF an IShellFolder::GetAttributesOfübergeben, wobei alle Attribute angefordert werden. Dieses Flag kann nicht mit dem SHGFI_ICON Flag angegeben werden.
SHGFI_ATTRIBUTES (0x000000800)
Dient zum Abrufen der Elementattribute. Die Attribute werden in das dwAttributes Element der struktur kopiert, die im psfi Parameter angegeben ist. Dies sind die gleichen Attribute, die von IShellFolder::GetAttributesOfabgerufen werden.
SHGFI_DISPLAYNAME (0x000000200)
Rufen Sie den Anzeigenamen für die Datei ab, bei dem es sich um den Namen handelt, der im Windows-Explorer angezeigt wird. Der Name wird in das szDisplayName Element der struktur kopiert, die in psfiangegeben ist. Der zurückgegebene Anzeigename verwendet den langen Dateinamen, falls vorhanden, anstelle des 8.3-Formulars des Dateinamens. Beachten Sie, dass der Anzeigename von Einstellungen betroffen sein 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 verpackt. Dieses Kennzeichen 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 struktur kopiert, die durch psfiangegeben wird, 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 pszPathangegebene Datei darstellt, wie sie 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 szDisplayName Element der struktur kopiert, die durch psfiangegeben wird. Der Index des Symbols wird in das iIcon-Element dieser Struktur kopiert.
SHGFI_LARGEICON (0x000000000)
Ändern Sie SHGFI_ICON, wodurch die Funktion das große Symbol der Datei abruft. Das SHGFI_ICON Flag muss ebenfalls festgelegt werden.
SHGFI_LINKOVERLAY (0x000008000)
Ändern Sie SHGFI_ICON, wodurch die Funktion die Verknüpfungsüberlagerung zum Symbol der Datei hinzufügen kann. Das SHGFI_ICON Flag muss ebenfalls festgelegt werden.
SHGFI_OPENICON (0x000000002)
Ändern Sie SHGFI_ICON, wodurch die Funktion das Geöffnete Symbol der Datei abruft. Wird auch verwendet, um SHGFI_SYSICONINDEXzu ändern, wodurch die Funktion das Handle an die Systembildliste 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 Overlaysymbols zurück. Der Wert des Überlagerungsindex wird in den oberen acht Bits des iIcon Member der struktur zurückgegeben, die durch psfiangegeben wird. Für dieses Flag muss auch die SHGFI_ICON festgelegt werden.
SHGFI_PIDL (0x000000008)
Geben Sie an, dass pszPath- die Adresse einer ITEMIDLIST- Struktur anstelle eines Pfadnamens ist.
SHGFI_SELECTED (0x000010000)
Ändern Sie SHGFI_ICON, sodass die Funktion das Symbol der Datei mit der Systemmarkierungsfarbe vermischt. Das SHGFI_ICON Flag muss ebenfalls festgelegt werden.
SHGFI_SHELLICONSIZE (0x000000004)
Ändern Sie SHGFI_ICON, wodurch die Funktion ein Shell-Symbol abruft. Wenn dieses Kennzeichen nicht angegeben ist, wird die Größe des Symbols entsprechend den Systemmetrikwerten angegeben. Das SHGFI_ICON Flag muss ebenfalls festgelegt werden.
SHGFI_SMALLICON (0x000000001)
Ändern Sie SHGFI_ICON, wodurch die Funktion das kleine Symbol der Datei abruft. Wird auch verwendet, um SHGFI_SYSICONINDEXzu ä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)
Dient zum Abrufen des Indexes eines Systembildlistensymbols. Bei erfolgreicher Ausführung wird der Index in das iIcon Member von psfikopiert. Der Rückgabewert ist ein Handle für die Systemimageliste. Nur die Bilder, deren Indizes erfolgreich in iIcon kopiert werden, sind gültig. Der Versuch, auf andere Bilder in der Systembildliste 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 struktur kopiert, die in psfiangegeben ist.
SHGFI_USEFILEATTRIBUTES (0x000000010)
Gibt an, dass die Funktion nicht versuchen soll, auf die durch pszPathangegebene Datei zuzugreifen. Stattdessen sollte sie so handeln, als ob die durch pszPath angegebene Datei mit den in dwFileAttributesübergebenen Dateiattributen vorhanden ist. Diese Kennzeichnung kann nicht mit dem SHGFI_ATTRIBUTES, SHGFI_EXETYPEoder SHGFI_PIDL Flags kombiniert werden.
Rückgabewert
Typ: DWORD_PTR
Gibt einen Wert zurück, dessen Bedeutung vom uFlags-Parameter abhängt.
Wenn uFlags- nicht SHGFI_EXETYPE oder SHGFI_SYSICONINDEXenthält, ist der Rückgabewert bei erfolgreicher Ausführung oder null ungleich Null.
Wenn uFlags- das SHGFI_EXETYPE Flag enthält, gibt der Rückgabewert den Typ der ausführbaren Datei an. Dies ist einer der folgenden Werte.
| Rückgabecode | Beschreibung |
|---|---|
|
Nicht ausführbare Datei oder eine Fehlerbedingung. |
|
Windows-Anwendung. |
|
MS-DOS .exe- oder .com datei |
|
Konsolenanwendung oder .bat Datei |
Bemerkungen
Sie sollten diese Funktion aus einem Hintergrundthread aufrufen. Dies kann dazu führen, dass die Benutzeroberfläche nicht mehr reagiert.
Wenn SHGetFileInfo einen Symbolpunkt im hIcon Member der SHFILEINFO Struktur zurückgibt, auf die psfiverweist, sind Sie dafür verantwortlich, es mit DestroyIcon freizusetzen, wenn Sie es nicht mehr benötigen.
Wenn Sie das SHGFI_EXETYPE-Flag 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 die 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);
Anmerkung
Der shellapi.h-Header definiert SHGetFileInfo als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.
Anforderungen
| Anforderung | Wert |
|---|---|
| mindestens unterstützte Client- | Windows XP [nur Desktop-Apps] |
| mindestens unterstützte Server- | Windows 2000 Server [nur Desktop-Apps] |
| Zielplattform- | Fenster |
| Header- | shellapi.h |
| Library | Shell32.lib |
| DLL- | Shell32.dll (Version 4.0 oder höher) |