Partilhar via

Desenvolvendo suplementos IFilter

  • Artigo

Observação

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

Você pode estender a Pesquisa de Área de Trabalho do Microsoft Windows (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 partes 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 partes de texto. O WDS adiciona as propriedades e o texto retornados pelo filtro ao catálogo. O WDS pode indexar qualquer tipo de arquivo para o qual ele tenha um filtro registrado.

Em algumas circunstâncias, você não precisa escrever um novo filtro. O WDS 2.x contém filtros para mais de 200 tipos de itens (incluindo itens de texto não criptografado, como arquivos HTML, XML e código-fonte) e usa a mesma tecnologia IFilterque 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 não criptografado. Se você tiver um tipo de arquivo que possa ser processado por um filtro de SharePoint Services existente ou pelo filtro de texto não criptografado, poderá adicionar a extensão de nome de arquivo e filtrar GUID ao Registro para que o WDS possa localizá-lo e usá-lo (consulte Para registrar um suplemento de filtro para obter mais informações).

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

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

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 em disco. A interface IPersistStream é o método preferencial para compatibilidade com o Windows Vista.
  • Interface IPersistFile – para carregar dados de um arquivo. Não há suporte para essa interface no Windows Vista.
  • Interface IPersistStorage – para carregar dados de um armazenamento estruturado OLE COM.

Um suplemento de filtro usa essas interfaces para obter o conteúdo do item e devolvê-los iterativamente ao índice até que o final do arquivo seja atingido. 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

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

Método Descrição
Init() Inicializa uma sessão de filtragem.
GetChunk() Posiciona o filtro no início da primeira ou próxima parte e retorna um descritor.
GetText() Recupera o texto da parte atual.
GetValue() Recupera valores de propriedade da parte atual.
BindRegion() Atualmente reservado para uso interno; não implemente. Esse método retorna E_NOTIMPL.

 

Ipersiststream

Essa interface carrega um arquivo de um fluxo para processamento mais seguro do que a Interface IPersistFile porque o contexto no qual um filtro IPersistStream é executado não precisa dos direitos de abrir arquivos no disco ou na rede. Dos dois métodos para acessar um único arquivo, esse é o método preferencial para compatibilidade com o Windows.

Método Descrição
IsDirty() Verifica se houve uma alteração. Esse método retorna E_NOTIMPL em filtros.
InitNew() Cria um novo armazenamento. Esse método retorna E_NOTIMPL em filtros.
Load() Inicializa um objeto do fluxo de onde ele foi salvo anteriormente.
Save() Salva um objeto no fluxo especificado e indica se o objeto deve redefinir seu sinalizador de 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 tem suporte no Windows Vista.

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

 

Ipersiststorage

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

Método Descrição
IsDirty() Verifica se houve uma alteração. Esse método retorna E_NOTIMPL em filtros.
InitNew() Cria um novo armazenamento. Esse método retorna E_NOTIMPL em filtros.
Load() Salva o armazenamento. Esse método retorna E_NOTIMPL em filtros.
Save() Retorna o tamanho em bytes do fluxo necessário para salvar o objeto. Esse método retorna E_NOTIMPL em filtros.
SaveCompleted() 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.

 

Saída de propriedades com filtros

A finalidade 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 partes 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 propriedade associados à parte. Esse processo se repete até getChunk relatar que não há mais partes no documento.

O método GetChunk recupera informações sobre o primeiro ou 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 uma ID de parte que aumenta monotonicamente, status informações sobre como a parte atual se relaciona com a parte anterior, um sinalizador que indica se a parte contém texto ou um valor, a localidade da parte e a especificação da propriedade da parte. A especificação da propriedade é um FULLPROPSPEC que consiste em um CLSID e um identificador de propriedade de cadeia de caracteres ou inteiro (por exemplo, D5CDD505-2E9C-101B-9397-08002B2CF9AE/PerceivedType). Ele identifica o tipo de propriedade em vez do próprio valor da propriedade.

O identificador de localidade de parte é usado para escolher um separador de palavras apropriado e é muito importante identificá-lo 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 do arquivo e ele atualmente não contiver informações de localidade, você deverá adicionar um recurso de usuário para habilitar a identificação de localidade adequada. O uso de um separador de palavras incompatível pode levar a uma experiência de consulta incorreta para o usuário.

O GetChunk gerencia apenas o acesso a partes e não retorna o texto ou o valor da propriedade em si. Em vez disso, chamadas subsequentes para GetText e GetValue recuperam o corpo da parte. GetText retorna partes de texto, que são cadeias de caracteres Unicode, da parte CHUNK_TEXT atual. Se a parte atual for muito grande, mais de uma chamada para o método GetText poderá ser necessária. Cada chamada para o método GetText recupera o texto que segue imediatamente o texto da última chamada para o método GetText . Por exemplo, o último caractere de uma chamada pode estar no meio de uma palavra e o primeiro caractere na próxima chamada continuaria com essa palavra. Os mecanismos de pesquisa devem lidar com essa situação.

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

Valores da propriedade

Os filtros devem gerar, no mínimo, as propriedades a seguir, que são as colunas padrão na exibição de resultados do WDS.

GUID PROPSPEC Nome amigável Descrição
F29F85E0-4FF9-1068-AB91-08002B27B3D9 2 PrimaryTitle Título exibido para este item.
F29F85E0-4FF9-1068-AB91-08002B27B3D9 4 PrimaryAuthors Pessoa mais associada a este item.
D5CDD505-2E9C-101B-9397-08002B2CF9AE PrimaryDate PrimaryDate Data mais importante para o item, como data recebida para email ou modificada para arquivos.
D5CDD505-2E9C-101B-9397-08002B2CF9AE PerceivedType PerceivedType Tipo de arquivo que está sendo analisado. Deve corresponder a um dos tipos de Pesquisa da Área de Trabalho do Windows listados em Tipo Percebido do WDS.

 

Para itens de texto não criptografado, o WDS extrai todas as propriedades definidas pelo texto e pelo sistema, como tamanho do arquivo ou extensão, na inclusão de novos tipos de arquivo de texto não criptografado para o índice). Outros tipos de propriedades que podem ser retornadas ao índice incluem:

  • Para arquivos: author, title, status, keywords
  • Para a mídia: álbum, gênero, câmera make, data tirada
  • 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, a 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 está relacionado. Muitas dessas propriedades são usadas para exibir os resultados da pesquisa na exibição de resultados do WDS. Por exemplo, a propriedade Title de um arquivo é mostrada como a coluna main na exibição de resultados padrão. Os objetos IFilter devem gerar todas as propriedades relacionadas ao tipo de item que estão analisando. Propriedades personalizadas não podem ser adicionadas no WDS 2.x. Para obter uma lista completa das propriedades disponíveis, consulte o Esquema do WDS.

Filtrar instalação do suplemento

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

  • O instalador deve usar o instalador EXE ou MSI.
  • As notas sobre a versão devem ser fornecidas.
  • Uma entrada Adicionar/Remover Programas deve ser criada para cada suplemento instalado.
  • O instalador deve assumir todas as configurações do Registro para o tipo de arquivo ou repositório específico que o suplemento atual entende.
  • Se um suplemento anterior estiver sendo substituído, o instalador deverá notificar o usuário.
  • 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 armazenar novamente.

CLSIDs necessários para registro

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

  • O primeiro identifica o manipulador persistente de todos os filtros, IID_IFilter, que é {89BCB740-6119-101A-BCB7-00DD010655AF}. Esse CLSID é constante para todos os filtros que implementam IFilter.
  • O segundo (o valor da chave IID_IFilter) identifica a implementação de IFilter para o 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 será 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, portanto, recomendamos que você os instale em Arquivos de Programas e inclua um caminho completo para o filtro no Registro. Por motivos de segurança, também é prudente especificar um caminho completo para sua DLL no registro. Caso contrário, uma versão "Cavalo de Tróia" da sua DLL poderá ser carregada se estiver no caminho do processo antes da sua versão.

 

Modelo de registro

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

  1. De CLSIDs localizados em:

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

    HKEY_CURRENT_USER\SOFTWARE\Microsoft\RSSearch\ContentIndexCommon\Filters

  2. No tipo de conteúdo do arquivo em:

    HKEY_LOCAL_MACHINE\SOFTWARE\Classes\MIME\Database\Content Type

  3. Na extensão de nome de arquivo (igual à API LoadIFilter do Win32) 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>>>

  4. De Padrão em:

    HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\RSSearch\ContentIndexCommon\Filters

Para registrar um suplemento de filtro

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

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

  1. 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}

  2. Registre a implementação de 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

  3. Registre a implementação de IFilter com a Pesquisa da Área de Trabalho do Windows com a seguinte chave e valor:

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

Referência

SchemaTable

Tipos percebidos

Desenvolvendo manipuladores de protocolo

Outros recursos

Ifilter