SHGetFileInfoW-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 SHGetFileInfoW(
[in] LPCWSTR pszPath,
DWORD dwFileAttributes,
[in, out] SHFILEINFOW *psfi,
UINT cbFileInfo,
UINT uFlags
);
Parameter
[in] pszPath
Typ: LPCTSTR
Ein Zeiger auf eine null-endende Zeichenfolge mit maximaler Länge MAX_PATH, die den Pfad und 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 fortgesetzt, als ob die Datei mit dem angegebenen Namen und den im dwFileAttributes-Parameter übergebenen Dateiattributen vorhanden wäre. 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 (form 8.3) oder lange Dateinamen verwenden.
dwFileAttributes
Art: DWORD
Eine Kombination aus mindestens einem Dateiattributeflag (FILE_ATTRIBUTE_ Werten, wie in Winnt.h definiert). Wenn uFlags das flag SHGFI_USEFILEATTRIBUTES nicht enthält, wird dieser Parameter ignoriert.
[in, out] psfi
Typ: SHFILEINFO*
Zeiger auf eine SHFILEINFO-Struktur zum Empfangen der Dateiinformationen.
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 flag SHGFI_ICON muss ebenfalls festgelegt werden.
SHGFI_ATTR_SPECIFIED (0x000020000)
Ändern Sie SHGFI_ATTRIBUTES , um anzugeben, dass das dwAttributes-Element der SHFILEINFO-Struktur in psfi die gewünschten spezifischen Attribute enthält. Diese Attribute werden an IShellFolder::GetAttributesOf übergeben. Wenn dieses Flag nicht angegeben ist, wird 0xFFFFFFFF an IShellFolder::GetAttributesOf übergeben und alle Attribute angefordert. Dieses Flag kann nicht mit dem SHGFI_ICON-Flag angegeben werden.
SHGFI_ATTRIBUTES (0x000000800)
Rufen Sie die Elementattribute ab. Die Attribute werden in den dwAttributes-Member der im psfi-Parameter angegebenen Struktur kopiert. Dies sind die gleichen 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 szDisplayName-Element der in psfi angegebenen Struktur kopiert. Der zurückgegebene Anzeigename verwendet den langen Dateinamen, sofern vorhanden, anstelle der 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 für das 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. 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 flag SHGFI_ICON muss ebenfalls festgelegt werden.
SHGFI_LINKOVERLAY (0x000008000)
Ändern Sie SHGFI_ICON, sodass die Funktion die Linküberlagerung zum Symbol der Datei hinzugibt. Das flag SHGFI_ICON 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, sodass 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 flag SHGFI_ICON und/oder SHGFI_SYSICONINDEX 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 durch 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 Systemherhebungsfarbe mischt. Das flag SHGFI_ICON muss ebenfalls festgelegt werden.
SHGFI_SHELLICONSIZE (0x000000004)
Ändern Sie SHGFI_ICON, sodass die Funktion ein Symbol in Shellgröße abruft. Wenn dieses Flag nicht angegeben ist, wird das Symbol von der Funktion entsprechend den Systemmetrikwerten angepasst. Das flag SHGFI_ICON 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, sodass die Funktion das Handle an die Systembildliste zurückgibt, die kleine Symbolbilder enthält. Das flag SHGFI_ICON und/oder SHGFI_SYSICONINDEX 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 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 in psfi angegebenen Struktur kopiert.
SHGFI_USEFILEATTRIBUTES (0x000000010)
Gibt an, dass die Funktion nicht versuchen sollte, auf die von pszPath angegebene Datei zuzugreifen. Stattdessen sollte es so handeln, als ob die von pszPath angegebene Datei mit den in dwFileAttributes übergebenen Dateiattributen vorhanden wäre. Dieses Flag kann nicht mit den flags SHGFI_ATTRIBUTES, SHGFI_EXETYPE oder SHGFI_PIDL 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 nonzero oder 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.
| Rückgabecode | Beschreibung |
|---|---|
|
Nicht ausgeführte Datei oder eine Fehlerbedingung. |
|
Windows-Anwendung. |
|
MS-DOS-.exe- oder .com datei |
|
Konsolenanwendung oder .bat-Datei |
Hinweise
Sie sollten diese Funktion über einen Hintergrundthread aufrufen. Andernfalls reagiert die Benutzeroberfläche 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);
Hinweis
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 nicht codierungsneutralem Code 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 |
|---|---|
| Unterstützte Mindestversion (Client) | Windows XP [nur Desktop-Apps] |
| Unterstützte Mindestversion (Server) | Windows 2000 Server [nur Desktop-Apps] |
| Zielplattform | Windows |
| Kopfzeile | shellapi.h |
| Bibliothek | Shell32.lib |
| DLL | Shell32.dll (Version 4.0 oder höher) |
Weitere Informationen
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für