Fonction SHSetFolderPathA (shlobj_core.h)

  • Article

Action déconseillée. Attribue un nouveau chemin d’accès à un dossier système identifié par son CSIDL.

Syntaxe

HRESULT SHSetFolderPathA(
  [in] int    csidl,
  [in] HANDLE hToken,
  [in] DWORD  dwFlags,
  [in] LPCSTR pszPath
);

Paramètres

[in] csidl

Type : int

Valeur CSIDL qui identifie le dossier dont le chemin 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, des parties du chemin d’accès peuvent être remplacées par des chaînes d’environnement, telles que %USERPROFILE.

[in] hToken

Type : HANDLE

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 à la instance de l’utilisateur actuel du dossier. Toutefois, vous devrez peut-être affecter une valeur à hToken pour les 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é correcte 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. Consultez Access Control pour plus d’informations sur les problèmes de contrôle d’accès.

[in] dwFlags

Type : DWORD

Réservé. Doit avoir la valeur 0.

[in] pszPath

Type : LPCTSTR

Pointeur vers une chaîne null de longueur 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 retournée

Type : HRESULT

Retourne les codes HRESULT standard, y compris les suivants :

Code de retour 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 les suivantes :
  • 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 vers la valeur pszPath est une chaîne vide («  ») de longueur zéro.

Remarques

Note À partir de Windows Vista, cette fonction est simplement un wrapper pour SHSetKnownFolderPath. La valeur CSIDL est traduite en la valeur KNOWNFOLDERID associée 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.

Notes

L’en-tête shlobj_core.h définit SHSetFolderPath comme un 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.

Configuration requise

Condition requise Valeur
Client minimal pris en charge Windows XP [applications de bureau uniquement]
Serveur minimal pris en charge Windows Server 2003 [applications de bureau uniquement]
Plateforme cible Windows
En-tête shlobj_core.h (inclure Shlobj.h, Shlobj_core.h)
Bibliothèque Shell32.lib
DLL Shell32.dll (version 5.0 ou ultérieure)

Voir aussi

IKnownFolder ::SetPath