Méthode IMarshal ::MarshalInterface (objidlbase.h)

Article
03/04/2024

Marshale un pointeur d’interface.

Syntaxe

HRESULT MarshalInterface(
  [in] IStream *pStm,
  [in] REFIID  riid,
  [in] void    *pv,
  [in] DWORD   dwDestContext,
  [in] void    *pvDestContext,
  [in] DWORD   mshlflags
);

Paramètres

[in] pStm

Pointeur vers le flux à utiliser pendant le marshaling.

[in] riid

Référence à l’identificateur de l’interface à marshaler. Cette interface doit être dérivée de l’interface IUnknown .

[in] pv

Pointeur vers le pointeur d’interface à marshaler. Ce paramètre peut avoir la valeur NULL si l’appelant n’a pas de pointeur vers l’interface souhaitée.

[in] dwDestContext

Contexte de destination dans lequel l’interface spécifiée doit être démarshalée. Les valeurs possibles pour dwDestContext proviennent de l’énumération MSHCTX. Actuellement, le démarshalage peut se produire dans un autre appartement du processus en cours (MSHCTX_INPROC) ou dans un autre processus sur le même ordinateur que le processus en cours (MSHCTX_LOCAL).

[in] pvDestContext

Ce paramètre est réservé et doit être 0.

[in] mshlflags

Indique si les données à marshaler doivent être transmises au processus client (cas classique) ou écrites dans une table globale, où elles peuvent être récupérées par plusieurs clients. Les valeurs possibles proviennent de l’énumération MSHLFLAGS .

Valeur retournée

Cette méthode peut retourner la valeur de retour standard E_FAIL, ainsi que les valeurs suivantes.

Code de retour	Description
S_OK	Le pointeur d’interface a été correctement marshalé.
E_NOINTERFACE	L’interface spécifiée n’est pas prise en charge.
STG_E_MEDIUMFULL	Le flux est plein.

Remarques

Cette méthode est appelée indirectement, dans un appel à CoMarshalInterface, par tout code du processus serveur chargé de marshaler un pointeur vers une interface sur un objet. Ce code de marshaling est généralement un stub généré par COM pour l’une des plusieurs interfaces qui peuvent marshaler un pointeur vers une interface implémentée sur un objet entièrement différent. Par exemple, les interfaces IClassFactory et IOleItemContainer . À des fins de discussion, le code responsable du marshaling d’un pointeur est appelé stub de marshaling.

Notes aux appelants

En règle générale, plutôt que d’appeler MarshalInterface directement, votre stub de marshaling doit plutôt appeler la fonction CoMarshalInterface , qui contient un appel à cette méthode. Le stub effectue cet appel pour commander à un objet d’écrire ses données de marshaling dans un flux. Le stub transmet ensuite les données de marshaling au processus client ou les écrit dans une table globale, où elles peuvent être démarssées par plusieurs clients. L’appel du stub à CoMarshalInterface est normalement précédé d’un appel à CoGetMarshalSizeMax pour obtenir la taille maximale de la mémoire tampon de flux dans laquelle les données de marshaling seront écrites.

Vous n’appelez pas explicitement cette méthode si vous implémentez des interfaces COM existantes ou définissez vos propres interfaces à l’aide du langage MIDL (Microsoft Interface Definition Language). Dans les deux cas, le stub généré par MIDL effectue automatiquement l’appel.

Si vous n’utilisez pas MIDL pour définir votre propre interface, votre stub de marshaling doit appeler cette méthode, directement ou indirectement. Votre implémentation stub doit appeler MarshalInterface immédiatement après le retour de son précédent appel à IMarshal ::GetMarshalSizeMax . Étant donné que la valeur retournée par GetMarshalSizeMax est garantie pour être valide uniquement tant que l’état interne de l’objet marshalé ne change pas, un retard dans l’appel de MarshalInterface entraîne le risque que l’objet nécessite une mémoire tampon de flux plus grande que celle initialement indiquée.

Si l’appelant a un pointeur vers l’interface à marshaler, il doit, par souci d’efficacité, utiliser le paramètre pv pour passer ce pointeur. De cette façon, une implémentation qui peut utiliser un tel pointeur pour déterminer le CLSID approprié pour le proxy n’a pas besoin d’appeler QueryInterface sur elle-même. Si un appelant n’a pas de pointeur vers l’interface à marshaler, il peut passer la valeur NULL.

Notes aux implémenteurs

Votre implémentation de MarshalInterface doit écrire dans le flux toutes les données nécessaires pour initialiser le proxy côté réception. Ces données incluent une référence à l’interface à marshaler, une valeur MSHLFLAGS spécifiant si les données doivent être retournées dans le processus client ou écrites dans une table globale, et tout ce qui est nécessaire pour se connecter à l’objet, comme un canal nommé, un handle vers une fenêtre ou un pointeur vers un canal RPC.

Votre implémentation ne doit pas supposer que le flux est suffisamment volumineux pour contenir toutes les données. Au lieu de cela, il doit gérer correctement une erreur STG_E_MEDIUMFULL. Juste avant de quitter, votre implémentation doit positionner le pointeur de recherche dans le flux immédiatement après le dernier octet de données écrit.

Si le paramètre pv a la valeur NULL et que votre implémentation a besoin d’un pointeur d’interface, elle peut appeler QueryInterface sur l’objet actif pour l’obtenir. Le paramètre pv existe simplement pour améliorer l’efficacité.

Pour vous assurer que votre implémentation de MarshalInterface continue de fonctionner correctement à mesure que les nouveaux contextes de destination sont pris en charge à l’avenir, délèguez le marshaling à l’implémentation COM par défaut pour toutes les valeurs dwDestContext que votre implémentation ne gère pas. Pour déléguer le marshaling à l’implémentation COM par défaut, appelez la fonction d’assistance CoGetStandardMarshal .

À l’aide de l’énumération MSHLFLAGS , les appelants peuvent spécifier si un pointeur d’interface doit être marshalé vers un seul client ou écrit dans une table globale, où il peut être démarshalé par plusieurs clients. Vous devez vous assurer que votre objet peut gérer les appels à partir de plusieurs proxys qui peuvent être créés à partir des mêmes données d’initialisation.

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	objidlbase.h (inclure ObjIdl.h)

Voir aussi

CoMarshalInterface

IMarshal

Partager via