Método IOleObject::SetClientSite (oleidl.h)

Artigo
03/01/2024

Informa um objeto inserido de seu local de exibição, chamado de "site cliente", dentro de seu contêiner.

Sintaxe

HRESULT SetClientSite(
  [in] IOleClientSite *pClientSite
);

Parâmetros

[in] pClientSite

Ponteiro para a interface IOleClientSite no site do cliente do aplicativo de contêiner.

Retornar valor

Esse método retorna S_OK com êxito. Outros valores retornados possíveis incluem o seguinte.

Código de retorno	Descrição
E_UNEXPECTED	Erro inesperado.

Comentários

Dentro de um documento composto, cada objeto inserido tem seu próprio site cliente – o local onde ele é exibido e por meio do qual recebe informações sobre seu armazenamento, interface do usuário e outros recursos. IOleObject::SetClientSite é o único método que permite que um objeto inserido obtenha um ponteiro para seu site cliente.

Anotações para chamadores

Um contêiner pode notificar um objeto de seu site cliente no momento em que o objeto é criado ou, posteriormente, quando o objeto é inicializado.

Ao criar ou carregar um objeto, um contêiner pode passar um ponteiro do site do cliente (juntamente com outros argumentos) para uma das seguintes funções auxiliares: OleCreate, OleCreateFromFile, OleCreateFromData ou OleLoad. Essas funções auxiliares carregam um manipulador de objetos para o novo objeto e chamam IOleObject::SetClientSite em nome do contêiner antes de retornar um ponteiro para o novo objeto.

Passar um ponteiro do site do cliente informa ao manipulador de objetos que o site do cliente está pronto para processar solicitações. Se é improvável que o site do cliente esteja pronto imediatamente após o carregamento do manipulador, talvez você queira que o contêiner passe um ponteiro nulo do site do cliente para a função auxiliar. O ponteiro NULL diz que nenhum site cliente está disponível e, portanto, adia a notificação do manipulador de objetos do site do cliente até que o objeto seja inicializado. Em resposta, a função auxiliar retorna um ponteiro para o objeto, mas ao receber esse ponteiro, o contêiner deve chamar IOleObject::SetClientSite como parte da inicialização do novo objeto.

Anotações aos implementadores

A implementação consiste simplesmente em incrementar a contagem de referência e armazenar o ponteiro para o site do cliente.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	oleidl.h