Función RoGetAgileReference (combaseapi.h)

Crea una referencia ágil para un objeto especificado por la interfaz especificada.

Sintaxis

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

Parámetros

[in] options

Las opciones de registro.

[in] riid

Identificador de interfaz del objeto para el que se obtiene una referencia ágil.

[in] pUnk

Puntero a la interfaz que se va a encapsular en una referencia ágil. Debe ser el mismo tipo que riid. Puede ser un puntero a un objeto en proceso o un puntero a un proxy de un objeto .

[out] ppAgileReference

Referencia ágil para el objeto . Llame al método Resolve para localizar el objeto en el apartamento en el que se llama a Resolve .

Valor devuelto

Esta función puede devolver uno de estos valores.

Valor devuelto	Descripción
S_OK	Si se devuelve este valor, significa que la función se completó correctamente.
E_INVALIDARG	El parámetro options no es válido.
E_OUTOFMEMORY	No se pudo construir la referencia ágil debido a una condición de memoria insuficiente.
E_NOINTERFACE	El parámetro pUnk no admite el identificador de interfaz especificado por el parámetro riid .
CO_E_NOT_SUPPORTED	El objeto implementa la interfaz INoMarshal .

Comentarios

Llame a la función RoGetAgileReference en un objeto existente para solicitar una referencia ágil al objeto. El objeto puede ser o no ágil, pero el IAgileReference devuelto es ágil. La referencia ágil se puede pasar a otro apartamento dentro del mismo proceso, donde se recupera el objeto original mediante la interfaz IAgileReference .

Esto es conceptualmente similar a la tabla de interfaz global existente (GIT). En lugar de interactuar con git, se obtiene un IAgileReference y se usa para recuperar el objeto directamente. Al igual que git es solo por proceso, las referencias ágiles son por proceso y no se pueden serializar.

La característica de referencia ágil proporciona una mejora del rendimiento sobre GIT. La referencia ágil realiza la serialización diligente de forma predeterminada, que guarda una llamada entre apartamentos en los casos en los que el objeto se recupera de la referencia ágil en un apartamento que es diferente del lugar en el que se creó la referencia ágil. Para mejorar el rendimiento adicional, los usuarios de la función RoGetAgileReference pueden usar la misma interfaz para crear una IAgileReference y resolver el objeto original. Esto guarda una llamada a QueryInterface adicional para obtener la interfaz deseada del objeto resuelto.

Por ejemplo, tiene un objeto no ágil denominado CDemoExample, que implementa las interfaces IDemo e IExample. Llame a la función RoGetAgileReference y pase el objeto , con IID_IDemo. Obtiene un puntero de interfaz IAgileReference , que es ágil, para que pueda pasarlo a un apartamento diferente. En el otro apartamento, llame al método Resolve , con IID_IExample. Usted recibe un puntero IExample que puede usar dentro de este apartamento. Este puntero IExample es un proxy IExample que está conectado al objeto CDemoExample original. La referencia ágil controla la complejidad de las operaciones, como serializar manualmente una secuencia y desacoplar en el otro lado del límite del apartamento.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 8.1 [aplicaciones de escritorio | Aplicaciones para UWP]
Servidor mínimo compatible	Windows Server 2012 R2 [aplicaciones de escritorio | Aplicaciones para UWP]
Plataforma de destino	Windows
Encabezado	combaseapi.h
Library	Ole32.lib
Archivo DLL	Ole32.dll

Consulte también

AgileReferenceOptions

IAgileReference