Implémentation de gestionnaires de filtres dans Recherche Windows

Article
06/13/2023

Il est important que vous compreniez la structure DLL requise d’un gestionnaire de filtre (implémentation de l’interface IFilter ).

Cette rubrique est organisée comme suit :

Implémentation et exportation des points d’entrée DLL
Implémentation de la classe IFilter et de la fabrique de classes
Hériter des interfaces COM
Implémentation des méthodes d’interface COM
- Méthodes COM qui ne sont pas implémentées
Ressources supplémentaires
Rubriques connexes

Implémentation et exportation des points d’entrée DLL

Chaque DLL IFilter (désignée par Ifilter.dll dans cette section) doit implémenter et exporter les points d’entrée suivants. Ces points d’entrée sont généralement exportés à l’aide d’un fichier de définition de module (.def) pour l’interface IFilter ou à l’aide du __declspec(dllexport) mot clé. Le fichier DLL peut être inscrit pour se trouver dans n’importe quel dossier, mais il réside généralement dans le dossier %SystemRoot%\system32.

Les points d’entrée DLL sont répertoriés et décrits dans le tableau suivant.

Nom de la DLL	Description de la DLL
Dllregisterserver	Le point d’entrée DllRegisterServer inscrit la DLL en tant que filtre dans le Registre. Vous inscrivez la DLL en exécutant le programme regsvr32.exe avec le nom de fichier DLL d’interface IFilter comme argument : `regsvr32.exe %SystemRoot%\system32\Ifilter.dll`
DllUnregisterServer, fonction	Le point d’entrée de la fonction DllUnregisterServer supprime la DLL en tant que gestionnaire persistant dans le Registre. Vous annulez l’inscription de la DLL en exécutant le programme regsvr32.exe avec l’indicateur `/u` : `regsvr32.exe /u %SystemRoot%\system32\Ifilter.dll`
DllGetClassObject, fonction	Le client d’indexation de contenu appelle le point d’entrée de la fonction DllGetClassObject , par le biais du modèle d’objet de composant (COM), pour créer un objet de fabrique de classes pour l’interface IFilter et obtenir un pointeur vers l’interface de fabrique de classe de cet objet.
DllCanUnloadNow, fonction	Le client d’indexation de contenu appelle le point d’entrée de la fonction DllCanUnloadNow , via COM, pour déterminer s’il est possible de décharger la DLL IFilter . L’interface IFilter est déchargée une fois inutilisée pendant un intervalle de temps, comme spécifié par la valeur de Registre FilterIdleTimeOut.

Implémentation de la classe IFilter et de la fabrique de classes

Au moins deux classes, telles que CFilter et CFilterCF, sont généralement implémentées par chaque DLL IFilter . La classe CFilter produit l’objet d’interface IFilter qui implémente la fonctionnalité de filtrage de contenu. Ses fonctions membres implémentent les méthodes d’interface de l’interface IFilter . Chaque classe IFilter nécessite un identificateur de classe unique (CLSID), que l’implémenteur d’interface IFilter génère.

La classe CFilterCF produit l’objet class-factory pour l’interface IFilter . La fabrique de classes est appelée, via son interface IClassFactory Interface , par le point d’entrée de la fonction DllGetClassObject de la DLL. La classe CFilterCF crée l’objet CFilter et retourne un pointeur vers IUnknown. Dans des cas plus complexes, un IFilter peut implémenter une hiérarchie de classes à la place de la classe CFilter unique.

Hériter des interfaces COM

Windows Search 3.0 et versions ultérieures nécessitent l’utilisation d’IPersistStream pour les raisons suivantes :

Pour garantir les performances et la compatibilité future.
Pour améliorer la sécurité. Les IFilters implémentés avec IPersistStream sont plus sécurisés , car le contexte dans lequel l’interface IFilter s’exécute n’a pas besoin des droits pour ouvrir des fichiers sur le disque ou sur le réseau.
Bien que Recherche Windows utilise uniquement IPersistStream, la classe d’interface IFilter peut également hériter des implémentations de l’interface IPersistFile et/ou de l’interface IPersistStorage à des fins de compatibilité descendante.

Ces interfaces sont déclarées dans les fichiers inclus dans le répertoire mssdk\include et ont des identificateurs d’interface (ID) prédéfinis. Le client d’indexation de contenu interroge l’interface IFilter via IUnknown pour déterminer laquelle de ces interfaces utiliser lors du filtrage du contenu.

Implémentation des méthodes d’interface COM

L’interface IFilter implémente les méthodes IUnknown pour la classe d’interface IFilter et la fabrique de classe d’interface IFilter. Le tableau suivant répertorie, dans l’ordre vtable, les interfaces et les méthodes spécifiques à l’interface IFilter que l’interface IFilter doit implémenter. L’interface IFilter doit implémenter au moins IPersistStream, mais peut implémenter d’autres interfaces dérivées d’IPersist.

Interface COM	Méthode
IClassFactory Interface	CreateInstance, LockServer
IClassFactory2, interface	GetLicInfo, RequestLicKey, CreateInstanceLic
Ifilter	IFilter::Init, IFilter::GetChunk, IFilter::GetText, IFilter::GetValue, IFilter::BindRegion
IPersist Interface	GetClassID
IPersistFile, interface	IsDirty, Load, Save, SaveCompleted, GetCurFile
IPersistStorage, interface	IsDirty, Charger, Enregistrer, GetSizeMax
IPersistStream	IsDirty, Charger, Enregistrer, GetSizeMax

La page de référence de chaque méthode spécifie les paramètres et le comportement fonctionnel de cette méthode. Chaque page de référence fournit également les codes de résultat à implémenter pour cette méthode. Les pages de référence pour les méthodes IFilter fournissent les codes spécifiques à l’interface dans FACILITY_ITF codes de résultat à implémenter, et le client d’indexation de contenu peut également gérer n’importe quel code de résultat générique, tel que FACILITY_NULL et FACILITY_WIN32. Pour plus d’informations, consultez Structure des codes d’erreur COM.

Méthodes COM qui ne sont pas implémentées

L’interface IFilter doit implémenter au moins IPersistStream, mais elle n’a pas besoin d’implémenter d’autres interfaces dérivées d’IPersist.

Recherche Windows n’a pas besoin d’implémenter les méthodes COM répertoriées dans le tableau suivant.

Méthode non obligatoire	Description
IPersistStream::IsDirty	Les filtres doivent retourner E_NOTIMPL.
IPersistStream::Save	Les filtres doivent retourner E_NOTIMPL.
IPersistStream::GetSizeMax	Les filtres doivent retourner E_NOTIMPL.
IFilter::BindRegion	Les filtres doivent retourner E_NOTIMPL.

Ressources supplémentaires

L’exemple de code IFilterSample , disponible sur GitHub, montre comment créer une classe de base IFilter pour implémenter l’interface IFilter .
Pour obtenir une vue d’ensemble du processus d’indexation, consultez Le processus d’indexation.
Pour obtenir une vue d’ensemble des types de fichiers, consultez Types de fichiers.
Pour interroger les attributs d’association de fichiers pour un type de fichier, consultez PerceivedTypes, SystemFileAssociations et Inscription d’application.