Fungsi CoGetClassObject (combaseapi.h)

Artikel
08/22/2023

Menyediakan pointer ke antarmuka pada objek kelas yang terkait dengan CLSID tertentu. CoGetClassObject menemukan, dan jika perlu, secara dinamis memuat kode yang dapat dieksekusi yang diperlukan untuk melakukan ini.

Panggil CoGetClassObject secara langsung untuk membuat beberapa objek melalui objek kelas yang terdapat CLSID di registri sistem. Anda juga dapat mengambil objek kelas dari komputer jarak jauh tertentu. Sebagian besar objek kelas mengimplementasikan antarmuka IClassFactory . Anda kemudian akan memanggil CreateInstance untuk membuat objek yang tidak diinisialisasi. Namun, tidak selalu perlu melalui proses ini. Untuk membuat satu objek, panggil fungsi CoCreateInstanceEx , yang memungkinkan Anda membuat instans pada komputer jarak jauh. Ini menggantikan fungsi CoCreateInstance , yang masih dapat digunakan untuk membuat instans di komputer lokal. Kedua fungsi merangkum menyambungkan ke objek kelas, membuat instans, dan merilis objek kelas. Dua fungsi lainnya, CoGetInstanceFromFile dan CoGetInstanceFromIStorage, menyediakan pembuatan instans pada sistem jarak jauh dan aktivasi objek. Ada banyak fungsi dan metode antarmuka yang tujuannya adalah untuk membuat objek dari satu jenis dan menyediakan penunjuk ke antarmuka pada objek tersebut.

Sintaks

HRESULT CoGetClassObject(
  [in]           REFCLSID rclsid,
  [in]           DWORD    dwClsContext,
  [in, optional] LPVOID   pvReserved,
  [in]           REFIID   riid,
  [out]          LPVOID   *ppv
);

Parameter

[in] rclsid

CLSID yang terkait dengan data dan kode yang akan Anda gunakan untuk membuat objek.

[in] dwClsContext

Konteks di mana kode yang dapat dieksekusi akan dijalankan. Untuk mengaktifkan aktivasi jarak jauh, sertakan CLSCTX_REMOTE_SERVER. Untuk informasi selengkapnya tentang nilai konteks dan penggunaannya, lihat enumerasi CLSCTX .

[in, optional] pvReserved

Pointer ke komputer untuk membuat instans objek kelas. Jika parameter ini NULL, objek kelas dibuat pada komputer saat ini atau di komputer yang ditentukan di bawah kunci RemoteServerName kelas, sesuai dengan interpretasi parameter dwClsCtx . Lihat COSERVERINFO.

[in] riid

Referensi ke pengidentifikasi antarmuka, yang akan disediakan dalam ppv pada pengembalian yang berhasil. Antarmuka ini akan digunakan untuk berkomunikasi dengan objek kelas. Biasanya nilai ini IID_IClassFactory, meskipun nilai lain seperti IID_IClassFactory2 yang mendukung bentuk lisensi diizinkan. Semua IID antarmuka yang ditentukan OLE didefinisikan dalam file header OLE sebagai IID_interfacename, di mana nama antarmuka adalah nama antarmuka.

[out] ppv

Alamat variabel pointer yang menerima pointer antarmuka yang diminta dalam riid. Setelah berhasil dikembalikan, *ppv berisi penunjuk antarmuka yang diminta.

Nilai kembali

Fungsi ini dapat mengembalikan nilai berikut.

Menampilkan kode	Deskripsi
S_OK	Lokasi dan koneksi ke objek kelas yang ditentukan berhasil.
REGDB_E_CLASSNOTREG	CLSID tidak terdaftar dengan benar. Kesalahan ini juga dapat menunjukkan bahwa nilai yang Anda tentukan di dwClsContext tidak ada di registri.
E_NOINTERFACE	Objek yang diacu oleh ppv tidak mendukung antarmuka yang diidentifikasi oleh riid, atau operasi QueryInterface pada objek kelas yang dikembalikan E_NOINTERFACE.
REGDB_E_READREGDB	Terjadi kesalahan saat membaca database pendaftaran.
CO_E_DLLNOTFOUND	DLL dalam proses atau DLL handler tidak ditemukan (tergantung pada konteksnya).
CO_E_APPNOTFOUND	Executable (.exe) tidak ditemukan (hanya CLSCTX_LOCAL_SERVER).
E_ACCESSDENIED	Ada kegagalan akses umum saat dimuat.
CO_E_ERRORINDLL	Ada kesalahan dalam gambar yang dapat dieksekusi.
CO_E_APPDIDNTREG	Executable diluncurkan, tetapi tidak mendaftarkan objek kelas (dan mungkin telah dimatikan).

Keterangan

Objek kelas di OLE adalah objek perantara yang mendukung antarmuka yang mengizinkan operasi yang umum untuk sekelompok objek. Objek dalam grup ini adalah instans yang berasal dari definisi objek yang sama yang diwakili oleh satu CLSID. Biasanya, antarmuka yang diterapkan pada objek kelas adalah IClassFactory, di mana Anda dapat membuat instans objek dari definisi (kelas) tertentu.

Panggilan ke CoGetClassObject membuat, menginisialisasi, dan memberi pemanggil akses (melalui penunjuk ke antarmuka yang ditentukan dengan parameter riid ) ke objek kelas. Objek kelas adalah objek yang terkait dengan CLSID yang Anda tentukan dalam parameter rclsid . Detail bagaimana sistem menemukan kode dan data terkait dalam komputer transparan bagi pemanggil, seperti halnya pemuatan dinamis kode apa pun yang belum dimuat.

Jika konteks kelas CLSCTX_REMOTE_SERVER, menunjukkan aktivasi jarak jauh diperlukan, struktur COSERVERINFO yang disediakan dalam parameter pServerInfo memungkinkan Anda menentukan komputer tempat server berada. Untuk informasi tentang algoritma yang digunakan untuk menemukan server jarak jauh ketika pServerInfo adalah NULL, lihat enumerasi CLSCTX .

Ada dua tempat untuk menemukan CLSID untuk kelas:

Registri memegang hubungan antara CLSID dan akhiran file, dan antara CLSID dan tanda tangan file untuk menentukan kelas objek.
Saat objek disimpan ke penyimpanan persisten, CLSID-nya disimpan dengan datanya.

Untuk membuat dan menginisialisasi objek dokumen OLE yang disematkan atau ditautkan, tidak perlu memanggil CoGetClassObject secara langsung. Sebagai gantinya, panggil fungsi OleCreate atau OleCreateXXX . Fungsi-fungsi ini merangkum seluruh instansiasi objek dan proses inisialisasi, dan memanggil, di antara fungsi lain, CoGetClassObject.

Parameter riid menentukan antarmuka yang akan digunakan klien untuk berkomunikasi dengan objek kelas. Dalam kebanyakan kasus, antarmuka ini adalah IClassFactory. Ini menyediakan akses ke metode CreateInstance , di mana pemanggil kemudian dapat membuat objek yang tidak diinisialisasi dari jenis yang ditentukan dalam implementasinya. Semua kelas yang terdaftar dalam sistem dengan CLSID harus menerapkan IClassFactory.

Namun, dalam kasus yang jarang terjadi, Anda mungkin ingin menentukan beberapa antarmuka lain yang menentukan operasi yang umum untuk sekumpulan objek. Misalnya, dalam cara OLE mengimplementasikan moniker, antarmuka pada objek kelas adalah IParseDisplayName, digunakan untuk mengubah nama tampilan objek menjadi moniker.

Parameter dwClsContext menentukan konteks eksekusi, memungkinkan satu CLSID dikaitkan dengan potongan kode yang berbeda dalam konteks eksekusi yang berbeda. Enumerasi CLSCTX menentukan bendera konteks yang tersedia. Konsultasi CoGetClassObject (sesuai dengan konteks yang ditunjukkan) baik registri maupun objek kelas yang saat ini terdaftar dengan memanggil fungsi CoRegisterClassObject .

Untuk merilis objek kelas, gunakan metode Rilis objek kelas. Fungsi CoRevokeClassObject hanya akan digunakan untuk menghapus CLSID objek kelas dari registri sistem.

Persyaratan


Klien minimum yang didukung	Windows 2000 Professional [hanya aplikasi desktop]
Server minimum yang didukung	Windows 2000 Server [hanya aplikasi desktop]
Target Platform	Windows
Header	combaseapi.h (termasuk Objbase.h)
Pustaka	Ole32.lib
DLL	Ole32.dll