Menginstal dan mendaftarkan pengelola protokol (Windows Search)

Menginstal handler protokol melibatkan penyalinan DLL ke lokasi yang sesuai di direktori Program Files, lalu mendaftarkan handler protokol melalui registri. Aplikasi penginstalan juga dapat menambahkan aturan akar pencarian dan cakupan untuk menentukan cakupan perayapan default untuk sumber data Shell.

Topik ini diatur sebagai berikut:

Tentang URL

Windows Search menggunakan URL untuk mengidentifikasi item secara unik dalam hierarki sumber data Shell Anda. URL yang merupakan simpul pertama dalam hierarki disebut akar pencarian; Windows Search akan mulai mengindeks di akar pencarian, meminta agar handler protokol menghitung tautan turunan untuk setiap URL.

Struktur URL yang khas adalah:

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

Sintaks URL dijelaskan dalam tabel berikut.

Sintaksis Deskripsi
<protokol> Mengidentifikasi handler protokol mana yang akan dipanggil untuk URL.
{user SID} Mengidentifikasi konteks keamanan pengguna di mana handler protokol dipanggil. Jika tidak ada pengidentifikasi keamanan pengguna (SID) yang diidentifikasi, handler protokol dipanggil dalam konteks keamanan layanan sistem.
<jalur> Menentukan hierarki penyimpanan, di mana setiap garis miring ('/') adalah pemisah di antara nama folder.
<Id Item> Mewakili string unik yang mengidentifikasi item anak (misalnya, nama file).

 

Pengindeks Pencarian Windows memangkas garis miring akhir dari URL. Akibatnya, Anda tidak dapat mengandalkan keberadaan slash terakhir untuk mengidentifikasi direktori dengan item. Handler protokol Anda harus dapat menangani sintaks URL ini. Pastikan bahwa nama protokol yang Anda pilih untuk mengidentifikasi sumber data Shell Anda tidak bertentangan dengan yang ada saat ini. Kami merekomendasikan konvensi penamaan ini: companyName.scheme.

Untuk informasi selengkapnya tentang membuat sumber data Shell, lihat Menerapkan Antarmuka Objek Folder Dasar.

Menerapkan antarmuka penangan protokol

Membuat handler protokol memerlukan implementasi tiga antarmuka berikut:

  • ISearchProtocol untuk mengelola objek UrlAccessor.
  • IUrlAccessor untuk mengekspos properti dan mengidentifikasi filter yang sesuai untuk item di sumber data Shell.
  • IFilter untuk memfilter file kepemilikan atau menghitung dan memfilter file yang disimpan secara hierarkis.

Selain tiga antarmuka wajib yang tercantum, antarmuka lain bersifat opsional, dan Anda memiliki kebebasan untuk mengimplementasikan antarmuka opsional mana pun yang paling sesuai untuk tugas yang dihadapi.

ISearchProtocol dan ISearchProtocol2

Antarmuka SearchProtocol menginisialisasi dan mengelola objek UrlAccessor handler protokol Anda. AntarmukaISearchProtocol2 adalah ekstensi opsionalISearchProtocol , dan menyertakan metode tambahan untuk menentukan informasi selengkapnya tentang pengguna dan item.

Iurlaccessor, iurlaccessor2, iurlaccessor3, dan IUrlAccessor4

Antarmuka IUrlAccessor dijelaskan dalam tabel berikut.

Antarmuka Deskripsi
IUrlAccessor Untuk URL tertentu, antarmukaIUrlAccessor menyediakan akses ke properti item yang diekspos di URL. Ini juga dapat mengikat properti tersebut ke filter khusus handler protokol (yaitu, filter selain yang terkait dengan nama file).
IUrlAccessor2 (opsional) AntarmukaIUrlAccessor2 memperluas IUrlAccessor dengan metode untuk mengambil halaman kode untuk properti item dan URL tampilannya, serta untuk memperoleh jenis item di URL tersebut (dokumen atau direktori).
IUrlAccessor3 (opsional) Antarmuka IUrlAccessor3 memperluas IUrlAccessor2 dengan metode yang mendapatkan array SID pengguna, memungkinkan host protokol pencarian mengatasnamakan pengguna ini saat mengindeks item.
IUrlAccessor4 (opsional) AntarmukaIUrlAccessor4memperluas fungsionalitas antarmukaIUrlAccessor3dengan metode yang mengidentifikasi apakah konten item harus diindeks.

 

Objek UrlAccessor dibuat dan diinisialisasi oleh objek SearchProtocol. Antarmuka IUrlAccessor menyediakan akses ke informasi penting melalui metode yang dijelaskan dalam tabel berikut.

Metode Deskripsi
IUrlAccessor::GetLastModified Mengembalikan waktu url terakhir diubah. Jika waktu ini lebih baru dari waktu ketika pengindeks terakhir kali memproses URL ini, penangan filter (implementasi antarmuka IFilter) dipanggil untuk mengekstrak data yang (mungkin) diubah untuk item tersebut. Waktu yang dimodifikasi untuk direktori diabaikan.
IUrlAccessor::IsDirectory Mengidentifikasi apakah URL mewakili sebuah folder yang berisi URL turunannya.
IUrlAccessor::BindToStream Terhubung dengan antarmuka IStream yang mewakili data dari sebuah file di penyimpanan data kustom.
IUrlAccessor::BindToFilter Ikatan ke protokol khusus handler IFilter, yang dapat mengekspos properti untuk item.
IUrlAccessor4::ShouldIndexItemContent Mengidentifikasi apakah konten item harus diindeks.

 

IProtocolHandlerSite

Antarmuka IProtocolHandlerSite digunakan untuk menginstansiasi handler filter, yang dihosting dalam proses terisolasi. Handler filter yang sesuai diperoleh untuk pengidentifikasi kelas persisten (CLSID) tertentu, kelas penyimpanan dokumen, atau ekstensi nama file. Manfaat meminta proses host untuk mengikat IFilter adalah bahwa proses host dapat mengelola proses penangan filter yang sesuai, dan mengontrol keamanan yang terlibat dalam memanggil handler.

Menerapkan pengendali filter untuk kontainer

Jika Anda menerapkan handler protokol hierarkis, maka Anda harus menerapkan handler filter untuk kontainer yang menghitung URL anak. Sebuah handler filter adalah implementasi dari antarmuka IFilter . Proses enumerasi adalah perulangan melalui metode IFilter::GetChunk dan IFilter::GetValue dari antarmuka IFilter; setiap URL turunan ditampilkan sebagai nilai dari properti tersebut.

IFilter::GetChunk mengembalikan properti kontainer. Untuk menghitung URL anak, IFilter::GetChunk mengembalikan salah satu hal berikut:

Mengembalikan PKEY_Search_UrlToIndexWithModificationTime lebih efisien karena pengindeks dapat segera menentukan apakah item perlu diindeks tanpa memanggil ISearchProtocol::CreateAccessor dan IUrlAccessor::GetLastModified metode.

Contoh kode berikut menunjukkan cara mengembalikan properti PKEY_Search_UrlToIndexWithModificationTime.

Penting

Hak Cipta (c) Microsoft Corporation. Hak cipta dilindungi oleh undang-undang

 

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

Kontainer komponen IFilter harus selalu menghitung semua URL anak meskipun URL anak belum berubah, karena pengindeks mendeteksi penghapusan melalui proses enumerasi. Jika output tanggal dalam PKEY_Search_UrlToIndexWithModificationTime menunjukkan bahwa data tidak berubah, pengindeks tidak memperbarui data untuk URL tersebut.

 

Menginstal dan mendaftarkan handler protokol

Menginstal handler protokol melibatkan penyalinan DLL ke lokasi yang sesuai di direktori Program Files, lalu mendaftarkan DLL. Pengendali protokol harus menerapkan registrasi mandiri untuk instalasi. Aplikasi penginstalan juga dapat menambahkan akar pencarian dan aturan cakupan untuk menentukan cakupan perayapan default untuk sumber data Shell, yang dijelaskan dalam bagian Memastikan Item Anda Diindeks pada akhir topik ini.

Panduan untuk mendaftarkan handler protokol

Anda harus mengikuti panduan ini saat mendaftarkan handler protokol:

  • Alat penginstal harus menggunakan alat penginstal EXE atau MSI.
  • Catatan rilis harus disediakan.
  • Entri Tambahkan/Hapus Program harus dibuat untuk setiap add-in yang terinstal.
  • Alat penginstal harus mengambil alih semua pengaturan registri untuk jenis file atau penyimpanan tertentu yang dipahami oleh add-in saat ini.
  • Jika add-in sebelumnya sedang ditimpa, penginstal harus menginformasikan pengguna.
  • Jika add-in yang lebih baru telah menimpa add-in sebelumnya, harus ada cara untuk memulihkan fungsionalitas add-in sebelumnya dan menjadikannya add-in default untuk jenis file tersebut lagi.
  • Alat penginstal harus menentukan cakupan perayapan default untuk pengindeks dengan menambahkan akar pencarian, dan aturan cakupan menggunakan Crawl Scope Manager (CSM).

Mendaftarkan handler protokol

Anda perlu membuat empat belas entri dalam registri untuk mendaftarkan komponen handler protokol, di mana:

  • Ver_Ind_ProgID adalah ProgID versi independen dari implementasi handler protokol.
  • Ver_Dep_ProgID adalah ProgID dependen versi dari implementasi handler protokol.
  • CLSID_1 adalah CLSID dari implementasi handler protokol.

Untuk mendaftarkan handler protokol:

  1. Daftarkan ProgID yang tidak bergantung versi dengan kunci dan nilai berikut:

    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. Daftarkan ProgID yang terkait versi dengan kunci dan nilai berikut:

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

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

  3. Daftarkan CLSID handler protokol dengan kunci dan nilai berikut:

    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. Daftarkan handler protokol dengan Windows Search. Dalam contoh berikut, <Nama Protokol> adalah nama protokol itu sendiri, seperti file, mapi, dan sebagainya:

    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>

    Sebelum Windows Vista:

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

Mendaftarkan pengelola tipe file untuk pengelola protokol

Anda perlu membuat dua entri dalam registri untuk mendaftarkan handler jenis file handler protokol (yang juga dikenal sebagai ekstensi 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>

Memastikan bahwa item Anda diindeks

Setelah menerapkan handler protokol, Anda harus menentukan item Shell mana yang akan diindeks oleh handler protokol Anda. Anda dapat menggunakan Pengelola Katalog untuk memulai pengindeksan ulang (untuk informasi selengkapnya, lihat MenggunakanPengelola Katalog ). Atau Anda juga dapat menggunakan Crawl Scope Manager (CSM) untuk menyiapkan aturan default yang menunjukkan URL yang Anda inginkan agar pengindeks dirayapi (untuk informasi selengkapnya, lihat Menggunakan Pengelola Cakupan Perayapan dan Mengelola Aturan Cakupan). Anda juga dapat menambahkan akar pencarian (untuk informasi selengkapnya, lihat Mengelola Akar Pencarian). Opsi lain yang tersedia untuk Anda adalah mengikuti prosedur dalam contoh ReIndex di Sampel Kode Pencarian Windows.

AntarmukaISearchCrawlScopeManagermenyediakan metode yang memberikan informasi kepada mesin pencari tentang kontainer yang perlu dirangkak dan/atau dipantau, serta item-item di bawah kontainer tersebut untuk disertakan atau dikecualikan saat proses perayapan atau pemantauan. Di Windows 7 dan yang lebih baru, ISearchCrawlScopeManager2 memperluas ISearchCrawlScopeManager dengan metode ISearchCrawlScopeManager2::GetVersion yang mengambil versi, yang memberi informasi kepada klien tentang apakah status CSM telah berubah.

Konseptual

Memahami Pengelola Protokol

Mengembangkan Peluncur Protokol

Pemberitahuan Indeks Perubahan

Menambahkan Ikon dan Menu Konteks

Sampel Kode : Ekstensi Shell untuk Handler Protokol

Membuat Konektor Pencarian untuk Pengendali Protokol

Pengelola Protokol Debug

 

 

  • Terakhir diperbarui pada