Installation et inscription de gestionnaires de protocole (recherche Windows)

  • Article

L’installation d’un gestionnaire de protocole implique la copie des DLL vers un emplacement approprié dans le répertoire Program Files, puis l’inscription du gestionnaire de protocole via le Registre. L’application d’installation peut également ajouter une racine de recherche et des règles d’étendue pour définir une étendue d’analyse par défaut pour la source de données Shell.

Cette rubrique est organisée comme suit :

À propos des URL

Windows Search utilise des URL pour identifier de manière unique les éléments de la hiérarchie de votre source de données Shell. L’URL qui est le premier nœud de la hiérarchie est appelée racine de recherche. Windows Search commence l’indexation à la racine de recherche, en demandant au gestionnaire de protocole d’énumérer les liens enfants pour chaque URL.

La structure d’URL classique est la suivante :

<protocol>:// [{user SID}/] <localhost>/<path>/[<ItemID>]

La syntaxe d’URL est décrite dans le tableau suivant.

Syntaxe Description
<protocol> Identifie le gestionnaire de protocole à appeler pour l’URL.
{SID de l’utilisateur} Identifie le contexte de sécurité utilisateur sous lequel le gestionnaire de protocole est appelé. Si aucun identificateur de sécurité (SID) utilisateur n’est identifié, le gestionnaire de protocole est appelé dans le contexte de sécurité du service système.
<path> Définit la hiérarchie du magasin, où chaque barre oblique (/) est un séparateur entre les noms de dossiers.
<ItemID> Représente une chaîne unique qui identifie l’élément enfant (par exemple, le nom de fichier).

 

L’indexeur Windows Search supprime la barre oblique finale des URL. Par conséquent, vous ne pouvez pas vous appuyer sur l’existence d’une barre oblique finale pour identifier un répertoire ou un élément. Votre gestionnaire de protocole doit être en mesure de gérer cette syntaxe d’URL. Vérifiez que le nom du protocole que vous sélectionnez pour identifier votre source de données Shell n’est pas en conflit avec les noms actuels. Nous vous recommandons cette convention d’affectation de noms : companyName.scheme.

Pour plus d’informations sur la création d’une source de données Shell, consultez Implémentation des interfaces d’objet dossier de base.

Implémentation des interfaces de gestionnaire de protocole

La création d’un gestionnaire de protocole nécessite l’implémentation des trois interfaces suivantes :

  • ISearchProtocol pour gérer les objets UrlAccessor.
  • IUrlAccessor pour exposer des propriétés et identifier les filtres appropriés pour les éléments de la source de données Shell.
  • IFilter pour filtrer des fichiers propriétaires ou pour énumérer et filtrer des fichiers stockés hiérarchiquement.

À part les trois interfaces obligatoires répertoriées, les autres interfaces sont facultatives et vous êtes libre d’implémenter les interfaces facultatives les plus appropriées pour la tâche à effectuer.

ISearchProtocol et ISearchProtocol2

Les interfaces SearchProtocol initialisent et gèrent les objets UrlAccessor de votre gestionnaire de protocole. L’interface ISearchProtocol2 est une extension facultative de ISearchProtocol et inclut une méthode supplémentaire pour spécifier plus d’informations sur l’utilisateur et l’élément.

IUrlAccessor, IUrlAccessor2, IUrlAccessor3 et IUrlAccessor4

Les interfaces IUrlAccessor sont décrites dans le tableau suivant.

Interface Description
IUrlAccessor Pour une URL spécifiée, l’interface IUrlAccessor permet d’accéder aux propriétés de l’élément exposé dans l’URL. Elle peut également lier ces propriétés à un filtre spécifique au gestionnaire de protocole (autrement dit, un filtre autre que celui associé au nom de fichier).
IUrlAccessor2 (facultatif) L’interface IUrlAccessor2 étend IUrlAccessor avec des méthodes qui obtiennent une page de codes pour les propriétés de l’élément et son URL d’affichage, et qui obtiennent le type d’élément dans l’URL (document ou répertoire).
IUrlAccessor3 (facultatif) L’interface IUrlAccessor3 étend IUrlAccessor2 avec une méthode qui obtient un tableau de SID utilisateurs, ce qui permet à l’hôte du protocole de recherche d’emprunter l’identité de ces utilisateurs pour indexer l’élément.
IUrlAccessor4 (facultatif) L’interface IUrlAccessor4 étend les fonctionnalités de l’interface IUrlAccessor3 avec une méthode qui identifie si le contenu de l’élément doit être indexé.

 

L’objet UrlAccessor est instancié et initialisé par un objet SearchProtocol. Les interfaces IUrlAccessor permettent d’accéder à des informations importantes par le biais des méthodes décrites dans le tableau suivant.

Méthode Description
IUrlAccessor::GetLastModified Retourne l’heure à laquelle l’URL a été modifiée pour la dernière fois. Si cette heure est plus récente que la dernière fois que l’indexeur a traité cette URL, les gestionnaires de filtres (implémentations de l’interface IFilter) sont appelés pour extraire les données modifiées (éventuellement) pour cet élément. Les heures de modification des répertoires sont ignorées.
IUrlAccessor::IsDirectory Identifie si l’URL représente un dossier contenant des URL enfants.
IUrlAccessor::BindToStream Effectue la liaison à une interface IStream qui représente les données d’un fichier dans un magasin de données personnalisé.
IUrlAccessor::BindToFilter Effectue la liaison à un IFilter spécifique au gestionnaire de protocole, qui peut exposer des propriétés pour l’élément.
IUrlAccessor4::ShouldIndexItemContent Identifie si le contenu de l’élément doit être indexé.

 

IProtocolHandlerSite

L’interface IProtocolHandlerSite est utilisée pour instancier un gestionnaire de filtres hébergé dans un processus isolé. Le gestionnaire de filtre approprié est obtenu pour un identificateur de classe persistant spécifié (CLSID), une classe de stockage de documents ou une extension de nom de fichier. L’avantage de demander au processus hôte d’effectuer la liaison à IFilter est que le processus hôte peut gérer le processus de localisation d’un gestionnaire de filtre approprié et contrôler la sécurité impliquée dans l’appel du gestionnaire.

Implémentation de gestionnaires de filtres pour conteneurs

Si vous implémentez un gestionnaire de protocole hiérarchique, vous devez alors implémenter un gestionnaire de filtres pour un conteneur qui énumère les URL enfants. Un gestionnaire de filtres est une implémentation de l’interface IFilter. Le processus d’énumération est une boucle via les méthodes IFilter::GetChunk et IFilter::GetValue de l’interface IFilter. Chaque URL enfant est exposée comme valeur de la propriété.

IFilter::GetChunk retourne les propriétés du conteneur. Pour énumérer les URL enfants, IFilter::GetChunk retourne l’une des valeurs suivantes :

Retourner PKEY_Search_UrlToIndexWithModificationTime est plus efficace, car l’indexeur peut déterminer immédiatement si l’élément doit être indexé sans appeler les méthodes ISearchProtocol::CreateAccessor et IUrlAccessor::GetLastModified.

L’exemple de code suivant montre comment retourner la propriété PKEY_Search_UrlToIndexWithModificationTime.

Important

Copyright (c) Microsoft Corporation. Tous droits réservés.

 

// Parameters are assumed to be valid

HRESULT GetPropVariantForUrlAndTime
    (PCWSTR pszUrl, const FILETIME &ftLastModified, PROPVARIANT **ppPropValue)
{
    *ppPropValue = NULL;

    // Allocate the propvariant pointer.
    size_t const cbAlloc = sizeof(**ppPropValue);
    *ppPropValue = (PROPVARIANT *)CoTaskMemAlloc(cbAlloc));

    HRESULT hr = *ppPropValue ? S_OK : E_OUTOFMEMORY;

    if (SUCCEEDED(hr))
    {
        PropVariantInit(*ppPropValue);  // Zero init the value

        // Now allocate enough memory for 2 nested PropVariants.
        // PKEY_Search_UrlToIndexWithModificationTime is an array of two PROPVARIANTs.
        PROPVARIANT *pVector = (PROPVARIANT *)CoTaskMemAlloc(sizeof(*pVector) * 2);
        hr = pVector ? S_OK : E_OUTOFMEMORY;

        if (SUCCEEDED(hr))
        {
            // Set the container PROPVARIANT to be a vector of two PROPVARIANTS.
            (*ppPropValue)->vt = VT_VARIANT | VT_VECTOR;
            (*ppPropValue)->capropvar.cElems = 2;
            (*ppPropValue)->capropvar.pElems = pVector;
            PWSTR pszUrlAlloc;
            hr = SHStrDup(pszUrl, &pszUrlAlloc);

            if (SUCCEEDED(hr))
            {
                // Now fill the array of PROPVARIANTS.
                // Put the pointer to the URL into the vector.
                (*ppPropValue)->capropvar.pElems[0].vt = VT_LPWSTR; 
                (*ppPropValue)->capropvar.pElems[0].pwszVal = pszUrlAlloc;

                 // Put the FILETIME into vector.
                (*ppPropValue)->capropvar.pElems[1].vt = VT_FILETIME; 
                (*ppPropValue)->capropvar.pElems[1].filetime = ftLastModified;
            }

            else
            {
                CoTaskMemFree(pVector);
            }
        }
 
        if (FAILED(hr))
        {
            CoTaskMemFree(*ppPropValue);
            *ppPropValue = NULL;
        }
    }
    return S_OK;
}

Remarque

Le composant IFilter d’un conteneur doit toujours énumérer toutes les URL enfants même si les URL enfants n’ont pas changé, car l’indexeur détecte les suppressions via le processus d’énumération. Si la sortie de date dans un PKEY_Search_UrlToIndexWithModificationTime indique que les données n’ont pas changé, l’indexeur ne met pas à jour les données de cette URL.

 

Installation et inscription d’un gestionnaire de protocole

L’installation de gestionnaires de protocoles implique la copie des DLL vers un emplacement approprié dans le répertoire Program Files, puis l’inscription des DLL. Les gestionnaires de protocoles doivent implémenter l’inscription automatique pour l’installation. L’application d’installation peut également ajouter une racine de recherche et des règles d’étendue pour définir une étendue d’analyse par défaut pour la source de données Shell, qui est décrite dans Vérifier que vos éléments sont indexés à la fin de cette rubrique.

Instructions pour l’inscription d’un gestionnaire de protocole

Vous devez suivre ces instructions lors de l’inscription d’un gestionnaire de protocole :

  • Le programme d’installation doit utiliser le programme d’installation EXE ou MSI.
  • Les notes de publication doivent être fournies.
  • Une entrée Ajouter/Supprimer des programmes doit être créée pour chaque complément installé.
  • Le programme d’installation doit prendre en charge tous les paramètres de Registre pour le type de fichier ou le magasin particulier que le complément actuel comprend.
  • Si un complément précédent est remplacé, le programme d’installation doit avertir l’utilisateur.
  • Si un complément plus récent a remplacé le complément précédent, il doit y avoir la possibilité de restaurer la fonctionnalité du complément précédent et de le rendre à nouveau le complément par défaut pour ce type de fichier.
  • Le programme d’installation doit définir une étendue d’analyse par défaut pour l’indexeur en ajoutant une racine de recherche et des règles d’étendue à l’aide du Gestionnaire de l’étendue d’analyse (CSM).

Inscription d’un gestionnaire de protocole

Vous devez effectuer quatorze entrées dans le Registre pour inscrire le composant du gestionnaire de protocole, où :

  • Ver_Ind_ProgID est le ProgID indépendant de la version de l’implémentation du gestionnaire de protocole.
  • Ver_Dep_ProgID est le ProgID dépendant de la version de l’implémentation du gestionnaire de protocole.
  • CLSID_1 est le CLSID de l’implémentation du gestionnaire de protocole.

Pour inscrire un gestionnaire de protocole :

  1. Inscrivez le ProgID indépendant de la version avec les clés et valeurs suivantes :

    HKEY_CLASSES_ROOT
   <Ver_Ind_ProgID>
      (Default) = <Protocol Handler Class Description>

    HKEY_CLASSES_ROOT
   <Ver_Ind_ProgID>
      CLSID
         (Default) = {CLSID_1}

    HKEY_CLASSES_ROOT
   <Ver_Ind_ProgID>
      CurVer
         (Default) = <Ver_Dep_ProgID>

  2. Inscrivez le ProgID dépendant de la version avec les clés et valeurs suivantes :

    HKEY_CLASSES_ROOT
   <Ver_Dep_ProgID>
      (Default) = <Protocol Handler Class Description>

    HKEY_CLASSES_ROOT
   <Ver_Dep_ProgID>
      CLSID
         (Default) = {CLSID_1}

  3. Inscrivez le CLSID du gestionnaire de protocole avec les clés et valeurs suivantes :

    HKEY_CLASSES_ROOT
   {CLSID_1}
      (Default) = <Protocol Handler Class Description>

    HKEY_CLASSES_ROOT
   {CLSID_1}
      {InprocServer32}
         (Default) = <DLL Install Path>
         Threading Model = Both

    HKEY_CLASSES_ROOT
   {CLSID_1}
      <ProgID>
         (Default) = <Ver_Dep_ProgID>

    HKEY_CLASSES_ROOT
   {CLSID_1}
      <ShellFolder>
         Attributes = dword:a0180000

    HKEY_CLASSES_ROOT
   {CLSID_1}
      TypeLib
         (Default) = {LIBID of PH Component}

    HKEY_CLASSES_ROOT
   {CLSID_1}
      VersionIndependentProgID
         (Default) = <Ver_Ind_ProgID>

  4. Inscrivez le gestionnaire de protocole auprès de Windows Search. Dans l’exemple suivant, le <Nom du protocole> est le nom du protocole lui-même, tel que file, mapi, etc. :

    HKEY_LOCAL_MACHINE
   SOFTWARE
      Microsoft
         Windows Search
            ProtocolHandlers
               <Protocol Name> = <Ver_Dep_ProgID>

    HKEY_CURRENT_USER
   SOFTWARE
      Microsoft
         Windows Search
            ProtocolHandlers
               <Protocol Name> = <Ver_Dep_ProgID>

    Avant Windows Vista :

    HKEY_CURRENT_USER
   SOFTWARE
      Microsoft
         Windows Desktop Search
            DS
               Index
                  ProtocolHandlers
                     <Protocol Name>
                        HasRequirements = dword:00000000
                        HasStartPage = dword:00000000

Inscription du gestionnaire de types de fichiers du gestionnaire de protocole

Vous devez effectuer deux entrées dans le Registre pour inscrire le gestionnaire de types de fichiers du gestionnaire de protocole (également appelé extension d’environnement).

  1. HKEY_LOCAL_MACHINE
   SOFTWARE
      Microsoft
         Windows
            CurrentVersion
               Explorer
                  Desktop
                     NameSpace
                        {CLSID of PH Implementation}
                           (Default) = <Shell Implementation Description>

  2. HKEY_LOCAL_MACHINE
   SOFTWARE
      Microsoft
         Windows
            CurrentVersion
               Explorer
                  Shell Extensions
                     Approved
                        {CLSID of PH Implementation} = <Shell Implementation Description>

S’assurer que vos éléments sont indexés

Une fois que vous avez implémenté votre gestionnaire de protocole, vous devez spécifier les éléments d’interpréteur de commandes que votre gestionnaire de protocole doit indexer. Vous pouvez utiliser le Gestionnaire de catalogues pour lancer la réindexation (pour plus d’informations, consultez Utilisation du Gestionnaire de catalogues). Vous pouvez également utiliser le Gestionnaire de l’étendue d’analyse (CSM) pour configurer des règles par défaut indiquant les URL que vous souhaitez que l’indexeur analyse (pour plus d’informations, voir Utilisation du Gestionnaire de l’étendue d’analyse et Utilisation du Gestionnaire de l’étendue d’analyse). Vous pouvez également ajouter une racine de recherche (pour plus d’informations, consultez Gestion des racines de recherche). Une autre option disponible est de suivre la procédure dans l’exemple ReIndex des Exemples de code Windows Search.

L’interface ISearchCrawlScopeManager fournit des méthodes qui informent le moteur de recherche des conteneurs à analyser et/ou regarder, et les éléments sous ces conteneurs à inclure ou exclure lors de l’analyse ou de l’observation. Dans Windows 7 et versions ultérieures, ISearchCrawlScopeManager2 étend ISearchCrawlScopeManager avec la méthode ISearchCrawlScopeManager2::GetVersion qui obtient la version, ce qui informe les clients si l’état du CSM a changé.

Conceptuel

Comprendre les gestionnaires de protocole

Développer des gestionnaires de protocoles

Notifier l’index des modifications

Ajouter des ’icônes et des menus contextuels

Exemple de code : extensions Shell pour les gestionnaires de protocoles

Création d’un connecteur de recherche pour un gestionnaire de protocole

Débogage de gestionnaires de protocoles