Fonction SHGetFolderLocation (shlobj_core.h)

Article
08/26/2023

Action déconseillée. Récupère le chemin d’accès d’un dossier en tant que structure ITEMIDLIST .

Syntaxe

SHSTDAPI SHGetFolderLocation(
  [in]  HWND             hwnd,
  [in]  int              csidl,
  [in]  HANDLE           hToken,
  [in]  DWORD            dwFlags,
  [out] PIDLIST_ABSOLUTE *ppidl
);

Paramètres

[in] hwnd

Type : HWND

Réservé.

[in] csidl

Type : int

Valeur CSIDL qui identifie le dossier à localiser. Les dossiers associés aux CSIDL peuvent ne pas exister sur un système particulier.

[in] hToken

Type : HANDLE

Jeton d’accès qui peut être utilisé pour représenter un utilisateur particulier. Il est généralement défini sur NULL, mais il peut être nécessaire lorsqu’il y a plusieurs utilisateurs pour ces dossiers qui sont traités comme appartenant à un seul utilisateur. Le dossier le plus couramment utilisé de ce type est Mes 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, 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.

L’attribution au paramètre hToken d’une valeur de -1 indique l’utilisateur par défaut. Cela permet aux clients de SHGetFolderLocation de rechercher des emplacements de dossiers (tels que le dossier Desktop) 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

[out] ppidl

Type : PIDLIST_ABSOLUTE*

Adresse d’un pointeur vers une structure de liste d’identificateurs d’élément qui spécifie l’emplacement du dossier par rapport à la racine de l’espace de noms (le bureau). Le paramètre ppidl est défini sur NULL en cas d’échec. L’application appelante est chargée de libérer cette ressource en appelant ILFree.

Valeur retournée

Type : HRESULT

Retourne S_OK en cas de réussite, ou une valeur d’erreur dans le cas contraire, y compris les éléments suivants :

Code de retour	Description
HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND)	Le CSIDL dans nFolder est valide, mais le dossier n’existe pas.
E_INVALIDARG	Le CSIDL dans nFolder n’est pas valide.

Remarques

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

Les fonctions SHGetFolderLocation, SHGetFolderPath, SHGetSpecialFolderLocation et SHGetSpecialFolderPath sont les méthodes recommandées pour obtenir des handles dans des dossiers sur des systèmes antérieurs à Windows Vista. Les fonctions telles que ExpandEnvironmentStrings qui utilisent directement les noms de variables d’environnement, sous la forme %VariableName%, peuvent ne pas être fiables.

Cette fonction est un sur-ensemble de SHGetSpecialFolderLocation, inclus avec les versions antérieures de l’interpréteur de commandes.

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 Server 2003 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	shlobj_core.h (inclure Shlobj.h)
Bibliothèque	Shell32.lib
DLL	Shell32.dll (version 5.0 ou ultérieure)

Voir aussi

IKnownFolder ::GetIDList