Cara Mencari Menggunakan VLV

Direktori Aktif mendukung pencarian tampilan daftar virtual (VLV). Gaya pencarian ini dirancang khusus untuk kumpulan hasil besar dan memungkinkan aplikasi untuk menampilkan subset ribuan entri tanpa benar-benar harus mengambil setiap entri.

Ada dua cara berbeda yang dapat digunakan oleh pencarian VLV. Yang pertama adalah mengambil atribut untuk entri tertentu berdasarkan offset numerik. Metode ini berguna saat mengambil hasil pencarian sebagai respons terhadap operasi pengguliran.

Cara kedua untuk menggunakan pencarian VLV adalah dengan mencari bagian atau semua atribut tekstual dan hanya menampilkan hasil pencarian. Contoh penggunaan ini adalah buku alamat. Jika pengguna mengetik "s", maka aplikasi dapat menggunakan pencarian VLV untuk mencari entri yang memiliki nama umum yang dimulai dengan "s". Jika pengguna kemudian menambahkan "m" ke "s", aplikasi dapat menggunakan pencarian VLV lain untuk mencari entri yang memiliki nama umum yang dimulai dengan "sm".

Untuk melakukan pencarian VLV, instruksikan ADSI untuk menggunakan kontrol VLV. Untuk melakukan ini, panggil metode IDirectorySearch::SetSearchPreference dengan opsi pencarian ADS_SEARCHPREF_VLV dengan nilai ADSTYPE_PROV_SPECIFIC . Nilai ADSTYPE_PROV_SPECIFIC adalah penunjuk ke struktur ADS_VLV yang berisi data tentang pencarian. Fungsi contoh GetVLVItemCount menunjukkan cara mengatur kedua preferensi pencarian ini.

Semua pencarian VLV harus menggunakan pengurutan hasil sisi server, yang dilakukan dengan mengatur preferensi pencarian ADS_SEARCHPREF_SORT_ON . Untuk informasi selengkapnya tentang preferensi pencarian ADS_SEARCHPREF_SORT_ON , lihat Mengurutkan Hasil Pencarian dengan IDirectorySearch.

Saat pencarian VLV dilakukan, sejumlah metadata tentang pencarian dikembalikan dalam kolom yang diambil dengan memanggil IDirectorySearch::GetColumn dengan pengidentifikasi ADS_VLV_RESPONSE. Data ini terkandung dalam struktur ADS_VLV. Kepentingan tertentu adalah anggota dwContentCount dan lpContextID . Anggota dwContentCount akan berisi jumlah hasil yang memenuhi kriteria pencarian VLV. Nilai ini dapat digunakan sebagai perkiraan jumlah total item yang akan dikembalikan untuk pencarian jenis tersebut. Anggota lpContextID berisi nilai yang ditentukan server yang dapat diteruskan ke pencarian berikutnya untuk mengidentifikasi pencarian. Menggunakan lpContextID dapat meningkatkan performa pencarian. Ketahuilah bahwa lpContextID adalah nilai yang ditentukan server dan panjangnya terkandung dalam anggota dwContextIDLength . Buffer ini dibebaskan ketika metode IDirectorySearch::FreeColumn dipanggil, sehingga pemanggil harus mengalokasikan buffer dengan ukuran yang sesuai dan menyalin dan menyimpan konten buffer di antara pencarian.

Untuk informasi selengkapnya tentang kontrol LDAP VLV, lihat Mencari dengan Kontrol VLV LDAP.

Untuk informasi selengkapnya, lihat:

• Mendapatkan Jumlah Item
• Mencari berdasarkan Offset
• Mencari berdasarkan String
• Contoh Kode untuk Menggunakan Pencarian VLV

Mendapatkan Jumlah Item

Untuk mendapatkan perkiraan jumlah item yang akan dikembalikan untuk pencarian tertentu, lakukan langkah-langkah berikut.

1. Isi struktur ADS_VLV dengan semua nilai nol atau NULL.

2. Isi ADS_SEARCHPREF_INFO dengan nilai berikut.

   • Atur anggota dwSearchPref ke ADS_SEARCHPREF_VLV.
   • Atur anggota vValue.dwType ke ADSTYPE_PROV_SPECIFIC.
   • Atur anggota vValue.ProviderSpecific.dwLength ke ukuran struktur ADS_VLV .
   • Atur anggota vValue.ProviderSpecific.lpValue ke alamat struktur ADS_VLV dari Langkah 1.

3. Isi struktur ADS_SORTKEY seperti yang ditunjukkan dalam Mengurutkan Hasil Pencarian dengan IDirectorySearch untuk mengurutkan atribut yang diinginkan.

4. Isi ADS_SEARCHPREF_INFO lain untuk menambahkan struktur ADS_SORTKEY ke preferensi pencarian seperti yang ditunjukkan dalam Mengurutkan Hasil Pencarian dengan IDirectorySearch.

5. Tambahkan preferensi pencarian lain yang diinginkan dan panggil IDirectorySearch::SetSearchPreference untuk mengatur preferensi pencarian.

6. Lakukan pencarian dengan IDirectorySearch::ExecuteSearch.

7. Dapatkan baris pertama hasil dengan memanggil IDirectorySearch::GetFirstRow.

8. Panggil IDirectorySearch::GetColumn dengan ADS_VLV_RESPONSE untuk mendapatkan metadata pencarian VLV.

9. Transmisikan pADsValues-ProviderSpecific.lpValue> dari struktur ADS_SEARCH_COLUMN ke penunjuk struktur ADS_VLV. Anggota dwContentCount dari struktur ADS_VLV ini berisi perkiraan jumlah item yang akan dikembalikan oleh pencarian jenis tersebut.

10. Jika pencarian VLV lain dengan jenis yang sama akan dilakukan, buat salinan data lpContextID dan pertahankan untuk pencarian VLV berikutnya.

Fungsi contoh GetVLVItemCount menunjukkan cara melakukan ini.

Mencari berdasarkan Offset

Satu hal yang membuat pencarian VLV begitu cepat adalah mungkin untuk mencari hasil tertentu oleh offset numerik. Misalnya, jika pencarian akan menghasilkan 10.000 item yang dikembalikan, pencarian VLV memungkinkan untuk mendapatkan informasi untuk sekitar item ke-4072 tanpa harus mengambil semua item sebelum item yang dimaksud.

Offset ditentukan sebagai rasio antara offset dan jumlah konten. Rasio berguna karena server mungkin tidak memiliki perkiraan yang akurat tentang jumlah entri yang ada dalam daftar atau ukuran daftar mungkin berubah selama pengguna menelusurinya. Karena Anda harus menunjukkan awal dan akhir daftar, Anda dapat menggunakan perkiraan nilai untuk jumlah konten dalam permintaan pencarian pertama, bersama dengan nilai offset. Server menggunakan data ini untuk menghitung offset yang sesuai dalam daftar, berdasarkan ide jumlah kontennya, yang dikirim dalam responsnya kepada klien melalui anggota dwContentCount dari struktur ADS_VLV . Misalnya, jika Anda memperkirakan ukuran daftar menjadi 3000, dan Anda ingin offset menjadi entri daftar 1500, Anda akan mengatur dwContentCount ke 3000 dan dwOffset ke 1500. Jika server memperkirakan ukuran daftar aktual menjadi 4500, server akan menghitung ulang offset ke 2250, dan mengembalikan perkiraan baru di dwContentCount dan dwOffset.

Fungsi contoh GetVLVItemText menunjukkan cara melakukan ini.

Dimungkinkan juga untuk mengambil lebih dari satu baris data dengan satu panggilan pencarian. Ini dilakukan di Langkah 1 dengan mengatur anggota dwBeforeCount dan dwAfterCount dari struktur ADS_VLV dengan tepat. Anggota dwBeforeCount berisi jumlah item yang muncul dalam daftar sebelum item yang dimaksud dan anggota dwAfterCount berisi jumlah item yang muncul dalam daftar setelah item yang dimaksud. Kedua jumlah ini mengecualikan item itu sendiri, jadi mengatur dwBeforeCount ke 10 dan dwAfterCount ke 10 akan menghasilkan total 21 item yang dikembalikan. Opsi ini memungkinkan penembolokan hasil pencarian di sisi klien.

Mencari berdasarkan String

Dimungkinkan juga untuk menggunakan pencarian VLV untuk menemukan item yang memiliki atribut string yang nilainya cocok dengan semua atau sebagian string tanpa harus mengambil semua item. Pencocokan string dilakukan terhadap atribut yang ditentukan dalam struktur ADS_SORTKEY preferensi pencarian ADS_SEARCHPREF_SORT_ON.

Untuk mencari item tertentu menurut string, lakukan langkah-langkah berikut.

1. Isi struktur ADS_VLV dengan nilai berikut. Anggota tambahan struktur harus diatur ke nol atau NULL.

   • Atur anggota pszTarget ke penunjuk ke string yang dihentikan NULL yang berisi string yang akan dicari.
   • Atur anggota lpContextID ke alamat salinan buffer ID konteks dan dwContextIDLength ke panjang, dalam byte, dari buffer ID konteks. Jika tidak ada ID konteks yang disimpan, kedua anggota ini harus nol atau NULL.

2. Atur preferensi pencarian seperti yang ditunjukkan pada Langkah 2 hingga 5 dari prosedur Mendapatkan Jumlah Item.

3. Lakukan pencarian dengan IDirectorySearch::ExecuteSearch.

4. Dapatkan baris pertama hasil dengan memanggil IDirectorySearch::GetFirstRow.

5. Panggil IDirectorySearch::GetColumn dengan nama atribut yang akan diambil untuk mendapatkan data aktual untuk item yang diminta.

6. Panggil IDirectorySearch::GetColumn dengan ADS_VLV_RESPONSE untuk mendapatkan metadata pencarian VLV.

7. Transmisikan pADsValues-ProviderSpecific.lpValue> dari struktur ADS_SEARCH_COLUMN ke penunjuk struktur ADS_VLV.

8. Buat salinan data lpContextID dan pertahankan untuk pencarian VLV berikutnya. Jika diperlukan, anggota dwOffset berisi indeks berbasis satu dari item pertama yang atribut stringnya dimulai dengan nilai yang ditentukan dalam pszTarget.

Fungsi contoh GetVLVItemsByString menunjukkan cara melakukan ini.

Demikian pula dengan mencari berdasarkan indeks, dimungkinkan juga untuk mengambil lebih dari satu baris data dengan satu panggilan pencarian. Ini dicapai dengan cara yang sama dengan mengatur anggota dwBeforeCount dan dwAfterCount dari struktur ADS_VLV dengan tepat.