Установка и регистрация обработчиков протоколов (Windows Search)

Статья
2023-06-13

При установке обработчика протокола необходимо скопировать библиотеки DLL в соответствующее расположение в каталоге Program Files, а затем зарегистрировать обработчик протокола через реестр. Приложение установки также может добавить корень поиска и правила области, чтобы определить область индексирования по умолчанию для источника данных Shell.

Этот раздел организован следующим образом:

о URL-адресах
Реализация интерфейсов обработчика протоколов
внедрение обработчиков для фильтрации контейнеров
установка и регистрация обработчика протоколов
Убедитесь, что ваши элементы индексируются
Связанные темы

Сведения о URL-адресах

Поиск Windows использует URL-адреса для уникальной идентификации элементов в иерархии данных вашей оболочки. URL-адрес, который является первым узлом в иерархии, называется корнем поиска; Поиск Windows начнет индексирование с корня поиска, запрашивая у обработчика протокола перечисление дочерних ссылок для каждого URL-адреса.

Типичная структура URL-адреса:

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

Синтаксис URL-адреса описан в следующей таблице.

Синтаксис	Описание
<протокол>	Определяет, какой обработчик протокола вызывается для URL-адреса.
{user SID}	Определяет контекст безопасности пользователя, в котором вызывается обработчик протокола. Если идентификатор безопасности пользователя (SID) не определен, обработчик протокола вызывается в контексте безопасности системной службы.
<маршрут>	Определяет иерархию хранилища, где каждая косая черта ('/') является разделителем между именами папок.
<ItemID>	Представляет уникальную строку, которая определяет дочерний элемент (например, имя файла).

Индексатор поиска Windows обрезает последнюю косую черту в URL-адресах. В результате вы не можете полагаться на наличие последней косой черты для различения каталога и элемента. Обработчик протокола должен иметь возможность обрабатывать этот синтаксис URL-адреса. Убедитесь, что выбранное имя протокола для идентификации вашего источника данных Shell не конфликтует с уже существующими. Мы рекомендуем использовать данную схему именования: companyName.scheme.

Для получения дополнительной информации о том, как создать источник данных Shell, см. внедрение интерфейсов основных объектов папок.

Реализация интерфейсов обработчика протоколов

Для создания обработчика протокола требуется реализация следующих трех интерфейсов:

ISearchProtocol для управления объектами UrlAccessor.
IUrlAccessor для отображения свойств и определения соответствующих фильтров для элементов в источнике данных оболочки.
IFilter фильтровать собственные файлы или перечислять и фильтровать иерархически сохраненные файлы.

Кроме трех обязательных интерфейсов, остальные интерфейсы являются необязательными, и вы можете реализовать любые необязательные интерфейсы, наиболее подходящие для задачи.

ISearchProtocol и ISearchProtocol2

Интерфейсы SearchProtocol инициализируют объекты URLAccessor обработчика протокола и управляют ими. Интерфейс ISearchProtocol2 является необязательным расширением ISearchProtocolи включает дополнительный метод, чтобы указать больше сведений о пользователе и элементе.

IUrlAccessor, IUrlAccessor2, IUrlAccessor3 и IUrlAccessor4

Интерфейсы IUrlAccessor описаны в следующей таблице.

Интерфейс	Описание
IUrlAccessor	Для указанного URL-адреса интерфейс IUrlAccessor предоставляет доступ к свойствам элемента, который предоставляется в URL-адресе. Он также может привязать эти свойства к фильтру, связанному с обработчиком протокола (т. е. фильтру, отличному от того, который связан с именем файла).
IUrlAccessor2 (необязательно)	Интерфейс IUrlAccessor2 расширяет IUrlAccessor методами, которые получают кодовую страницу для свойств элемента и URL-адрес его отображения, а также тип элемента в URL-адресе (документ или каталог).
IUrlAccessor3 (необязательно)	Интерфейс IUrlAccessor3 расширяет IUrlAccessor2 с помощью метода, который получает массив идентификаторов SID пользователей, что позволяет узлу протокола поиска олицетворять этих пользователей для индексации элемента.
IUrlAccessor4 (необязательно)	Интерфейс IUrlAccessor4 расширяет функциональные возможности интерфейса IUrlAccessor3 с помощью метода, определяющего, следует ли индексировать содержимое элемента.

Объект UrlAccessor создается и инициализируется объектом SearchProtocol. ИнтерфейсыIUrlAccessorпредоставляют доступ к важным фрагментам информации с помощью методов, описанных в следующей таблице.

Метод	Описание
IUrlAccessor::GetLastModified	Возвращает время последнего изменения URL-адреса. Если это время более недавнее, чем последний раз, когда индексатор обработал этот URL-адрес, обработчики фильтров (реализации интерфейса IFilter) вызываются для извлечения измененных данных для этого элемента (возможно). Для каталогов время изменения игнорируется.
IUrlAccessor::IsDirectory	Определяет, представляет ли URL-адрес папку, содержащую дочерние URL-адреса.
IUrlAccessor::BindToStream	Привязывается к интерфейсу IStream, представляющему данные файла в пользовательском хранилище данных.
IUrlAccessor::BindToFilter	Привязывается к определенному обработчику протокола IFilter, который может предоставлять свойства для элемента.
IUrlAccessor4::ShouldIndexItemContent	Определяет, следует ли индексировать содержимое элемента.

IProtocolHandlerSite

Интерфейс IProtocolHandlerSite используется для создания экземпляра обработчика фильтра, размещенного в изолированном процессе. Подходящий обработчик фильтра выбирается для указанного идентификатора постоянного класса (CLSID), класса хранилища документов или расширения файла. Преимущество запроса хост-процесса на привязку к IFilter заключается в том, что хост-процесс может управлять процессом поиска соответствующего обработчика фильтров и контролировать безопасность, связанную с вызовом обработчика.

Реализация обработчиков фильтров для контейнеров

Если вы реализуете иерархический обработчик протокола, необходимо реализовать обработчик фильтра для контейнера, который перечисляет дочерние URL-адреса. Обработчик фильтра — это реализация интерфейса IFilter. Процесс перечисления представляет собой цикл, использующий методы IFilter::GetChunk и IFilter::GetValue интерфейса IFilter; каждый дочерний URL-адрес раскрывается как значение свойства.

IFilter::GetChunk возвращает свойства контейнера. Чтобы перечислить дочерние URL-адреса, IFilter::GetChunk возвращает одно из следующих значений:

PKEY_Search_UrlToIndex:

URL-адрес элемента без последнего изменения времени. IFilter::GetValue возвращает PROPVARIANT, содержащий дочерний URL-адрес.
PKEY_Search_UrlToIndexWithModificationTime:

URL-адрес и время последнего изменения. IFilter::GetValue возвращает PROPVARIANT, содержащий вектор дочернего URL-адреса и последнее измененное время.

Возврат PKEY_Search_UrlToIndexWithModificationTime эффективнее, так как индексатор может немедленно определить, нужно ли индексировать элемент, не вызывая методы ISearchProtocol::CreateAccessor и IUrlAccessor::GetLastModified.

В следующем примере кода показано, как вернуть свойство 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;
}

Заметка

КомпонентконтейнераIFilter всегда должен перечислять все дочерние URL-адреса, даже если дочерние URL-адреса не изменились, так как индексатор обнаруживает удаления через процесс перечисления. Если выходные данные даты в PKEY_Search_UrlToIndexWithModificationTime указывают на то, что данные не изменились, индексатор не обновляет данные для этого URL-адреса.

Установка и регистрация обработчика протокола

Установка обработчиков протоколов включает копирование библиотек DLL в соответствующее расположение в каталоге Program Files, а затем регистрацию библиотек DLL. Обработчики протоколов должны реализовать самостоятельную регистрацию для установки. Приложение установки также может добавить корневой каталог поиска и правила области для определения области обхода по умолчанию для источника данных оболочки, который рассматривается в Обеспечение индексации элементов в конце этого раздела.

Регистрация обработчика протокола

Чтобы зарегистрировать компонент обработчика протокола, необходимо внести в реестр четырнадцать записей, где:

Ver_Ind_ProgID — это независимый от версии ProgID реализации обработчика протокола.
Ver_Dep_ProgID — это версионно-зависимый ProgID реализации обработчика протокола.
CLSID_1 — это CLSID реализации обработчика протокола.

Регистрация обработчика протокола:

Зарегистрируйте независимый идентификатор ProgID версии со следующими ключами и значениями:

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>

Зарегистрируйте зависимый от версии ProgID со следующими ключами и значениями:

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

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

Зарегистрируйте CLSID обработчика протокола со следующими ключами и значениями:

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>

Зарегистрируйте обработчик протокола в Службе поиска Windows. В следующем примере <имя протокола> — это имя самого протокола, например file, mapi и т. д.

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>

До Windows Vista:

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

Регистрация обработчика типов файлов для обработчика протокола

Чтобы зарегистрировать обработчик типов файлов для обработчика протокола (также известного как расширение оболочки), необходимо сделать две записи в реестре.

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>

Обеспечение индексации предметов

После реализации обработчика протокола необходимо указать, какие элементы оболочки обработчик протокола должен индексировать. Диспетчер каталогов можно использовать для запуска повторного индексирования (дополнительные сведения см. в с помощью диспетчера каталогов). Кроме того, можно использовать Менеджер областей обхода (CSM) для настройки стандартных правил, указывающих URL-адреса, которые должен индексировать поисковый робот (дополнительные сведения см. в статье Использование Менеджера областей обхода и Управление правилами областей). Вы также можете добавить корневой узел поиска (дополнительные сведения см. в разделе Управление корневыми узлами поиска). Другим вариантом, доступным для вас, является выполнение процедуры в примере ReIndex в примерах кода поиска Windows.

Интерфейс ISearchCrawlScopeManager предоставляет методы, которые уведомляют поисковую систему о контейнерах для обхода и/или наблюдения, и об элементах в этих контейнерах, которые следует включать или исключать при выполнении этих действий. В Windows 7 и более поздних версиях ISearchCrawlScopeManager2 расширяет ISearchCrawlScopeManagerс помощью метода ISearchCrawlScopeManager2::GetVersion, который сообщает клиентам о том, изменилось ли состояние CSM.

концептуальные
Основные сведения о обработчиках протоколов
Разработка обработчиков протоколов
Уведомление о изменениях индекса
добавление значков и контекстных меню
пример кода : расширения оболочки для обработчиков протоколов
Создание Коннектора Поиска для Обработчика Протокола
обработчики отладочных протоколов