IMarshal ::GetUnmarshalClass, méthode (objidl.h)

  • Article

Récupère le CLSID du code de démarshalation.

Syntaxe

HRESULT GetUnmarshalClass(
  [in]  REFIID riid,
  [in]  void   *pv,
  [in]  DWORD  dwDestContext,
  [in]  void   *pvDestContext,
  [in]  DWORD  mshlflags,
  [out] CLSID  *pCid
);

Paramètres

[in] riid

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

[in] pv

Pointeur vers l’interface à marshaler ; 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 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] pCid

Pointeur qui reçoit le CLSID à utiliser pour créer un proxy dans le processus client.

Valeur retournée

Si la méthode réussit, la valeur de retour est S_OK. Sinon, c’est S_FALSE.

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.

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 appelle l’implémentation de cette méthode par l’objet pour obtenir le CLSID à utiliser lors de la création d’un instance du proxy. Le client, lors de la réception du CLSID, charge la DLL répertoriée pour lui dans le registre système.

Vous n’appelez pas explicitement cette méthode si vous implémentez des interfaces COM existantes ou si vous utilisez le langage MIDL (Microsoft Interface Definition Language) pour définir vos propres interfaces. Dans les deux cas, le stub effectue automatiquement l’appel. Consultez Définition d’interfaces COM.

Si vous n’utilisez pas MIDL pour définir votre propre interface, votre stub doit appeler cette méthode, directement ou indirectement, pour obtenir le CLSID dont la bibliothèque COM côté client a besoin pour créer un proxy pour l’objet implémentant l’interface.

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

COM appelle GetUnmarshalClass pour obtenir le CLSID à utiliser pour créer un proxy dans le processus client. Le CLSID à utiliser pour un proxy n’est normalement pas celui de l’objet d’origine, mais celui que vous aurez généré (à l’aide de l’outil Guidgen.exe) spécifiquement pour votre objet proxy.

Implémentez cette méthode pour chaque objet qui fournit le marshaling pour une ou plusieurs de ses interfaces. Le code responsable du marshaling de l’objet écrit le CLSID, ainsi que les données de marshaling, dans un flux ; COM extrait le CLSID et les données du flux côté réception.

Si votre implémentation de proxy consiste simplement à copier la totalité de l’objet d’origine dans le processus client, éliminant ainsi la nécessité de transférer les appels à l’objet d’origine, le CLSID retourné est identique à celui de l’objet d’origine. Bien entendu, cette stratégie est recommandée uniquement pour les objets qui ne sont pas censés changer.

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 GetUnmarshalClass 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 CoGetStandardMarshal .

Note La valeur de Registre ThreadingModel doit être Both pour un serveur in-process qui implémente le CLSID retourné par la méthode GetUnmarshalClass . Pour plus d’informations, consultez InprocServer32.
 

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

CoMarshalInterface

IMarshal