SHGetKnownFolderItem-Funktion (shlobj_core.h)

Artikel
03/04/2024

Ruft ein IShellItem-Objekt ab, das einen bekannten Ordner darstellt.

Syntax

HRESULT SHGetKnownFolderItem(
  [in]  REFKNOWNFOLDERID  rfid,
  [in]  KNOWN_FOLDER_FLAG flags,
  [in]  HANDLE            hToken,
  [in]  REFIID            riid,
  [out] void              **ppv
);

Parameter

[in] rfid

Typ: REFKNOWNFOLDERID

Ein Verweis auf die KNOWNFOLDERID, eine GUID , die den Ordner identifiziert, der das Element enthält.

[in] flags

Typ: KNOWN_FOLDER_FLAG

Flags, die spezielle Optionen angeben, die beim Abrufen des bekannten Ordners IShellItem verwendet werden. Dieser Wert kann KF_FLAG_DEFAULT werden. Andernfalls wird mindestens ein wert der KNOWN_FOLDER_FLAG .

[in] hToken

Typ: HANDLE

Ein Zugriffstoken , das verwendet wird, um einen bestimmten Benutzer darzustellen. Dieser Parameter wird in der Regel auf NULL festgelegt. In diesem Fall versucht die Funktion, auf die instance des aktuellen Benutzers des Ordners zuzugreifen. Möglicherweise müssen Sie hToken jedoch einen Wert für die Ordner zuweisen, die mehrere Benutzer haben können, aber als zu einem einzelnen Benutzer gehören behandelt werden. Der am häufigsten verwendete Ordner dieses Typs ist Dokumente.

Die aufrufende Anwendung ist für den korrekten Identitätswechsel verantwortlich, wenn hToken ungleich NULL ist. Es muss über geeignete Sicherheitsberechtigungen für den jeweiligen Benutzer verfügen, einschließlich TOKEN_QUERY und TOKEN_IMPERSONATE, und die Registrierungsstruktur des Benutzers muss derzeit eingebunden sein. Weitere Informationen zu Problemen mit der Zugriffssteuerung finden Sie unter Access Control.

Wenn Sie dem hToken-Parameter den Wert -1 zuweisen, wird der Standardbenutzer angegeben. Dadurch können Clients von SHSetKnownFolderPath Ordnerspeicherorte (z. B. den Desktopordner ) für den Standardbenutzer festlegen. Das Benutzerprofil Standardbenutzer wird dupliziert, wenn ein neues Benutzerkonto erstellt wird, und enthält spezielle Ordner wie Dokumente und Desktop. Alle Elemente, die dem Ordner Standardbenutzer hinzugefügt werden, werden auch in jedem neuen Benutzerkonto angezeigt. Beachten Sie, dass für den Zugriff auf die Standardbenutzerordner Administratorrechte erforderlich sind.

[in] riid

Typ: REFIID

Ein Verweis auf die IID der Schnittstelle, die das Element darstellt, in der Regel IID_IShellItem oder IID_IShellItem2.

[out] ppv

Typ: void**

Wenn diese Methode zurückgibt, enthält den in riid angeforderten Schnittstellenzeiger.

Rückgabewert

Typ: HRESULT

Gibt bei erfolgreicher Ausführung S_OK oder andernfalls einen Fehlerwert zurück, einschließlich der folgenden:

Rückgabecode	Beschreibung
E_INVALIDARG	Dieser Wert kann unter anderem angeben, dass der rfid-Parameter auf eine KNOWNFOLDERID verweist, die nicht im System vorhanden ist. Nicht alle KNOWNFOLDERID-Werte sind auf allen Systemen vorhanden. Verwenden Sie IKnownFolderManager::GetFolderIds , um den Satz von KNOWNFOLDERID-Werten für das aktuelle System abzurufen.

Hinweise

Der Aufrufer dieser Funktion muss über Administratorrechte verfügen. Um diese Funktion in öffentlichen bekannten Ordnern aufzurufen, muss der Aufrufer über Administratorrechte verfügen. Für benutzerspezifische bekannte Ordner benötigt der Aufrufer nur Benutzerberechtigungen.

Einige der bekannten Ordner, z. B. der Ordner "Dokumente" , sind benutzerbezogen. Jeder Benutzer verfügt über einen anderen Pfad für seinen Ordner "Dokumente" . Wenn hTokenNULL ist, versucht die API, auf die instance des Ordners der aufrufenden Anwendung zuzugreifen, d. hToken ist der des aktuellen Benutzers. Wenn hToken ein gültiges Benutzertoken ist, versucht die API, die Identität des Benutzers mit diesem Token zu annehmen, und versucht, auf die instance dieses Benutzers zuzugreifen.

Diese Funktion kann nicht für Ordner vom Typ KF_CATEGORY_FIXED und KF_CATEGORY_VIRTUAL aufgerufen werden.

Um diese Funktion in einem Ordner vom Typ KF_CATEGORY_COMMON aufzurufen, muss die aufrufende Anwendung mit erhöhten Rechten ausgeführt werden.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 7 [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 R2 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	shlobj_core.h (shlobj.h einschließen)
Bibliothek	Shell32.lib
DLL	Shell32.dll (Version 6.1 oder höher)
APIs	ext-ms-win-shell-shell32-l1-2-1 (eingeführt in Windows 10, Version 10.0.10240)