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

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 être 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émarshalation peut se produire dans un autre appartement du processus actuel (MSHCTX_INPROC) ou dans un autre processus sur le même ordinateur que le processus actuel (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é marshalé avec succès.
E_NOINTERFACE	L’interface spécifiée n’est pas prise en charge.
STG_E_MEDIUMFULL	Le flux est plein.

Notes

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.

Remarques aux appelants

En règle générale, au lieu d’appeler MarshalInterface directement, votre stub de marshaling doit appeler la fonction CoMarshalInterface , qui contient un appel à cette méthode. Le stub effectue cet appel à la commande d’un objet pour é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émarché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 si vous 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 de stub doit appeler MarshalInterface immédiatement après son précédent appel à IMarshal::GetMarshalSizeMax retourné. Étant donné que la valeur retournée par GetMarshalSizeMax est garantie d’ê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 indiquée à l’origine.

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 null.

Remarques 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 au 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 grand 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 des données écrites.

Si le paramètre pv est NULL et que votre implémentation a besoin d’un pointeur d’interface, elle peut appeler QueryInterface sur l’objet actuel 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 de 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 client unique 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 provenant de plusieurs proxys qui peuvent être créés à partir des mêmes données d’initialisation.

Spécifications

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

Voir aussi

CoMarshalInterface

IMarshal