SHGetKnownFolderItem-Funktion (shlobj_core.h)

Ruft ein IShellItem - Objekt, 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 ein oder mehrere der KNOWN_FOLDER_FLAG Werte.

[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 Instanz des aktuellen Benutzers des Ordners zuzugreifen. Möglicherweise müssen Sie jedoch dem hToken einen Wert für diese Ordner zuweisen, die mehrere Benutzer haben können, aber als Zugehörigkeit zu einem einzelnen Benutzer 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. Sie muss über geeignete Sicherheitsberechtigungen für den jeweiligen Benutzer verfügen, einschließlich TOKEN_QUERY und TOKEN_IMPERSONATE, und die Registrierungsstruktur des Benutzers muss zurzeit bereitgestellt werden. Weitere Informationen zu Problemen mit der Zugriffssteuerung finden Sie unter "Zugriffssteuerung ".

Wenn Sie den hToken-Parameter einem Wert von -1 zuweisen, wird der Standardbenutzer angegeben. Dadurch können Clients von SHSetKnownFolderPath Ordnerspeicherorte (z. B. den Desktopordner ) für den Standardbenutzer festlegen. Das Benutzerprofil des Standardbenutzers wird dupliziert, wenn ein neues Benutzerkonto erstellt wird, und enthält spezielle Ordner wie Dokumente und Desktop. Alle Elemente, die dem Standardbenutzerordner hinzugefügt werden, werden auch in einem 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ückgegeben wird, enthält sie den in riid angeforderten Schnittstellenzeiger.

Rückgabewert

Typ: HRESULT-

Gibt S_OK zurück, wenn dies erfolgreich ist, oder einen anderen Fehlerwert, einschließlich der folgenden:

Bemerkungen

Um diese Funktion in öffentlichen bekannten Ordnern aufzurufen, muss der Aufrufer über Administratorrechte verfügen. Für bekannte Ordner pro Benutzer erfordert der Aufrufer nur Benutzerberechtigungen.

Einige der bekannten Ordner, z. B. der Ordner "Dokumente ", sind pro Benutzer. Jeder Benutzer hat einen anderen Pfad für den Ordner "Dokumente ". Wenn hTokenNULL ist, versucht die API, auf die Instanz der aufrufenden Anwendung des Ordners zuzugreifen, d. h. der des aktuellen Benutzers. Wenn hToken ein gültiges Benutzertoken ist, versucht die API, den Benutzer mit diesem Token zu imitieren und versucht, auf die Instanz 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.

Requirements

Siehe auch

IKnownFolder::GetPath

IKnownFolderManager::Redirect

Beispiel für bekannte Ordner

SHCreateItemInKnownFolder

SHGetKnownFolderIDList

SHGetKnownFolderPath