Metode IDispatch::GetIDsOfNames (oaidl.h)

Artikel
08/25/2023

Memetakan satu anggota dan sekumpulan nama argumen opsional ke sekumpulan DISPID bilangan bulat yang sesuai, yang dapat digunakan pada panggilan berikutnya ke Panggil. Fungsi pengiriman DispGetIDsOfNames menyediakan implementasi standar GetIDsOfNames.

Sintaks

HRESULT GetIDsOfNames(
  [in]  REFIID   riid,
  [in]  LPOLESTR *rgszNames,
  [in]  UINT     cNames,
  [in]  LCID     lcid,
  [out] DISPID   *rgDispId
);

Parameter

[in] riid

Disiapkan untuk penggunaan masa mendatang. Pasti IID_NULL.

[in] rgszNames

Array nama yang akan dipetakan.

[in] cNames

Jumlah nama yang akan dipetakan.

[in] lcid

Konteks lokal untuk menginterpretasikan nama.

[out] rgDispId

Array yang dialokasikan penelepon, setiap elemen berisi pengidentifikasi (ID) yang sesuai dengan salah satu nama yang diteruskan dalam array rgszNames. Elemen pertama mewakili nama anggota. Elemen berikutnya mewakili setiap parameter anggota.

Nilai kembali

Metode ini dapat mengembalikan salah satu nilai ini.

Menampilkan kode	Deskripsi
S_OK	Berhasil.
E_OUTOFMEMORY	Kehabisan memori.
DISP_E_UNKNOWNNAME	Satu atau beberapa nama yang ditentukan tidak diketahui. Array DISPID yang dikembalikan berisi DISPID_UNKNOWN untuk setiap entri yang sesuai dengan nama yang tidak diketahui.
DISP_E_UNKNOWNLCID	Pengidentifikasi lokal (LCID) tidak dikenali.

Keterangan

Implementasi IDispatch dapat mengaitkan nilai ID bilangan bulat positif dengan nama tertentu. Nol dicadangkan untuk properti default, atau Nilai ; –1 dicadangkan untuk menunjukkan nama yang tidak diketahui; dan nilai negatif lainnya didefinisikan untuk tujuan lain. Misalnya, jika GetIDsOfNames dipanggil, dan implementasi tidak mengenali satu atau beberapa nama, ia mengembalikan DISP_E_UNKNOWNNAME, dan array rgDispId berisi DISPID_UNKNOWN untuk entri yang sesuai dengan nama yang tidak diketahui.

DISPID anggota dan parameter harus tetap konstan selama masa pakai objek. Ini memungkinkan klien untuk mendapatkan DISPID sekali, dan menyimpannya untuk digunakan nanti.

Ketika GetIDsOfNames dipanggil dengan lebih dari satu nama, nama depan (rgszNames[0]) sesuai dengan nama anggota, dan nama berikutnya sesuai dengan nama parameter anggota.

Nama yang sama dapat memetakan ke DISPID yang berbeda, tergantung pada konteks. Misalnya, nama mungkin memiliki DISPID ketika digunakan sebagai nama anggota dengan antarmuka tertentu, ID yang berbeda sebagai anggota antarmuka yang berbeda, dan pemetaan yang berbeda untuk setiap kali muncul sebagai parameter.

GetIDsOfNames digunakan saat klien IDispatch mengikat ke nama pada durasi. Untuk mengikat pada waktu kompilasi, klien IDispatch dapat memetakan nama ke DISPID dengan menggunakan antarmuka informasi jenis yang dijelaskan dalam Antarmuka Deskripsi Jenis. Ini memungkinkan klien untuk mengikat anggota pada waktu kompilasi dan menghindari panggilan GetIDsOfNames pada durasi. Untuk deskripsi pengikatan pada waktu kompilasi, lihat Antarmuka Deskripsi Jenis.

Implementasi GetIDsOfNames tidak peka huruf besar/kecil. Pengguna yang memerlukan pemetaan nama peka huruf besar/kecil harus menggunakan antarmuka informasi jenis untuk memetakan nama ke DISPID, daripada memanggil GetIDsOfNames.

Hati Anda tidak dapat menggunakan metode ini untuk mengakses nilai yang telah ditambahkan secara dinamis, seperti nilai yang ditambahkan melalui JavaScript. Sebagai gantinya, gunakan GetDispID antarmuka IDispatchEx. Untuk informasi selengkapnya, lihat antarmuka IDispatchEx.

Contoh

Kode berikut dari file sampel Baris Lines.cpp mengimplementasikan fungsi anggota GetIDsOfNames untuk kelas CLine. Objek ActiveX atau OLE menggunakan implementasi standar, DispGetIDsOfNames. Implementasi ini bergantung pada DispGetIdsOfNames untuk memvalidasi argumen input. Untuk membantu meminimalkan risiko keamanan, sertakan kode yang melakukan validasi argumen input yang lebih kuat.

STDMETHODIMP 
CLine::GetIDsOfNames(
      REFIID riid,
      OLECHAR ** rgszNames,
      UINT cNames,
      LCID lcid,
      DISPID * rgDispId)
{
      return DispGetIDsOfNames(m_ptinfo, rgszNames, cNames, rgDispId);
}

Kode berikut mungkin muncul di klien ActiveX yang memanggil GetIDsOfNames untuk mendapatkan DISPID properti Warna CLine.

HRESULT hresult;
IDispatch * pdisp = (IDispatch *)NULL;
DISPID dispid;
OLECHAR * szMember = "color";

// Code that sets a pointer to the dispatch (pdisp) is omitted.

hresult = pdisp->GetIDsOfNames(
   IID_NULL,
   &szMember,
   1, LOCALE_SYSTEM_DEFAULT,
   &dispid);