Méthode IShellFolder ::P arseDisplayName (shobjidl_core.h)

  • Article

Convertit le nom d’affichage d’un objet de fichier ou d’un dossier en liste d’identificateur d’élément.

Syntaxe

HRESULT ParseDisplayName(
  [in]      HWND             hwnd,
  [in]      IBindCtx         *pbc,
  [in]      LPWSTR           pszDisplayName,
  [out]     ULONG            *pchEaten,
  [out]     PIDLIST_RELATIVE *ppidl,
  [in, out] ULONG            *pdwAttributes
);

Paramètres

[in] hwnd

Type : HWND

Handle de fenêtre. Le client doit fournir un handle de fenêtre s’il affiche une boîte de dialogue ou une boîte de message. Sinon, définissez hwnd sur NULL.

[in] pbc

Type : IBindCtx*

facultatif. Pointeur vers un contexte de liaison utilisé pour passer des paramètres en tant qu’entrées et sorties à la fonction d’analyse. Ces paramètres passés sont souvent spécifiques à la source de données et sont documentés par les propriétaires de la source de données. Par exemple, la source de données du système de fichiers accepte le nom analysé (en tant que structure de WIN32_FIND_DATA ), à l’aide du paramètre de contexte de liaison STR_FILE_SYS_BIND_DATA . STR_PARSE_PREFER_FOLDER_BROWSING peut être transmis pour indiquer que les URL sont analysées à l’aide de la source de données du système de fichiers lorsque cela est possible. Construisez un objet de contexte de liaison à l’aide de CreateBindCtx et renseignez les valeurs à l’aide de IBindCtx ::RegisterObjectParam. Pour obtenir la liste complète de ces clés , consultez Lier des clés de chaîne de contexte.

Si aucune donnée n’est transmise ou reçue de la fonction d’analyse, cette valeur peut être NULL.

[in] pszDisplayName

Type : LPWSTR

Chaîne Unicode terminée par null avec le nom d’affichage. Étant donné que chaque dossier Shell définit sa propre syntaxe d’analyse, la forme que cette chaîne peut prendre peut varier. Le dossier de bureau, pour instance, accepte des chemins d’accès tels que « C :\My Docs\My File.txt ». Il accepte également les références aux éléments de l’espace de noms auxquels un GUID est associé à l’aide de la syntaxe « ::{GUID} ». Par exemple, pour récupérer une liste d’identificateurs complets pour le panneau de configuration à partir du dossier du bureau, vous pouvez utiliser les éléments suivants :

::{CLSID for Control Panel}\::{CLSID for printers folder}

[out] pchEaten

Type : ULONG*

Pointeur vers une valeur ULONG qui reçoit le nombre de caractères du nom d’affichage analysé. Si votre application n’a pas besoin de ces informations, définissez pchEaten sur NULL et aucune valeur ne sera retournée.

[out] ppidl

Type : PIDLIST_RELATIVE*

Lorsque cette méthode retourne, contient un pointeur vers le PIDL de l’objet. La liste d’identificateurs d’élément retourné spécifie l’élément relatif au dossier d’analyse. Si l’objet associé à pszDisplayName se trouve dans le dossier d’analyse, la liste d’identificateurs d’élément retournée ne contiendra qu’une seule structure SHITEMID . Si l’objet se trouve dans un sous-dossier du dossier d’analyse, la liste d’identificateurs d’élément retournée contiendra plusieurs structures SHITEMID . Si une erreur se produit, la valeur NULL est retournée dans cette adresse.

Lorsqu’elle n’est plus nécessaire, il incombe à l’appelant de libérer cette ressource en appelant CoTaskMemFree.

[in, out] pdwAttributes

Type : ULONG*

Valeur utilisée pour interroger les attributs de fichier. S’il n’est pas utilisé, il doit être défini sur NULL. Pour rechercher un ou plusieurs attributs, initialisez ce paramètre avec les indicateurs SFGAO qui représentent les attributs d’intérêt. En retour, les attributs qui ont la valeur true et qui ont été demandés seront définis.

Valeur retournée

Type : HRESULT

Si cette méthode réussit, elle retourne S_OK. Sinon, elle retourne un code d’erreur HRESULT.

Remarques

Certains dossiers Shell peuvent ne pas implémenter IShellFolder ::P arseDisplayName. Chaque dossier qui le fait définit sa propre syntaxe d’analyse.

ParseDisplayName n’est pas censé gérer le chemin relatif ou les indicateurs de dossier parent (« . » ou « .. »). Il appartient à l’appelant de les supprimer de manière appropriée.

N’utilisez pas l’indicateur SFGAO_VALIDATE dans pdwAttributes pour vérifier l’existence de l’élément dont le nom est analysé. IShellFolder ::P arseDisplayName valide implicitement l’existence de l’élément, sauf si ce comportement est remplacé par un paramètre de contexte de liaison spécial.

L’interrogation de certains attributs peut être relativement lente et utiliser des quantités importantes de mémoire. Par exemple, pour déterminer si un fichier est partagé, l’interpréteur de commandes charge les composants réseau. Cette procédure peut nécessiter le chargement de plusieurs DLL. L’objectif de pdwAttributes est de vous permettre de limiter la requête aux seules informations nécessaires. Le fragment de code suivant montre comment déterminer si un fichier est compressé.

LPITEMIDLIST pidl;
ULONG cbEaten;
DWORD dwAttribs = SFGAO_COMPRESSED;

hres = psf->ParseDisplayName(NULL,
                             NULL,
                             lpwszDisplayName,
                             &cbEaten,  // This can be NULL
                             &pidl,
                             &dwAttribs);

if(dwAttribs & SFGAO_COMPRESSED)
{
    // Do something with the compressed file
}

Étant donné que pdwAttributes est un paramètre in/out, il doit toujours être initialisé. Si vous passez une valeur non initialisée, certains bits peuvent être définis par inadvertance. IShellFolder ::P arseDisplayName interroge ensuite les attributs correspondants, ce qui peut entraîner des retards indésirables ou des demandes de mémoire. Si vous ne souhaitez pas interroger les attributs, définissez pdwAttributes sur NULL pour éviter tout comportement imprévisible.

Cette méthode est similaire à la méthode IParseDisplayName ::P arseDisplayName .

Configuration requise

Condition requise Valeur
Client minimal pris en charge Windows XP [applications de bureau uniquement]
Serveur minimal pris en charge Windows 2000 Server [applications de bureau uniquement]
Plateforme cible Windows
En-tête shobjidl_core.h (inclure Shobjidl.h)
DLL Shell32.dll (version 4.0 ou ultérieure)

Voir aussi

IShellFolder

IShellFolder2

IShellFolder ::GetAttributesOf

IShellLink