Fungsi CoCreateInstanceEx (combaseapi.h)

Artikel
08/22/2023

Membuat instans kelas tertentu di komputer tertentu.

Sintaks

HRESULT CoCreateInstanceEx(
  [in]      REFCLSID     Clsid,
  [in]      IUnknown     *punkOuter,
  [in]      DWORD        dwClsCtx,
  [in]      COSERVERINFO *pServerInfo,
  [in]      DWORD        dwCount,
  [in, out] MULTI_QI     *pResults
);

Parameter

[in] Clsid

CLSID objek yang akan dibuat.

[in] punkOuter

Jika parameter ini non-NULL, menunjukkan instans sedang dibuat sebagai bagian dari agregat, dan punkOuter akan digunakan sebagai IUnknown pengendali instans baru. Agregasi saat ini tidak didukung lintas proses atau lintas komputer. Saat membuat instans objek di luar proses, CLASS_E_NOAGGREGATION akan dikembalikan jika punkOuter bukan NULL.

[in] dwClsCtx

Nilai dari enumerasi CLSCTX .

[in] pServerInfo

Informasi tentang komputer untuk membuat instans objek. Lihat COSERVERINFO. Parameter ini dapat berupa NULL, dalam hal ini objek dibuat di komputer lokal atau di komputer yang ditentukan dalam registri di bawah nilai RemoteServerName kelas, sesuai dengan interpretasi parameter dwClsCtx .

[in] dwCount

Jumlah struktur dalam pResults. Nilai ini harus lebih besar dari 0.

[in, out] pResults

Array struktur MULTI_QI . Setiap struktur memiliki tiga anggota: pengidentifikasi untuk antarmuka yang diminta (pIID), lokasi untuk mengembalikan penunjuk antarmuka (pItf) dan nilai pengembalian panggilan ke QueryInterface (jam).

Nilai kembali

Fungsi ini dapat mengembalikan nilai pengembalian standar E_INVALIDARG, serta nilai berikut.

Menampilkan kode	Deskripsi
S_OK	Menunjukkan keberhasilan.
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.
CO_S_NOTALLINTERFACES	Setidaknya satu, tetapi tidak semua antarmuka yang diminta dalam array pResults berhasil diambil. Anggota jam dari masing-masing struktur MULTI_QI dalam pResults menunjukkan dengan S_OK atau E_NOINTERFACE apakah antarmuka tertentu dikembalikan.
E_NOINTERFACE	Tidak ada antarmuka yang diminta dalam array pResults yang berhasil diambil.

Keterangan

CoCreateInstanceEx membuat satu objek yang tidak diinisialisasi yang terkait dengan CLSID yang diberikan pada komputer jarak jauh tertentu. Ini adalah ekstensi dari fungsi CoCreateInstance, yang hanya membuat objek di komputer lokal. Selain itu, daripada meminta satu antarmuka dan mendapatkan satu penunjuk ke antarmuka tersebut, CoCreateInstanceEx memungkinkan untuk menentukan array struktur, masing-masing menunjuk ke pengidentifikasi antarmuka (IID) pada input, dan, saat kembali, berisi (jika tersedia) penunjuk ke antarmuka yang diminta dan nilai pengembalian panggilan QueryInterface untuk antarmuka tersebut. Ini memungkinkan lebih sedikit perjalanan pulang pergi antar komputer.

Fungsi ini merangkum tiga panggilan: pertama, ke CoGetClassObject untuk terhubung ke objek kelas yang terkait dengan CLSID yang ditentukan, menentukan lokasi kelas; kedua, ke IClassFactory::CreateInstance untuk membuat instans yang tidak diinisialisasi, dan akhirnya, ke IClassFactory::Release, untuk merilis objek kelas.

Objek yang dibuat masih harus diinisialisasi melalui panggilan ke salah satu antarmuka inisialisasi (seperti IPersistStorage::Load). Dua fungsi, CoGetInstanceFromFile dan CoGetInstanceFromIStorage merangkum pembuatan instans dan inisialisasi dari sumber yang jelas.

Struktur COSERVERINFO yang diteruskan sebagai parameter pServerInfo berisi pengaturan keamanan yang akan digunakan COM saat membuat instans baru dari objek yang ditentukan. Perhatikan bahwa parameter ini tidak memengaruhi pengaturan keamanan yang digunakan saat melakukan panggilan metode pada objek yang dibuat. Pengaturan keamanan tersebut dapat dikonfigurasi, per antarmuka, dengan fungsi CoSetProxyBlanket . Lihat juga, IClientSecurity::SetBlanket.

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

Lihat juga

CoGetInstanceFromFile

CoGetInstanceFromIStorage

Bagikan melalui