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

  • Artigo

Recupera o CLSID do código unmarshaling.

Sintaxe

HRESULT GetUnmarshalClass(
  [in]  REFIID riid,
  [in]  void   *pv,
  [in]  DWORD  dwDestContext,
  [in]  void   *pvDestContext,
  [in]  DWORD  mshlflags,
  [out] CLSID  *pCid
);

Parâmetros

[in] riid

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

[in] pv

Um ponteiro para a interface a ser empacotada; 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 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] pCid

Um ponteiro que recebe o CLSID a ser usado para criar um proxy no processo do cliente.

Retornar valor

Se o método for bem-sucedido, o valor retornado será S_OK. Caso contrário, será S_FALSE.

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.

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 chama a implementação do objeto desse método para obter o CLSID a ser usado na criação de uma instância do proxy. O cliente, ao receber o CLSID, carrega a DLL listada para ele no registro do sistema.

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. Em ambos os casos, o stub faz a chamada automaticamente. Consulte Definindo interfaces COM.

Se você não estiver usando MIDL para definir sua própria interface, seu stub deverá chamar esse método, direta ou indiretamente, para obter o CLSID que a biblioteca COM do lado do cliente precisa para criar um proxy para o objeto que implementa a interface.

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

O COM chama GetUnmarshalClass para obter o CLSID a ser usado para criar um proxy no processo do cliente. O CLSID a ser usado para um proxy normalmente não é o do objeto original, mas um que você terá gerado (usando a ferramenta Guidgen.exe) especificamente para o objeto proxy.

Implemente esse método para cada objeto que fornece marshaling para uma ou mais de suas interfaces. O código responsável pelo marshaling do objeto grava o CLSID, juntamente com os dados de marshaling, em um fluxo; O COM extrai o CLSID e os dados do fluxo no lado receptor.

Se a implementação do proxy consistir simplesmente em copiar todo o objeto original para o processo do cliente, eliminando assim a necessidade de encaminhar chamadas para o objeto original, o CLSID retornado seria o mesmo que o do objeto original. Essa estratégia, é claro, é aconselhável apenas para objetos que não devem ser alterados.

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 sua implementação de GetUnmarshalClass 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 CoGetStandardMarshal .

Nota O valor do registro ThreadingModel deve ser Ambos para um servidor em processo que implementa o CLSID retornado do método GetUnmarshalClass . Para obter mais informações, consulte InprocServer32.
 

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

Comarshalinterface

IMarshal