RoGetAgileReference, fonction (combaseapi.h)

Crée une référence agile pour un objet spécifié par l’interface donnée.

Syntaxe

HRESULT RoGetAgileReference(
  [in]  AgileReferenceOptions options,
  [in]  REFIID                riid,
  [in]  IUnknown              *pUnk,
  [out] IAgileReference       **ppAgileReference
);

Paramètres

[in] options

Options d’inscription.

[in] riid

ID d’interface de l’objet pour lequel une référence agile est obtenue.

[in] pUnk

Pointeur vers l’interface à encapsuler dans une référence agile. Il doit être du même type que riid. Il peut s’agir d’un pointeur vers un objet in-process ou d’un pointeur vers un proxy d’un objet.

[out] ppAgileReference

Référence agile pour l’objet . Appelez la méthode Resolve pour localiser l’objet dans l’appartement dans lequel Resolve est appelé.

Valeur retournée

Cette fonction peut retourner l’une de ces valeurs.

Remarques

Appelez la fonction RoGetAgileReference sur un objet existant pour demander une référence agile à l’objet . L’objet peut être agile ou non, mais l’IAgileReference retourné est agile. La référence agile peut être passée à un autre appartement dans le même processus, où l’objet d’origine est récupéré à l’aide de l’interface IAgileReference .

D’un point de vue conceptuel, cela ressemble à la table d’interface globale (GIT) existante. Au lieu d’interagir avec git, une IAgileReference est obtenue et utilisée pour récupérer directement l’objet. Tout comme le git est par processus uniquement, les références agiles sont par processus et ne peuvent pas être marshalées.

La fonctionnalité de référence agile offre une amélioration des performances par rapport à GIT. La référence agile effectue un marshaling hâtif par défaut, ce qui enregistre un appel inter-appartements dans les cas où l’objet est récupéré à partir de la référence agile dans un appartement différent de l’endroit où la référence agile a été créée. Pour améliorer davantage les performances, les utilisateurs de la fonction RoGetAgileReference peuvent utiliser la même interface pour créer un IAgileReference et résoudre l’objet d’origine. Cela enregistre un appel QueryInterface supplémentaire pour obtenir l’interface souhaitée à partir de l’objet résolu.

Par exemple, vous avez un objet non agile nommé CDemoExample, qui implémente les interfaces IDemo et IExample. Appelez la fonction RoGetAgileReference et passez l’objet, avec IID_IDemo. Vous récupérez un pointeur d’interface IAgileReference , qui est agile, afin de pouvoir le passer à un autre appartement. Dans l’autre appartement, appelez la méthode Resolve , avec IID_IExample. Vous obtenez un pointeur IExample que vous pouvez utiliser dans cet appartement. Ce pointeur IExample est un proxy IExample connecté à l’objet CDemoExample d’origine. La référence agile gère la complexité des opérations telles que le marshaling manuel vers un flux et le démarshalation de l’autre côté de la limite d’appartement.

Configuration requise

Voir aussi

AgileReferenceOptions

IAgileReference