Fonction SHGetFolderLocation (shlobj_core.h)

Article
03/15/2023

Action déconseillée. Récupère le chemin 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 existe plusieurs utilisateurs pour ces dossiers 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’est pas NULL. Il doit disposer de privilèges de sécurité appropriés pour l’utilisateur particulier, et la ruche de Registre de l’utilisateur doit être actuellement monté. Pour plus d’informations sur les problèmes de contrôle d’accès, consultez Access Control.

L’affectation du paramètre hToken à une valeur de -1 indique l’utilisateur par défaut. Cela permet aux clients de SHGetFolderLocation de rechercher des emplacements de dossier (tels que le dossier Bureau) pour l’utilisateur par défaut. Le profil utilisateur par défaut est dupliqué lorsque tout 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

[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 (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 si elle réussit ou une valeur d’erreur sinon, 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.

Notes

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

Les fonctions SHGetFolderLocation, SHGetFolderPath, SHGetSpecialFolderLocation et SHGetSpecialFolderPath sont les moyens préférés d’obtenir des handles sur 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 super ensemble de SHGetSpecialFolderLocation, inclus avec les versions antérieures de l’interpréteur de commandes.

Configuration requise


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