Fonction SHGetKnownFolderPath (shlobj_core.h)
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 |
|---|---|
|
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). |
|
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) |