CoCreateFreeThreadedMarshaler, fonction (combaseapi.h)

  • Article

Crée un objet pouvant être agrégable capable d’un marshaling dépendant du contexte.

Syntaxe

HRESULT CoCreateFreeThreadedMarshaler(
  [in]  LPUNKNOWN punkOuter,
  [out] LPUNKNOWN *ppunkMarshal
);

Paramètres

[in] punkOuter

Pointeur vers le contrôle IUnknown de l’objet d’agrégation.

[out] ppunkMarshal

Adresse de la variable pointeur qui reçoit le pointeur d’interface vers le marshaleur agrégable.

Valeur retournée

Cette fonction peut retourner la valeur de retour standard E_OUTOFMEMORY, ainsi que la valeur suivante.

Code de retour Description
S_OK
 Le marshaleur a été créé.

Remarques

La fonction CoCreateFreeThreadedMarshaler permet à un objet de marshaler efficacement des pointeurs d’interface entre des threads dans le même processus. Si vos objets ne prennent pas en charge le marshaling interthread, vous n’avez pas besoin d’appeler cette fonction. Il est destiné à être utilisé par les serveurs DLL à thread libre qui doivent être accessibles directement par tous les threads d’un processus, même ceux associés à des appartements à thread unique. Il marshale sur mesure le pointeur de la mémoire réelle dans d’autres appartements comme un faux « proxy » et donne ainsi un accès direct à tous les appelants, même s’ils ne sont pas à thread libre.

La fonction CoCreateFreeThreadedMarshaler effectue les tâches suivantes :

  1. Crée un objet marshaler à thread libre.
  2. Agrège ce marshaleur à l’objet spécifié par le paramètre punkOuter . Cet objet est normalement celui dont les pointeurs d’interface doivent être marshalés.
L’implémentation d’IMarshal par l’objet d’agrégation doit déléguer les appels QueryInterface pour IID_IMarshal au IUnknown du marshaleur à thread libre. Lors de la réception d’un appel, le marshaleur à thread libre effectue les tâches suivantes :
  1. Vérifie le contexte de destination spécifié par le paramètre dwDestContext de la fonction CoMarshalInterface.
  2. Si le contexte de destination est MSHCTX_INPROC, copie le pointeur d’interface dans le flux de marshaling.
  3. Si le contexte de destination est une autre valeur, recherche ou crée un instance du marshaleur par défaut (standard) de COM et lui délègue le marshaling.
Les valeurs de dwDestContext proviennent de l’énumération MSHCTX . MSHCTX_INPROC indique que le pointeur d’interface doit être marshalé entre différents threads dans le même processus. Étant donné que les deux threads ont accès au même espace d’adressage, le thread client peut déréférencer le pointeur directement au lieu d’avoir à diriger les appels vers un proxy. Dans tous les autres cas, un proxy étant requis, CoCreateFreeThreadedMarshaler délègue le travail de marshaling à l’implémentation par défaut de COM.

L’utilisation de la fonction CoCreateFreeThreadedMarshaler doit être très soignée. Cela est dû au fait que les performances des objets qui agrègent le marshaleur à thread libre sont obtenues par le biais d’une violation calculée des règles de COM, avec le risque toujours présent de comportement non défini, sauf si l’objet fonctionne dans certaines restrictions. Les restrictions les plus importantes sont les suivantes :

  • Un objet marshaler à thread libre ne peut pas contenir de pointeurs directs vers des interfaces sur un objet qui n’agrège pas le marshaleur à thread libre dans son état. Si l’objet devait utiliser des références directes à des objets agrégés monothread ordinaires, il peut rompre leur propriété à thread unique. Si l’objet devait utiliser des références directes à des objets d’agrégation multithread ordinaires, ces objets peuvent se comporter de manière à ne pas afficher de sensibilité aux besoins des clients d’agrégation à thread unique direct. Par exemple, ces objets peuvent faire tourner de nouveaux threads et passer des paramètres aux threads qui sont des références à des objets d’agrégation monothread ordinaires.
  • Un objet marshaler à thread libre ne peut pas contenir de références à des proxys à des objets dans d’autres appartements. Les proxys sont sensibles au modèle de thread et peuvent retourner RPC_E_WRONG_THREAD s’ils sont appelés par le mauvais client.

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

CoGetInterfaceAndReleaseStream

CoMarshalInterThreadInterfaceInStream