Método IOleObject::D oVerb (oleidl.h)

Artigo
03/15/2023

Solicita que um objeto execute uma ação em resposta a ação de um usuário final. As ações possíveis são enumeradas para o objeto em IOleObject::EnumVerbs.

Sintaxe

HRESULT DoVerb(
  [in] LONG           iVerb,
  [in] LPMSG          lpmsg,
  [in] IOleClientSite *pActiveSite,
  [in] LONG           lindex,
  [in] HWND           hwndParent,
  [in] LPCRECT        lprcPosRect
);

Parâmetros

[in] iVerb

Número atribuído ao verbo na estrutura OLEVERB retornada por IOleObject::EnumVerbs.

[in] lpmsg

Ponteiro para a estrutura MSG que descreve o evento (como um clique duplo) que invocou o verbo. O chamador deve passar a estrutura MSG sem modificação, sem tentar interpretar ou alterar os valores de qualquer um dos membros da estrutura.

[in] pActiveSite

Ponteiro para a interface IOleClientSite no site do cliente ativo do objeto, em que ocorreu o evento que invocou o verbo.

[in] lindex

Esse parâmetro é reservado e precisa ser zero.

[in] hwndParent

Identificador da janela do documento que contém o objeto. Isso e lprcPosRect juntos possibilitam abrir uma janela temporária para um objeto, em que hwndParent é a janela pai na qual a janela do objeto deve ser exibida e lprcPosRect define a área disponível para exibir a janela do objeto dentro desse pai. Uma janela temporária é útil, por exemplo, para um objeto multimídia que se abre para reprodução, mas não para edição.

[in] lprcPosRect

Ponteiro para a estrutura RECT que contém as coordenadas, em pixels, que definem o retângulo delimitador de um objeto em hwndParent. Isso e hwndParent juntos permitem abrir objetos multimídia para reprodução, mas não para edição.

Retornar valor

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

Código de retorno	Descrição
OLE_E_NOT_INPLACEACTIVE	iVerb definido como OLEIVERB_UIACTIVATE ou OLEIVERB_INPLACEACTIVATE e o objeto ainda não está visível.
OLE_E_CANT_BINDTOSOURCE	O manipulador de objetos ou o objeto de link não pode se conectar à origem do link.
DV_E_LINDEX	Lindex inválido.
OLEOBJ_S_CANNOT_DOVERB_NOW	O verbo é válido, mas no estado atual do objeto ele não pode executar a ação correspondente.
OLEOBJ_S_INVALIDHWND	DoVerb foi bem-sucedido, mas hwndParent é inválido.
OLEOBJ_E_NOVERBS	O objeto não dá suporte a verbos.
OLEOBJ_S_INVALIDVERB	A origem do link está em uma rede que não está conectada a uma unidade neste computador.
MK_E_CONNECT	A origem do link está em uma rede que não está conectada a uma unidade neste computador.
OLE_E_CLASSDIFF	A classe para a origem do link passou por uma conversão.
E_NOTIMPL	O objeto não dá suporte à ativação in-loco ou não reconhece um número de verbo negativo.

Comentários

Um "verbo" é uma ação que um objeto OLE executa em resposta a uma mensagem de seu contêiner. O contêiner de um objeto ou um cliente vinculado ao objeto normalmente chama IOleObject::D oVerb em resposta a alguma ação do usuário final, como clicar duas vezes no objeto. As várias ações disponíveis para um determinado objeto são enumeradas em uma estrutura OLEVERB , que o contêiner obtém chamando IOleObject::EnumVerbs. IOleObject::D oVerb corresponde ao valor de iVerb em relação ao membro iVerb da estrutura para determinar qual verbo invocar.

Por meio de IOleObject::EnumVerbs, um objeto, em vez de seu contêiner, determina quais verbos (ou seja, ações) ele dá suporte. O OLE 2 define sete verbos disponíveis, mas não necessariamente úteis, para todos os objetos. Além disso, cada objeto pode definir verbos adicionais exclusivos para ele. A tabela a seguir descreve os verbos definidos pelo OLE.

Verbo	Descrição
OLEIVERB_PRIMARY (0L)	Especifica a ação que ocorre quando um usuário final clica duas vezes no objeto em seu contêiner. O objeto, não o contêiner, determina essa ação. Se o objeto der suporte à ativação in-loco, o verbo primário geralmente ativará o objeto no local.
OLEIVERB_SHOW (-1)	Instrui um objeto a se mostrar para edição ou exibição. Chamado para exibir objetos recém-inseridos para edição inicial e para mostrar fontes de link. Normalmente, um alias para algum outro verbo definido pelo objeto.
OLEIVERB_OPEN (-2)	Instrui um objeto, incluindo um que, de outra forma, dá suporte à ativação in-loco, para se abrir para edição em uma janela separada da do contêiner. Se o objeto não der suporte à ativação in-loco, esse verbo terá a mesma semântica que OLEIVERB_SHOW.
OLEIVERB_HIDE (-3)	Faz com que um objeto remova sua interface do usuário da exibição. Aplica-se somente a objetos que são ativados in-loco.
OLEIVERB_UIACTIVATE (-4)	Ativa um objeto no local, juntamente com seu conjunto completo de ferramentas de interface do usuário, incluindo menus, barras de ferramentas e seu nome na barra de título da janela do contêiner. Se o objeto não der suporte à ativação in-loco, ele deverá retornar E_NOTIMPL.
OLEIVERB_INPLACEACTIVATE (-5)	Ativa um objeto no local sem exibir ferramentas, como menus e barras de ferramentas, que os usuários finais precisam alterar o comportamento ou a aparência do objeto. Clicar com um único clique em um objeto faz com que ele negocie a exibição de suas ferramentas de interface do usuário com seu contêiner. Se o contêiner recusar, o objeto permanecerá ativo, mas sem suas ferramentas exibidas.
OLEIVERB_DISCARDUNDOSTATE (-6)	Usado para instruir os objetos a descartar qualquer estado de desfazer que eles possam estar mantendo sem desativar o objeto.

Anotações aos Chamadores

Os contêineres chamam IOleObject::D oVerb como parte da inicialização de um objeto recém-criado. Antes de fazer a chamada, os contêineres devem primeiro chamar IOleObject::SetClientSite para informar o objeto de seu local de exibição e IOleObject::SetHostNames para alertar o objeto de que ele é um objeto inserido e disparar alterações apropriadas na interface do usuário do aplicativo de objeto em preparação para abrir uma janela de edição.

IOleObject::D oVerb executa automaticamente o aplicativo de servidor OLE. Se ocorrer um erro durante a execução do verbo, o aplicativo objeto será desligado.

Se um usuário final invocar um verbo por alguns meios diferentes de selecionar um comando em um menu (digamos, clicando duas vezes ou, mais raramente, clicando em um objeto), o contêiner do objeto deverá passar um ponteiro para uma estrutura msg do Windows que contém a mensagem apropriada. Por exemplo, se o usuário final invocar um verbo clicando duas vezes no objeto , o contêiner deverá passar uma estrutura MSG contendo WM_LBUTTONDBLCLK, WM_MBUTTONDBLCLK ou WM_RBUTTONDBLCLK. Se o contêiner não passar nenhuma mensagem, lpmsg deverá ser definido como NULL. O objeto deve ignorar o membro hwnd da estrutura MSG passada, mas pode usar todos os outros membros msg.

Se o contêiner de inserção do objeto chamar IOleObject::D oVerb, o ponteiro do site do cliente (pClientSite) passado para IOleObject::D oVerb será o mesmo do site de inserção. Se o objeto inserido for uma fonte de link, o ponteiro passado para IOleObject::D oVerb será o do site cliente do cliente de vinculação.

Quando IOleObject::D oVerb é invocado em um link OLE, ele pode retornar OLE_E_CLASSDIFF ou MK_CONNECTMANUALLY. O objeto link retorna o erro anterior quando a origem do link foi submetida a algum tipo de conversão enquanto o link era passivo. O objeto link retorna o último erro quando a origem do link está localizada em uma unidade de rede que não está conectada atualmente ao computador do chamador. A única maneira de conectar um link nessas condições é primeiro chamar IUnknown::QueryInterface, solicitar IOleLink, alocar um contexto de associação e executar a origem do link chamando IOleLink::BindToSource.

Os aplicativos de contêiner que não dão suporte à ativação in-loco geral ainda podem usar os parâmetros hwndParent e lprcPosRect para dar suporte à reprodução in-loco de arquivos multimídia. Os contêineres devem passar parâmetros hwndParent e lprcPosRect válidos para IOleObject::D oVerb.

Alguns exemplos de código passam um valor lindex de -1 em vez de zero. O valor -1 funciona, mas deve ser evitado em favor de zero. O parâmetro lindex é um parâmetro reservado e, por motivos de consistência, a Microsoft recomenda atribuir um valor zero a todos os parâmetros reservados.

Observações aos implementadores

Além dos verbos acima, um objeto pode definir em sua estrutura OLEVERB verbos adicionais que são específicos para si mesmo. Os números positivos designam esses verbos específicos do objeto. Um objeto deve tratar qualquer número de verbo positivo desconhecido como se fosse o verbo primário e retornar OLEOBJ_S_INVALIDVERB para a função de chamada. O objeto deve ignorar verbos com números negativos que não reconhece e retorna E_NOTIMPL.

Se o verbo que está sendo executado colocar o objeto no estado em execução, você deverá registrar o objeto na ROT (tabela de objetos em execução), mesmo que seu aplicativo de servidor não dê suporte à vinculação. O registro é importante porque o objeto em algum momento pode servir como a origem de um link em um contêiner que dá suporte a links para inserções. Registrar o objeto com o ROT permite que o cliente de link obtenha um ponteiro para o objeto diretamente, em vez de ter que passar pelo contêiner do objeto. Para executar o registro, chame IOleClientSite::GetMoniker para obter o moniker completo do objeto, chame a função GetRunningObjectTable para obter um ponteiro para o ROT e, em seguida, chame IRunningObjectTable::Register.

Nota Quando o objeto sair do estado em execução, lembre-se de revogar o registro do objeto com o ROT chamando IOleObject::Close. Se o documento de contêiner do objeto for renomeado enquanto o objeto estiver em execução, você deverá revogar o registro do objeto e registrá-lo novamente no ROT, usando seu novo nome. O contêiner deve informar o objeto de seu novo moniker chamando IOleObject::SetMoniker ou respondendo à chamada do objeto IOleClientSite::GetMoniker.

Ao mostrar uma janela como resultado de IOleObject::D oVerb, é muito importante que o objeto chame explicitamente SetForegroundWindow em sua janela de edição. Isso garante que a janela do objeto fique visível para o usuário, mesmo que outro processo a tenha ocultado originalmente. Para obter mais informações, consulte SetForegroundWindow e SetActiveWindow.

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