SHSetFolderPathW, fonction (shlobj_core.h)

Article
11/20/2024

Obsolescent. Affecte un nouveau chemin d’accès à un dossier système identifié par son CSIDL.

Syntaxe

HRESULT SHSetFolderPathW(
  [in] int     csidl,
  [in] HANDLE  hToken,
  [in] DWORD   dwFlags,
  [in] LPCWSTR pszPath
);

Paramètres

[in] csidl

Type : int

Valeur CSIDL qui identifie le dossier dont le chemin d’accès doit être défini. Seuls les dossiers physiques sont valides. Si un dossier virtuel est spécifié, cette fonction échoue.

Ajoutez la valeur CSIDL_FLAG_DONT_UNEXPAND au CSIDL pour vous assurer que la chaîne est écrite dans le Registre exactement comme indiqué. Si l’indicateur CSIDL_FLAG_DONT_UNEXPAND n’est pas inclus, les parties du chemin d’accès peuvent être remplacées par des chaînes d’environnement, telles que %USERPROFILE%.

[in] hToken

Type : HANDLE

Un jeton d’accès qui peut être 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’a pas la valeur 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 de contrôle d’accès.

[in] dwFlags

Type : DWORD

Réservé. Doit être défini sur 0.

[in] pszPath

Type : LPCTSTR

Pointeur vers une chaîne de longueur null MAX_PATH qui contient le nouveau chemin d’accès du dossier. Cette valeur ne peut pas être NULL et la chaîne ne peut pas être de longueur nulle.

Valeur de retour

Type : HRESULT

Retourne des codes HRESULT standard , notamment les suivants :

Retourner le code	Description
S_OK	Le chemin d’accès du dossier a été correctement mis à jour.
E_INVALIDARG	Plusieurs conditions d’erreur provoquent le retour de cette valeur, notamment : La valeur csidl n’est pas valide. La valeur csidl ne fait pas référence à un dossier virtuel. La valeur csidl ne fait pas référence à un dossier système. La valeur csidl fait référence à un dossier qui ne peut pas être renommé ou déplacé. La valeur dwFlags n’est pas 0 (zéro). La valeur pszPath est NULL. La chaîne pointée par valeur pszPath est une chaîne vide (« ») de longueur zéro.

Retourner le code

Description

S_OK

Le chemin d’accès du dossier a été correctement mis à jour.

E_INVALIDARG

Plusieurs conditions d’erreur provoquent le retour de cette valeur, notamment :

La valeur csidl n’est pas valide.
La valeur csidl ne fait pas référence à un dossier virtuel.
La valeur csidl ne fait pas référence à un dossier système.
La valeur csidl fait référence à un dossier qui ne peut pas être renommé ou déplacé.
La valeur dwFlags n’est pas 0 (zéro).
La valeur pszPath est NULL.
La chaîne pointée par valeur pszPath est une chaîne vide (« ») de longueur zéro.

Remarques

Remarque à partir de Windows Vista, cette fonction est simplement un wrapper pour SHSetKnownFolderPath. La valeur CSIDL est traduite en son KNOWNFOLDERID associé et SHSetKnownFolderPath est appelée. Les nouvelles applications doivent utiliser le système de dossiers connu plutôt que l’ancien système CSIDL, qui est pris en charge uniquement pour la compatibilité descendante.

SHSetFolderPath n’est pas exporté par nom à partir de Shell32.dll. Pour utiliser la fonction, vous devez appeler GetProcAddress avec ordinal 231 pour SHSetFolderPathA (pour les chaînes ANSI) ou ordinal 232 pour SHSetFolderPathW (pour les chaînes Unicode) pour obtenir un pointeur de fonction.

Il est recommandé d’exprimer les chemins sous forme de chaînes Unicode, car les noms de dossiers peuvent contenir des caractères Unicode non expressibles dans ANSI.

Note

L’en-tête shlobj_core.h définit SHSetFolderPath comme alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. Le mélange de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.

Exigences

Exigence	Valeur
client minimum pris en charge	Windows XP [applications de bureau uniquement]
serveur minimum pris en charge	Windows Server 2003 [applications de bureau uniquement]
plateforme cible	Windows
d’en-tête	shlobj_core.h (include Shlobj.h, Shlobj_core.h)
bibliothèque	Shell32.lib
DLL	Shell32.dll (version 5.0 ou ultérieure)

Voir aussi

IKnownFolder ::SetPath

Partager via