SHGetKnownFolderIDList-Funktion (shlobj_core.h)

Artikel
08/26/2023

Ruft den Pfad eines bekannten Ordners als ITEMIDLIST-Struktur ab.

Syntax

HRESULT SHGetKnownFolderIDList(
  [in]  REFKNOWNFOLDERID rfid,
  [in]  DWORD            dwFlags,
  [in]  HANDLE           hToken,
  [out] PIDLIST_ABSOLUTE *ppidl
);

Parameter

[in] rfid

Typ: REFKNOWNFOLDERID

Ein Verweis auf die KNOWNFOLDERID , die den Ordner identifiziert. Die Ordner, die den bekannten Ordner-IDs zugeordnet sind, sind möglicherweise nicht auf einem bestimmten System vorhanden.

[in] dwFlags

Art: DWORD

Flags, die spezielle Abrufoptionen angeben. Dieser Wert kann 0 sein. Andernfalls handelt es sich um einen oder mehrere der KNOWN_FOLDER_FLAG Werte.

[in] hToken

Typ: HANDLE

Ein Zugriffstoken , das verwendet wird, um einen bestimmten Benutzer darzustellen. Dieser Parameter wird normalerweise 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 nicht 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 Zugriffssteuerungsproblemen finden Sie unter Access Control.

Das Zuweisen des hToken-Parameters mit dem Wert -1 gibt den Standardbenutzer an. Dadurch können Clients von SHGetKnownFolderIDList Ordnerspeicherorte (z. B. den Desktopordner ) für den Standardbenutzer suchen. Das Standardbenutzerprofil 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 wurden, werden auch in jedem neuen Benutzerkonto angezeigt. Beachten Sie, dass für den Zugriff auf die Standardbenutzerordner Administratorrechte erforderlich sind.

[out] ppidl

Typ: PIDLIST_ABSOLUTE*

Wenn diese Methode zurückgibt, enthält einen Zeiger auf die PIDL des Ordners. Dieser Parameter wird nicht initialisiert übergeben. Der Aufrufer ist dafür verantwortlich, die zurückgegebene PIDL freizugeben, wenn sie nicht mehr benötigt wird, indem er ILFree aufruft.

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 im System nicht 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

Diese Funktion ersetzt SHGetFolderLocation. Diese ältere Funktion ist jetzt einfach ein Wrapper für SHGetKnownFolderIDList.

Aufrufer, die diese Funktion verwenden, müssen mindestens Über Benutzerberechtigungen verfügen.

Einige bekannte Ordner, z. B. der Ordner Dokumente , sind benutzerbezogen. Jeder Benutzer hat einen anderen Pfad für den Ordner Dokumente . Wenn hTokenNULL ist, versucht die API, auf die instance des aktuellen Benutzers des Ordners zuzugreifen. 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 des Ordners dieses Benutzers zuzugreifen.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows Vista [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	shlobj_core.h (einschließlich Shlobj.h)
Bibliothek	Shell32.lib
DLL	Shell32.dll (Version 6.0.6000 oder höher)

Weitere Informationen

IKnownFolder::GetPath

Bekannte Ordner (Beispiel)

SHGetKnownFolderPath

SHSetKnownFolderPath

Share via