Implementieren von Filterhandlern in Windows Search

Artikel
06/13/2023

Es ist wichtig, dass Sie die erforderliche DLL-Struktur eines Filterhandlers (eine Implementierung der IFilter-Schnittstelle ) kennen.

Dieses Thema ist wie folgt organisiert:

Implementieren und Exportieren der DLL-Einstiegspunkte
Implementieren der IFilter-Klasse und -Klassenfactory
Erben der COM-Schnittstellen
Implementieren der COM-Schnittstellenmethoden
- COM-Methoden, die nicht implementiert sind
Weitere Ressourcen
Zugehörige Themen

Implementieren und Exportieren der DLL-Einstiegspunkte

Jede IFilter-DLL (bezeichnet durch Ifilter.dll in diesem Abschnitt) muss die folgenden Einstiegspunkte implementieren und exportieren. Diese Einstiegspunkte werden in der Regel mithilfe einer Moduldefinitionsdatei (DEF) für die IFilter-Schnittstelle oder mithilfe des __declspec(dllexport) Schlüsselwort (keyword) exportiert. Die DLL-Datei kann in einem beliebigen Ordner registriert werden, befindet sich jedoch normalerweise im Ordner %SystemRoot%\system32.

DLL-Einstiegspunkte werden in der folgenden Tabelle aufgeführt und beschrieben.

DLL-Name	DLL-Beschreibung
Dllregisterserver	Der Einstiegspunkt DllRegisterServer registriert die DLL als Filter in der Registrierung. Sie registrieren die DLL, indem Sie das regsvr32.exe-Programm mit dem DLL-Dateinamen der IFilter-Schnittstelle als Argument ausführen: `regsvr32.exe %SystemRoot%\system32\Ifilter.dll`
DllUnregisterServer-Funktion	Der Einstiegspunkt DllUnregisterServer-Funktion entfernt die DLL als persistenten Handler in der Registrierung. Sie heben die Registrierung der DLL auf, indem Sie das regsvr32.exe-Programm mit dem `/u` Flag ausführen: `regsvr32.exe /u %SystemRoot%\system32\Ifilter.dll`
DllGetClassObject-Funktion	Der Inhaltsindizierungsclient ruft den Einstiegspunkt dllGetClassObject-Funktion über Component Object Model (COM) auf, um ein Klassen factory-Objekt für die IFilter-Schnittstelle zu erstellen und einen Zeiger auf die Class Factory-Schnittstelle dieses Objekts abzurufen.
DllCanUnloadNow-Funktion	Der Inhaltsindizierungsclient ruft den Einstiegspunkt dllCanUnloadNow-Funktion über COM auf, um zu bestimmen, ob es möglich ist, die IFilter-DLL zu entladen. Die IFilter-Schnittstelle wird entladen, nachdem sie für ein Intervall nicht verwendet wurde, wie durch den Registrierungswert FilterIdleTimeOut angegeben.

Implementieren der IFilter-Klasse und -Klassenfactory

Mindestens zwei Klassen, z. B. CFilter und CFilterCF, werden in der Regel von jeder IFilter-DLL implementiert. Die CFilter-Klasse erzeugt das IFilter-Schnittstellenobjekt , das die Inhaltsfilterfunktion implementiert. Ihre Memberfunktionen implementieren die Schnittstellenmethoden der IFilter-Schnittstelle . Jede IFilter-Klasse erfordert einen eindeutigen Klassenbezeichner (CLSID), den der IFilter-Schnittstellenimplementierer generiert.

Die CFilterCF-Klasse erzeugt das class-factory-Objekt für die IFilter-Schnittstelle . Die Klassenfactory wird über ihre IClassFactory-Schnittstelle vom Einstiegspunkt der DllGetClassObject-Funktion der DLL aufgerufen. Die CFilterCF-Klasse erstellt das CFilter-Objekt und gibt einen Zeiger auf IUnknown zurück. In komplexeren Fällen kann ein IFilter anstelle der einzelnen CFilter-Klasse eine Klassenhierarchie implementieren.

Erben der COM-Schnittstellen

Windows Search 3.0 und höher erfordern die Verwendung von IPersistStream aus den folgenden Gründen:

Um Leistung und zukünftige Kompatibilität sicherzustellen.
Um die Sicherheit zu erhöhen. IFilters, die mit IPersistStream implementiert wurden, sind sicherer, da der Kontext, in dem die IFilter-Schnittstelle ausgeführt wird, nicht die Rechte zum Öffnen von Dateien auf dem Datenträger oder über das Netzwerk benötigt.
Während Windows Search nur IPersistStream verwendet, kann die IFilter-Schnittstellenklasse aus Gründen der Abwärtskompatibilität auch die Implementierungen der IPersistFile-Schnittstelle und/oder IPersistStorage-Schnittstelle erben.

Diese Schnittstellen werden in Dateien deklariert, die aus dem Verzeichnis mssdk\include enthalten sind und über vordefinierte Schnittstellenbezeichner (IIDs) verfügen. Der Inhaltsindizierungsclient fragt die IFilter-Schnittstelle über IUnknown ab, um zu bestimmen, welche dieser Schnittstellen beim Filtern von Inhalten verwendet werden soll.

Implementieren der COM-Schnittstellenmethoden

Die IFilter-Schnittstelle implementiert die IUnknown-Methoden sowohl für die IFilter-Schnittstellenklasse als auch für die IFilter-Schnittstellenklassen-Factory. In der folgenden Tabelle sind in vtabler Reihenfolge die IFilter-schnittstellenspezifischen Schnittstellen und Methoden aufgeführt, die von der IFilter-Schnittstelle implementiert werden sollen. Die IFilter-Schnittstelle muss mindestens IPersistStream implementieren, kann jedoch zusätzliche von IPersist abgeleitete Schnittstellen implementieren.

COM-Schnittstelle	Methode
IClassFactory-Schnittstelle	CreateInstance, LockServer
IClassFactory2-Schnittstelle	GetLicInfo, RequestLicKey, CreateInstanceLicLic
Ifilter	IFilter::Init, IFilter::GetChunk, IFilter::GetText, IFilter::GetValue, IFilter::BindRegion
IPersist-Schnittstelle	Getclassid
IPersistFile-Schnittstelle	IsDirty, Load, Save, SaveCompleted, GetCurFile
IPersistStorage-Schnittstelle	IsDirty, Load, Save, GetSizeMax
Ipersiststream	IsDirty, Load, Save, GetSizeMax

Die Referenzseite für jede Methode gibt die Parameter und das funktionsbezogene Verhalten für diese Methode an. Jede Verweisseite enthält auch die Ergebniscodes, die für diese Methode implementiert werden sollen. Auf den Referenzseiten für die IFilter-Methoden werden die schnittstellenspezifischen Codes in FACILITY_ITF zu implementierenden Ergebniscodes angegeben, und der Inhaltsindizierungsclient kann auch alle generischen Ergebniscodes verarbeiten, z. B. FACILITY_NULL und FACILITY_WIN32. Weitere Informationen finden Sie unter Struktur von COM-Fehlercodes.

COM-Methoden, die nicht implementiert sind

Die IFilter-Schnittstelle muss mindestens IPersistStream implementieren, aber keine zusätzlichen von IPersist abgeleiteten Schnittstellen implementieren.

Windows Search muss die in der folgenden Tabelle aufgeführten COM-Methoden nicht implementieren.

Methode, die nicht erforderlich ist	BESCHREIBUNG
IPersistStream::IsDirty	Filter sollten E_NOTIMPL zurückgeben.
IPersistStream::Save	Filter sollten E_NOTIMPL zurückgeben.
IPersistStream::GetSizeMax	Filter sollten E_NOTIMPL zurückgeben.
IFilter::BindRegion	Filter sollten E_NOTIMPL zurückgeben.

Zusätzliche Ressourcen

Das auf GitHub verfügbare IFilterSample-Codebeispiel veranschaulicht das Erstellen einer IFilter-Basisklasse zum Implementieren der IFilter-Schnittstelle.
Eine Übersicht über den Indizierungsprozess finden Sie unter Der Indizierungsprozess.
Eine Übersicht über Dateitypen finden Sie unter Dateitypen.
Informationen zum Abfragen von Dateizuordnungsattributen für einen Dateityp finden Sie unter PerceivedTypes, SystemFileAssociations und Anwendungsregistrierung.