CoInitializeEx, fonction (combaseapi.h)

Initialise la bibliothèque COM à 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 être 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 de retour

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

Retourner le code	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écifié un modèle d’accès concurrentiel incompatible pour ce thread. Cela peut également indiquer qu’un changement de l’appartement à threads neutres vers l’appartement à thread unique s’est produit.

Remarques

CoInitializeEx doit être appelée au moins une fois et est généralement appelée 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 les appels valides suivants retournent S_FALSE. Si l’indicateur de concurrence ne correspond pas, l’appel échoue et retourne RPC_E_CHANGED_MODE. (Dans le cadre de cette règle, un appel à CoInitialize équivaut à appeler CoInitializeEx avec l’indicateur COINIT_APARTMENTTHREADED.) Pour annuler l’initialisation de 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 correspondant à CoUninitialize. Une fois COM non initialisé sur un thread, vous pouvez le réinitialiser en tout mode, sous réserve des contraintes ci-dessus.

Vous devez initialiser la bibliothèque COM sur un thread avant d’appeler l’une des fonctions de bibliothèque, sauf 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.

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 arrivent uniquement aux limites de file d’attente de messages (lorsque le PeekMessage ou SendMessage fonction est appelée).

Les objets créés sur un thread COM dans un multithread apartment (MTA) doivent être en mesure de recevoir des appels de méthode à partir 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 mutex pour protéger les données de l’objet.

Lorsqu’un objet configuré pour s’exécuter dans l’appartement threaded neutre (NTA) est appelé par un thread qui se trouve dans un objet STA ou MTA, ce thread est transféré vers l’appliance réseau. 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 de COINIT_APARTMENTTHREADED. Par conséquent, un appartement initialisé pour la concurrence d’objets multithreads 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, CoInitializeExou CoUninitialize à partir de la fonction DllMain.

Exigences

Exigence	Valeur
client minimum pris en charge	Windows 2000 Professionnel [applications de bureau | Applications UWP]
serveur minimum pris en charge	Windows 2000 Server [applications de bureau | Applications UWP]
plateforme cible	Windows
d’en-tête	combaseapi.h (include Objbase.h)
bibliothèque	Ole32.lib
DLL	Ole32.dll

Voir aussi

processus , threads et appartements