Fungsi CoInitialize (objbase.h)

  • Artikel

Menginisialisasi pustaka COM pada utas saat ini dan mengidentifikasi model konkurensi sebagai apartemen utas tunggal (STA).

Aplikasi baru harus memanggil CoInitializeEx alih-alih CoInitialize.

Jika Anda ingin menggunakan Windows Runtime, Anda harus memanggil RoInitialize atau Windows::Foundation::Initialize sebagai gantinya.

Sintaks

HRESULT CoInitialize(
  [in, optional] LPVOID pvReserved
);

Parameter

[in, optional] pvReserved

Parameter ini dicadangkan dan harus NULL.

Menampilkan nilai

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

Menampilkan kode Deskripsi
S_OK
 Pustaka COM berhasil diinisialisasi pada utas ini.
S_FALSE
 Pustaka COM sudah diinisialisasi pada utas ini.
RPC_E_CHANGED_MODE
 Panggilan sebelumnya ke CoInitializeEx menentukan model konkurensi untuk utas ini sebagai apartemen multithread (MTA). Ini juga bisa menunjukkan bahwa perubahan dari apartemen berulir netral ke apartemen berulir tunggal telah terjadi.

Keterangan

Anda perlu menginisialisasi pustaka COM pada utas sebelum Anda memanggil salah satu fungsi pustaka kecuali CoGetMalloc, untuk mendapatkan penunjuk ke alokator standar, dan fungsi alokasi memori.

Setelah model konkurensi untuk utas diatur, model tersebut tidak dapat diubah. Panggilan ke CoInitialize di apartemen yang sebelumnya diinisialisasi sebagai multithreaded akan gagal dan kembali RPC_E_CHANGED_MODE.

CoInitializeEx menyediakan fungsionalitas yang sama dengan CoInitialize dan juga menyediakan parameter untuk secara eksplisit menentukan model konkurensi utas. CoInitialize memanggil CoInitializeEx dan menentukan model konkurensi sebagai apartemen utas tunggal. Aplikasi yang dikembangkan saat ini harus memanggil CoInitializeEx daripada CoInitialize.

Biasanya, pustaka COM diinisialisasi pada utas hanya sekali. Panggilan berikutnya untuk CoInitialize atau CoInitializeEx pada utas yang sama akan berhasil, selama mereka tidak mencoba mengubah model konkurensi, tetapi akan mengembalikan S_FALSE. Untuk menutup pustaka COM dengan anggun, setiap panggilan yang berhasil untuk CoInitialize atau CoInitializeEx, termasuk yang mengembalikan S_FALSE, harus diseimbangkan dengan panggilan yang sesuai untuk CoUninitialize. Namun, utas pertama dalam aplikasi yang memanggil CoInitialize dengan 0 (atau CoInitializeEx dengan COINIT_APARTMENTTHREADED) harus menjadi utas terakhir untuk memanggil CoUninitialize. Jika tidak, panggilan berikutnya untuk CoInitialize pada STA akan gagal dan aplikasi tidak akan berfungsi.

Karena tidak ada cara untuk mengontrol urutan di mana server dalam proses dimuat atau dibongkar, jangan panggil CoInitialize, CoInitializeEx, atau CoUninitialize dari fungsi DllMain .

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 objbase.h
Pustaka Ole32.lib
DLL Ole32.dll
Set API ext-ms-win-com-sta-l1-1-0 (diperkenalkan dalam Windows 10, versi 10.0.20166)

Lihat juga

CoInitializeEx