Création de gestionnaires d’extensions d’environnement

Les fonctionnalités de l’interpréteur de commandes peuvent être étendues avec des entrées de Registre et des fichiers .ini. Bien que cette approche de l’extension de l’interpréteur de commandes soit simple et adéquate à de nombreuses fins, elle est limitée. Par exemple, si vous utilisez le Registre pour spécifier une icône personnalisée pour un type de fichier, la même icône s’affiche pour chaque fichier de ce type. L’extension de l’interpréteur de commandes avec le Registre ne vous permet pas de faire varier l’icône pour différents fichiers du même type. D’autres aspects de l’interpréteur de commandes, tels que la feuille de propriétés Propriétés qui peut être affichée lorsqu’un clic droit est fait sur un fichier, ne peuvent pas être modifiés du tout avec le Registre.

Une approche plus puissante et flexible de l’extension de l’interpréteur de commandes consiste à implémenter des gestionnaires d’extensions d’interpréteur de commandes. Ces gestionnaires peuvent être implémentés pour diverses actions que l’interpréteur de commandes peut effectuer. Avant d’effectuer l’action, l’interpréteur de commandes interroge le gestionnaire d’extensions, ce qui lui donne la possibilité de modifier l’action. Un exemple courant est un gestionnaire d’extension de menu contextuel. Si un fichier est implémenté pour un type de fichier, il est interrogé chaque fois que l’un des fichiers fait l’objet d’un clic droit. Le gestionnaire peut ensuite spécifier des éléments de menu supplémentaires fichier par fichier, plutôt que d’avoir le même jeu pour l’ensemble du type de fichier.

Ce document explique comment implémenter les gestionnaires d’extensions qui vous permettent de modifier diverses actions de l’interpréteur de commandes. Les gestionnaires suivants sont associés à un type de fichier particulier et vous permettent de spécifier fichier par fichier :

D’autres gestionnaires ne sont pas associés à un type de fichier particulier, mais sont appelés avant certaines opérations de l’interpréteur de commandes :

Les détails de l’implémentation de gestionnaires d’extensions spécifiques sont abordés dans les sections répertoriées ci-dessus. Le reste de ce document traite de certains problèmes d’implémentation communs à tous les gestionnaires d’extensions Shell.

• Implémentation des gestionnaires d’extensions Shell
  • Implémentation d’IPersistFile
  • Implémentation d’IShellExtInit
  • Personnalisation de l’info-bulle
• Amélioration de Windows Search avec des gestionnaires d’extension shell
• Enregistrement de gestionnaires d’extensions d’environnement
  • Noms des gestionnaires
  • Objets shell prédéfinis
  • Exemple d’inscription de gestionnaire d’extensions
• Rubriques connexes

Implémentation des gestionnaires d’extensions Shell

Une grande partie de l’implémentation d’un objet gestionnaire d’extension Shell dépend de son type. Il y a cependant quelques éléments communs. Cette section décrit les aspects de l’implémentation partagés par tous les gestionnaires d’extensions Shell.

De nombreux gestionnaires d’extensions Shell sont des objets COM (Component Object Model) in-process. Ils doivent se voir attribuer un GUID et les inscrire comme décrit dans Inscription des gestionnaires d’extensions shell. Elles sont implémentées en tant que DLL et doivent exporter les fonctions standard suivantes :

• DllMain. Point d’entrée standard de la DLL.
• DllGetClassObject. Expose la fabrique de classes de l’objet.
• DllCanUnloadNow. COM appelle cette fonction pour déterminer si l’objet sert des clients. Si ce n’est pas le cas, le système peut décharger la DLL et libérer la mémoire associée.

Comme tous les objets COM, les gestionnaires d’extension Shell doivent implémenter une interface IUnknown et une fabrique de classes. La plupart des gestionnaires d’extensions doivent également implémenter une interface IPersistFile ou IShellExtInit dans Windows XP ou une version antérieure. Ils ont été remplacés par IInitializeWithStream, IInitializeWithItem et IInitializeWithFile dans Windows Vista. L’interpréteur de commandes utilise ces interfaces pour initialiser le gestionnaire.

L’interface IPersistFile doit être implémentée par les éléments suivants :

• Gestionnaires de données
• Drop handlers

Dans le passé, les gestionnaires d’icônes étaient également nécessaires pour implémenter IPersistFile, mais cela n’est plus vrai. Pour les gestionnaires d’icônes, IPersistFile est désormais facultatif et d’autres interfaces telles que IInitializeWithItem sont préférées.

L’interface IShellExtInit doit être implémentée par les éléments suivants :

• Gestionnaires de menu contextuel
• Gestionnaires glisser-déplacer
• Gestionnaires de feuilles de propriétés

Implémentation d’IPersistFile

L’interface IPersistFile est destinée à permettre à un objet d’être chargé ou enregistré dans un fichier disque. Il a six méthodes en plus de IUnknown, cinq de ses propres et la méthode GetClassID qu’il hérite d’IPersist. Avec les extensions Shell, IPersist est utilisé uniquement pour initialiser un objet gestionnaire d’extensions Shell. Étant donné qu’il n’est généralement pas nécessaire de lire ou d’écrire sur le disque, seules les méthodes GetClassID et Load nécessitent une implémentation non-automatique.

L’interpréteur de commandes appelle d’abord GetClassID , et la fonction retourne l’identificateur de classe (CLSID) de l’objet gestionnaire d’extensions. L’interpréteur de commandes appelle ensuite Load et passe deux valeurs. Le premier, pszFileName, est une chaîne Unicode avec le nom du fichier ou du dossier sur lequel Shell est sur le point d’opérer. Le second est dwMode, qui indique le mode d’accès aux fichiers. Étant donné qu’il n’est généralement pas nécessaire d’accéder aux fichiers, dwMode est généralement égal à zéro. La méthode stocke ces valeurs si nécessaire pour une référence ultérieure.

Le fragment de code suivant illustre comment un gestionnaire d’extension Shell classique implémente les méthodes GetClassID et Load . Il est conçu pour gérer ANSI ou Unicode. CLSID_SampleExtHandler est le GUID de l’objet de gestionnaire d’extension, et CSampleExtHandler est le nom de la classe utilisée pour implémenter l’interface. Les variables m_szFileName et m_dwMode sont des variables privées utilisées pour stocker le nom et les indicateurs d’accès du fichier.

wchar_t m_szFileName[MAX_PATH];    // The file name
DWORD m_dwMode;                  // The file access mode

CSampleExtHandler::GetClassID(CLSID *pCLSID)
{
    *pCLSID = CLSID_SampleExtHandler;
}

CSampleExtHandler::Load(PCWSTR pszFile, DWORD dwMode)
{
    m_dwMode = dwMode;
    return StringCchCopy(_szFileName, ARRAYSIZE(m_szFileName), pszFile);
}

Implémentation d’IShellExtInit

L’interface IShellExtInit a une seule méthode, IShellExtInit::Initialize, en plus de IUnknown. La méthode a trois paramètres que l’interpréteur de commandes peut utiliser pour passer différents types d’informations. Les valeurs passées dépendent du type de gestionnaire, et certaines peuvent être définies sur NULL.

• pIDFolder contient le pointeur d’un dossier vers une liste d’identificateurs d’élément (PIDL). Pour les extensions de feuille de propriétés, elle est NULL. Pour les extensions de menu contextuel, il s’agit du PIDL du dossier qui contient l’élément dont le menu contextuel est affiché. Pour les gestionnaires de glisser-déplacer non par défaut, il s’agit du PIDL du dossier cible.
• pDataObject contient un pointeur vers l’interface IDataObject d’un objet de données. L’objet de données contient un ou plusieurs noms de fichiers au format CF_HDROP .
• hRegKey contient une clé de Registre pour l’objet fichier ou le type de dossier.

La méthode IShellExtInit::Initialize stocke le nom de fichier, le pointeur IDataObject et la clé de Registre si nécessaire pour une utilisation ultérieure. Le fragment de code suivant illustre une implémentation de IShellExtInit::Initialize. Par souci de simplicité, cet exemple suppose que l’objet de données ne contient qu’un seul fichier. En général, il peut contenir plusieurs fichiers qui devront chacun être extraits.

LPCITEMIDLIST  m_pIDFolder;           //The folder's PIDL
wchar_t        m_szFile[MAX_PATH];    //The file name
IDataObject   *m_pDataObj;            //The IDataObject pointer
HKEY           m_hRegKey;             //The file or folder's registry key

STDMETHODIMP CShellExt::Initialize(LPCITEMIDLIST pIDFolder, 
                                   IDataObject *pDataObj, 
                                   HKEY hRegKey) 
{ 
    // If Initialize has already been called, release the old PIDL
    ILFree(m_pIDFolder);
    m_pIDFolder = nullptr;

    // Store the new PIDL.
    if (pIDFolder)
    {
        m_pIDFolder = ILClone(pIDFolder);
    }
    
    // If Initialize has already been called, release the old
    // IDataObject pointer.
    if (m_pDataObj)
    { 
        m_pDataObj->Release(); 
    }
     
    // If a data object pointer was passed in, save it and
    // extract the file name. 
    if (pDataObj) 
    { 
        m_pDataObj = pDataObj; 
        pDataObj->AddRef(); 
      
        STGMEDIUM   medium;
        FORMATETC   fe = {CF_HDROP, NULL, DVASPECT_CONTENT, -1, TYMED_HGLOBAL};
        UINT        uCount;

        if (SUCCEEDED(m_pDataObj->GetData(&fe, &medium)))
        {
            // Get the count of files dropped.
            uCount = DragQueryFile((HDROP)medium.hGlobal, (UINT)-1, NULL, 0);

            // Get the first file name from the CF_HDROP.
            if (uCount)
                DragQueryFile((HDROP)medium.hGlobal, 0, m_szFile, 
                              sizeof(m_szFile)/sizeof(TCHAR));

            ReleaseStgMedium(&medium);
        }
    }

    // Duplicate the registry handle. 
    if (hRegKey) 
        RegOpenKeyEx(hRegKey, nullptr, 0L, MAXIMUM_ALLOWED, &m_hRegKey); 
    return S_OK; 
}

CSampleExtHandler est le nom de la classe utilisée pour implémenter l’interface. Les variables m_pIDFolder, m_pDataObject, m_szFileName et m_hRegKey sont des variables privées utilisées pour stocker les informations transmises. Par souci de simplicité, cet exemple suppose qu’un seul nom de fichier sera conservé par l’objet de données. Une fois la structure FORMATETC récupérée à partir de l’objet de données, DragQueryFile est utilisé pour extraire le nom de fichier du membre medium.hGlobal de la structure FORMATETC. Si une clé de Registre est passée, la méthode utilise RegOpenKeyEx pour ouvrir la clé et affecte le handle à m_hRegKey.

Personnalisation de l’info-bulle

Il existe deux façons de personnaliser les info-bulles :

• Implémentez un objet qui prend en charge IQueryInfo , puis inscrivez cet objet sous la sous-clé appropriée dans le Registre (voir Inscription des gestionnaires d’extension shell ci-dessous).
• Spécifiez une chaîne fixe ou une liste de propriétés de fichier spécifiques à afficher.

Pour afficher une chaîne fixe pour une extension d’espace de noms, créez une entrée appelée InfoTip dans la clé {CLSID} de votre extension d’espace de noms. Définissez la valeur de cette entrée sur la chaîne littérale que vous souhaitez afficher, comme illustré dans cet exemple, ou sur une chaîne indirecte qui spécifie une ressource et un index dans cette ressource (à des fins de localisation).

HKEY_CLASSES_ROOT
   CLSID
      {CLSID}
         InfoTip = InfoTip string for your namespace extension

Pour afficher une chaîne fixe pour un type de fichier, créez une entrée appelée InfoTip dans la clé ProgID de ce type de fichier. Définissez la valeur de cette entrée sur la chaîne littérale que vous souhaitez afficher ou une chaîne indirecte qui spécifie une ressource et un index dans cette ressource (à des fins de localisation), comme illustré dans cet exemple.

HKEY_CLASSES_ROOT
   ProgID
      InfoTip = Resource.dll, 3

Si vous souhaitez que l’interpréteur de commandes affiche des propriétés de fichier spécifiques dans l’info-bulle pour un type de fichier spécifique, créez une entrée appelée InfoTip dans la clé ProgID pour ce type de fichier. Définissez la valeur de cette entrée sur une liste délimitée par des points-virgules de noms de propriétés canoniques, de paires d’identificateur de format (FMTID)/identificateur de propriété (PID), ou les deux. Cette valeur doit commencer par « prop: » pour l’identifier en tant que chaîne de liste de propriétés. Si vous omettez « prop: », la valeur est considérée comme une chaîne littérale et affichée en tant que telle.

Dans l’exemple suivant, propname est un nom de propriété canonique (par exemple, System.Date) et {fmtid},pid est une paire FMTID/PID .

HKEY_CLASSES_ROOT
   ProgID
      InfoTip = prop:propname;propname;{fmtid},pid;{fmtid},pid

Les noms de propriétés suivants peuvent être utilisés :

Amélioration de La recherche Windows avec des gestionnaires d’extension Shell

Les gestionnaires d’extensions shell peuvent être utilisés pour améliorer l’expérience utilisateur fournie par un gestionnaire de protocole Windows Search. Pour permettre de telles améliorations, le gestionnaire d’extension Shell de prise en charge doit être conçu pour s’intégrer au gestionnaire de protocole de recherche en tant que source de données. Pour plus d’informations sur l’amélioration d’un gestionnaire de protocole Recherche Windows via l’intégration à un gestionnaire d’extension Shell, consultez Ajout d’icônes, d’aperçus et de menus contextuels. Pour plus d’informations sur les gestionnaires de protocole De recherche Windows, consultez Développement de gestionnaires de protocole.

Enregistrement de gestionnaires d’extensions d’environnement

Un objet gestionnaire d’extension Shell doit être inscrit avant que l’interpréteur de commandes puisse l’utiliser. Cette section est une présentation générale de l’inscription d’un gestionnaire d’extensions Shell.

Chaque fois que vous créez ou modifiez un gestionnaire d’extensions Shell, il est important d’informer le système que vous avez apporté une modification avec SHChangeNotify, en spécifiant l’événement SHCNE_ASSOCCHANGED . Si vous n’appelez pas SHChangeNotify, la modification peut ne pas être reconnue tant que le système n’est pas redémarré.

Comme pour tous les objets COM, vous devez créer un GUID pour le gestionnaire à l’aide d’un outil tel que UUIDGEN.exe. Créez une clé sous HKEY_CLASSES_ROOT\CLSID dont le nom est la forme de chaîne du GUID. Étant donné que les gestionnaires d’extensions Shell sont des serveurs in-process, vous devez créer une clé InProcServer32 sous la clé GUID avec la valeur par défaut définie sur le chemin d’accès de la DLL du gestionnaire. Utilisez le modèle de thread d’appartement.

Chaque fois que l’interpréteur de commandes prend une action qui peut impliquer un gestionnaire d’extension Shell, il vérifie la clé de Registre appropriée. La clé sous laquelle un gestionnaire d’extension est inscrit contrôle donc quand il sera appelé. Par instance, il est courant d’avoir un gestionnaire de menus contextuels appelé lorsque l’interpréteur de commandes affiche un menu contextuel pour un membre d’un type de fichier. Dans ce cas, le gestionnaire doit être inscrit sous la clé ProgID du type de fichier.

Noms des gestionnaires

Pour activer un gestionnaire d’extension Shell, créez une sous-clé avec le nom de sous-clé du gestionnaire (voir ci-dessous) sous la sous-clé ShellEx du ProgID (pour les types de fichiers) ou le nom du type d’objet Shell (pour les objets Shell prédéfinis).

Par exemple, si vous souhaitez inscrire un gestionnaire d’extension de menu contextuel pour MyProgram.1, vous devez commencer par créer la sous-clé suivante :

HKEY_CLASSES_ROOT
   MyProgram.1
      ShellEx
         ContextMenuHandlers

Pour les gestionnaires suivants, créez une sous-clé sous la clé « Handler Subkey name » dont le nom est la version de chaîne du CLSID de l’extension Shell. Plusieurs extensions peuvent être inscrites sous la clé de nom de sous-clé du gestionnaire en créant plusieurs sous-clés.

Pour les gestionnaires suivants, la valeur par défaut de la clé « Handler Subkey Name » est la version sous-chaîne du CLSID de l’extension Shell. Une seule extension peut être inscrite pour ces gestionnaires.

Les sous-clés spécifiées pour ajouter Épingler au menu Démarrer et Épingler à la barre des tâches au menu contextuel d’un élément sont requises uniquement pour les types de fichiers qui incluent l’entrée IsShortCut .

La prise en charge des gestionnaires de fournisseurs de colonnes a été supprimée dans Windows Vista. En outre, depuis Windows Vista, IPropertySetStorage est déprécié en faveur de IPropertyStore.

Bien que IExtractImage reste pris en charge, IThumbnailProvider est préféré pour Windows Vista et versions ultérieures.

Objets shell prédéfinis

L’interpréteur de commandes définit des objets supplémentaires sous HKEY_CLASSES_ROOT qui peuvent être étendus de la même façon que les types de fichiers. Par exemple, pour ajouter un gestionnaire de feuilles de propriétés pour tous les fichiers, vous pouvez vous inscrire sous la clé PropertySheetHandlers .

HKEY_CLASSES_ROOT
   *
      shellex
         PropertySheetHandlers

Le tableau suivant indique les différentes sous-clés de HKEY_CLASSES_ROOT sous lesquelles les gestionnaires d’extensions peuvent être inscrits. Notez que de nombreux gestionnaires d’extensions ne peuvent pas être inscrits sous toutes les sous-clés répertoriées. Pour plus d’informations, consultez la documentation du gestionnaire spécifique.

Remarques :

• Le menu contextuel d’arrière-plan du dossier de fichiers est accessible en cliquant avec le bouton droit dans un dossier de fichiers, mais pas sur le contenu du dossier.
• Les « verbes » sont des commandes spéciales inscrites sous HKEY_CLASSES_ROOT\verbede l’interpréteur\de sous-clés\ .
• Pour Type de réseau\\#, « # » est un code de type de fournisseur réseau en décimal. Le code de type de fournisseur de réseau est le mot haut d’un type de réseau. La liste des types de réseau est donnée dans le fichier d’en-tête Winnetwk.h (valeurs WNNC_NET_*). Par exemple, WNNC_NET_SHIVA est 0x00330000, de sorte que la clé de type correspondante serait HKEY_CLASSES_ROOT\type\réseau\51 .
• « network_provider_name » est un nom de fournisseur de réseau tel que spécifié par WNetGetProviderName, avec les espaces convertis en traits de soulignement. Par exemple, si le fournisseur réseau Microsoft Networking est installé, son nom de fournisseur est « Microsoft Windows Network » et le network_provider_name correspondant est Microsoft_Windows_Network.

Exemple d’inscription de gestionnaire d’extensions

Pour activer un gestionnaire particulier, créez une sous-clé sous la clé de type du gestionnaire d’extension avec le nom du gestionnaire. L’interpréteur de commandes n’utilise pas le nom du gestionnaire, mais il doit être différent de tous les autres noms sous cette sous-clé de type. Définissez la valeur par défaut de la sous-clé name sur la forme de chaîne du GUID du gestionnaire.

L’exemple suivant illustre les entrées de Registre qui activent les gestionnaires de menu contextuel et d’extension de feuille de propriétés, à l’aide d’un exemple de type de fichier .myp :

HKEY_CLASSES_ROOT
   .myp
      (Default) = MyProgram.1
   CLSID
      {00000000-1111-2222-3333-444444444444}
         InProcServer32
            (Default) = C:\MyDir\MyCommand.dll
            ThreadingModel = Apartment
      {11111111-2222-3333-4444-555555555555}
         InProcServer32
            (Default) = C:\MyDir\MyPropSheet.dll
            ThreadingModel = Apartment
   MyProgram.1
      (Default) = MyProgram Application
      Shellex
         ContextMenuHandler
            MyCommand
               (Default) = {00000000-1111-2222-3333-444444444444}
         PropertySheetHandlers
            MyPropSheet
               (Default) = {11111111-2222-3333-4444-555555555555}

La procédure d’inscription décrite dans cette section doit être suivie pour tous les systèmes Windows.

Rubriques connexes

Conseils pour l’implémentation d’extensions In-Process