Fonction SHGetFolderPathW (shlobj_core.h)

Article
03/02/2024

Action déconseillée. Obtient le chemin d’accès d’un dossier identifié par une valeur CSIDL .

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

Syntaxe

SHFOLDERAPI SHGetFolderPathW(
  [in]  HWND   hwnd,
  [in]  int    csidl,
  [in]  HANDLE hToken,
  [in]  DWORD  dwFlags,
  [out] LPWSTR pszPath
);

Paramètres

[in] hwnd

Type : HWND

Réservé.

[in] csidl

Type : int

Valeur CSIDL qui identifie le dossier dont le chemin d’accès doit être récupéré. Seuls les dossiers réels sont valides. Si un dossier virtuel est spécifié, cette fonction échoue. Vous pouvez forcer la création d’un dossier en combinant le CSIDL du dossier avec CSIDL_FLAG_CREATE.

[in] hToken

Type : HANDLE

Jeton d’accès qui peut être utilisé pour représenter un utilisateur particulier.

Microsoft Windows 2000 et versions antérieures : Définissez toujours ce paramètre sur NULL.

Windows XP et versions ultérieures : Ce paramètre est généralement défini sur NULL, mais vous devrez peut-être affecter une valeur non NULL à 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.

Le processus appelant est responsable de l’emprunt d’identité correct lorsque hToken n’a pas la valeur NULL. Le processus d’appel doit disposer des privilèges de sécurité appropriés pour l’utilisateur particulier, notamment TOKEN_QUERY et TOKEN_IMPERSONATE, et la ruche du 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.

L’attribution au paramètre hToken d’une valeur de -1 indique l’utilisateur par défaut. Cela permet aux clients de SHGetFolderPath de rechercher les emplacements des dossiers (tels que le dossier Bureau) pour l’utilisateur par défaut. Le profil utilisateur par défaut est dupliqué lors de la création d’un nouveau compte d’utilisateur et inclut des dossiers spéciaux tels que Mes 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.

[in] dwFlags

Type : DWORD

Indicateurs qui spécifient le chemin d’accès à retourner. Cette valeur est utilisée dans les cas où le dossier associé à un KNOWNFOLDERID (ou CSIDL) peut être déplacé, renommé, redirigé ou itinérant d’une langue à l’autre par un utilisateur ou un administrateur.

Le système de dossiers connus qui sous-tend SHGetFolderPath permet aux utilisateurs ou aux administrateurs de rediriger un dossier connu vers un emplacement adapté à leurs besoins. Pour ce faire, appelez IKnownFolderManager ::Redirect, qui définit la valeur « current » du dossier associé à l’indicateur SHGFP_TYPE_CURRENT.

La valeur par défaut du dossier, qui est l’emplacement du dossier si un utilisateur ou un administrateur ne l’avait pas redirigé ailleurs, est récupérée en spécifiant l’indicateur SHGFP_TYPE_DEFAULT. Cette valeur peut être utilisée pour implémenter une fonctionnalité de « restauration par défaut » pour un dossier connu.

Par exemple, la valeur par défaut (SHGFP_TYPE_DEFAULT) pour FOLDERID_Music (CSIDL_MYMUSIC) est « C :\Users\user name\Music ». Si le dossier a été redirigé, la valeur actuelle (SHGFP_TYPE_CURRENT) peut être « D :\Music ». Si le dossier n’a pas été redirigé, SHGFP_TYPE_DEFAULT et SHGFP_TYPE_CURRENT récupérer le même chemin.

SHGFP_TYPE_CURRENT

Récupérez le chemin d’accès actuel du dossier.

SHGFP_TYPE_DEFAULT

Récupérez le chemin d’accès par défaut du dossier.

[out] pszPath

Type : LPWSTR

Pointeur vers une chaîne terminée par un caractère Null de longueur MAX_PATH qui recevra le chemin d’accès. Si une erreur se produit ou si S_FALSE est retourné, cette chaîne est vide. Le chemin retourné n’inclut pas de barre oblique inverse de fin. Par exemple, « C :\Users » est retourné au lieu de « C :\Users\ ».

Valeur retournée

Type : HRESULT

Si cette fonction réussit, elle retourne S_OK. Sinon, elle retourne un code d’erreur HRESULT.

Remarques

Cette fonction est un sur-ensemble de SHGetSpecialFolderPath.

Seules certaines valeurs CSIDL sont prises en charge, notamment les suivantes :

Exemples

L’exemple de code suivant utilise SHGetFolderPath pour rechercher ou créer un dossier, puis crée un fichier dans celui-ci.

TCHAR szPath[MAX_PATH];

if(SUCCEEDED(SHGetFolderPath(NULL, 
                             CSIDL_PERSONAL|CSIDL_FLAG_CREATE, 
                             NULL, 
                             0, 
                             szPath))) 
{
    PathAppend(szPath, TEXT("New Doc.txt"));
    HANDLE hFile = CreateFile(szPath, ...);
}

Notes

L’en-tête shlobj_core.h définit SHGetFolderPath en tant qu’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. La combinaison 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 2000 Professionnel, Windows XP [applications de bureau uniquement]
Serveur minimal pris en charge	Windows 2000 Server [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 ::GetPath

Partager via