Fungsi QISearch (shlwapi.h)

Artikel
08/26/2023

Implementasi berbasis tabel dari metode IUnknown::QueryInterface .

Sintaks

HRESULT QISearch(
  [in]  void     *that,
  [in]  LPCQITAB pqit,
  [in]  REFIID   riid,
  [out] void     **ppv
);

Parameter

[in] that

Jenis: void*

Penunjuk ke dasar objek COM.

[in] pqit

Jenis: LPCQITAB

Array struktur QITAB . Struktur terakhir dalam array harus mengatur anggota piid-nya ke NULL dan anggota dwOffset-nya diatur ke 0.

[in] riid

Jenis: REFIID

Referensi ke IID antarmuka untuk diambil melalui ppv.

[out] ppv

Jenis: void**

Ketika metode ini berhasil dikembalikan, berisi pointer antarmuka yang diminta dalam riid.

Nilai kembali

Jenis: HRESULT

Mengembalikan S_OK jika antarmuka yang diminta ditemukan dalam tabel atau jika antarmuka yang diminta adalah IUnknown. Mengembalikan E_NOINTERFACE jika antarmuka yang diminta tidak ditemukan.

Keterangan

Catatan Sebelum Windows Vista, QISearch tidak diekspor berdasarkan nama atau dideklarasikan dalam file header publik. Untuk menggunakannya dalam kasus tersebut, Anda harus menggunakan GetProcAddress dan meminta ordinal 219 dari Shlwapi.dll untuk mendapatkan penunjuk fungsi. Di bawah Windows Vista, QISearch disertakan dalam Shlwapi.h dan ini tidak diperlukan.

Jika antarmuka yang diminta adalah IUnknown, maka QISearch menggunakan entri pertama dari array struktur QITAB yang ditentukan. Jika tidak, QISearch mencari tabel hingga menemukan IID yang cocok atau mencapai akhir tabel. Jika IID yang cocok ditemukan, fungsi memajukan penunjuk antarmuka terkait dengan jumlah byte yang ditentukan oleh anggota dwOffset dari struktur QITAB antarmuka dan diinterpretasikan kembali sebagai penunjuk COM. Penunjuk tersebut ditetapkan ke parameter ppv fungsi QISearch. Metode ini juga memanggil IUnknown::AddRef untuk menambah jumlah referensi antarmuka.

Jika QISearch mencapai akhir tabel tanpa menemukan antarmuka, QISearch mengembalikan E_NOINTERFACE dan mengatur ppv ke NULL.

Penting untuk menyertakan semua antarmuka yang berlaku dalam tabel. Misalnya, jika objek mengimplementasikan antarmuka turunan, Anda juga harus menyertakan antarmuka dasar dalam tabel.

Kami menyarankan agar Anda menggunakan makro IID_PPV_ARGS , yang ditentukan dalam Objbase.h, untuk mengemas parameter riid dan ppv . Makro ini menyediakan IID yang benar berdasarkan antarmuka yang ditunjukkan oleh nilai dalam ppv, yang menghilangkan kemungkinan kesalahan pengkodian dalam riid yang dapat menyebabkan hasil yang tidak terduga.

Catatan Pustaka Templat Aktif (ATL) menyediakan versi yang jauh lebih baik dari implementasi QueryInterface berbasis tabel.

Contoh

Contoh berikut menggambarkan cara menggunakan QISearch untuk mengimplementasikan QueryInterface. Ini menggunakan makro offsetofclass dari ATL untuk menghitung offset dari dasar objek CSample ke antarmuka yang ditentukan.

Objek ini mendukung dua antarmuka selain IUnknown, sehingga ada dua entri non-NULL dalam tabel QITAB . Entri untuk setiap antarmuka menentukan penunjuk ke IID terkait (IID_IPersist atau IID_IPersistFolder) dan offset penunjuk antarmuka relatif terhadap penunjuk dasar kelas. Sampel menggunakan makro offsetofclass dari ATL untuk menentukan offset tersebut.

Catatan Lupa menyertakan semua kelas dasar, termasuk kelas tidak langsung, adalah kesalahan umum. Perhatikan bahwa ada entri untuk antarmuka IPersist . Antarmuka ini adalah kelas dasar tidak langsung untuk CSample, diwarisi melalui IPersistFolder.


class CSample : public IPersistFolder
{
  public:
    CSample() { /* other construction goes here */ }
    
    STDMETHODIMP QueryInterface(REFIID riid, void **ppv);
    STDMETHODIMP_(ULONG) AddRef();
    STDMETHODIMP_(ULONG) Release();
  
    // *** IPersist ***
    STDMETHODIMP GetClassID(CLSID *pClassID);
    
    // *** IPersistFolder ***
    STDMETHODIMP Initialize(LPCITEMIDLIST pidl);
  
  private:
  // private members go here
};

HRESULT CSample::QueryInterface(REFIID riid, void **ppv)
{
    static QITAB rgqit[] = 
    {   
        QITABENT(CSample, IPersist),
        QITABENT(CSample, IPersistFolder)
        { 0 },
    };

    return QISearch(this, rgqit, IID_PPV_ARGS(&ppv));
}

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows 2000 Professional, Windows XP [hanya aplikasi desktop]
Server minimum yang didukung	Windows 2000 Server, Windows Server 2003 [hanya aplikasi desktop]
Target Platform	Windows
Header	shlwapi.h
Pustaka	Shlwapi.lib
DLL	Shlwapi.dll (versi 5.0 atau yang lebih baru)

Bagikan melalui