Fonction SHGetKnownFolderItem (shlobj_core.h)

Article
03/02/2024

Récupère un objet IShellItem qui représente un dossier connu.

Syntaxe

HRESULT SHGetKnownFolderItem(
  [in]  REFKNOWNFOLDERID  rfid,
  [in]  KNOWN_FOLDER_FLAG flags,
  [in]  HANDLE            hToken,
  [in]  REFIID            riid,
  [out] void              **ppv
);

Paramètres

[in] rfid

Type : REFKNOWNFOLDERID

Référence au KNOWNFOLDERID, un GUID qui identifie le dossier qui contient l’élément.

[in] flags

Type : KNOWN_FOLDER_FLAG

Indicateurs qui spécifient des options spéciales utilisées dans la récupération du dossier connu IShellItem. Cette valeur peut être KF_FLAG_DEFAULT ; sinon, 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é correcte 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 SHSetKnownFolderPath de définir des emplacements de dossiers (tels que le dossier Desktop ) pour l’utilisateur par défaut. Le profil utilisateur 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 s’affichent également dans tout nouveau compte d’utilisateur. Notez que l’accès aux dossiers Utilisateur par défaut nécessite des privilèges d’administrateur.

[in] riid

Type : REFIID

Référence à l’IID de l’interface qui représente l’élément, généralement IID_IShellItem ou IID_IShellItem2.

[out] ppv

Type : void**

Lorsque cette méthode retourne, contient le pointeur d’interface demandé dans riid.

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, 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 de valeurs KNOWNFOLDERID pour le système actuel.

Remarques

L’appelant de cette fonction doit disposer de privilèges d’administrateur. Pour appeler cette fonction sur des dossiers publics connus, l’appelant doit disposer de privilèges d’administrateur. Pour les dossiers connus par utilisateur, l’appelant n’a besoin que de privilèges utilisateur.

Certains des dossiers connus, par exemple le dossier Documents , sont par utilisateur. Chaque utilisateur a un chemin d’accès différent pour son dossier Documents . Si hToken a la valeur NULL, l’API tente d’accéder à la instance de l’application appelante du dossier, qui est celle de l’utilisateur actuel. 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 aux instance de cet utilisateur.

Cette fonction ne peut pas être appelée sur les dossiers de type KF_CATEGORY_FIXED et KF_CATEGORY_VIRTUAL.

Pour appeler cette fonction sur un dossier de type KF_CATEGORY_COMMON, l’application appelante doit s’exécuter avec des privilèges élevés.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 7 [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2008 R2 [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.1 ou ultérieure)
Ensemble d’API	ext-ms-win-shell-shell32-l1-2-1 (introduit dans Windows 10, version 10.0.10240)