Fonction SHGetKnownFolderPath (shlobj_core.h)

Article
08/26/2023

Récupère le chemin d’accès complet d’un dossier connu identifié par le KNOWNFOLDERID du dossier.

Syntaxe

HRESULT SHGetKnownFolderPath(
  [in]           REFKNOWNFOLDERID rfid,
  [in]           DWORD            dwFlags,
  [in, optional] HANDLE           hToken,
  [out]          PWSTR            *ppszPath
);

Paramètres

[in] rfid

Type : REFKNOWNFOLDERID

Référence au KNOWNFOLDERID qui identifie le dossier.

[in] dwFlags

Type : DWORD

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

[in, optional] hToken

Type : HANDLE

Jeton d’accès qui représente un utilisateur particulier. Si ce paramètre a la valeur NULL, qui est l’utilisation la plus courante, la fonction demande le dossier connu pour l’utilisateur actuel.

Demandez le dossier d’un utilisateur spécifique en transmettant le hToken de cet utilisateur. Cela se fait généralement dans le contexte d’un service qui dispose de privilèges suffisants pour récupérer le jeton d’un utilisateur donné. Ce jeton doit être ouvert avec des droits de TOKEN_QUERY et de TOKEN_IMPERSONATE . Dans certains cas, vous devez également inclure TOKEN_DUPLICATE. En plus de passer le hToken de l’utilisateur, la ruche de registre de cet utilisateur spécifique doit être 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 SHGetKnownFolderPath de rechercher 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.

[out] ppszPath

Type : PWSTR*

Lorsque cette méthode retourne, contient l’adresse d’un pointeur vers une chaîne Unicode terminée par null qui spécifie le chemin d’accès du dossier connu. Le processus d’appel est chargé de libérer cette ressource une fois qu’elle n’est plus nécessaire en appelant CoTaskMemFree, que SHGetKnownFolderPath réussisse ou non. Le chemin retourné n’inclut pas de barre oblique inverse de fin. Par exemple, « C:\Users » est retourné au lieu de « C:\Users\ ».

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_FAIL	Entre autres, cette valeur peut indiquer que le paramètre rfid fait référence à un KNOWNFOLDERID qui n’a pas de chemin d’accès (tel qu’un dossier marqué comme KF_CATEGORY_VIRTUAL).
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

Cette fonction remplace SHGetFolderPath. Cette ancienne fonction est désormais simplement un wrapper pour SHGetKnownFolderPath.

Configuration requise


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)
DLL	Shell32.dll (version 6.0.6000 ou ultérieure)

Voir aussi

IKnownFolder::GetPath

Dossiers connus, exemple

SHGetKnownFolderIDList

SHSetKnownFolderPath