SHSetKnownFolderPath-Funktion (shlobj_core.h)

Artikel
08/26/2023

Leitet einen bekannten Ordner an einen neuen Speicherort um.

Syntax

HRESULT SHSetKnownFolderPath(
  [in] REFKNOWNFOLDERID rfid,
  [in] DWORD            dwFlags,
  [in] HANDLE           hToken,
  [in] PCWSTR           pszPath
);

Parameter

[in] rfid

Typ: REFKNOWNFOLDERID

Eine GUID , die den bekannten Ordner identifiziert.

[in] dwFlags

Art: DWORD

Entweder 0 oder der folgende Wert.

KF_FLAG_DONT_UNEXPAND

Wenn dieses Flag festgelegt ist, können Teile des Pfads, auf den von pszPath verwiesen wird, durch Umgebungszeichenfolgen wie %USERPROFILE%dargestellt werden.

[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] pszPath

Typ: PCWSTR

Ein Zeiger auf den neuen Pfad des Ordners. Dies ist eine unicode-Zeichenfolge mit Null-Endung der Länge MAX_PATH. Dieser Pfad darf nicht 0 (null) sein.

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

Diese Funktion ersetzt SHSetFolderPath. Diese ältere Funktion ist jetzt einfach ein Wrapper für SHSetKnownFolderPath.

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 Vista [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	shlobj_core.h (shlobj.h einschließen)
DLL	Shell32.dll (Version 6.0.6000 oder höher)