SHSetKnownFolderPath, fonction (shlobj_core.h)

Redirige un dossier connu vers un nouvel emplacement.

Syntaxe

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

Paramètres

[in] rfid

Type : REFKNOWNFOLDERID

GUID qui identifie le dossier connu.

[in] dwFlags

Type : DWORD

0 ou la valeur suivante.

KF_FLAG_DONT_UNEXPAND

Si cet indicateur est défini, les parties du chemin référencé par pszPath peuvent être représentées par des chaînes d’environnement telles que %USERPROFILE%.

[in] hToken

Type : HANDLE

Jeton d’accès utilisé pour représenter un utilisateur particulier. Ce paramètre est généralement défini sur NULL, auquel cas la fonction tente d’accéder à l’instance de l’utilisateur actuel du dossier. Toutefois, vous devrez peut-être affecter une valeur à hToken pour ces dossiers qui peuvent avoir plusieurs utilisateurs, mais qui sont traités comme appartenant à un seul utilisateur. Le dossier le plus couramment utilisé de ce type est Documents.

L’application appelante est responsable de l’emprunt d’identité correct lorsque hToken n’est pas null. Il doit disposer des privilèges de sécurité appropriés pour l’utilisateur particulier, notamment TOKEN_QUERY et TOKEN_IMPERSONATE, et la ruche de Registre de l’utilisateur doit être actuellement montée. Pour plus d’informations sur les problèmes de contrôle d’accès, consultez Contrôle d’accès.

L’affectation du paramètre hToken à une valeur de -1 indique l’utilisateur par défaut. Cela permet aux clients de SHSetKnownFolderPath de définir des emplacements de dossier (tels que le dossier Desktop ) pour l’utilisateur par défaut. Le profil utilisateur par défaut est dupliqué lorsque tout nouveau compte d’utilisateur est créé et inclut des dossiers spéciaux tels que Documents et Bureau. Tous les éléments ajoutés au dossier Utilisateur par défaut apparaissent également dans n’importe quel nouveau compte d’utilisateur. Notez que l’accès aux dossiers utilisateur par défaut nécessite des privilèges d’administrateur.

[in] pszPath

Type : PCWSTR

Pointeur vers le nouveau chemin d’accès du dossier. Il s’agit d’une chaîne Unicode terminée par null MAX_PATH. Ce chemin d’accès ne peut pas être de longueur nulle.

Valeur retournée

Type : HRESULT

Retourne S_OK si elle réussit ou une valeur d’erreur sinon, y compris les éléments suivants :

Remarques

Cette fonction remplace SHSetFolderPath. Cette fonction plus ancienne est désormais simplement un wrapper pour SHSetKnownFolderPath.

L’appelant de cette fonction doit disposer de privilèges d’administrateur. Pour appeler cette fonction sur des dossiers connus publics, l’appelant doit disposer de privilèges d’administrateur. Pour les dossiers connus par utilisateur, l’appelant requiert uniquement des privilèges utilisateur.

Certains des dossiers connus, par exemple, le dossier Documents , sont par utilisateur. Chaque utilisateur a un chemin différent pour son dossier Documents . Si hToken a la valeur NULL, l’API tente d’accéder à l’instance de l’application appelante du dossier, qui est celle de l’utilisateur actuel. Si hToken est un jeton d’utilisateur valide, l’API tente d’emprunter l’identité de l’utilisateur à l’aide de ce jeton et tente d’accéder à l’instance de cet utilisateur.

Cette fonction ne peut pas être appelée sur des dossiers de type KF_CATEGORY_FIXED et KF_CATEGORY_VIRTUAL.

Pour appeler cette fonction sur un dossier de type KF_CATEGORY_COMMON, l’application appelante doit s’exécuter avec des privilèges élevés.

Spécifications

Voir aussi

IKnownFolder ::GetPath

IKnownFolder ::SetPath

IKnownFolderManager ::Redirect

Exemple de dossiers connus

SHGetKnownFolderIDList

SHGetKnownFolderPath