Mencari dengan Antarmuka IDirectorySearch

Antarmuka IDirectorySearch menyediakan antarmuka tingkat tinggi dan overhead rendah untuk mengkueri data direktori atau katalog global. Antarmuka IDirectorySearch COM hanya dapat digunakan dengan vtable, dan dengan demikian, tidak tersedia untuk lingkungan pengembangan berbasis Automation.

Untuk melakukan pencarian

1. Ikat ke objek dalam direktori.
2. Panggil QueryInterface untuk mendapatkan penunjuk IDirectorySearch.
3. Jalankan pencarian menggunakan penunjuk IDirectorySearch . Panggil metode IDirectorySearch::ExecuteSearch, dan berikan filter pencarian, nama atribut yang diminta, dan parameter lainnya.

Untuk informasi selengkapnya tentang sintaks filter pencarian, lihat Sintaks Filter Pencarian.

Eksekusi kueri khusus untuk penyedia. Dengan beberapa penyedia, eksekusi kueri aktual tidak terjadi sampai IDirectorySearch::GetFirstRow atau IDirectorySearch::GetNextRow dipanggil. Antarmuka IDirectorySearch bekerja dengan filter pencarian secara langsung. Baik dialek SQL maupun dialek LDAP tidak diperlukan.

Antarmuka IDirectorySearch menyediakan metode untuk menghitung kumpulan hasil, baris demi baris. Metode IDirectorySearch::GetFirstRow mengambil baris pertama dan IDirectorySearch::GetNextRow memindahkan Anda ke baris berikutnya dari baris saat ini. Ketika Anda telah mencapai baris terakhir, memanggil metode ini mengembalikan kode kesalahan S_ADS_NOMORE_ROWS. Sebaliknya, IDirectorySearch::GetPreviousRow memindahkan Anda kembali satu baris pada satu waktu. Nilai pengembalian S_ADS_NOMORE_ROWS menunjukkan bahwa Anda telah mencapai baris pertama dari kumpulan hasil. Metode ini beroperasi pada tataan hasil, residen dalam memori, pada klien. Dengan demikian, ketika pencarian halaman dan asinkron dilakukan dan opsi _CACHE_RESULTS dinonaktifkan, pengguliran mundur dapat memiliki konsekuensi yang tidak terduga.

Ketika Anda telah menemukan baris yang sesuai, panggil IDirectorySearch::GetColumn untuk mendapatkan item data, kolom menurut kolom. Untuk setiap panggilan, Anda meneruskan nama kolom yang diminati. Item data yang dikembalikan adalah penunjuk ke struktur ADS_SEARCH_COLUMN. GetColumn mengalokasikan struktur ini untuk Anda, tetapi Anda harus membebaskannya menggunakan FreeColumn. Panggil CloseSearchHandle untuk menyelesaikan operasi pencarian.

Untuk melakukan pencarian direktori

1. Ikat ke penyedia LDAP. Ini mungkin pengendali domain atau penyedia katalog global.

2. Ambil Antarmuka COM IDirectorySearch dengan panggilan ke QueryInterface; operasi ini mungkin telah dilakukan di Langkah 1 selama pengikatan awal.

   Secara opsional, panggil SetSearchPreference untuk memilih opsi untuk menangani hasil pencarian Anda.

3. Panggil ExecuteSearch. Bergantung pada opsi yang diatur dalam SetSearchPreference , ini mungkin, atau mungkin tidak, mulai eksekusi kueri.

4. Panggil GetNextRow untuk memindahkan indeks baris (internal ke IDirectorySearch) ke baris pertama.

5. Baca data dari baris menggunakan GetColumn, lalu panggil FreeColumn untuk merilis memori yang dialokasikan oleh GetColumn.

6. Ulangi Langkah 5 hingga semua data diambil dari hasil pencarian, atau hingga GetNextRow kembali S_ADS_NOMORE_ROWS.

7. Panggil AbandonSearch dan CloseSearchHandle setelah selesai.

Contoh kode berikut menunjukkan skenario ini. Untuk mulai mengikat ADSI, panggil fungsi ADsOpenObject.

HRESULT hr = S_OK; // COM result variable
ADS_SEARCH_COLUMN col;  // COL for iterations
LPWSTR szUsername = NULL; // user name
LPWSTR szPassword = NULL; // password
 
// Interface Pointers.
IDirectorySearch     *pDSSearch    =NULL;
 
// Initialize COM.
CoInitialize(0);

// Add code to securely retrieve the user name and password or
// leave both as NULL to use the default security context.
 
// Open a connection with server.
hr = ADsOpenObject(L"LDAP://coho.salmon.Fabrikam.com", 
szUsername,
szPassword,
ADS_SECURE_AUTHENTICATION,
IID_IDirectorySearch,
(void **)&pDSSearch);

Ini menyediakan penunjuk ke antarmuka IDirectorySearch.

Sekarang setelah ada antarmuka COM untuk instans IDirectoryInterface, panggil IDirectorySearch::SetSearchPreference.

Buat array nama atribut untuk bersiap memanggil fungsi IDirectorySearch::ExecuteSearch. Nama atribut ditentukan dalam skema Direktori Aktif. Untuk informasi selengkapnya tentang definisi skema, lihat Model Skema ADSI. Nama atribut yang tercantum dikembalikan, jika didukung oleh objek, sebagai kumpulan hasil pencarian.

LPWSTR pszAttr[] = { L"description", L"Name", L"distinguishedname" };
ADS_SEARCH_HANDLE hSearch;
DWORD dwCount = 0;
DWORD dwAttrNameSize = sizeof(pszAttr)/sizeof(LPWSTR);

Sekarang, panggil fungsi ExecuteSearch. Pencarian tidak berjalan sampai Anda memanggil metode GetNextRow.

// Search for all objects with the 'cn' property that start with c.
hr = pDSSearch->ExecuteSearch(L"(cn=c*)",pszAttr ,dwAttrNameSize,&hSearch );

Panggil GetNextRow untuk mengurutkan baris dalam hasil. Setiap baris kemudian dikueri untuk atribut "deskripsi". Jika atribut ditemukan, atribut akan ditampilkan.

LPWSTR pszColumn;
    while( pDSSearch->GetNextRow( hSearch) != S_ADS_NOMORE_ROWS )
    {
        // Get the property.
        hr = pDSSearch->GetColumn( hSearch, L"description", &col );
 
        // If this object supports this attribute, display it.
        if ( SUCCEEDED(hr) )
        { 
           if (col.dwADsType == ADSTYPE_CASE_IGNORE_STRING)
              wprintf(L"The description property:%s\r\n", col.pADsValues->CaseIgnoreString); 
           pDSSearch->FreeColumn( &col );
        }
        else
            puts("description property NOT available");
        puts("------------------------------------------------");
        dwCount++;
    }
    pDSSearch->CloseSearchHandle(hSearch);
    pDSSearch->Release();

Untuk mengakhiri pencarian, panggil metode AbandonSearch.

Ketahuilah bahwa jika ukuran halaman tidak diatur, GetNextRow memblokir hingga seluruh tataan hasil dikembalikan ke klien. Jika ukuran halaman diatur, maka GetNextRow memblokir hingga halaman pertama (ukuran halaman = jumlah baris dalam halaman) dikembalikan. Jika ukuran halaman diatur dan kueri akan diurutkan dan Anda tidak mencari setidaknya satu atribut terindeks, maka nilai ukuran halaman diabaikan, dan server menghitung seluruh hasil yang ditetapkan sebelum mengembalikan data. Ini memiliki efek pemblokiran GetNextRow hingga kueri selesai.

Catatan

Untuk mengubah kueri ini dari pencarian direktori ke pencarian katalog global, panggilan ADsOpenObject diubah.

 

// Open a connection with the server.
hr = ADsOpenObject(L"GC://coho.salmon.Fabrikam.com", 
szUsername, 
szPassword, 
ADS_SECURE_AUTHENTICATION,
IID_IDirectorySearch,
(void **)&pDSSearch);