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

Faz 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 marshalada. Essa interface deve ser derivada da interface IUnknown .

[in] pv

Um ponteiro para o ponteiro da interface a ser empacotado. 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 desmarsada. 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 marshalados 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 .

Retornar valor

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

Código de retorno	Descrição
S_OK	O ponteiro da interface foi empacotado 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 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 para chamadores

Normalmente, em vez de chamar MarshalInterface diretamente, seu 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 eles podem ser não gravados 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 LINGUAGEM de Definição de Interface da Microsoft (MIDL). 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, seu 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 apenas enquanto o estado interno do objeto que está sendo marshalado não for alterado, um atraso na chamada marshalInterface executará o risco de que o objeto exigirá um buffer de fluxo maior do que o indicado originalmente.

Se o chamador tiver um ponteiro para a interface a ser marshalada, ele deverá, em 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 mesmo. Se um chamador não tiver um ponteiro para a interface a ser marshalada, ele poderá passar NULL.

Anotações aos implementadores

Sua implementação do 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 marshalada, um valor MSHLFLAGS especificando se os dados devem ser retornados ao 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 de busca 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, delegar 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 garantir que seu objeto possa lidar com chamadas de vários proxies que podem ser criados com base nos mesmos dados de inicialização.

Requisitos

Requisito	Valor
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	objidlbase.h (inclua ObjIdl.h)

Confira também

Comarshalinterface

IMarshal