Instalación y registro de controladores de protocolo (Windows Search)

La instalación de un controlador de protocolo implica copiar los archivos DLL en una ubicación adecuada en el directorio Archivos de programa y, a continuación, registrar el controlador de protocolo a través del registro. La aplicación de instalación también puede agregar reglas de ámbito y raíz de búsqueda para definir un ámbito de rastreo predeterminado para el origen de datos de Shell.

Este tema se organiza de la siguiente manera:

• Acerca de las direcciones URL
• Implementación de interfaces de controlador de protocolo
  • ISearchProtocol e ISearchProtocol2
  • IUrlAccessor, IUrlAccessor2, IUrlAccessor3 e IUrlAccessor4
  • IProtocolHandlerSite
• Implementación de controladores de filtro para contenedores
• Instalación y registro de un controlador de protocolo
  • Directrices para registrar un controlador de protocolo
  • Registrar un controlador de protocolo
  • Registrar el controlador de tipos de archivo del controlador de protocolo
• Asegurarse de que los elementos están indexados
• Temas relacionados

Acerca de las direcciones URL

Windows Search usa direcciones URL para identificar de forma única los elementos de la jerarquía del origen de datos de Shell. La dirección URL que es el primer nodo de la jerarquía se denomina raíz de búsqueda; Windows Search comenzará a indexar en la raíz de búsqueda, solicitando que el controlador de protocolo enumera los vínculos secundarios de cada dirección URL.

La estructura de dirección URL típica es:

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

La sintaxis de la dirección URL se describe en la tabla siguiente.

Sintaxis	Descripción
<protocolo>	Identifica qué controlador de protocolo se va a invocar para la dirección URL.
{SID de usuario}	Identifica el contexto de seguridad del usuario en el que se llama al controlador de protocolo. Si no se identifica ningún identificador de seguridad de usuario (SID), se llama al controlador de protocolo en el contexto de seguridad del servicio del sistema.
<path>	Define la jerarquía del almacén, donde cada barra diagonal ('/') es un separador entre los nombres de carpeta.
<ItemID>	Representa una cadena única que identifica el elemento secundario (por ejemplo, el nombre de archivo).

 

El indexador de Windows Search recorta la barra diagonal final de las direcciones URL. Como resultado, no puede confiar en la existencia de una barra diagonal final para identificar un directorio frente a un elemento. El controlador de protocolo debe ser capaz de controlar esta sintaxis de dirección URL. Asegúrese de que el nombre del protocolo que seleccione para identificar el origen de datos de Shell no entra en conflicto con los actuales. Se recomienda esta convención de nomenclatura: companyName.scheme.

Para obtener más información sobre cómo crear un origen de datos de Shell, vea Implementación de las interfaces básicas de objetos de carpeta.

Implementación de interfaces de controlador de protocolo

La creación de un controlador de protocolo requiere la implementación de las tres interfaces siguientes:

• ISearchProtocol para administrar objetos UrlAccessor.
• IUrlAccessor para exponer propiedades e identificar los filtros adecuados para los elementos del origen de datos de Shell.
• IFilter para filtrar archivos propietarios o para enumerar y filtrar archivos almacenados jerárquicamente.

Aparte de las tres interfaces obligatorias enumeradas, las otras interfaces son opcionales y tiene la libertad de implementar las interfaces opcionales más adecuadas para la tarea en cuestión.

ISearchProtocol e ISearchProtocol2

Las interfaces SearchProtocol inicializan y administran los objetos UrlAccessor del controlador de protocolos. La interfazISearchProtocol2 es una extensión opcional de ISearchProtocol e incluye un método adicional para especificar más información sobre el usuario y el elemento.

IUrlAccessor, IUrlAccessor2, IUrlAccessor3 e IUrlAccessor4

Las interfaces IUrlAccessor se describen en la tabla siguiente.

Interfaz	Descripción
IUrlAccessor	Para una dirección URL especificada, la interfazIUrlAccessor proporciona acceso a las propiedades del elemento que se expone en la dirección URL. También puede enlazar esas propiedades a un filtro específico del controlador de protocolo (es decir, un filtro distinto del asociado al nombre de archivo).
IUrlAccessor2 (opcional)	La interfaz IUrlAccessor2extiendeIUrlAccessorcon métodos que obtienen una página de códigos para las propiedades del elemento y su dirección URL de visualización, y que obtienen el tipo de elemento en la dirección URL (documento o directorio).
IUrlAccessor3 (opcional)	La interfaz IUrlAccessor3 extiende IUrlAccessor2 con un método que obtiene una matriz de SID de usuario, lo que permite que el host del protocolo de búsqueda suplantara a estos usuarios para indexar el elemento.
IUrlAccessor4 (opcional)	La interfaz IUrlAccessor4amplía la funcionalidad de la interfaz IUrlAccessor3con un método que identifica si se debe indexar el contenido del elemento.

 

El objeto UrlAccessor se crea una instancia e inicializa mediante un objeto SearchProtocol. Las interfaces IUrlAccessor proporcionan acceso a partes importantes de información a través de los métodos descritos en la tabla siguiente.

Method	Descripción
IUrlAccessor::GetLastModified	Devuelve la hora en que se modificó por última vez la dirección URL. Si esta vez es más reciente que la última vez que el indexador procesó esta dirección URL, se llama a los controladores de filtro (implementaciones de la interfaz IFilter ) para extraer los datos modificados (posiblemente) modificados para ese elemento. Se omiten las horas de modificación de los directorios.
IUrlAccessor::IsDirectory	Identifica si la dirección URL representa una carpeta que contiene direcciones URL secundarias.
IUrlAccessor::BindToStream	Enlaza a una interfaz IStream que representa los datos de un archivo en un almacén de datos personalizado.
IUrlAccessor::BindToFilter	Enlaza a un IFilter específico del controlador de protocolo, que puede exponer propiedades para el elemento.
IUrlAccessor4::ShouldIndexItemContent	Identifica si se debe indexar el contenido del elemento.

 

IProtocolHandlerSite

La interfaz IProtocolHandlerSite se usa para crear instancias de un controlador de filtros, que se hospeda en un proceso aislado. El controlador de filtro adecuado se obtiene para un identificador de clase persistente especificado (CLSID), la clase de almacenamiento de documentos o la extensión de nombre de archivo. La ventaja de pedir al proceso host que se enlace a IFilter es que el proceso de host puede administrar el proceso de localización de un controlador de filtro adecuado y controlar la seguridad implicada en llamar al controlador.

Implementación de controladores de filtro para contenedores

Si va a implementar un controlador de protocolo jerárquico, debe implementar un controlador de filtro para un contenedor que enumera las direcciones URL secundarias. Un controlador de filtro es una implementación de la interfazIFilter. El proceso de enumeración es un bucle a través de los métodos IFilter::GetChunk y IFilter::GetValue de la interfaz IFilter; cada dirección URL secundaria se expone como el valor de la propiedad.

IFilter::GetChunk devuelve las propiedades del contenedor. Para enumerar las direcciones URL secundarias, IFilter::GetChunk devuelve una de las siguientes opciones:

• PKEY_Search_UrlToIndex:

  Dirección URL del elemento sin la hora de la última modificación. IFilter::GetValue devuelve un PROPVARIANT que contiene la dirección URL secundaria.

• PKEY_Search_UrlToIndexWithModificationTime:

  La dirección URL y la hora de la última modificación. IFilter::GetValue devuelve un PROPVARIANT que contiene un vector de la dirección URL secundaria y la hora de la última modificación.

Devolver PKEY_Search_UrlToIndexWithModificationTime es más eficaz porque el indexador puede determinar inmediatamente si el elemento debe indexarse sin llamar a los métodos ISearchProtocol::CreateAccessor y IUrlAccessor::GetLastModified métodos.

En el código de ejemplo siguiente se muestra cómo devolver la propiedad PKEY_Search_UrlToIndexWithModificationTime.

Importante

Copyright (c) Microsoft Corporation. Todos los derechos reservados.

 

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

Nota:

Un componente IFilter de contenedor siempre debe enumerar todas las direcciones URL secundarias aunque no hayan cambiado las direcciones URL secundarias, ya que el indexador detecta eliminaciones a través del proceso de enumeración. Si la salida de fecha en un PKEY_Search_UrlToIndexWithModificationTime indica que los datos no han cambiado, el indexador no actualiza los datos de esa dirección URL.

 

Instalación y registro de un controlador de protocolo

La instalación de controladores de protocolo implica copiar los archivos DLL en una ubicación adecuada en el directorio Archivos de programa y, a continuación, registrar los archivos DLL. Los controladores de protocolo deben implementar el registro propio para la instalación. La aplicación de instalación también puede agregar una raíz de búsqueda y reglas de ámbito para definir un ámbito de rastreo predeterminado para el origen de datos de Shell, que se describe en Asegurarse de que los elementos se indexan al final de este tema.

Directrices para registrar un controlador de protocolo

Debe seguir estas instrucciones al registrar un controlador de protocolo:

• El instalador debe usar el instalador EXE o MSI.
• Se deben proporcionar notas de la versión.
• Se debe crear una entrada Agregar o quitar programas para cada complemento instalado.
• El instalador debe asumir toda la configuración del registro para el tipo de archivo determinado o almacenar que comprende el complemento actual.
• Si se sobrescribe un complemento anterior, el instalador debe notificar al usuario.
• Si un complemento más reciente ha sobrescrito el complemento anterior, debe haber la capacidad de restaurar la funcionalidad del complemento anterior y convertirlo de nuevo en el complemento predeterminado para ese tipo de archivo.
• El instalador debe definir un ámbito de rastreo predeterminado para el indexador agregando una raíz de búsqueda y reglas de ámbito mediante el Administrador de ámbitos de rastreo (CSM).

Registro de un controlador de protocolo

Debe realizar catorce entradas en el registro para registrar el componente de controlador de protocolo, donde:

• Ver_Ind_ProgID es la versión independiente de ProgID de la implementación del controlador de protocolos.
• Ver_Dep_ProgID es la versión dependiente de ProgID de la implementación del controlador de protocolos.
• CLSID_1 es el CLSID de la implementación del controlador de protocolos.

Para registrar un controlador de protocolo:

1. Registre la versión independiente de ProgID con las siguientes claves y 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 la versión dependiente de ProgID con las claves y valores siguientes:

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

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

3. Registre el CLSID del controlador de protocolo con las claves y valores siguientes:

   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 el controlador de protocolo con Windows Search. En el ejemplo siguiente, <nombre de protocolo> es el nombre del propio protocolo, como archivo, mapi, etc.:

   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 de Windows Vista:

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

Registro del controlador de tipo de archivo del controlador de protocolo

Debe realizar dos entradas en el registro para registrar el controlador de tipo de archivo del controlador de protocolo (que también se conoce como extensión de 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>
   

Asegurarse de que los elementos están indexados

Después de implementar el controlador de protocolo, debe especificar qué elementos de Shell va a indexar el controlador de protocolo. Puede usar el Administrador de catálogos para iniciar la reindización (para obtener más información, vea Uso del Administrador de catálogos). También puede usar el Administrador de ámbitos de rastreo (CSM) para configurar reglas predeterminadas que indican las direcciones URL que desea que el indexador rastree (para obtener más información, vea Uso del Administrador de ámbitos de rastreo y Administración de reglas de ámbito). También puede agregar una raíz de búsqueda (para obtener más información, vea Administración de raíces de búsqueda). Otra opción disponible es seguir el procedimiento del ejemplo ReIndex en Ejemplos de código de Windows Search.

La interfaz ISearchCrawlScopeManager proporciona métodos que notifican al motor de búsqueda de contenedores que rastrean o vigilan, y los elementos de esos contenedores que se van a incluir o excluir al rastrear o observar. En Windows 7 y versiones posteriores, ISearchCrawlScopeManager2 extiende ISearchCrawlScopeManager con el método ISearchCrawlScopeManager2::GetVersion que obtiene la versión, que informa a los clientes de si el estado del CSM ha cambiado.

Temas relacionados

Conceptual

Descripción de los controladores de protocolo

Desarrollo de controladores de protocolo

Notificación del índice de cambios

Adición de iconos y menús contextuales

Ejemplo de código: Extensiones de shell para controladores de protocolo

Creación de un conector de Search para un controlador de protocolo

Depuración de controladores de protocolo