Fonction SHGetKnownFolderIDList (shlobj_core.h)

  • Article

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

Syntaxe

HRESULT SHGetKnownFolderIDList(
  [in]  REFKNOWNFOLDERID rfid,
  [in]  DWORD            dwFlags,
  [in]  HANDLE           hToken,
  [out] PIDLIST_ABSOLUTE *ppidl
);

Paramètres

[in] rfid

Type : REFKNOWNFOLDERID

Référence au KNOWNFOLDERID qui identifie le dossier. Les dossiers associés aux ID de dossier connus peuvent ne pas exister sur un système particulier.

[in] dwFlags

Type : DWORD

Indicateurs qui spécifient des options de récupération spéciales. Cette valeur peut être 0 ; sinon, il s’agit d’une ou plusieurs des valeurs KNOWN_FOLDER_FLAG .

[in] hToken

Type : HANDLE

Jeton d’accès 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é correct 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.

L’attribution au paramètre hToken d’une valeur de -1 indique l’utilisateur par défaut. Cela permet aux clients de SHGetKnownFolderIDList 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 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. Notez que l’accès aux dossiers Utilisateur par défaut nécessite des privilèges d’administrateur.

[out] ppidl

Type : PIDLIST_ABSOLUTE*

Lorsque cette méthode est retournée, contient un pointeur vers le PIDL du dossier. Ce paramètre est passé sans être initialisé. L’appelant est chargé de libérer le PIDL retourné quand il n’est plus nécessaire 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
E_INVALIDARG
 Entre autres choses, cette valeur peut indiquer que le paramètre rfid fait référence à un KNOWNFOLDERID qui n’est pas présent sur le système. Toutes les valeurs KNOWNFOLDERID ne sont pas présentes sur tous les systèmes. Utilisez IKnownFolderManager ::GetFolderIds pour récupérer l’ensemble des valeurs KNOWNFOLDERID pour le système actuel.

Remarques

Cette fonction remplace SHGetFolderLocation. Cette fonction plus ancienne est désormais simplement un wrapper pour SHGetKnownFolderIDList.

Les appelants qui utilisent cette fonction doivent avoir au moins des privilèges Utilisateur.

Certains dossiers connus, par exemple le dossier Documents , sont par utilisateur. Chaque utilisateur a un chemin d’accès différent pour le dossier Documents . Si hToken a la valeur NULL, l’API tente d’accéder à la instance de l’utilisateur actuel du dossier. Si hToken est un jeton utilisateur valide, l’API tente d’emprunter l’identité de l’utilisateur à l’aide de ce jeton et tente d’accéder à la instance de cet utilisateur du dossier.

Configuration requise

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

Voir aussi

IKnownFolder ::GetPath

Dossiers connus, exemple

SHGetKnownFolderPath

SHSetKnownFolderPath