Instalando e registrando manipuladores de protocolo (Pesquisa do Windows)

A instalação de um manipulador de protocolo envolve a cópia das DLL(s) para um local apropriado no diretório Arquivos de Programas e, em seguida, o registro do manipulador de protocolo por meio do registro. O aplicativo de instalação também pode adicionar uma raiz de pesquisa e regras de escopo para definir um escopo de rastreamento padrão para a fonte de dados do Shell.

Este tópico é organizado da seguinte maneira:

• Sobre URLs
• Implementando interfaces de manipulador de protocolo
  • ISearchProtocol e ISearchProtocol2
  • IUrlAccessor, IUrlAccessor2, IUrlAccessor3 e IUrlAccessor4
  • IProtocolHandlerSite
• Implementando manipuladores de filtro para contêineres
• Instalando e registrando um manipulador de protocolo
  • Diretrizes para registrar um manipulador de protocolo
  • Registrando um manipulador de protocolo
  • Registrando o manipulador de tipo de arquivo do manipulador de protocolo
• Garantindo que seus itens sejam indexados
• tópicos relacionados

Sobre urls

O Windows Search usa URLs para identificar exclusivamente itens na hierarquia da fonte de dados do Shell. A URL que é o primeiro nó na hierarquia é chamada raiz de pesquisa; A Pesquisa do Windows começará a indexar na raiz de pesquisa, solicitando que o manipulador de protocolo enumere links filho para cada URL.

A estrutura de URL típica é:

<protocol>:// [{user SID}/] <localhost>/<path>/[<ItemID>]

A sintaxe de URL é descrita na tabela a seguir.

O Indexador de Pesquisa do Windows corta a barra final das URLs. Como resultado, você não pode contar com a existência de uma barra final para identificar um diretório versus um item. Seu manipulador de protocolo deve ser capaz de lidar com essa sintaxe de URL. Verifique se o nome do protocolo selecionado para identificar a fonte de dados do Shell não está em conflito com os atuais. Recomendamos esta convenção de nomenclatura: companyName.scheme.

Para obter mais informações sobre como criar uma fonte de dados do Shell, consulte Implementando as interfaces básicas de objeto de pasta.

Implementando interfaces de manipulador de protocolo

A criação de um manipulador de protocolo requer a implementação das três interfaces a seguir:

• ISearchProtocol para gerenciar objetos UrlAccessor.
• IUrlAccessor para expor propriedades e identificar filtros apropriados para itens na fonte de dados do Shell.
• IFilter para filtrar arquivos proprietários ou para enumerar e filtrar arquivos armazenados hierarquicamente.

Além das três interfaces obrigatórias listadas, as outras interfaces são opcionais e você tem a liberdade de implementar as interfaces opcionais mais apropriadas para a tarefa em questão.

ISearchProtocol e ISearchProtocol2

As interfaces SearchProtocol inicializam e gerenciam os objetos urlAccessor do manipulador de protocolo. A interface ISearchProtocol2 é uma extensão opcional do ISearchProtocol e inclui um método extra para especificar mais informações sobre o usuário e o item.

Iurlaccessor, iurlaccessor2, iurlaccessor3 e IUrlAccessor4

As interfaces do IUrlAccessor são descritas na tabela a seguir.

O objeto UrlAccessor é instanciado e inicializado por um objeto SearchProtocol. As interfaces IUrlAccessor fornecem acesso a informações importantes por meio dos métodos descritos na tabela a seguir.

IProtocolHandlerSite

A interface IProtocolHandlerSite é usada para instanciar um manipulador de filtro, que é hospedado em um processo isolado. O manipulador de filtro apropriado é obtido para um CLSID (identificador de classe persistente), uma classe de armazenamento de documento ou uma extensão de nome de arquivo especificado. O benefício de solicitar que o processo de host se associe ao IFilter é que o processo de host pode gerenciar o processo de localização de um manipulador de filtro apropriado e controlar a segurança envolvida na chamada do manipulador.

Implementando manipuladores de filtro para contêineres

Se você estiver implementando um manipulador de protocolo hierárquico, deverá implementar um manipulador de filtro para um contêiner que enumera URLs filho. Um manipulador de filtro é uma implementação da interface IFilter . O processo de enumeração é um loop através dos métodos IFilter::GetChunk e IFilter::GetValue da interface IFilter; cada URL filho é exposta como valor da propriedade.

IFilter::GetChunk retorna as propriedades do contêiner. Para enumerar URLs filhas, IFilter::GetChunk retorna uma das seguintes opções:

• PKEY_Search_UrlToIndex:

  URL para o item sem o tempo da última modificação. IFilter::GetValue retorna um PROPVARIANT que contém a URL filho.

• PKEY_Search_UrlToIndexWithModificationTime:

  A URL e a hora da última modificação. IFilter::GetValue retorna um PROPVARIANT que contém um vetor da URL filha e a data da última modificação.

Retornar PKEY_Search_UrlToIndexWithModificationTime é mais eficiente porque o indexador pode determinar imediatamente se o item precisa ser indexado sem chamar os métodos ISearchProtocol::CreateAccessor e IUrlAccessor::GetLastModified .

O código de exemplo a seguir demonstra como retornar a propriedade PKEY_Search_UrlToIndexWithModificationTime .

// Parameters are assumed to be valid

HRESULT GetPropVariantForUrlAndTime
    (PCWSTR pszUrl, const FILETIME &ftLastModified, PROPVARIANT **ppPropValue)
{
    *ppPropValue = NULL;

    // Allocate the propvariant pointer.
    size_t const cbAlloc = sizeof(**ppPropValue);
    *ppPropValue = (PROPVARIANT *)CoTaskMemAlloc(cbAlloc));

    HRESULT hr = *ppPropValue ? S_OK : E_OUTOFMEMORY;

    if (SUCCEEDED(hr))
    {
        PropVariantInit(*ppPropValue);  // Zero init the value

        // Now allocate enough memory for 2 nested PropVariants.
        // PKEY_Search_UrlToIndexWithModificationTime is an array of two PROPVARIANTs.
        PROPVARIANT *pVector = (PROPVARIANT *)CoTaskMemAlloc(sizeof(*pVector) * 2);
        hr = pVector ? S_OK : E_OUTOFMEMORY;

        if (SUCCEEDED(hr))
        {
            // Set the container PROPVARIANT to be a vector of two PROPVARIANTS.
            (*ppPropValue)->vt = VT_VARIANT | VT_VECTOR;
            (*ppPropValue)->capropvar.cElems = 2;
            (*ppPropValue)->capropvar.pElems = pVector;
            PWSTR pszUrlAlloc;
            hr = SHStrDup(pszUrl, &pszUrlAlloc);

            if (SUCCEEDED(hr))
            {
                // Now fill the array of PROPVARIANTS.
                // Put the pointer to the URL into the vector.
                (*ppPropValue)->capropvar.pElems[0].vt = VT_LPWSTR; 
                (*ppPropValue)->capropvar.pElems[0].pwszVal = pszUrlAlloc;

                 // Put the FILETIME into vector.
                (*ppPropValue)->capropvar.pElems[1].vt = VT_FILETIME; 
                (*ppPropValue)->capropvar.pElems[1].filetime = ftLastModified;
            }

            else
            {
                CoTaskMemFree(pVector);
            }
        }
 
        if (FAILED(hr))
        {
            CoTaskMemFree(*ppPropValue);
            *ppPropValue = NULL;
        }
    }
    return S_OK;
}

Instalando e registrando um manipulador de protocolo

A instalação de manipuladores de protocolo envolve copiar as DLL(s) para um local apropriado no diretório Arquivos de Programas e, em seguida, registrar as DLL(s). Os manipuladores de protocolo devem implementar o auto-registro para instalação. O aplicativo de instalação também pode adicionar uma raiz de pesquisa e regras de escopo para definir um escopo padrão de rastreamento para a fonte de dados do Shell, conforme discutido em Garantindo que seus itens sejam indexados no final deste tópico.

Diretrizes para registrar um manipulador de protocolo

Você deve seguir estas diretrizes ao registrar um manipulador de protocolo:

• O instalador deve usar o instalador EXE ou MSI.
• As notas de versão devem ser fornecidas.
• Uma entrada Adicionar ou Remover Programas deve ser criada para cada complemento instalado.
• O instalador deve assumir todas as configurações do Registro para o tipo de arquivo ou armazenamento específico que o suplemento atual reconhece.
• 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 novamente.
• O instalador deve definir um escopo de rastreamento padrão para o indexador adicionando uma raiz de pesquisa e regras de escopo usando o Gerenciador de Escopo de Rastreamento (CSM).

Registrando um manipulador de protocolo

Você precisa fazer quatorze entradas no registro para registrar o componente do manipulador de protocolo, em que:

• Ver_Ind_ProgID é o ProgID independente de versão da implementação do manipulador de protocolo.
• Ver_Dep_ProgID é o ProgID dependente da versão da implementação do manipulador de protocolo.
• CLSID_1 é o CLSID da implementação do manipulador de protocolo.

Para registrar um manipulador de protocolo:

1. Registre o ProgID independente de versão com as seguintes chaves e valores:

   HKEY_CLASSES_ROOT
      <Ver_Ind_ProgID>
         (Default) = <Protocol Handler Class Description>
   

   HKEY_CLASSES_ROOT
      <Ver_Ind_ProgID>
         CLSID
            (Default) = {CLSID_1}
   

   HKEY_CLASSES_ROOT
      <Ver_Ind_ProgID>
         CurVer
            (Default) = <Ver_Dep_ProgID>
   

2. Registre o ProgID dependente da versão com as seguintes chaves e valores:

   HKEY_CLASSES_ROOT
      <Ver_Dep_ProgID>
         (Default) = <Protocol Handler Class Description>
   

   HKEY_CLASSES_ROOT
      <Ver_Dep_ProgID>
         CLSID
            (Default) = {CLSID_1}
   

3. Registre o CLSID do manipulador de protocolo com as seguintes chaves e valores:

   HKEY_CLASSES_ROOT
      {CLSID_1}
         (Default) = <Protocol Handler Class Description>
   

   HKEY_CLASSES_ROOT
      {CLSID_1}
         {InprocServer32}
            (Default) = <DLL Install Path>
            Threading Model = Both
   

   HKEY_CLASSES_ROOT
      {CLSID_1}
         <ProgID>
            (Default) = <Ver_Dep_ProgID>
   

   HKEY_CLASSES_ROOT
      {CLSID_1}
         <ShellFolder>
            Attributes = dword:a0180000
   

   HKEY_CLASSES_ROOT
      {CLSID_1}
         TypeLib
            (Default) = {LIBID of PH Component}
   

   HKEY_CLASSES_ROOT
      {CLSID_1}
         VersionIndependentProgID
            (Default) = <Ver_Ind_ProgID>
   

4. Registre o manipulador de protocolo com o Windows Search. No exemplo a seguir, <Nome> do Protocolo é o nome do próprio protocolo, como arquivo, mapi e assim por diante:

   HKEY_LOCAL_MACHINE
      SOFTWARE
         Microsoft
            Windows Search
               ProtocolHandlers
                  <Protocol Name> = <Ver_Dep_ProgID>
   

   HKEY_CURRENT_USER
      SOFTWARE
         Microsoft
            Windows Search
               ProtocolHandlers
                  <Protocol Name> = <Ver_Dep_ProgID>
   

   Antes do Windows Vista:

   HKEY_CURRENT_USER
      SOFTWARE
         Microsoft
            Windows Desktop Search
               DS
                  Index
                     ProtocolHandlers
                        <Protocol Name>
                           HasRequirements = dword:00000000
                           HasStartPage = dword:00000000
   

Registrando o manipulador de tipo de arquivo do manipulador de protocolo

Você precisa fazer duas entradas no registro para registrar o manipulador de tipo de arquivo do manipulador de protocolo (que também é conhecido como uma extensão shell).

1. HKEY_LOCAL_MACHINE
      SOFTWARE
         Microsoft
            Windows
               CurrentVersion
                  Explorer
                     Desktop
                        NameSpace
                           {CLSID of PH Implementation}
                              (Default) = <Shell Implementation Description>
   

2. HKEY_LOCAL_MACHINE
      SOFTWARE
         Microsoft
            Windows
               CurrentVersion
                  Explorer
                     Shell Extensions
                        Approved
                           {CLSID of PH Implementation} = <Shell Implementation Description>
   

Garantindo que seus itens sejam indexados

Depois de implementar o manipulador de protocolo, você deve especificar quais itens do Shell seu manipulador de protocolo deve indexar. Você pode usar o Gerenciador de Catálogos para iniciar a re indexação (para obter mais informações, consulte Usando o Gerenciador de Catálogos). Ou você também pode usar o Gerenciador de Escopo de Rastreamento (CSM) para configurar regras padrão que indicam as URLs que você deseja que o indexador rastreie (para obter mais informações, consulte Como usar o Gerenciador de Escopo de Rastreamento e Gerenciar Regras de Escopo). Você também pode adicionar uma raiz de pesquisa (para obter mais informações, consulte Gerenciando raízes de pesquisa). Outra opção disponível para você é seguir o procedimento no exemplo ReIndex em Exemplos de Código de Pesquisa do Windows.

A interface ISearchCrawlScopeManager fornece métodos que notificam o mecanismo de pesquisa sobre contêineres para rastrear e/ou monitorar, e itens nesses contêineres para incluir ou excluir durante o rastreamento ou monitoramento. No Windows 7 e posterior, ISearchCrawlScopeManager2 estende ISearchCrawlScopeManager com o método ISearchCrawlScopeManager2::GetVersion que obtém a versão, que informa aos clientes se o estado do CSM foi alterado.

Tópicos relacionados

Conceitual

Noções básicas sobre manipuladores de protocolo

Desenvolvendo manipuladores de protocolo

Notificando o índice de alterações

Adicionando ícones e menus de contexto

Exemplo de código: extensões de shell para manipuladores de protocolo

Criando um conector de pesquisa para um manipulador de protocolo

Depurando manipuladores de protocolo