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

Recupera o tamanho máximo do buffer que será necessário durante o marshaling.

Sintaxe

HRESULT GetMarshalSizeMax(
  [in]  REFIID riid,
  [in]  void   *pv,
  [in]  DWORD  dwDestContext,
  [in]  void   *pvDestContext,
  [in]  DWORD  mshlflags,
  [out] DWORD  *pSize
);

Parâmetros

[in] riid

Uma referência ao identificador da interface a ser empacotada.

[in] pv

O ponteiro de interface a ser realizado em marshaling. Este parâmetro pode ser NULL.

[in] dwDestContext

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

[in] pvDestContext

Esse parâmetro é reservado e deve ser NULL.

[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 .

[out] pSize

Um ponteiro para uma variável que recebe o tamanho máximo do buffer.

Retornar valor

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

Código de retorno	Descrição
E_NOINTERFACE	Não há suporte para a interface especificada.

Comentários

Esse método é chamado indiretamente, em uma chamada para CoGetMarshalSizeMax, 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.

Para criar um proxy para um objeto , COM requer duas informações do objeto original: a quantidade de dados a serem gravados no fluxo de marshaling e o CLSID do proxy.

O stub de marshaling obtém essas duas informações com chamadas sucessivas para CoGetMarshalSizeMax e CoMarshalInterface.

Anotações aos Chamadores

O stub de marshaling, por meio de uma chamada para CoGetMarshalSizeMax, chama a implementação do objeto desse método para pré-alocar o buffer de fluxo que será passado para MarshalInterface.

Você não chamará explicitamente esse método se estiver implementando interfaces COM existentes ou usando a MIDL (Linguagem de Definição de Interface) da Microsoft para definir suas próprias interfaces personalizadas. 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 (consulte Definindo interfaces COM), seu stub de marshaling não precisará chamar GetMarshalSizeMax, embora isso seja altamente recomendado. Um objeto sabe melhor do que um stub de interface qual é o tamanho máximo de um pacote de dados de marshaling. Portanto, a menos que você esteja fornecendo um fluxo de crescimento automático que seja tão eficiente que a sobrecarga de expandi-lo seja insignificante, você deve chamar esse método mesmo ao implementar suas próprias interfaces.

O valor retornado por esse método tem a garantia de ser válido apenas desde que o estado interno do objeto que está sendo realizado em marshaling não seja alterado. Portanto, o marshaling real deve ser feito imediatamente após o retorno dessa função ou o stub executa o risco de que o objeto, devido a alguma alteração no estado, possa exigir mais memória para realizar marshaling do que o indicado originalmente.

Observações aos implementadores

Sua implementação de MarshalInterface usará o buffer pré-alocado para gravar dados de marshaling no fluxo. Se o buffer for muito pequeno, a operação de marshaling falhará. Portanto, o valor retornado por esse método deve ser uma estimativa conservadora da quantidade de dados que serão necessários para realizar marshaling da interface. A violação desse requisito deve ser tratada como um erro catastrófico.

Em uma chamada subsequente para MarshalInterface, sua implementação IMarshal não pode depender do chamador realmente ter chamado GetMarshalSizeMax com antecedência. Ele ainda deve ter cuidado com STG_E_MEDIUMFULL erros retornados pelo fluxo e estar preparado para lidar com eles normalmente.

Para garantir que sua implementação de GetMarshalSizeMax 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 entende. Para delegar o marshaling para a implementação padrão COM, chame a função CoGetStandardMarshal .

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	objidl.h

Confira também

CoGetMarshalSizeMax

IMarshal