Fungsi CoGetInstanceFromFile (objbase.h)

Artikel
03/15/2023

Membuat objek baru dan menginisialisasinya dari file menggunakan IPersistFile::Load.

Sintaks

HRESULT CoGetInstanceFromFile(
  [in, optional] COSERVERINFO *pServerInfo,
  [in, optional] CLSID        *pClsid,
  [in, optional] IUnknown     *punkOuter,
  [in]           DWORD        dwClsCtx,
  [in]           DWORD        grfMode,
  [in]           OLECHAR      *pwszName,
  [in]           DWORD        dwCount,
  [in, out]      MULTI_QI     *pResults
);

Parameter

[in, optional] pServerInfo

Penunjuk ke struktur COSERVERINFO yang menentukan komputer untuk membuat instans objek dan pengaturan autentikasi yang akan digunakan. Parameter ini bisa NULL, dalam hal ini objek dibuat di komputer saat ini, di komputer yang ditentukan di bawah nilai registri RemoteServerName untuk kelas , atau di komputer tempat file pwszName berada jika nilai ActivateAtStorage ditentukan untuk kelas atau tidak ada informasi registri lokal.

[in, optional] pClsid

Penunjuk ke pengidentifikasi kelas objek yang akan dibuat. Parameter ini bisa NULL, dalam hal ini ada panggilan ke GetClassFile, menggunakan pwszName sebagai parameternya untuk mendapatkan kelas objek yang akan diinstansiasi.

[in, optional] punkOuter

Ketika non-NULL, menunjukkan instans sedang dibuat sebagai bagian dari agregat, dan punkOuter akan digunakan sebagai penunjuk ke IUnknown pengendali instans baru. Agregasi 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] grfMode

Menentukan bagaimana file akan dibuka. Lihat Konstanta STGM.

[in] pwszName

File yang digunakan untuk menginisialisasi objek dengan IPersistFile::Load. Parameter ini tidak boleh NULL.

[in] dwCount

Jumlah struktur dalam pResults. Parameter 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	Fungsi berhasil mengambil semua antarmuka.
CO_S_NOTALLINTERFACES	Setidaknya satu, tetapi tidak semua antarmuka yang diminta dalam array pResults berhasil diambil. Anggota jam dari masing-masing struktur MULTI_QI 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

CoGetInstanceFromFile membuat objek baru dan menginisialisasinya dari file menggunakan IPersistFile::Load. Hasil dari fungsi ini mirip dengan membuat instans dengan panggilan ke CoCreateInstanceEx, diikuti dengan panggilan inisialisasi ke IPersistFile::Load, dengan perbedaan penting berikut:

Lebih sedikit perjalanan pulang pergi jaringan yang diperlukan oleh fungsi ini saat membuat instans objek pada komputer jarak jauh.
Dalam kasus di mana dwClsCtx diatur ke CLSCTX_REMOTE_SERVER dan pServerInfo adalah NULL, jika kelas terdaftar dengan sub-kunci ActivateAtStorage atau tidak memiliki informasi registri terkait, fungsi ini akan membuat instans objek di komputer tempat pwszName berada, menyediakan lalu lintas jaringan yang paling tidak mungkin.

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	objbase.h
Pustaka	Ole32.lib
DLL	ComBase.dll

Lihat juga

CLSCTX

CoCreateInstanceEx

CoGetInstanceFromIStorage