Fonction CoInitializeEx (combaseapi.h)

  • Article

Initialise la bibliothèque COM pour l’utiliser par le thread appelant, définit le modèle d’accès concurrentiel du thread et crée un nouvel appartement pour le thread si nécessaire.

Vous devez appeler Windows ::Foundation ::Initialize pour initialiser le thread au lieu de CoInitializeEx si vous souhaitez utiliser les API Windows Runtime ou si vous souhaitez utiliser les composants COM et Windows Runtime. Windows ::Foundation ::Initialize suffit à utiliser pour les composants COM.

Syntaxe

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

Paramètres

[in, optional] pvReserved

Ce paramètre est réservé et doit avoir la valeur NULL.

[in] dwCoInit

Modèle d’accès concurrentiel et options d’initialisation pour le thread. Les valeurs de ce paramètre sont extraites de l’énumération COINIT . Toute combinaison de valeurs de COINIT peut être utilisée, sauf que les indicateurs COINIT_APARTMENTTHREADED et COINIT_MULTITHREADED ne peuvent pas être définis. La valeur par défaut est COINIT_MULTITHREADED.

Valeur retournée

Cette fonction peut retourner les valeurs de retour standard E_INVALIDARG, E_OUTOFMEMORY et E_UNEXPECTED, ainsi que les valeurs suivantes.

Code de retour Description
S_OK
 La bibliothèque COM a été initialisée avec succès sur ce thread.
S_FALSE
 La bibliothèque COM est déjà initialisée sur ce thread.
RPC_E_CHANGED_MODE
 Un appel précédent à CoInitializeEx spécifiait le modèle d’accès concurrentiel pour ce thread en tant qu’appartement multithread (MTA). Cela peut également indiquer qu’un changement d’appartement à thread neutre à un appartement à thread unique s’est produit.

Remarques

CoInitializeEx doit être appelé au moins une fois, et n’est généralement appelé qu’une seule fois, pour chaque thread qui utilise la bibliothèque COM. Plusieurs appels à CoInitializeEx par le même thread sont autorisés tant qu’ils passent le même indicateur d’accès concurrentiel, mais que les appels valides suivants retournent S_FALSE. Pour fermer la bibliothèque COM correctement sur un thread, chaque appel réussi à CoInitialize ou CoInitializeEx, y compris tout appel qui retourne S_FALSE, doit être équilibré par un appel à CoUninitialize correspondant.

Vous devez initialiser la bibliothèque COM sur un thread avant d’appeler l’une des fonctions de bibliothèque à l’exception de CoGetMalloc, pour obtenir un pointeur vers l’allocateur standard et les fonctions d’allocation de mémoire.

Sinon, la fonction COM retourne CO_E_NOTINITIALIZED.

Une fois le modèle d’accès concurrentiel défini pour un thread, il ne peut pas être modifié. Un appel à CoInitialize sur un appartement précédemment initialisé comme multithread échoue et retourne RPC_E_CHANGED_MODE.

Les objets créés dans un appartement à thread unique (STA) reçoivent des appels de méthode uniquement à partir du thread de leur appartement, de sorte que les appels sont sérialisés et n’arrivent qu’aux limites de la file d’attente de messages (lorsque la fonction PeekMessage ou SendMessage est appelée).

Les objets créés sur un thread COM dans un appartement multithread (MTA) doivent pouvoir recevoir des appels de méthode d’autres threads à tout moment. Vous implémentez généralement une forme de contrôle d’accès concurrentiel dans le code d’un objet multithread à l’aide de primitives de synchronisation telles que des sections critiques, des sémaphores ou des mutexes pour protéger les données de l’objet.

Lorsqu’un objet configuré pour s’exécuter dans l’appartement threadé neutre (NTA) est appelé par un thread qui se trouve dans un STA ou dans le MTA, ce thread est transféré vers le NTA. Si ce thread appelle par la suite CoInitializeEx, l’appel échoue et retourne RPC_E_CHANGED_MODE.

Étant donné que les technologies OLE ne sont pas thread-safe, la fonction OleInitialize appelle CoInitializeEx avec l’indicateur COINIT_APARTMENTTHREADED. Par conséquent, un appartement initialisé pour la concurrence d’objets multithread ne peut pas utiliser les fonctionnalités activées par OleInitialize.

Étant donné qu’il n’existe aucun moyen de contrôler l’ordre dans lequel les serveurs in-process sont chargés ou déchargés, n’appelez pas CoInitialize, CoInitializeEx ou CoUninitialize à partir de la fonction DllMain .

Configuration requise

Condition requise Valeur
Client minimal pris en charge Windows 2000 Professionnel [applications de bureau | Applications UWP]
Serveur minimal pris en charge Windows 2000 Server [applications de bureau | Applications UWP]
Plateforme cible Windows
En-tête combaseapi.h (inclure Objbase.h)
Bibliothèque Ole32.lib
DLL Ole32.dll

Voir aussi

Processus, threads et appartements