Função RoGetAgileReference (combaseapi.h)

Cria uma referência agile para um objeto especificado pela interface fornecida.

Sintaxe

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

Parâmetros

[in] options

As opções de registro.

[in] riid

A ID da interface do objeto para o qual uma referência agile está sendo obtida.

[in] pUnk

Ponteiro para a interface a ser encapsulada em uma referência agile. Deve ser do mesmo tipo que riid. Pode ser um ponteiro para um objeto em processo ou um ponteiro para um proxy de um objeto .

[out] ppAgileReference

A referência agile para o objeto . Chame o método Resolve para localizar o objeto no apartment no qual Resolve é chamado.

Retornar valor

Essa função pode retornar um desses valores.

Valor retornado	Descrição
S_OK	A função foi concluída com êxito.
E_INVALIDARG	O parâmetro options em inválido.
E_OUTOFMEMORY	A referência agile não pôde ser construída devido a uma condição de memória insuficiente.
E_NOINTERFACE	O parâmetro pUnk não dá suporte à ID de interface especificada pelo parâmetro riid .
CO_E_NOT_SUPPORTED	O objeto implementa a interface INoMarshal .

Comentários

Chame a função RoGetAgileReference em um objeto existente para solicitar uma referência agile ao objeto . O objeto pode ou não ser ágil, mas o IAgileReference retornado é ágil. A referência agile pode ser passada para outro apartment dentro do mesmo processo, em que o objeto original é recuperado usando a interface IAgileReference .

Isso é conceitualmente semelhante à GIT (Tabela de Interface Global) existente. Em vez de interagir com o GIT, um IAgileReference é obtido e usado para recuperar o objeto diretamente. Assim como o GIT é somente por processo, as referências ágeis são por processo e não podem ser empacotadas.

O recurso de referência agile fornece uma melhoria de desempenho em relação ao GIT. A referência agile executa marshaling adiantado por padrão, o que salva uma chamada entre apartamentos nos casos em que o objeto é recuperado da referência agile em um apartment diferente de onde a referência agile foi criada. Para aprimoramento de desempenho adicional, os usuários da função RoGetAgileReference podem usar a mesma interface para criar um IAgileReference e resolve o objeto original. Isso salva uma chamada QueryInterface adicional para obter a interface desejada do objeto resolvido.

Por exemplo, você tem um objeto não agile chamado CDemoExample, que implementa as interfaces IDemo e IExample. Chame a função RoGetAgileReference e passe o objeto com IID_IDemo. Você recebe de volta um ponteiro de interface IAgileReference , que é ágil, para que você possa passá-lo para um apartamento diferente. No outro apartment, chame o método Resolve , com IID_IExample. Você recebe de volta um ponteiro IExample que você pode usar dentro deste apartamento. Esse ponteiro IExample é um proxy IExample conectado ao objeto CDemoExample original. A referência agile lida com a complexidade das operações, como realizar marshaling manualmente em um fluxo e desmarsalar do outro lado do limite do apartamento.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 8.1 [aplicativos da área de trabalho | Aplicativos UWP]
Servidor mínimo com suporte	Windows Server 2012 R2 [aplicativos da área de trabalho | Aplicativos UWP]
Plataforma de Destino	Windows
Cabeçalho	combaseapi.h
Biblioteca	Ole32.lib
DLL	Ole32.dll

Confira também

AgileReferenceOptions

IAgileReference