SHSetKnownFolderPath-Funktion (shlobj_core.h)

Leitet einen bekannten Ordner an einen neuen Speicherort um.

Syntax

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

Die 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 pszPath verweist, durch Umgebungszeichenfolgen wie z %USERPROFILE%. B. 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 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] pszPath

Typ: PCWSTR-

Ein Zeiger auf den neuen Pfad des Ordners. Dies ist eine mit Null beendete Unicode-Zeichenfolge MAX_PATH. Dieser Pfad darf nicht von null Länge sein.

Rückgabewert

Typ: HRESULT-

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

Bemerkungen

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 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.

Anforderungen

Siehe auch

IKnownFolder::GetPath

IKnownFolder::SetPath

IKnownFolderManager::Redirect

Beispiel für bekannte Ordner

SHGetKnownFolderIDList

SHGetKnownFolderPath