Função CoCreateFreeThreadedMarshaler (combaseapi.h)
Cria um objeto agregável capaz de realizar marshaling dependente de contexto.
Sintaxe
HRESULT CoCreateFreeThreadedMarshaler(
[in] LPUNKNOWN punkOuter,
[out] LPUNKNOWN *ppunkMarshal
);
Parâmetros
[in] punkOuter
Um ponteiro para o IUnknown controlador do objeto de agregação.
[out] ppunkMarshal
Endereço da variável de ponteiro que recebe o ponteiro de interface para o marshaler agregável.
Retornar valor
Essa função pode retornar o valor retornado padrão E_OUTOFMEMORY, bem como o valor a seguir.
| Código de retorno | Descrição |
|---|---|
|
O marshaler foi criado. |
Comentários
A função CoCreateFreeThreadedMarshaler permite que um objeto marshaling eficientemente ponteiros de interface entre threads no mesmo processo. Se os objetos não derem suporte ao marshaling interthread, você não precisará chamar essa função. Ele destina-se ao uso por servidores DLL de thread livre que devem ser acessados diretamente por todos os threads em um processo, até mesmo os threads associados a apartments de thread único. Ele realiza marshaling personalizado do ponteiro de memória real para outros apartamentos como um falso "proxy" e, assim, dá acesso direto a todos os chamadores, mesmo que eles não sejam livres.
A função CoCreateFreeThreadedMarshaler executa as seguintes tarefas:
- Cria um objeto marshaler de thread livre.
- Agrega esse marshaler ao objeto especificado pelo parâmetro punkOuter . Normalmente, esse objeto é aquele cujos ponteiros de interface devem ser empacotados.
- Verifica o contexto de destino especificado pelo parâmetro dwDestContext da função CoMarshalInterface.
- Se o contexto de destino for MSHCTX_INPROC, copiará o ponteiro da interface para o fluxo de marshaling.
- Se o contexto de destino for qualquer outro valor, localizará ou criará uma instância do marshaler padrão (padrão) do COM e delega o marshaling para ele.
É necessário ter muito cuidado ao usar a função CoCreateFreeThreadedMarshaler . Isso ocorre porque o desempenho de objetos que agregam o marshaler de thread livre é obtido por meio de uma violação calculada das regras de COM, com o risco sempre presente de comportamento indefinido, a menos que o objeto opere dentro de determinadas restrições. As restrições mais importantes são:
- Um objeto marshaler de thread livre não pode conter ponteiros diretos para interfaces em um objeto que não agrega o marshaler de thread livre como parte de seu estado. Se o objeto usar referências diretas a objetos de agregação de thread único comuns, ele poderá interromper sua única propriedade threaded. Se o objeto usar referências diretas a objetos de agregação multithread comuns, esses objetos poderão se comportar de maneiras que não mostram nenhuma sensibilidade às necessidades de clientes de agregação direta de thread único. Por exemplo, esses objetos podem girar novos threads e passar parâmetros para os threads que são referências a objetos de agregação de thread único comuns.
- Um objeto marshaler de thread livre não pode conter referências a proxies para objetos em outros apartments. Os proxies são sensíveis ao modelo de threading e podem retornar RPC_E_WRONG_THREAD se chamados pelo cliente errado.
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 | combaseapi.h (inclua Objbase.h) |
| Biblioteca | Ole32.lib |
| DLL | Ole32.dll |