SHGetFolderPathW, fonction (shlobj_core.h)

Article
11/20/2024

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

Remarque à partir de Windows Vista, cette fonction est simplement un wrapper pour SHGetKnownFolderPath. La valeur CSIDL est traduite en son KNOWNFOLDERID associée, puis SHGetKnownFolderPath 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.

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 les CSIDL du dossier avec CSIDL_FLAG_CREATE.

[in] hToken

Type : HANDLE

Un 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 NULL nonà hToken pour ces dossiers pouvant 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’est pasNULL. Le processus appelant doit disposer de 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.

L’affectation du paramètre hToken une valeur de -1 indique l’utilisateur par défaut. Cela permet aux clients de SHGetFolderPath de rechercher des emplacements de dossiers (tels que le dossier De bureau) pour l’utilisateur par défaut. Le profil utilisateur par défaut est dupliqué quand un nouveau compte d’utilisateur est créé 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 à renvoyer. 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 dans plusieurs langues par un utilisateur ou un administrateur.

Le système de dossiers connu 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 « actuelle » 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 de 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\nom d’utilisateur\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 null-terminated de longueur MAX_PATH qui recevra le chemin d’accès. Si une erreur se produit ou S_FALSE est retournée, cette chaîne est vide. Le chemin retourné n’inclut pas de barre oblique inverse de fin. Par exemple, « C :\Users » est retourné plutôt que « C :\Users\ ».

Valeur de retour

Type : HRESULT

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

Remarques

Cette fonction est un super-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, ...);
}

Note

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

Partager via