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

Article
08/25/2023

Récupère la taille maximale de la mémoire tampon qui sera nécessaire pendant le marshaling.

Syntaxe

HRESULT GetMarshalSizeMax(
  [in]  REFIID riid,
  [in]  void   *pv,
  [in]  DWORD  dwDestContext,
  [in]  void   *pvDestContext,
  [in]  DWORD  mshlflags,
  [out] DWORD  *pSize
);

Paramètres

[in] riid

Référence à l’identificateur de l’interface à marshaler.

[in] pv

Pointeur d’interface à marshaler. Ce paramètre peut être NULL.

[in] dwDestContext

Contexte de destination dans lequel l’interface spécifiée doit être démarshalée. Les valeurs possibles proviennent de l’énumération MSHCTX. 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 NULL.

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

[out] pSize

Pointeur vers une variable qui reçoit la taille maximale de la mémoire tampon.

Valeur retournée

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

Code de retour	Description
E_NOINTERFACE	L’interface spécifiée n’est pas prise en charge.

Remarques

Cette méthode est appelée indirectement, dans un appel à CoGetMarshalSizeMax, 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.

Pour créer un proxy pour un objet, COM nécessite deux éléments d’informations de l’objet d’origine : la quantité de données à écrire dans le flux de marshaling et le CLSID du proxy.

Le stub de marshaling obtient ces deux informations avec des appels successifs à CoGetMarshalSizeMax et CoMarshalInterface.

Remarques aux appelants

Le stub de marshaling, via un appel à CoGetMarshalSizeMax, appelle l’implémentation de cette méthode par l’objet pour préallouer la mémoire tampon de flux qui sera passée à MarshalInterface.

Vous n’appelez pas explicitement cette méthode si vous implémentez des interfaces COM existantes ou utilisez le langage MIDL (Microsoft Interface Definition Language) pour définir vos propres interfaces personnalisées. 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 (voir Définition des interfaces COM), votre stub de marshaling n’a pas besoin d’appeler GetMarshalSizeMax, bien qu’il soit fortement recommandé de le faire. Un objet sait mieux qu’un stub d’interface quelle est la taille maximale d’un paquet de données de marshaling. Par conséquent, à moins que vous ne fournissiez un flux à croissance automatique si efficace que la surcharge liée à son développement est insignifiante, vous devez appeler cette méthode même lors de l’implémentation de vos propres interfaces.

La valeur retournée par cette méthode est garantie comme valide uniquement tant que l’état interne de l’objet marshalé ne change pas. Par conséquent, le marshaling réel doit être effectué immédiatement après le retour de cette fonction, sinon le stub court le risque que l’objet, en raison d’un changement d’état, nécessite plus de mémoire pour marshaler qu’il ne l’a initialement indiqué.

Remarques aux implémenteurs

Votre implémentation de MarshalInterface utilise la mémoire tampon préallouée pour écrire des données de marshalage dans le flux. Si la mémoire tampon est trop petite, l’opération de marshaling échoue. Par conséquent, la valeur retournée par cette méthode doit être une estimation prudente de la quantité de données qui sera nécessaire pour marshaler l’interface. La violation de cette exigence doit être traitée comme une erreur catastrophique.

Dans un appel ultérieur à MarshalInterface, votre implémentation IMarshal ne peut pas s’appuyer sur l’appelant ayant appelé GetMarshalSizeMax au préalable. Il doit toujours se méfier des erreurs STG_E_MEDIUMFULL retournées par le flux et être prêt à les gérer avec grâce.

Pour vous assurer que votre implémentation de GetMarshalSizeMax continuera de fonctionner correctement à mesure que de nouveaux contextes de destination seront 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 comprend pas. Pour déléguer le marshaling à l’implémentation COM par défaut, appelez la fonction CoGetStandardMarshal .

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	objidl.h

Voir aussi

CoGetMarshalSizeMax

IMarshal

Partager via