Desenvolvendo complementos IFilter

2025-03-27

Observação

O Windows Desktop Search 2.x é uma tecnologia obsoleta que estava originalmente disponível como um suplemento para o Windows XP e Windows Server 2003. Em versões posteriores, use Windows Search em vez disso.

Você pode estender o Microsoft Windows Desktop Search (WDS) com suplementos de filtro, componentes que implementam a interface IFilter, para incluir novos tipos de arquivo. Os filtros são responsáveis por acessar e analisar dados em arquivos e por retornar pares de propriedades e valores, bem como pedaços de texto para indexação. Durante o processo de indexação, o WDS chama o filtro apropriado com a URL para cada arquivo ou item. O filtro primeiro extrai metadados que correspondem às propriedades marcadas como recuperáveis no esquema WDS, como título, tamanho do arquivo e data da última modificação. Em seguida, ele divide o conteúdo do item em pedaços de texto. O WDS adiciona as propriedades e o texto retornado pelo filtro ao catálogo. O WDS pode indexar qualquer tipo de ficheiro para o qual tenha um filtro registado.

Em algumas circunstâncias, não é necessário escrever um novo filtro. O WDS 2.x contém filtros para mais de 200 tipos de itens (incluindo itens de texto simples, como HTML, XML e arquivos de código-fonte) e usa a mesma tecnologia IFilterque o SharePoint Services. Se você já tiver filtros instalados para seus tipos de arquivo, o WDS poderá usar esses filtros existentes para indexar esses dados. Além disso, o WDS inclui um filtro geral para tipos de arquivo baseados em texto simples. Se você tiver um tipo de arquivo que possa ser processado por um filtro existente do SharePoint Services ou pelo filtro de texto sem formatação, poderá adicionar a extensão de nome de arquivo e o GUID do filtro ao Registro para que o WDS possa localizá-lo e usá-lo (consulte Registrar um suplemento de filtro para obter mais informações).

Se, no entanto, tiver um formato de ficheiro ou dados proprietários e não de texto simples, escrever uma implementação de filtro personalizada é a única maneira de garantir que o WDS possa indexar o formato de ficheiro no catálogo. Você pode ter apenas um suplemento de filtro para um tipo de arquivo, portanto, é possível substituir um filtro existente ou fazer com que outro filtro substitua o seu para um tipo de arquivo específico.

Esta seção contém os seguintes tópicos:

Interfaces de filtro necessárias
Propriedades de saída com filtros
- Valores de propriedade
Instalação do Suplemento de Filtro
Tópicos relacionados

Interfaces de filtro necessárias

Um suplemento de filtro deve implementar a interface IFiltere uma das seguintes interfaces:

IPersistStream - Para carregar dados de um fluxo. Isso é mais seguro do que usar arquivos porque nada é gravado no disco. A interface IPersistStream é o método preferido para compatibilidade direta com o Windows Vista.
IPersistFile Interface - Para carregar dados de um arquivo. Esta interface não é suportada no Windows Vista.
IPersistStorage Interface - Para carregar dados de um armazenamento estruturado OLE COM.

Um suplemento de filtro usa estas interfaces para obter o conteúdo do item e devolvê-lo iterativamente ao índice até alcançar o final do ficheiro. Um suplemento de filtro deve ser o mais robusto possível para lidar com arquivos corrompidos e aqueles que não atendem aos formatos de entrada esperados.

IFilter Interface

Esta é uma interface necessária para uma implementação de filtro. Para obter mais informações, consulte a IFilterreferência da interface.

Método	Descrição
Init()	Inicializa uma sessão de filtragem.
GetChunk()	Posiciona o filtro no início do primeiro ou próximo bloco e retorna um descritor.
GetText()	Recupera texto do bloco atual.
GetValue()	Recupera valores de propriedade do fragmento atual.
BindRegion()	Atualmente reservado para uso interno; não deve ser implementado. Esse método retorna E_NOTIMPL.

IPersistStream

Esta interface carrega um ficheiro de um fluxo para um processamento mais seguro do que a Interface IPersistFile, porque o contexto no qual um filtro da Interface IPersistStream é executado não necessita dos direitos para abrir quaisquer ficheiros no disco ou pela rede. Dos dois métodos para acessar um único arquivo, este é o método preferido para compatibilidade direta com o Windows.

Método	Descrição
IsDirty()	Verifica se houve alguma alteração. Esse método retorna E_NOTIMPL em filtros.
InitNew()	Cria um novo armazenamento. Esse método retorna E_NOTIMPL em filtros.
Carregar()	Inicializa um objeto a partir do fluxo de dados onde foi anteriormente salvo.
Salvar()	Salva um objeto no fluxo especificado e indica se o objeto deve redefinir seu sinalizador sujo. Esse método retorna E_NOTIMPL em filtros.
GetSizeMax()	Retorna o tamanho em bytes do fluxo necessário para salvar o objeto. Esse método retorna E_NOTIMPL em filtros.

IPersistFile

Essa interface carrega um arquivo por caminho absoluto e não é suportada no Windows Vista.

Método	Descrição
GetCurFile()	Obtém o nome atual do arquivo associado ao objeto. Retorna o caminho especificado em Load().
Carregar()	Abre o arquivo especificado e inicializa um objeto a partir do conteúdo do arquivo. Você pode atrasar a abertura do arquivo até precisar dele.
GetClassID()	Retorna o identificador de classe (CLSID) para o novo tipo de arquivo. Você deve usar uuidgen.exe para gerar um CLSID exclusivo.
IsDirty()	Precisa apenas retornar E_NOTIMPL em filtros
Salvar()	Precisa apenas retornar E_NOTIMPL em filtros
SalvarConcluído()	Precisa apenas retornar E_NOTIMPL em filtros

IPersistStorage

Essa interface suporta o modelo de armazenamento estruturado, no qual cada objeto contido tem seu próprio armazenamento aninhado no armazenamento do contêiner. Como IPersistFile Interface, essa interface é carregada por caminho absoluto e não é suportada no Windows Vista.

Método	Descrição
IsDirty()	Verifica se houve alguma alteração. Esse método retorna E_NOTIMPL em filtros.
InitNew()	Cria um novo armazenamento. Esse método retorna E_NOTIMPL em filtros.
Load()	Poupa espaço de armazenamento. Esse método retorna E_NOTIMPL em filtros.
Salvar()	Retorna o tamanho em bytes do fluxo necessário para salvar o objeto. Esse método retorna E_NOTIMPL em filtros.
SalvarConcluído()	Reservado para uso interno. Esse método retorna E_NOTIMPL em filtros.
HandsOffStorage()	Reservado para uso interno. Esse método retorna E_NOTIMPL em filtros.

Propriedades de saída com filtros

O objetivo de um filtro é extrair o conteúdo e as propriedades dos arquivos para inclusão no índice de texto completo. O WDS primeiro chama o método Load nas implementações IPersistFile, IPersistStream ou IPersistStorage e, em seguida, invoca o método Init da implementação IFilter. GetChunk é chamado para recuperar segmentos de texto ou dados de valor de propriedade e, em seguida, GetText ou GetValue é chamado quantas vezes forem necessárias para recuperar todos os valores de texto ou de propriedade associados ao segmento. Esse processo se repete até que GetChunk informe que não há mais partes no documento.

O método GetChunk recupera informações sobre o primeiro ou o próximo bloco lógico de informações do arquivo que está sendo filtrado e retorna essas informações em uma estrutura STAT_CHUNK, incluindo um ID de bloco monotonicamente crescente, informações de status sobre como o bloco atual se relaciona com o bloco anterior, um sinalizador que indica se o bloco contém texto ou um valor, a localidade do pedaço e a especificação da propriedade do bloco. A especificação da propriedade é uma FULLPROPSPEC que consiste em um CLSID e um identificador de propriedade que pode ser um valor inteiro ou uma string (por exemplo, D5CDD505-2E9C-101B-9397-08002B2CF9AE/PerceivedType). Ele identifica o tipo de propriedade em vez do valor da propriedade em si.

O identificador de localidade de bloco é usado para escolher um separador de palavras apropriado e é muito importante que você o identifique corretamente. Se o filtro não puder determinar a localidade do texto, ele deverá assumir a localidade padrão do sistema, disponível usando GetSystemDefaultLCID. Se você controlar o formato de arquivo e ele atualmente não contém informações de localidade, você deve adicionar um recurso de usuário para habilitar a identificação de localidade adequada. Usar um separador de palavras incompatível pode levar a uma experiência de consulta ruim para o usuário.

GetChunk apenas gere o acesso a blocos e não retorna o texto ou o valor da propriedade propriamente dito. Em vez disso, chamadas subsequentes para GetText e GetValue recuperam o corpo do bloco. GetText retorna blocos de texto, que são cadeias de caracteres Unicode, do bloco CHUNK_TEXT atual. Se o bloco atual for muito grande, mais de uma chamada para o método GetText pode ser necessária. Cada chamada para o método GetText recupera o texto que segue imediatamente o texto da última chamada para o GetText método. Por exemplo, o último caractere de uma chamada pode estar no meio de uma palavra, e o primeiro caractere na próxima chamada continuaria essa palavra. Os motores de busca têm de lidar com esta situação.

GetValue retorna valores de propriedade para o bloco atual CHUNK_VALUE em estruturas PROPVARIANT, que podem conter uma ampla variedade de tipos de dados. GetValue deve alocar a estrutura PROPVARIANT por si só usando CoTaskMemAlloc. O chamador de GetValue é responsável por libertar a memória apontada pelo PROPVARIANT usando o PropVariantClear e por libertar a própria estrutura com o CoTaskMemFree. Para obter mais informações sobre PROPVARIANTs, consulte a referência PROPVARIANT.

Valores de propriedade

Os filtros devem produzir, no mínimo, as seguintes propriedades, que são as colunas padrão na visualização de resultados do WDS.

Identificador Único Global (GUID)	PROPSPEC	Nome amigável	Descrição
F29F85E0-4FF9-1068-AB91-08002B27B3D9	2	Título Primário	Título exibido para este item.
F29F85E0-4FF9-1068-AB91-08002B27B3D9	4	Autores Primários	Pessoa mais associada a este item.
D5CDD505-2E9C-101B-9397-08002B2CF9AE	Data Primária	Data Primária	Data mais relevante de um item, como a data de receção do e-mail ou a modificação de ficheiros.
D5CDD505-2E9C-101B-9397-08002B2CF9AE	TipoPercebido	TipoPercebido	Tipo de arquivo que está sendo analisado. Deve corresponder a um dos tipos de Pesquisa na Área de Trabalho do Windows listados em WDS Tipo Percebido.

Para itens de texto simples, o WDS extrai todo o texto e propriedades definidas pelo sistema, como tamanho de arquivo ou extensão, incluindo novos tipos de arquivo de texto sem formatação no índice). Outros tipos de propriedades que podem ser retornadas ao índice incluem:

Para ficheiros: autor, título, estado, palavras-chave
Para mídia: álbum, gênero, marca da câmera, data tomada
Para comunicações: de, para, cc, importância
Para contatos: cargo, telefone comercial, empresa

A lista acima agrupa propriedades comuns a um Tipo Percebido especificado; no entanto, qualquer propriedade pode ser usada independentemente do tipo. Por exemplo, empresa pode ser usada para o nome do empregador de um contato e também pode ser usada para se referir ao nome de um cliente ao qual o arquivo se relaciona. Muitas dessas propriedades são usadas para exibir resultados de pesquisa na exibição de resultados do WDS. Por exemplo, a propriedade Title de um arquivo é mostrada como a coluna principal na exibição de resultados padrão. Os objetos IFilter devem produzir todas as propriedades relacionadas ao tipo de item que estão analisando. Não é possível adicionar propriedades personalizadas ao WDS 2.x. Para uma lista completa das propriedades disponíveis, consulte o WDS Schema.

Instalação do suplemento de filtro

A instalação do filtro envolve copiar a DLL para um local apropriado no diretório Arquivos de Programas e registrá-la. Os filtros devem implementar o auto-registro para instalação e devem seguir estas diretrizes:

O instalador deve usar o instalador EXE ou MSI.
Notas de versão devem ser fornecidas.
Uma entrada Adicionar ou Remover Programas deve ser criada para cada suplemento instalado.
O instalador deve assumir todas as configurações do Registro para o tipo de ficheiro específico ou armazenamento que o complemento atual compreende.
Se um suplemento existente for substituído, o instalador deve notificar o utilizador.
Se um suplemento mais recente tiver substituído o suplemento anterior, deverá haver a capacidade de restaurar a funcionalidade do suplemento anterior e torná-lo o suplemento padrão para esse tipo de arquivo ou armazenamento novamente.

CLSIDs necessários para o registo

Há três identificadores de classe, ou CLSIDs, associados a cada filtro. Você precisará gerar um ou mais deles (use uuidgen.exe) para registrar seu suplemento de filtro.

O primeiro identifica o manipulador persistente de todos os filtros, IID_IFilter, que é {89BCB740-6119-101A-BCB7-00DD010655AF}. Este CLSID é constante para todos os filtros que implementam IFilter.
O segundo (o valor da chave IID_IFilter) identifica a implementação do IFilter para seu tipo de arquivo. Essa chave contém um valor InprocServer32 que especifica o nome da DLL por caminho e o modelo de threading. Se o filtro estiver no caminho do sistema, como o diretório system32, um nome de arquivo é suficiente. Caso contrário, esse valor deve ter uma especificação de caminho completo.
O terceiro identifica o tipo de arquivo que o filtro processa e é retornado pelo método GetClassID em sua interface IPersist.

Observação

Em versões futuras dos sistemas operacionais da Microsoft, a instalação de arquivos no diretório system32 pode ficar mais difícil, por isso recomendamos que você os instale em Arquivos de Programas e inclua um caminho completo para o filtro no registro. Por razões de segurança, também é prudente especificar um caminho completo para sua DLL no registro. Caso contrário, uma versão "cavalo de Troia" da sua DLL pode ser carregada se acontecer de estar no caminho do processo antes da sua versão.

Modelo de Registo

Quando o WDS está pronto para filtrar um arquivo, ele procura no registro sob a extensão do arquivo para determinar qual filtro carregar. Em seguida, segue uma série de links de registro para encontrar o nome da DLL de filtro, nesta ordem:

Dos CLSIDs localizados em:

HKEY_CURRENT_USER\SOFTWARE\Microsoft\RSSearch\ContentIndexCommon\Filters\Override\RSApp

HKEY_CURRENT_USER\SOFTWARE\Microsoft\RSSearch\ContentIndexCommon\Filters
A partir do tipo de conteúdo do ficheiro em:

HKEY_LOCAL_MACHINE\SOFTWARE\Classes\MIME\Database\Content Type
A partir da extensão de nome de arquivo (o mesmo que Win32 LoadIFilter API) em:

HKEY_CURRENT_USER\SOFTWARE\Microsoft\RSSearch\ContentIndexCommon\Filters\Override\RSApp

HKEY_CURRENT_USER\SOFTWARE\Microsoft\RSSearch\ContentIndexCommon\Filters

HKEY_CLASSES_ROOT\extpersistentHandler->CLSID->IID_IFilter->CLSID
De Default em:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\RSSearch\ContentIndexCommon\Filters

Para registar um complemento de filtro

Você precisa fazer um total de oito entradas no registro para registrar seu suplemento de filtro, onde:

.ext é a nova extensão de nome de arquivo
GUID_1 pode ser qualquer novo GUID gerado para esta extensão
89BCB740-6119-101A-BCB7-00DD010655AF é o GUID da interface IFilter, que constitui uma constante para todas as implementações da IFilter.

Registre o manipulador persistente para a extensão de nome de arquivo com as seguintes chaves e valores:

HKEY_CLASSES_ROOT\<.ext>\PersistentHandler
   (Default) = {GUID_1}

HKEY_CLASSES_ROOT\CLSID\{GUID_1}
   (Default) = <Persistent Handler Description>

HKEY_CLASSES_ROOT\CLSID\{GUID_1}\PersistentAddinsRegistered
   (Default) = (Value Not Set)

HKEY_CLASSES_ROOT\CLSID\{GUID_1}\PersistentAddinsRegistered\{89BCB740-6119-101A-BCB7-00DD010655AF}
   (Default) = {CLSID of IFilter implementation}

HKEY_CLASSES_ROOT\CLSID\{GUID_1}\PersistentHandler
   (Default) = {GUID_1}

Registre a implementação do IFilter com as seguintes chaves e valores:

HKEY_CLASSES_ROOT\CLSID\{CLSID of IFilter implementation}
   (Default) = Extension IFilter Description">

HKEY_CLASSES_ROOT\CLSID\{CLSID of IFilter implementation}\InprocServer32
   (Default) = <DLL Install Path>
   ThreadingModel = Both

Registre a implementação do IFilter com o Windows Desktop Search com a seguinte chave e valor:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\RSSearch\ContentIndexCommon\Filters\Extension\<.ext>
   (Default) = {CLSID of IFilter implementation}"

Referência
TabelaEsquema
Tipos percebidos
Desenvolvendo manipuladores de protocolo
Outros recursos
IFilter