Implementazione di gestori di filtri in Windows Search

Articolo
06/13/2023

È importante comprendere la struttura DLL richiesta di un gestore di filtri (un'implementazione dell'interfaccia IFilter ).

Questo argomento è organizzato come segue:

Implementazione ed esportazione dei punti di ingresso della DLL
Implementazione della classe IFilter e della class factory
Ereditarietà delle interfacce COM
Implementazione dei metodi di interfaccia COM
- Metodi COM non implementati
Risorse aggiuntive
Argomenti correlati

Implementazione ed esportazione dei punti di ingresso della DLL

Ogni DLL IFilter (indicato da Ifilter.dll in questa sezione) deve implementare ed esportare i punti di ingresso seguenti. Questi punti di ingresso vengono in genere esportati usando un file module-definition (def) per l'interfaccia IFilter o usando la parola chiave __declspec(dllexport). Il file DLL può essere registrato in qualsiasi cartella, ma in genere si trova nella cartella %SystemRoot%\system32.

I punti di ingresso dll sono elencati e descritti nella tabella seguente.

Nome DLL	Descrizione dll
Dllregisterserver	Il punto di ingresso DllRegisterServer registra la DLL come filtro nel Registro di sistema. Per registrare la DLL, eseguire il programma regsvr32.exe con il nome file DLL dell'interfaccia IFilter come argomento: `regsvr32.exe %SystemRoot%\system32\Ifilter.dll`
Funzione DllUnregisterServer	Il punto di ingresso della funzione DllUnregisterServer rimuove la DLL come gestore permanente nel Registro di sistema. Annullare la registrazione della DLL eseguendo il programma regsvr32.exe con il `/u` flag : `regsvr32.exe /u %SystemRoot%\system32\Ifilter.dll`
Funzione DllGetClassObject	Il client di indicizzazione del contenuto chiama il punto di ingresso della funzione DllGetClassObject tramite Component Object Model (COM), per creare un oggetto class factory per l'interfaccia IFilter e ottenere un puntatore all'interfaccia class factory di tale oggetto.
Funzione DllCanUnloadNow	Il client di indicizzazione del contenuto chiama il punto di ingresso della funzione DllCanUnloadNow tramite COM per determinare se è possibile scaricare la DLL IFilter . L'interfaccia IFilter viene scaricata dopo che è inutilizzata per un intervallo di tempo, come specificato dal valore del Registro di sistema FilterIdleTimeOut.

Implementazione della classe IFilter e della class factory

Almeno due classi, ad esempio CFilter e CFilterCF , vengono in genere implementate da ogni DLL IFilter. La classe CFilter produce l'oggetto interfaccia IFilter che implementa la funzionalità di filtro del contenuto. Le funzioni membro implementano i metodi di interfaccia dell'interfaccia IFilter . Ogni classe IFilter richiede un identificatore di classe univoco (CLSID), generato dall'implementazione dell'interfaccia IFilter .

La classe CFilterCF produce l'oggetto class-factory per l'interfaccia IFilter . La class factory viene chiamata, tramite l'interfaccia IClassFactory , dal punto di ingresso della funzione DllGetClassObject della DLL. La classe CFilterCF crea l'oggetto CFilter e restituisce un puntatore a IUnknown. In casi più complessi, un IFilter può implementare una gerarchia di classi al posto della singola classe CFilter.

Ereditarietà delle interfacce COM

Windows Search 3.0 e versioni successive richiedono l'uso di IPersistStream per i motivi seguenti:

Per garantire prestazioni e compatibilità futura.
Per aumentare la sicurezza. IFilter implementati con IPersistStream sono più sicuri perché il contesto in cui viene eseguita l'interfaccia IFilter non richiede i diritti per aprire i file sul disco o in rete.
Anche se Windows Search usa solo IPersistStream, la classe di interfaccia IFilter può anche ereditare l'interfaccia IPersistFile e/o le implementazioni dell'interfaccia IPersistStorage per garantire la compatibilità con le versioni precedenti.

Queste interfacce vengono dichiarate nei file inclusi nella directory mssdk\include e hanno identificatori di interfaccia predefiniti (IID). Il client di indicizzazione del contenuto esegue una query sull'interfaccia IFilter tramite IUnknown per determinare quale di queste interfacce usare durante il filtro del contenuto.

Implementazione dei metodi di interfaccia COM

L'interfaccia IFilter implementa i metodi IUnknown sia per la classe di interfaccia IFilter che per la factory della classe di interfaccia IFilter . Nella tabella seguente sono elencati, in ordine di tabella virtuale, interfacce e metodi specifici dell'interfaccia IFilter che devono essere implementati dall'interfaccia IFilter . L'interfaccia IFilter deve implementare almeno IPersistStream, ma può implementare interfacce aggiuntive derivate da IPersist.

Interfaccia COM	Metodo
Interfaccia IClassFactory	CreateInstance, LockServer
Interfaccia IClassFactory2	GetLicInfo, RequestLicKey, CreateInstanceLic
Ifilter	IFilter::Init, IFilter::GetChunk, IFilter::GetText, IFilter::GetValue, IFilter::BindRegion
Interfaccia IPersist	GetClassID
Interfaccia IPersistFile	IsDirty, Load, Save, SaveCompleted, GetCurFile
Interfaccia IPersistStorage	IsDirty, Load, Save, GetSizeMax
Ipersiststream	IsDirty, Load, Save, GetSizeMax

La pagina di riferimento per ogni metodo specifica i parametri e il comportamento funzionale per tale metodo. Ogni pagina di riferimento fornisce anche i codici dei risultati da implementare per tale metodo. Le pagine di riferimento per i metodi IFilter forniscono i codici specifici dell'interfaccia in FACILITY_ITF codici dei risultati da implementare e il client di indicizzazione del contenuto può anche gestire qualsiasi codice di risultato generico, ad esempio FACILITY_NULL e FACILITY_WIN32. Per altre informazioni, vedere Struttura dei codici di errore COM.

Metodi COM non implementati

L'interfaccia IFilter deve implementare almeno IPersistStream, ma non deve implementare interfacce aggiuntive derivate da IPersist.

Windows Search non deve implementare i metodi COM elencati nella tabella seguente.

Metodo non obbligatorio	Descrizione
IPersistStream::IsDirty	I filtri devono restituire E_NOTIMPL.
IPersistStream::Save	I filtri devono restituire E_NOTIMPL.
IPersistStream::GetSizeMax	I filtri devono restituire E_NOTIMPL.
IFilter::BindRegion	I filtri devono restituire E_NOTIMPL.

Risorse aggiuntive

L'esempio di codice IFilterSample , disponibile in GitHub, illustra come creare una classe di base IFilter per implementare l'interfaccia IFilter .
Per una panoramica del processo di indicizzazione, vedere Processo di indicizzazione.
Per una panoramica dei tipi di file, vedere Tipi di file.
Per eseguire query sugli attributi di associazione di file per un tipo di file, vedere PerceivedTypes, SystemFileAssociations e Application Registration.