CoInitialize-Funktion (objbase.h)

  • Artikel

Initialisiert die COM-Bibliothek im aktuellen Thread und identifiziert das Parallelitätsmodell als Singlethread-Apartment (STA).

Neue Anwendungen sollten CoInitializeEx anstelle von CoInitialize aufrufen.

Wenn Sie die Windows-Runtime verwenden möchten, müssen Sie stattdessen RoInitialize oder Windows::Foundation::Initialize aufrufen.

Syntax

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

Parameter

[in, optional] pvReserved

Dieser Parameter ist reserviert und muss NULL sein.

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 wird 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 Neutralthread-Wohnung zu Singlethread-Wohnung stattgefunden hat.

Hinweise

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

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.

CoInitializeEx bietet die gleiche Funktionalität wie CoInitialize und stellt auch einen Parameter bereit, um das Parallelitätsmodell des Threads explizit anzugeben. CoInitialize ruft CoInitializeEx auf und gibt das Parallelitätsmodell als Singlethread-Apartment an. Anwendungen, die heute entwickelt werden, sollten CoInitializeEx statt CoInitialize aufrufen.

In der Regel wird die COM-Bibliothek in einem Thread nur einmal initialisiert. Nachfolgende Aufrufe von CoInitialize oder CoInitializeEx im selben Thread sind erfolgreich, solange sie nicht versuchen, das Parallelitätsmodell zu ändern, sondern S_FALSE zurückgeben. Um die COM-Bibliothek ordnungsgemäß zu schließen, muss jeder erfolgreiche Aufruf von CoInitialize oder CoInitializeEx, einschließlich der Aufrufe, die S_FALSE zurückgeben, durch einen entsprechenden Aufruf von CoUninitialize ausgeglichen werden. Der erste Thread in der Anwendung, der CoInitialize mit 0 (oder CoInitializeEx mit COINIT_APARTMENTTHREADED) aufruft, muss jedoch der letzte Thread sein, der CoUninitialize aufruft. Andernfalls schlagen nachfolgende Aufrufe von CoInitialize für die STA fehl, und die Anwendung funktioniert nicht.

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

   
Unterstützte Mindestversion (Client) Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server) Windows 2000 Server [nur Desktop-Apps]
Zielplattform Windows
Kopfzeile objbase.h
Bibliothek Ole32.lib
DLL Ole32.dll
APIs ext-ms-win-com-sta-l1-1-0 (eingeführt in Windows 10, Version 10.0.20166)

Weitere Informationen

CoInitializeEx