CoCreateFreeThreadedMarshaler, fonction (combaseapi.h)
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 |
|---|---|
|
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 :
- Crée un objet marshaler à thread libre.
- 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.
- Vérifie le contexte de destination spécifié par le paramètre dwDestContext de la fonction CoMarshalInterface.
- Si le contexte de destination est MSHCTX_INPROC, copie le pointeur d’interface dans le flux de marshaling.
- 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.
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 |