Fungsi CoInitializeEx (combaseapi.h)

Menginisialisasi pustaka COM untuk digunakan oleh utas panggilan, mengatur model konkurensi utas, dan membuat apartemen baru untuk utas jika diperlukan.

Anda harus memanggil Windows::Foundation::Initialize untuk menginisialisasi utas alih-alih CoInitializeEx jika Anda ingin menggunakan WINDOWS Runtime API atau jika Anda ingin menggunakan komponen COM dan Windows Runtime. Windows::Foundation::Initialize cukup untuk digunakan untuk komponen COM.

Sintaksis

HRESULT CoInitializeEx(
  [in, optional] LPVOID pvReserved,
  [in]           DWORD  dwCoInit
);

Parameter

[in, optional] pvReserved

Parameter ini dicadangkan dan harus NULL.

[in] dwCoInit

Model konkurensi dan opsi inisialisasi untuk utas. Nilai untuk parameter ini diambil dari enumerasi COINIT. Kombinasi nilai apa pun dari COINIT dapat digunakan, kecuali bahwa bendera COINIT_APARTMENTTHREADED dan COINIT_MULTITHREADED tidak dapat diatur. Defaultnya adalah COINIT_MULTITHREADED.

Mengembalikan nilai

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

Mengembalikan 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 yang tidak kompatibel untuk utas ini. Ini juga dapat menunjukkan bahwa perubahan dari apartemen berulir netral ke apartemen berulir tunggal telah terjadi.

Komentar

CoInitializeEx harus dipanggil setidaknya sekali, dan biasanya dipanggil hanya sekali, untuk setiap utas yang menggunakan pustaka COM. Beberapa panggilan ke CoInitializeEx dengan utas yang sama diizinkan selama mereka melewati bendera konkurensi yang sama, tetapi panggilan yang valid berikutnya mengembalikan S_FALSE. Jika bendera konkurensi tidak cocok, maka panggilan gagal dan mengembalikan RPC_E_CHANGED_MODE. (Untuk tujuan aturan ini, panggilan ke CoInitialize setara dengan memanggil CoInitializeEx dengan bendera COINIT_APARTMENTTHREADED.) Untuk tidak menginisialisasi pustaka COM dengan anggun pada utas, setiap panggilan yang berhasil untuk CoInitialize atau CoInitializeEx, termasuk panggilan apa pun yang mengembalikan S_FALSE, harus diseimbangkan dengan panggilan yang sesuai untuk CoUninitialize. Setelah COM tidak diinisialisasi pada utas, Anda dapat menginisialisasinya kembali dalam mode apa pun, tunduk pada batasan di atas.

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

Objek yang dibuat di apartemen berulir tunggal (STA) hanya menerima panggilan metode dari utas apartemen mereka, sehingga panggilan diserialisasikan dan hanya tiba di batas antrean pesan (ketika fungsi PeekMessage atau SendMessage dipanggil).

Objek yang dibuat pada utas COM di apartemen multithread (MTA) harus dapat menerima panggilan metode dari utas lain kapan saja. Anda biasanya akan menerapkan beberapa bentuk kontrol konkurensi dalam kode objek multithreaded menggunakan primitif sinkronisasi seperti bagian penting, semaphores, atau mutex untuk membantu melindungi data objek.

Ketika objek yang dikonfigurasi untuk berjalan di apartemen utas netral (NTA) dipanggil oleh utas yang berada di STA atau MTA, utas tersebut ditransfer ke NTA. Jika utas ini kemudian memanggil CoInitializeEx, panggilan gagal dan mengembalikan RPC_E_CHANGED_MODE.

Karena teknologi OLE tidak aman utas, fungsi OleInitialize memanggil CoInitializeEx dengan bendera COINIT_APARTMENTTHREADED. Akibatnya, apartemen yang diinisialisasi untuk konkurensi objek multithreaded tidak dapat menggunakan fitur yang diaktifkan oleh OleInitialize.

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

Syarat	Nilai
klien minimum yang didukung	Windows 2000 Professional [aplikasi desktop | Aplikasi UWP]
server minimum yang didukung	Windows 2000 Server [aplikasi desktop | Aplikasi UWP]
Platform Target	Windows
Header	combaseapi.h (termasuk Objbase.h)
Pustaka	Ole32.lib
DLL	Ole32.dll

Lihat juga

Proses, Utas, dan Apartemen