Método IMarshal::MarshalInterface (objidl.h)

Realiza marshaling de um ponteiro de interface.

Sintaxe

HRESULT MarshalInterface(
  [in] IStream *pStm,
  [in] REFIID  riid,
  [in] void    *pv,
  [in] DWORD   dwDestContext,
  [in] void    *pvDestContext,
  [in] DWORD   mshlflags
);

Parâmetros

[in] pStm

Um ponteiro para o fluxo a ser usado durante o marshaling.

[in] riid

Uma referência ao identificador da interface a ser empacotada. Essa interface deve ser derivada da interface IUnknown .

[in] pv

Um ponteiro para o ponteiro de interface a ser realizado em marshaling. Esse parâmetro poderá ser NULL se o chamador não tiver um ponteiro para a interface desejada.

[in] dwDestContext

O contexto de destino em que a interface especificada deve ser desmarsalada. Os valores possíveis para dwDestContext vêm da enumeração MSHCTX. Atualmente, pode ocorrer unmarshaling em outro apartament do processo atual (MSHCTX_INPROC) ou em outro processo no mesmo computador o processo atual (MSHCTX_LOCAL).

[in] pvDestContext

Esse parâmetro é reservado e deve ser 0.

[in] mshlflags

Indica se os dados a serem empacotados devem ser transmitidos de volta para o processo do cliente, o caso típico, ou gravados em uma tabela global, em que podem ser recuperados por vários clientes. Os valores possíveis vêm da enumeração MSHLFLAGS .

Valor retornado

Esse método pode retornar o valor retornado padrão E_FAIL, bem como os valores a seguir.

Código de retorno	Descrição
S_OK	O ponteiro da interface foi realizado com êxito.
E_NOINTERFACE	Não há suporte para a interface especificada.
STG_E_MEDIUMFULL	O fluxo está cheio.

Comentários

Esse método é chamado indiretamente, em uma chamada para CoMarshalInterface, por qualquer código no processo do servidor que seja responsável por realizar marshaling de um ponteiro para uma interface em um objeto . Esse código de marshaling geralmente é um stub gerado pelo COM para uma das várias interfaces que podem realizar marshaling de um ponteiro para uma interface implementada em um objeto totalmente diferente. Os exemplos incluem as interfaces IClassFactory e IOleItemContainer . Para fins de discussão, o código responsável pelo marshaling de um ponteiro é chamado de stub de marshaling.

Anotações aos Chamadores

Normalmente, em vez de chamar MarshalInterface diretamente, o stub de marshaling deve chamar a função CoMarshalInterface , que contém uma chamada para esse método. O stub faz essa chamada para comandar um objeto para gravar seus dados de marshaling em um fluxo. Em seguida, o stub passa os dados de marshaling de volta para o processo do cliente ou os grava em uma tabela global, em que ele pode ser nãomarshalado por vários clientes. A chamada do stub para CoMarshalInterface normalmente é precedida por uma chamada para CoGetMarshalSizeMax para obter o tamanho máximo do buffer de fluxo no qual os dados de marshaling serão gravados.

Você não chamará explicitamente esse método se estiver implementando interfaces COM existentes ou definindo suas próprias interfaces usando a MIDL (Linguagem de Definição de Interface da Microsoft). Em ambos os casos, o stub gerado por MIDL faz a chamada automaticamente.

Se você não estiver usando MIDL para definir sua própria interface, o stub de marshaling deverá chamar esse método, direta ou indiretamente. Sua implementação de stub deve chamar MarshalInterface imediatamente após a chamada anterior para IMarshal::GetMarshalSizeMax retornar. Como o valor retornado por GetMarshalSizeMax tem a garantia de ser válido somente desde que o estado interno do objeto que está sendo realizado em marshaling não seja alterado, um atraso na chamada de MarshalInterface executa o risco de que o objeto exija um buffer de fluxo maior do que o indicado originalmente.

Se o chamador tiver um ponteiro para a interface a ser empacotada, ele deverá, por questão de eficiência, usar o parâmetro pv para passar esse ponteiro. Dessa forma, uma implementação que pode usar esse ponteiro para determinar o CLSID apropriado para o proxy não precisa chamar QueryInterface em si. Se um chamador não tiver um ponteiro para a interface a ser empacotada, ele poderá passar NULL.

Observações aos implementadores

Sua implementação de MarshalInterface deve gravar no fluxo quaisquer dados necessários para inicializar o proxy no lado receptor. Esses dados incluem uma referência à interface a ser empacotada, um valor MSHLFLAGS especificando se os dados devem ser retornados para o processo do cliente ou gravados em uma tabela global e o que for necessário para se conectar ao objeto, como um pipe nomeado, identificador para uma janela ou ponteiro para um canal RPC.

Sua implementação não deve assumir que o fluxo é grande o suficiente para manter todos os dados. Em vez disso, ele deve lidar normalmente com um erro de STG_E_MEDIUMFULL. Pouco antes de sair, sua implementação deve posicionar o ponteiro seek no fluxo imediatamente após o último byte de dados gravados.

Se o parâmetro pv for NULL e sua implementação precisar de um ponteiro de interface, ele poderá chamar QueryInterface no objeto atual para obtê-lo. O parâmetro pv existe apenas para melhorar a eficiência.

Para garantir que a implementação do MarshalInterface continue funcionando corretamente à medida que novos contextos de destino tiverem suporte no futuro, delegue o marshaling para a implementação padrão COM para todos os valores dwDestContext que sua implementação não manipula. Para delegar o marshaling para a implementação padrão COM, chame a função auxiliar CoGetStandardMarshal .

Usando a enumeração MSHLFLAGS , os chamadores podem especificar se um ponteiro de interface deve ser empacotado de volta para um único cliente ou gravado em uma tabela global, em que ele pode ser nãomarsalizado por vários clientes. Você deve verificar se o objeto pode lidar com chamadas de vários proxies que podem ser criados com base nos mesmos dados de inicialização.

Requisitos

Cliente mínimo com suporte	Windows 2000 Professional [aplicativos da área de trabalho | Aplicativos UWP]
Servidor mínimo com suporte	Windows 2000 Server [aplicativos da área de trabalho | Aplicativos UWP]
Plataforma de Destino	Windows
Cabeçalho	objidl.h (inclua ObjIdl.h)

Confira também

Comarshalinterface

IMarshal