Implementando manipuladores de filtro na Pesquisa do Windows

Artigo
06/13/2023

É importante que você entenda a estrutura de DLL necessária de um manipulador de filtro (uma implementação da interface IFilter ).

Este tópico é organizado da seguinte maneira:

Implementando e exportando os pontos de entrada de DLL
Implementando a classe IFilter e a fábrica de classes
Herdando as interfaces COM
Implementando os métodos de interface COM
- Métodos COM que não são implementados
Recursos adicionais
Tópicos relacionados

Implementando e exportando os pontos de entrada de DLL

Cada DLL de IFilter (indicada por Ifilter.dll nesta seção) deve implementar e exportar os pontos de entrada a seguir. Esses pontos de entrada normalmente são exportados usando um arquivo de definição de módulo (.def) para a interface IFilter ou usando o palavra-chave __declspec(dllexport). O arquivo DLL pode ser registrado para estar em qualquer pasta, mas geralmente reside na pasta %SystemRoot%\system32.

Os pontos de entrada de DLL são listados e descritos na tabela a seguir.

Nome da DLL	Descrição da DLL
Dllregisterserver	O ponto de entrada DllRegisterServer registra a DLL como um filtro no registro. Registre a DLL executando o programa regsvr32.exe com o nome de arquivo DLL da interface IFilter como um argumento: `regsvr32.exe %SystemRoot%\system32\Ifilter.dll`
Função DllUnregisterServer	O ponto de entrada da função DllUnregisterServer remove a DLL como um manipulador persistente no registro. Cancele o registro da DLL executando o programa regsvr32.exe com o `/u` sinalizador : `regsvr32.exe /u %SystemRoot%\system32\Ifilter.dll`
Função DllGetClassObject	O cliente de indexação de conteúdo chama o ponto de entrada da Função DllGetClassObject , por meio do COM (Component Object Model), para criar um objeto de fábrica de classe para a interface IFilter e para obter um ponteiro para a interface de fábrica de classe desse objeto.
Função DllCanUnloadNow	O cliente de indexação de conteúdo chama o ponto de entrada da função DllCanUnloadNow , por meio de COM, para determinar se é possível descarregar a DLL IFilter . A interface IFilter é descarregada depois de não ser usada por um intervalo de tempo, conforme especificado pelo valor do Registro FilterIdleTimeOut.

Implementando a classe IFilter e a fábrica de classes

Pelo menos duas classes, como CFilter e CFilterCF, normalmente são implementadas por cada DLL IFilter . A classe CFilter produz o objeto de interface IFilter que implementa a funcionalidade de filtragem de conteúdo. Suas funções membro implementam os métodos de interface da interface IFilter . Cada classe IFilter requer um CLSID (identificador de classe exclusivo), que o implementador de interface IFilter gera.

A classe CFilterCF produz o objeto class-factory para a interface IFilter . A fábrica de classes é chamada, por meio de sua interface IClassFactory Interface , pelo ponto de entrada da função DllGetClassObject da DLL. A classe CFilterCF cria o objeto CFilter e retorna um ponteiro para IUnknown. Em casos mais complexos, um IFilter pode implementar uma hierarquia de classe no lugar da única classe CFilter.

Herdando as interfaces COM

O Windows Search 3.0 e posteriores exigem que você use IPersistStream pelos seguintes motivos:

Para garantir o desempenho e a compatibilidade futura.
Para ajudar a aumentar a segurança. IFilters implementados com IPersistStream são mais seguros porque o contexto no qual a interface IFilter é executada não precisa dos direitos para abrir arquivos no disco ou pela rede.
Embora o Windows Search use apenas IPersistStream, a classe de interface IFilter também pode herdar as implementações da interface IPersistFile e/ou interface IPersistStorage para compatibilidade com versões anteriores.

Essas interfaces são declaradas em arquivos incluídos do diretório mssdk\include e têm IIDs (identificadores de interface predefinidos). O cliente de indexação de conteúdo consulta a interface IFilter por meio de IUnknown para determinar quais dessas interfaces usar ao filtrar conteúdo.

Implementando os métodos de interface COM

A interface IFilter implementa os métodos IUnknown para a classe de interface IFilter e a fábrica de classe de interface IFilter . A tabela a seguir lista, em ordem vtable, as interfaces e métodos específicos da interface IFilter que a interface IFilter deve implementar. A interface IFilter deve implementar pelo menos IPersistStream, mas pode implementar interfaces adicionais derivadas de IPersist.

Interface COM	Método
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, Load, Save, GetSizeMax
Ipersiststream	IsDirty, Load, Save, GetSizeMax

A página de referência para cada método especifica os parâmetros e o comportamento funcional para esse método. Cada página de referência também fornece os códigos de resultado a serem implementados para esse método. As páginas de referência para os métodos IFilter fornecem os códigos específicos da interface em FACILITY_ITF códigos de resultado a serem implementados e o cliente de indexação de conteúdo também pode lidar com qualquer um dos códigos de resultado genéricos, como FACILITY_NULL e FACILITY_WIN32. Para obter mais informações, consulte Estrutura de códigos de erro COM.

Métodos COM que não são implementados

A interface IFilter deve implementar pelo menos IPersistStream, mas não precisa implementar interfaces adicionais derivadas de IPersist.

O Windows Search não precisa implementar os métodos COM listados na tabela a seguir.

Método que não é necessário	Descrição
IPersistStream::IsDirty	Os filtros devem retornar E_NOTIMPL.
IPersistStream::Save	Os filtros devem retornar E_NOTIMPL.
IPersistStream::GetSizeMax	Os filtros devem retornar E_NOTIMPL.
IFilter::BindRegion	Os filtros devem retornar E_NOTIMPL.

Recursos adicionais

O exemplo de código IFilterSample , disponível no GitHub, demonstra como criar uma classe base IFilter para implementar a interface IFilter .
Para obter uma visão geral do processo de indexação, consulte O processo de indexação.
Para obter uma visão geral dos tipos de arquivo, consulte Tipos de arquivo.
Para consultar atributos de associação de arquivo para um tipo de arquivo, consulte PerceivedTypes, SystemFileAssociations e Application Registration.