プロトコルハンドラーのインストールと登録 (Windows 検索)

[アーティクル]
12/23/2023

プロトコルハンドラーをインストールするには、DLL を Program Files ディレクトリ内の適切な場所にコピーし、レジストリを介してプロトコルハンドラーを登録する必要があります。インストールアプリケーションでは、検索ルートとスコープの規則を追加して、シェルデータソースの既定のクロール範囲を定義することもできます。

このトピックは次のように構成されています。

URL について
プロトコルハンドラーインターフェイスの実装
コンテナー向けフィルターハンドラーの実装
プロトコルハンドラーのインストールと登録
項目のインデックスが作成されていることを確認する
関連トピック

URL について

Windows Search では、URL を使用して、シェルデータソースの階層内の項目を一意に識別します。階層内の最初のノードである URL は、検索ルートと呼ばれます。Windows Search は検索ルートでインデックス作成を開始し、プロトコルハンドラーが各 URL の子リンクを列挙するよう要求します。

一般的な URL 構造は次のとおりです。

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

URL 構文について次の表で説明します。

構文	説明
<protocol>	URL に対してどのプロトコルハンドラーを呼び出すかを指定します。
{user SID}	プロトコルハンドラーが呼び出されるユーザーセキュリティコンテキストを識別します。ユーザーセキュリティ識別子 (SID) が識別されない場合、プロトコルハンドラーはシステムサービスのセキュリティコンテキストで呼び出されます。
<path>	ストアの階層を定義します。各スラッシュ ('/') はフォルダー名の間の区切り記号です。
<ItemID>	子項目 (ファイル名など) を識別する一意の文字列を表します。

Windows Search インデクサーは、URL から最後のスラッシュをトリミングします。そのため、最後のスラッシュの存在に依存して、ディレクトリと項目を識別することはできません。プロトコルハンドラーは、この URL 構文を処理できるようにする必要があります。シェルデータソースを識別するために選択したプロトコル名が、現在のものと競合していないことを確認します。次の名前付け規則をお勧めします: companyName.scheme。

シェルデータソースの作成に関する詳細については、「基本的なフォルダーオブジェクトインターフェイスの実装」を参照してください。

プロトコルハンドラーインターフェイスの実装

プロトコルハンドラーの作成には、次の 3 つのインターフェイスを実装する必要があります。

UrlAccessor オブジェクトを管理する ISearchProtocol。
プロパティを公開し、シェルデータソース内の項目に対する適切なフィルターを識別する IUrlAccessor。
専用ファイルをフィルター処理したり、階層的に格納されたファイルを列挙およびフィルター処理したりする IFilter。

3 つの必須インターフェイス以外のインターフェイスは省略可能であり、手元のタスクに最適な任意のインターフェイスを自由に実装できます。

ISearchProtocol と ISearchProtocol2

SearchProtocol インターフェイスは、プロトコルハンドラー UrlAccessor オブジェクトを初期化して管理します。 ISearchProtocol2 インターフェイスは、ISearchProtocol のオプションの拡張であり、ユーザーと項目に関する詳細情報を指定する追加のメソッドが含まれています。

IUrlAccessor、IUrlAccessor2、IUrlAccessor3、および IUrlAccessor4

IUrlAccessor インターフェイスについては、次の表で説明します。

Interface	説明
IUrlAccessor	指定された URL の場合、IUrlAccessor インターフェイスには、URL で公開されている項目のプロパティへのアクセスが用意されています。また、これらのプロパティをプロトコルハンドラー固有のフィルター (つまり、ファイル名に関連付けられているフィルター以外のフィルター) にバインドすることもできます。
IUrlAccessor2 (省略可能)	IUrlAccessor2 インターフェイスは、項目のプロパティとその表示 URL のコードページを取得し、URL (ドキュメントまたはディレクトリ) 内の項目の種類を取得するメソッドで IUrlAccessor を拡張します。
IUrlAccessor3 (省略可能)	IUrlAccessor3 インターフェイスは、ユーザー SID の配列を取得するメソッドで IUrlAccessor2 を拡張し、検索プロトコルホストがこれらのユーザーの権限を借用して項目のインデックスを作成できるようにします。
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 インターフェイスの IFilter::GetChunk メソッドと IFilter::GetValue メソッドを通じたループです。各子 URL はプロパティの値として公開されます。

IFilter::GetChunk はコンテナーのプロパティを返します。子 URL を列挙するために、 IFilter::GetChunk は次のいずれかを返します。

PKEY_Search_UrlToIndex:

最終更新時刻のない項目の URL。 IFilter::GetValue は、子 URL を含む PROPVARIANT を返します。
PKEY_Search_UrlToIndexWithModificationTime:

URL と最終変更時刻。 IFilter::GetValue は、子 URL と最終変更時刻のベクターを含む PROPVARIANT を返します。

ISearchProtocol::CreateAccessor メソッドと IUrlAccessor::GetLastModified メソッドを呼び出すことなく項目のインデックスを作成する必要があるかどうかをインデクサーですぐに判断できるため、PKEY_Search_UrlToIndexWithModificationTime を返す方が効率的です。

次のコード例は、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;
}

Note

インデクサーが列挙プロセスを通じて削除を検出するため、コンテナー IFilter コンポーネントは、子 URL が変更されていない場合でも、常にすべての子 URL を列挙する必要があります。 PKEY_Search_UrlToIndexWithModificationTime の日付出力でデータが変更されていないことが示されている場合、インデクサーはその URL のデータを更新しません。

プロトコルハンドラーのインストールと登録

プロトコルハンドラーをインストールするには、DLL を Program Files ディレクトリ内の適切な場所にコピーして、DLL を登録する必要があります。プロトコルハンドラーは、インストールのために自己登録を実装する必要があります。インストールアプリケーションでは、検索ルートとスコープの規則を追加してシェルデータソースの既定のクロール範囲を定義することもできます。これについては、このトピックの最後にある「項目のインデックスが作成されていることを確認する」で説明されています。

プロトコルハンドラーの登録に関するガイドライン

プロトコルハンドラーを登録する場合は、次のガイドラインに従う必要があります。

インストーラーでは、EXE または MSI インストーラーを使用する必要があります。
リリースノートを指定する必要があります。
インストールされているアドインごとに、[プログラムの追加と削除] エントリを作成する必要があります。
インストーラーは、特定のファイルの種類または現在のアドインで認識されるストアのすべてのレジストリ設定を引き継ぐ必要があります。
以前のアドインが上書きされている場合、インストーラーはユーザーに通知する必要があります。
新しいアドインで以前のアドインが上書きされた場合は、以前のアドインの機能を復元し、もう一度そのファイルの種類の既定のアドインに戻す機能が必要です。
インストーラーでは、検索ルートを追加してインデクサーの既定のクロール範囲を定義し、クロール範囲マネージャー (CSM) を使用してスコープの規則を定義する必要があります。

プロトコルハンドラーの登録

次の場所にプロトコルハンドラーコンポーネントを登録するには、レジストリに 14 個のエントリを作成する必要があります。

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 Search に登録します。次の例では、<プロトコル名>はプロトコル自体の名前 (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

プロトコルハンドラーのファイルの種類ハンドラーの登録

プロトコルハンドラーのファイルの種類ハンドラー (シェル拡張機能とも呼ばれます) を登録するには、レジストリに 2 個のエントリを作成する必要があります。

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 を示す既定の規則を設定することもできます (詳細については、「クロール範囲マネージャーの使用」と「スコープの規則の管理」を参照してください)。検索ルートを追加することもできます (詳細については、「検索ルートの管理」を参照してください)。使用可能なもう 1 つのオプションは、Windows Search コードサンプルの ReIndex サンプルの手順に従う方法です。

ISearchCrawlScopeManager インターフェイスには、クロールや監視を行うコンテナーの検索エンジンに通知するメソッドと、クロールまたは監視時に含めるか除外するコンテナーの下の項目が用意されています。 Windows 7 以降では、ISearchCrawlScopeManager2 は、バージョンを取得する ISearchCrawlScopeManager2::GetVersion メソッドを使用して ISearchCrawlScopeManager を拡張し、CSM の状態が変更されたかどうかをクライアントに通知します。

Conceptual
プロトコルハンドラーについて
プロトコルハンドラーの開発
インデックスの変更通知
アイコンとコンテキストメニューの追加
コードサンプル: プロトコルハンドラーのシェル拡張機能
プロトコルハンドラーの検索コネクタの作成
プロトコルハンドラーのデバッグ

プロトコルハンドラーのインストールと登録 (Windows 検索)

URL について

プロトコルハンドラーインターフェイスの実装

ISearchProtocol と ISearchProtocol2

IUrlAccessor、IUrlAccessor2、IUrlAccessor3、および IUrlAccessor4

IProtocolHandlerSite

コンテナー向けフィルターハンドラーの実装

プロトコルハンドラーのインストールと登録

プロトコルハンドラーの登録に関するガイドライン

プロトコルハンドラーの登録

プロトコルハンドラーのファイルの種類ハンドラーの登録

項目のインデックスが作成されていることを確認する

フィードバック

フィードバック

その他のリソース

プロトコル ハンドラーのインストールと登録 (Windows 検索)

URL について

プロトコル ハンドラー インターフェイスの実装

ISearchProtocol と ISearchProtocol2

IUrlAccessor、IUrlAccessor2、IUrlAccessor3、および IUrlAccessor4

IProtocolHandlerSite

コンテナー向けフィルター ハンドラーの実装

プロトコル ハンドラーのインストールと登録

プロトコル ハンドラーの登録に関するガイドライン

プロトコル ハンドラーの登録

プロトコル ハンドラーのファイルの種類ハンドラーの登録

項目のインデックスが作成されていることを確認する

関連トピック

フィードバック

フィードバック

その他のリソース

プロトコルハンドラーのインストールと登録 (Windows 検索)

プロトコルハンドラーインターフェイスの実装

コンテナー向けフィルターハンドラーの実装

プロトコルハンドラーのインストールと登録

プロトコルハンドラーの登録に関するガイドライン

プロトコルハンドラーの登録

プロトコルハンドラーのファイルの種類ハンドラーの登録