Instalar e registrar manipuladores de protocolo (Windows Search)

Artigo
12/23/2023

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
Implementar interfaces de manipulador de protocolo
Implementar manipuladores de filtro para contêineres
Instalar e registrar um manipulador de protocolo
Garantir 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 de raiz da pesquisa; o Windows Search começará a indexar na raiz da 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.

Sintaxe	Descrição
<protocol>	Identifica qual manipulador de protocolo invocar para a URL.
{user SID}	Identifica o contexto de segurança do usuário no qual o manipulador de protocolo é chamado. Se nenhum identificador de segurança de usuário (SID) for identificado, o manipulador de protocolo será chamado no contexto de segurança do serviço do sistema.
<caminho>	Define a hierarquia do repositório, em que cada barra ("/") é um separador entre nomes de pasta.
<ItemID>	Representa uma cadeia de caracteres exclusiva que identifica o item filho (por exemplo, o nome do arquivo).

O Windows Search Indexer corta a barra final das URLs. Como resultado, você não pode contar com a existência de uma barra final para diferenciar um diretório de um item. Seu manipulador de protocolo deve ser capaz de lidar com essa sintaxe de URL. Certifique-se de que o nome do protocolo selecionado para identificar a fonte de dados do Shell não esteja 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, confira Implementar 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 ISearchProtocole inclui um método extra para especificar mais informações sobre o usuário e o item.

IUrlAccessor, IUrlAccessor2, IUrlAccessor3 e IUrlAccessor4

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

Interface	Descrição
IUrlAccessor	Para uma URL especificada, a interface IUrlAccessor fornece acesso às propriedades do item exposto na URL. Ela também pode associar essas propriedades a um filtro específico do manipulador de protocolo (ou seja, um filtro diferente daquele associado ao nome do arquivo).
IUrlAccessor2 (opcional)	A interface IUrlAccessor2 estende IUrlAccessorcom métodos que obtêm uma página de código para as propriedades do item e sua URL de exibição e que obtêm o tipo de item na URL (documento ou diretório).
IUrlAccessor3 (opcional)	A interface IUrlAccessor3 estende IUrlAccessor2 com um método que obtém uma matriz de SIDs de usuário, permitindo que o host do protocolo de pesquisa represente esses usuários para indexar o item.
IUrlAccessor4 (opcional)	A interface IUrlAccessor4 estende a funcionalidade da interface IUrlAccessor3com um método que identifica se o conteúdo do item deve ser indexado.

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.

Método	Descrição
IUrlAccessor::GetLastModified	Retorna a hora em que a URL foi modificada pela última vez. Se essa hora for mais recente do que a última vez que o indexador processou essa URL, os manipuladores de filtro (implementações da interface IFilter) serão chamados para extrair os dados (possivelmente) alterados para esse item. Os horários modificados para diretórios são ignorados.
IUrlAccessor::IsDirectory	Identifica se a URL representa uma pasta que contém URLs filho.
IUrlAccessor::BindToStream	Associa-se a uma interface IStream que representa os dados de um arquivo em um armazenamento de dados personalizado.
IUrlAccessor::BindToFilter	Associa a um IFilter específico do manipulador de protocolo, que pode expor propriedades para o item.
IUrlAccessor4::ShouldIndexItemContent	Identifica se o conteúdo do item deve ser indexado.

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 identificador de classe persistente (CLSID), 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.

Implementar 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 por meio dos métodos IFilter::GetChunk e IFilter::GetValue da interface IFilter; cada URL filho é exposta como o valor da propriedade.

IFilter::GetChunk retorna as propriedades do contêiner. Para enumerar URLs filho, IFilter::GetChunk retorna um dos seguintes:

PKEY_Search_UrlToIndex:

A URL para o item sem a hora 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 filho e a hora 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.

Importante

// 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;
}

Observação

Um componente IFilter de contêiner deve sempre enumerar todas as URLs filho mesmo que as URLs filho não tenham sido alteradas, pois o indexador detecta exclusões por meio do processo de enumeração. Se a saída de data em um PKEY_Search_UrlToIndexWithModificationTime indicar que os dados não foram alterados, o indexador não atualizará os dados dessa URL.

Instalar e registrar 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 de rastreamento padrão para a fonte de dados do Shell, o que é abordado em Garantir 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/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 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 do Escopo de Rastreamento (CSM).

Registrar 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:

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>

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}

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>

Registre o manipulador de protocolo com o Windows Search. No exemplo a seguir, <Nome do protocolo> é o nome do próprio protocolo, como por exemplo 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

Registrar 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 do Shell).

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

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

Garantir que seus itens sejam indexados

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

A interface ISearchCrawlScopeManager fornece métodos que notificam o mecanismo de pesquisa de contêineres para rastrear e/ou assistir, e os itens nesses contêineres que devem ser incluídos ou excluídos ao rastrear ou assistir. No Windows 7 e posterior, ISearchCrawlScopeManager2 estende ISearchCrawlScopeManager com o método ISearchCrawlScopeManager2::GetVersion que obtém a versão, o que informa aos clientes se o estado do CSM foi alterado.

Conceitual
Noções básicas sobre manipuladores de protocolo
Desenvolver manipuladores de protocolo
Notificar o índice de alterações
Adicionar ícones e menus de contexto
Exemplo de código: extensões de Shell para manipuladores de protocolo
Criar um conector de pesquisa para um manipulador de protocolo
Depurar manipuladores de protocolo

Compartilhar via

Instalar e registrar manipuladores de protocolo (Windows Search)

Sobre URLs

Implementando interfaces de manipulador de protocolo

ISearchProtocol e ISearchProtocol2

IUrlAccessor, IUrlAccessor2, IUrlAccessor3 e IUrlAccessor4

IProtocolHandlerSite

Implementar manipuladores de filtro para contêineres

Instalar e registrar um manipulador de protocolo

Diretrizes para registrar um manipulador de protocolo

Registrar um manipulador de protocolo

Registrar o manipulador de tipo de arquivo do manipulador de protocolo

Garantir que seus itens sejam indexados

Comentários

Recursos adicionais

Compartilhar via

Instalar e registrar manipuladores de protocolo (Windows Search)

Sobre URLs

Implementando interfaces de manipulador de protocolo

ISearchProtocol e ISearchProtocol2

IUrlAccessor, IUrlAccessor2, IUrlAccessor3 e IUrlAccessor4

IProtocolHandlerSite

Implementar manipuladores de filtro para contêineres

Instalar e registrar um manipulador de protocolo

Diretrizes para registrar um manipulador de protocolo

Registrar um manipulador de protocolo

Registrar o manipulador de tipo de arquivo do manipulador de protocolo

Garantir que seus itens sejam indexados

Tópicos relacionados

Comentários

Recursos adicionais