Fungsi CoInitializeEx (combaseapi.h)

  • Artikel

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.

Sintaks

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 keduanya. Defaultnya adalah COINIT_MULTITHREADED.

Nilai kembali

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

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. Untuk menutup pustaka COM dengan anggun pada utas, setiap panggilan yang berhasil ke CoInitialize atau CoInitializeEx, termasuk panggilan apa pun yang mengembalikan S_FALSE, harus diseimbangkan dengan panggilan yang sesuai untuk CoUninitialize.

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.

Jika tidak, fungsi COM akan mengembalikan CO_E_NOTINITIALIZED.

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.

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 untuk 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

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

Lihat juga

Proses, Utas, dan Apartemen