CoInitializeEx-Funktion (combaseapi.h)
Initialisiert die COM-Bibliothek für die Verwendung durch den aufrufenden Thread, legt das Parallelitätsmodell des Threads fest und erstellt bei Bedarf eine neue Wohnung 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 möchten oder wenn Sie sowohl COM- als auch 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. Werte für diesen Parameter werden aus der COINIT Enumeration entnommen. Jede Kombination von Werten aus COINIT- kann verwendet werden, außer dass die COINIT_APARTMENTTHREADED und COINIT_MULTITHREADED Flags nicht beide festgelegt werden können. Der Standardwert ist COINIT_MULTITHREADED.
Rückgabewert
Diese Funktion kann die Standardrücklaufwerte E_INVALIDARG, E_OUTOFMEMORY und E_UNEXPECTED sowie die folgenden Werte zurückgeben.
| Rückgabecode | Beschreibung |
|---|---|
|
Die COM-Bibliothek wurde in diesem Thread erfolgreich initialisiert. |
|
Die COM-Bibliothek wird bereits in diesem Thread initialisiert. |
|
Ein vorheriger Aufruf von CoInitializeEx ein inkompatibles Parallelitätsmodell für diesen Thread angegeben. Dies könnte auch darauf hindeuten, dass eine Änderung von Neutralthread-Wohnung zu Singlethread-Wohnung eingetreten ist. |
Bemerkungen
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ätsflagge übergeben, aber nachfolgende gültige Aufrufe geben S_FALSE zurück. Wenn das Parallelitätsflagge nicht übereinstimmt, schlägt der Aufruf fehl und gibt RPC_E_CHANGED_MODE zurück. (Für diese Regel entspricht ein Aufruf CoInitialize- dem Aufrufen CoInitializeEx- mit dem COINIT_APARTMENTTHREADED-Flag.) Um die COM-Bibliothek ordnungsgemäß in einem Thread zu initialisieren, muss jeder erfolgreiche Aufruf CoInitialize oder CoInitializeEx, einschließlich aller Aufrufe, die S_FALSE zurückgeben, durch einen entsprechenden Aufruf von CoUninitializeausgeglichen werden. Nachdem COM in einem Thread nicht initialisiert wurde, können Sie sie in jedem Modus neu initialisieren, vorbehaltlich der oben genannten Einschränkungen.
Sie müssen die COM-Bibliothek in einem Thread initialisieren, bevor Sie eine der Bibliotheksfunktionen außer CoGetMalloc-aufrufen, um einen Zeiger auf den Standardverteiler und die Speicherzuweisungsfunktionen abzurufen. Andernfalls gibt die COM-Funktion CO_E_NOTINITIALIZED zurück.
Objekte, die in einem Singlethreaded Apartment (STA) erstellt wurden, empfangen Methodenaufrufe nur über den Thread ihrer Wohnung, sodass Anrufe serialisiert und nur an Nachrichtenwarteschlangengrenzen eingehen (wenn die PeekMessage- oder SendMessage--Funktion aufgerufen wird).
Objekte, die in einem COM-Thread in einer Multithread-Wohnung (MTA) erstellt wurden, müssen jederzeit Methodenaufrufe von anderen Threads empfangen können. In der Regel implementieren Sie eine Form des Parallelitätssteuerelements im Code eines Multithread-Objekts mithilfe von Synchronisierungsgrundtypen wie kritische Abschnitte, Semaphoren oder Mutexes, 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 in einem STA oder dem MTA befindet, überträgt dieser Thread an den NTA. 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-Funktion CoInitializeEx- mit dem COINIT_APARTMENTTHREADED-Flag auf. Ein Apartment, das für multithreaded-Objektkoncurrency initialisiert wird, kann daher nicht die von OleInitializeaktivierten Features verwenden.
Da es keine Möglichkeit gibt, die Reihenfolge zu steuern, in der Prozessserver geladen oder entladen werden, rufen Sie nicht CoInitialize, CoInitializeExoder CoUninitialize aus der DllMain--Funktion auf.
Anforderungen
| Anforderung | Wert |
|---|---|
| mindestens unterstützte Client- | Windows 2000 Professional [Desktop-Apps | UWP-Apps] |
| mindestens unterstützte Server- | Windows 2000 Server [Desktop-Apps | UWP-Apps] |
| Zielplattform- | Fenster |
| Header- | combaseapi.h (include Objbase.h) |
| Library | Ole32.lib |
| DLL- | Ole32.dll |