Fungsi CoCreateInstance (combaseapi.h)

Artikel
22/08/2023

Membuat dan menginisialisasi objek tunggal dari kelas yang terkait dengan CLSID tertentu.

Panggil CoCreateInstance saat Anda hanya ingin membuat satu objek pada sistem lokal. Untuk membuat satu objek pada sistem jarak jauh, panggil fungsi CoCreateInstanceEx . Untuk membuat beberapa objek berdasarkan satu CLSID, panggil fungsi CoGetClassObject .

Sintaks

HRESULT CoCreateInstance(
  [in]  REFCLSID  rclsid,
  [in]  LPUNKNOWN pUnkOuter,
  [in]  DWORD     dwClsContext,
  [in]  REFIID    riid,
  [out] LPVOID    *ppv
);

Parameter

[in] rclsid

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

[in] pUnkOuter

Jika NULL, menunjukkan bahwa objek tidak dibuat sebagai bagian dari agregat. Jika non-NULL, arahkan ke antarmuka IUnknown objek agregat ( IUnknown pengontrol).

[in] dwClsContext

Konteks di mana kode yang mengelola objek yang baru dibuat akan berjalan. Nilai diambil dari enumerasi CLSCTX.

[in] riid

Referensi ke pengidentifikasi antarmuka yang akan digunakan untuk berkomunikasi dengan objek.

[out] ppv

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

Nilai kembali

Fungsi ini dapat mengembalikan nilai berikut.

Menampilkan kode	Deskripsi
S_OK	Instans kelas objek yang ditentukan berhasil dibuat.
REGDB_E_CLASSNOTREG	Kelas yang ditentukan tidak terdaftar dalam database pendaftaran. Juga dapat menunjukkan bahwa jenis server yang Anda minta dalam enumerasi CLSCTX tidak terdaftar atau nilai untuk jenis server di registri rusak.
CLASS_E_NOAGGREGATION	Kelas ini tidak dapat dibuat sebagai bagian dari agregat.
E_NOINTERFACE	Kelas yang ditentukan tidak mengimplementasikan antarmuka yang diminta, atau IUnknown pengontrol tidak mengekspos antarmuka yang diminta.
E_POINTER	Parameter ppv adalah NULL.

Keterangan

Fungsi CoCreateInstance menyediakan pintasan yang nyaman dengan menyambungkan ke objek kelas yang terkait dengan CLSID yang ditentukan, membuat instans yang diinisialisasi default, dan merilis objek kelas. Dengan demikian, ini merangkum fungsionalitas berikut:

CoGetClassObject(rclsid, dwClsContext, NULL, IID_IClassFactory, &pCF); 
hresult = pCF->CreateInstance(pUnkOuter, riid, ppvObj);
pCF->Release();

Lebih mudah untuk menggunakan CoCreateInstance ketika Anda hanya perlu membuat satu instans objek pada komputer lokal. Jika Anda membuat instans di komputer jarak jauh, panggil CoCreateInstanceEx. Saat Anda membuat beberapa instans, lebih efisien untuk mendapatkan pointer ke antarmuka IClassFactory objek kelas dan menggunakan metodenya sesuai kebutuhan. Dalam kasus terakhir, Anda harus menggunakan fungsi CoGetClassObject .

Dalam enumerasi CLSCTX , Anda dapat menentukan jenis server yang digunakan untuk mengelola objek. Konstanta dapat CLSCTX_INPROC_SERVER, CLSCTX_INPROC_HANDLER, CLSCTX_LOCAL_SERVER, CLSCTX_REMOTE_SERVER atau kombinasi apa pun dari nilai-nilai ini. Konstanta CLSCTX_ALL didefinisikan sebagai kombinasi keempatnya. Untuk informasi selengkapnya tentang penggunaan satu atau kombinasi konstanta ini, lihat CLSCTX.

Aplikasi UWP

Meskipun tidak ada batasan di mana CLSID yang dapat diteruskan aplikasi UWP ke CoCreateInstance, banyak objek akan gagal dengan E_ACCESSDENIED karena alasan keamanan, terutama jika tidak berjalan dalam proses. Selain itu, bahkan jika Anda berhasil membuat objek, itu mungkin gagal di lain waktu karena batasan keamanan UWP, perbedaan model aplikasi, dll. Secara khusus, tugas latar belakang harus membatasi objek yang berkomunikasi dengannya untuk menghindari macet atau komplikasi lainnya karena terhubung siaga.

Contoh

// Create WIC factory
hr = CoCreateInstance(
    CLSID_WICImagingFactory,
    NULL,
    CLSCTX_INPROC_SERVER,
    IID_PPV_ARGS(&m_pIWICFactory)
    );

Persyaratan

Persyaratan	Nilai
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