Menginstal dan Mendaftarkan Handler Protokol (Windows Search)

Artikel
12/21/2023

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
Menerapkan Antarmuka Handler Protokol
Menerapkan Handler Filter untuk Kontainer
Menginstal dan Mendaftarkan Handler Protokol
Memastikan bahwa Item Anda Diindeks
Topik terkait

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.

Sintaks	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.
<jalan>	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 garis miring akhir untuk mengidentifikasi direktori versus 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 Handler 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 untuk 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. Antarmuka ISearchProtocol2 adalah ekstensi opsional dari ISearchProtocol, dan menyertakan metode tambahan untuk menentukan informasi lebih lanjut tentang pengguna dan item.

IUrlAccessor, IUrlAccessor2, IUrlAccessor3, dan IUrlAccessor4

Antarmuka IUrlAccessor dijelaskan dalam tabel berikut.

Antarmuka	Deskripsi
IUrlAccessor	Untuk URL tertentu, antarmuka IUrlAccessor 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)	Antarmuka IUrlAccessor2 memperluas IUrlAccessor dengan metode yang mendapatkan halaman kode untuk properti item dan URL tampilannya, dan yang mendapatkan jenis item di URL (dokumen atau direktori).
IUrlAccessor3 (opsional)	Antarmuka IUrlAccessor3 memperluas IUrlAccessor2 dengan metode yang mendapatkan array SID pengguna, memungkinkan host protokol pencarian untuk meniru pengguna ini untuk mengindeks item.
IUrlAccessor4 (opsional)	Antarmuka IUrlAccessor4 memperluas fungsionalitas antarmuka IUrlAccessor3 dengan 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 kali ini lebih baru daripada terakhir kali pengindeks memproses URL ini, penangan filter (implementasi antarmuka IFilter) dipanggil untuk mengekstrak data yang diubah (mungkin) untuk item tersebut. Waktu yang dimodifikasi untuk direktori diabaikan.
IUrlAccessor::IsDirectory	Mengidentifikasi apakah URL mewakili folder yang berisi URL anak.
IUrlAccessor::BindToStream	Mengikat ke antarmuka IStream yang mewakili data file di penyimpanan data kustom.
IUrlAccessor::BindToFilter	Ikatan ke IFilter khusus handler protokol, yang dapat mengekspos properti untuk item.
IUrlAccessor4::ShouldIndexItemContent	Mengidentifikasi apakah konten item harus diindeks.

IProtocolHandlerSite

Antarmuka IProtocolHandlerSite digunakan untuk membuat instans 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 menemukan handler filter yang sesuai, dan mengontrol keamanan yang terlibat dalam memanggil handler.

Menerapkan Handler Filter untuk Kontainer

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

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

PKEY_Search_UrlToIndex:

URL ke item tanpa waktu terakhir diubah. IFilter::GetValue mengembalikan PROPVARIANT yang berisi URL anak.
PKEY_Search_UrlToIndexWithModificationTime:

URL dan waktu terakhir diubah. IFilter::GetValue mengembalikan PROPVARIANT yang berisi vektor URL anak dan waktu terakhir diubah.

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

Contoh kode berikut menunjukkan cara mengembalikan properti PKEY_Search_UrlToIndexWithModificationTime .

Penting

Hak Cipta (c) Microsoft Corporation. Semua hak dilindungi 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;
}

Catatan

Komponen IFilter kontainer 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. Penangan protokol harus menerapkan pendaftaran mandiri untuk penginstalan. Aplikasi penginstalan juga dapat menambahkan akar pencarian, dan aturan cakupan untuk menentukan cakupan perayapan default untuk sumber data Shell, yang dibahas dalam Memastikan bahwa Item Anda Diindeks di 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 tertentu atau menyimpan yang dipahami add-in saat ini.
Jika add-in sebelumnya sedang ditimpa, penginstal harus memberi tahu pengguna.
Jika add-in yang lebih baru telah menimpa add-in sebelumnya, seharusnya ada kemampuan 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 independen versi 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:

Daftarkan ProgID independen 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>

Daftarkan ProgID dependen 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}

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>

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 Handler Tipe File Penangan Protokol

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

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 Menggunakan Pengelola Katalog). Atau Anda juga dapat menggunakan Crawl Scope Manager (CSM) untuk menyiapkan aturan default yang menunjukkan URL yang Anda inginkan untuk dirayapi pengindeks (untuk informasi selengkapnya, lihat Menggunakan Pengelola Lingkup 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 sampel ReIndex di Sampel Kode Pencarian Windows.

Antarmuka ISearchCrawlScopeManager menyediakan metode yang memberi tahu mesin pencari kontainer untuk merangkak dan/atau menonton, dan item di bawah kontainer tersebut untuk disertakan atau dikecualikan saat merangkak atau menonton. Di Windows 7 dan yang lebih baru, ISearchCrawlScopeManager2 memperluas ISearchCrawlScopeManager dengan metode ISearchCrawlScopeManager2::GetVersion yang mendapatkan versi, yang memberi tahu klien apakah status CSM telah berubah.

Konseptual
Memahami Handler Protokol
Mengembangkan Handler Protokol
Memberi tahu Indeks Perubahan
Menambahkan Ikon dan Menu Konteks
Sampel Kode: Ekstensi Shell untuk Penangan Protokol
Membuat Koneksi or Pencarian untuk Handler Protokol
Penangan Protokol Debugging

Bagikan melalui

Menginstal dan Mendaftarkan Handler Protokol (Windows Search)

Tentang URL

Menerapkan Antarmuka Handler Protokol

ISearchProtocol dan ISearchProtocol2

IUrlAccessor, IUrlAccessor2, IUrlAccessor3, dan IUrlAccessor4

IProtocolHandlerSite

Menerapkan Handler Filter untuk Kontainer

Menginstal dan Mendaftarkan Handler Protokol

Panduan untuk Mendaftarkan Handler Protokol

Mendaftarkan Handler Protokol

Mendaftarkan Handler Tipe File Penangan Protokol

Memastikan bahwa Item Anda Diindeks

Saran dan Komentar

Sumber Daya Tambahan:

Bagikan melalui

Menginstal dan Mendaftarkan Handler Protokol (Windows Search)

Tentang URL

Menerapkan Antarmuka Handler Protokol

ISearchProtocol dan ISearchProtocol2

IUrlAccessor, IUrlAccessor2, IUrlAccessor3, dan IUrlAccessor4

IProtocolHandlerSite

Menerapkan Handler Filter untuk Kontainer

Menginstal dan Mendaftarkan Handler Protokol

Panduan untuk Mendaftarkan Handler Protokol

Mendaftarkan Handler Protokol

Mendaftarkan Handler Tipe File Penangan Protokol

Memastikan bahwa Item Anda Diindeks

Topik terkait

Saran dan Komentar

Sumber Daya Tambahan: