CoInitializeEx-Funktion (combaseapi.h)

  • Artikel

Initialisiert die COM-Bibliothek zur Verwendung durch den aufrufenden Thread, legt das Parallelitätsmodell des Threads fest und erstellt bei Bedarf ein neues Apartment für den Thread.

Sie sollten Windows::Foundation::Initialize aufrufen, um den Thread anstelle von CoInitializeEx zu initialisieren, wenn Sie die Windows-Runtime-APIs verwenden oder com- und Windows-Runtime Komponenten verwenden möchten. Windows::Foundation::Initialize reicht aus, um für COM-Komponenten zu verwenden.

Syntax

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

Parameter

[in, optional] pvReserved

Dieser Parameter ist reserviert und muss NULL sein.

[in] dwCoInit

Das Parallelitätsmodell und die Initialisierungsoptionen für den Thread. Die Werte für diesen Parameter stammen aus der COINIT-Enumeration . Es kann eine beliebige Kombination von Werten aus COINIT verwendet werden, mit der Ausnahme, dass die Flags COINIT_APARTMENTTHREADED und COINIT_MULTITHREADED nicht beide festgelegt werden können. Der Standardwert ist COINIT_MULTITHREADED.

Rückgabewert

Diese Funktion kann die Standardrückgabewerte E_INVALIDARG, E_OUTOFMEMORY und E_UNEXPECTED sowie die folgenden Werte zurückgeben.

Rückgabecode BESCHREIBUNG
S_OK
 Die COM-Bibliothek wurde in diesem Thread erfolgreich initialisiert.
S_FALSE
 Die COM-Bibliothek wurde bereits in diesem Thread initialisiert.
RPC_E_CHANGED_MODE
 Ein vorheriger Aufruf von CoInitializeEx hat das Parallelitätsmodell für diesen Thread als Multithread-Apartment (MTA) angegeben. Dies könnte auch darauf hindeuten, dass ein Wechsel von einer Neutralthread-Wohnung zu einer Singlethread-Wohnung erfolgt ist.

Hinweise

CoInitializeEx muss mindestens einmal aufgerufen werden und wird in der Regel nur einmal für jeden Thread aufgerufen, der die COM-Bibliothek verwendet. Mehrere Aufrufe von CoInitializeEx durch denselben Thread sind zulässig, solange sie das gleiche Parallelitätsflag übergeben, aber nachfolgende gültige Aufrufe geben S_FALSE zurück. Um die COM-Bibliothek ordnungsgemäß in einem Thread zu schließen, muss jeder erfolgreiche Aufruf von CoInitialize oder CoInitializeEx, einschließlich aller Aufrufe, die S_FALSE zurückgeben, durch einen entsprechenden Aufruf von CoUninitialize ausgeglichen werden.

Sie müssen die COM-Bibliothek in einem Thread initialisieren, bevor Sie eine der Bibliotheksfunktionen außer CoGetMalloc aufrufen, um einen Zeiger auf die Standardzuweisung und die Speicherbelegungsfunktionen abzurufen.

Andernfalls gibt die COM-Funktion CO_E_NOTINITIALIZED zurück.

Nachdem das Parallelitätsmodell für einen Thread festgelegt wurde, kann es nicht mehr geändert werden. Ein Aufruf von CoInitialize für ein Apartment, das zuvor als Multithread initialisiert wurde, schlägt fehl und gibt RPC_E_CHANGED_MODE zurück.

Objekte, die in einem Singlethread-Apartment (STA) erstellt werden, empfangen Methodenaufrufe nur aus dem Thread ihrer Wohnung, sodass Aufrufe serialisiert werden und nur an Nachrichtenwarteschlangengrenzen ankommen (wenn die PeekMessage - oder SendMessage-Funktion aufgerufen wird).

Objekte, die in einem COM-Thread in einem Multithread-Apartment (MTA) erstellt werden, müssen jederzeit Methodenaufrufe von anderen Threads empfangen können. Sie würden in der Regel eine Form der Parallelitätssteuerung im Code eines Multithreadobjekts implementieren, indem Sie Synchronisierungsgrundtypen wie kritische Abschnitte, Semaphore oder Mutexe verwenden, um die Daten des Objekts zu schützen.

Wenn ein Objekt, das für die Ausführung in der neutralen Thread-Wohnung (NTA) konfiguriert ist, von einem Thread aufgerufen wird, der sich entweder in einem STA oder MTA befindet, wird dieser Thread an den NTA übertragen. Wenn dieser Thread anschließend CoInitializeEx aufruft, schlägt der Aufruf fehl und gibt RPC_E_CHANGED_MODE zurück.

Da OLE-Technologien nicht threadsicher sind, ruft die OleInitialize-FunktionCoInitializeEx mit dem flag COINIT_APARTMENTTHREADED auf. Daher kann ein Apartment, das für die Parallelität von Multithreadobjekten initialisiert wird, die von OleInitialize aktivierten Features nicht verwenden.

Da es keine Möglichkeit gibt, die Reihenfolge zu steuern, in der Prozessserver geladen oder entladen werden, rufen Sie CoInitialize, CoInitializeEx oder CoUninitialize nicht über die DllMain-Funktion auf.

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Windows 2000 Professional [Desktop-Apps | UWP-Apps]
Unterstützte Mindestversion (Server) Windows 2000 Server [Desktop-Apps | UWP-Apps]
Zielplattform Windows
Kopfzeile combaseapi.h (include Objbase.h)
Bibliothek Ole32.lib
DLL Ole32.dll

Weitere Informationen

Prozesse, Threads und Apartments