IOleObject::DoVerb

9/8/2008

Este método solicita um objeto para executar uma ação em resposta ao final-ação do usuário. As ações possíveis são enumeradas para o objeto no IOleObject::EnumVerbs.

Syntax

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

Parameters

• iVerb
  [no] Número atribuído para o verbo in a OLEVERB estrutura retornada por EnumVerbs.

• lpmsg
  [no] Ponteiro longo para o MSG estrutura descrevendo o evento que chamada de verbo.

  O chamador deve transmitir o MSG estrutura mantidos inalterada, sem tentar interpretar ou alterar os valores de qualquer um dos membros do lpmsg.

• pActiveSite
  [no] Ponteiro para o IOleClientSite interface no ativo do o objeto site cliente, onde o evento ocorreu que chamada de verbo.

• lIndex
  [no] Reservado para uso futuro; definido como zero.

• hwndParent
  [no] Tratar a janela de documento que contém o objeto.

  Isso e lprcPosRect possibilitam a aberto um janela temporário para um objeto, onde hwndParent é a janela pai no qual janela do objeto é ser exibida, e lprcPosRect Define a área disponível para exibir a janela objeto dentro desse pai.

  Uma janela temporária é útil, de exemplo, para uma multimídia objeto que abre próprio para reprodução, mas não para edição.

• lprcPosRect
  [no] Ponteiro longo para o RECT estrutura que contém as coordenadas, em pixels, que definem retângulo delimitador de um objeto no hwndParent.

  Isso e hwndParent habilitar juntos abrindo multimídia objetos para reprodução, mas não para edição.

Return Value

Um dos valores na seguinte tabela é retornada.

Valor	Descrição
S_OK	Objeto chamado o verbo especificado.
OLE_E_NOT_INPLACEACTIVE	O iVerb parâmetro está definido como OLEIVERB_UIACTIVATE ou OLEIVERB_INPLACEACTIVATE e o objeto não estiver visível.
OLE_E_CANT_BINDTOSOURCE	Objeto manipulador ou link de objeto não é possível conectar a origem de link.
DV_E_LINDEX	Inválido lIndex.
OLEOBJ_S_CANNOT_DOVERB_NOW	O verbo é válido, mas no estado do objeto a ela não é possível executar o correspondente ação.
OLEOBJ_S_INVALIDHWND	DoVerb foi bem-sucedido mas hwndParent é inválido.
OLEOBJ_E_NOVERBS	O objeto não suporte verbos.
OLEOBJ_S_INVALIDVERB	O objeto não reconhece um número positivo verbo. Verbo é tratado como OLEIVERB_PRIMARY.
MK_E_CONNECT	A origem link é entre uma rede que não está conectado a uma unidade nesta máquina.
OLE_E_CLASSDIFF	A classe para a origem do link passou uma conversão.
E_NOTIMPL	O objeto não suporte in-place activation ou não reconhece um número negativo verbo.

Remarks

Um verbo é uma ação que um objeto OLE executa em resposta a uma mensagem de seu contêiner. Contêiner de um objeto, ou um cliente vinculado o objeto, normalmente chamadas DoVerb Em resposta a alguma ação, such as clicando duas vezes o objeto usuário.

Os vários disponível ações para um determinado objeto é enumerados em um OLEVERB estrutura, o qual o contêiner obtém por chamado EnumVerbs.

DoVerb Coincide com o valor de iVerb Em relação a iVerb membro da estrutura para determinar qual verbo para invocar.

Por meio EnumVerbs, um objeto, em vez seu contêiner, determina quais verbos (ações) ele oferece suporte.

OLE 2 define sete verbos que estão disponível, mas não necessariamente útil, para todos os objetos. Além disso, cada objeto pode definir verbos adicionais que são exclusivo a ele.

O seguinte verbos são definidos pelo OLE:

• OLEIVERB_PRIMARY (0L)
  Especifica a ação que ocorre quando um usuário clica duas vezes o objeto no seu contêiner. O objeto, não o contêiner, determina esta ação.

  Se o objeto oferece suporte a in-place activation, o primário verbo normalmente Ativa o objeto no local.

• OLEIVERB_SHOW (– 1)
  Instrui um objeto para apresentação próprio para edição ou visualização. Chamado para objetos exibir recém-inserido para edição inicial e a apresentação link fontes. Geralmente, um alias para alguns outro verbo Object-defined.

• OLEIVERB_OPEN (– 2)
  Instrui um objeto, inclusive uma que caso contrário oferece suporte para in-place activation, aberto próprio para edição em separar uma janela de seu contêiner.

  Se o objeto não suporte in-place activation, esse verbo tem a mesma semântica como OLEIVERB_SHOW.

• OLEIVERB_HIDE (–3)
  Faz com que um objeto para remover seu interface do usuário a partir de exibição. Aplica-se somente a objetos que são ativados no-local.

• OLEIVERB_UIACTIVATE (–4)
  Ativa um objeto no local, along with o conjunto completo de usuário-ferramentas interface, incluindo menus, barras de ferramentas e seu nome na barra de título da janela contêiner.

  Se o objeto não suporte in-place activation, ela deve retornar E_NOTIMPL.

• OLEIVERB_INPLACEACTIVATE (–5)
  Ativa um objeto no local sem Exibindo ferramentas, como os menus e barras de ferramentas, que os usuários precisam para alteração de comportamento ou aparência do objeto.

  Clicando em tal um objeto único faz com que ele negociar a exibir do seu usuário-ferramentas interface com seu contêiner. Se o contêiner recusa, o objeto permanece ativo, mas sem suas ferramentas exibidas.

• OLEIVERB_DISCARDUNDOSTATE (–6)
  Usada para instruir objetos para descartar qualquer Desfazer estado que eles podem ser manutenção sem desativar o objeto.

Para determinar se a plataforma oferece suporte a esta interface, consulte Determinando suporte COM APIs.

Observação Para chamadores

Chamar recipientes DoVerb Como parte de inicializar um objeto recém-criado.

Antes de fazer a chamar, recipientes devem fazer o seguinte:

• Chamar IOleObject::SetClientSite Para informar o objeto de sua localidade exibir
• Chamar IOleObject::SetHostNames Para alerta o objeto que é um objeto incorporado e ao disparador apropriado muda para interface de usuário do aplicativo de objeto na preparação para abrir um janela de edição.

Como o OleActivate função em OLE 1, DoVerb Executa automaticamente o aplicativo de servidor OLE. Se ocorrer um erro durante a execução verbo, o aplicativo objeto está desligado.

Se um usuário chama um verbo por alguns meios diferente selecionando um comando de um menu (digamos, ao clicar duas vezes ou, mais raramente, clicando em um objeto único), contêiner do objeto deve transmitir um (ponteirolpmsg) para um Windows MSG estrutura que contém o apropriado mensagem.

De exemplo, se o usuário chama um verbo clicando duas vezes o objeto, o contêiner deve transmitir um MSG estrutura que contém WM_LBUTTONDBLCLK, WM_MBUTTONDBLCLK ou WM_RBUTTONDBLCLK.

Se nenhuma mensagem, passa o contêiner lpmsg Deve ser definido como NULL.

O objeto deve ignorar o hwnd membro do passado MSG estrutura, mas pode usar todos os outros MSG Os membros.

Se incorporação de objeto contêiner chamadas DoVerb, o cliente-site (ponteiropClientSite) passado para DoVerb é o mesmo a incorporação do site. Se o objeto incorporado é uma origem link, o ponteiro passados para DoVerb é de site cliente do cliente de vinculação.

Quando DoVerb é chamado em um link OLE, ele pode retornar OLE_E_CLASSDIFF ou MK_CONNECTMANUALLY:

• O objeto link retorna OLE_E_CLASSDIFF quando a origem link tem sido sujeitos a alguns classificar de conversão enquanto o link foi passivo.
• O objeto link retorna MK_CONNECTMANUALLY quando a origem link está em uma unidade rede que não esteja conectada ao computador do chamador.

Os aplicativos recipientes que não in-place activation geral não suporte ainda podem usar o hwndParent e lprcPosRect Parâmetros para suporte em-local reprodução de multimídia arquivos. Recipientes devem transmitir válido hwndParent e lprcPosRect Parâmetros para DoVerb.

Alguns transmitir amostras codificar um lIndex valor de – 1 instead of zero. A valor – 1 funciona, mas deve ser evitado in favor of zero.

O lIndex parâmetro é reservado e, por motivos de consistência Microsoft recomenda atribuição um zero valor para todos os parâmetros reservados.

Notas para Implementers

Em adição para os verbos acima, um objeto pode definir na sua OLEVERB estrutura verbos adicionais que são específicos próprio. Números positivos designar esses verbos específica de objetos.

Um objeto deve tratar um desconhecido positivo verbo número como se fosse o primário verbo e OLE_S_INVALIDVERB de retorno para a função chamado.

O objeto deve ignorar verbos com números negativos que ele não reconhece e retornar E_NOTIMPL.

Se o verbo que está sendo executado coloca o objeto de execução estado, registrar o objeto no Running Object Table (ROT) mesmo se o aplicativo servidor não suporte vinculação. O registro é importante porque o objeto Talvez em alguns têm apontar como a origem de um link em um contêiner que ofereça suporte a links para embeddings.

Registrando o objeto com o ROT permite que o cliente link para get um ponteiro para o objeto diretamente, em vez de ter que percorrer contêiner do objeto.

Para executar o registro, faça o seguinte:

1. Chamar IOleClientSite::GetMoniker Para o moniker completo do objeto, get
2. Chamar o GetRunningObjectTable função para get um ponteiro para o ROT e, em seguida,
3. Chamar IRunningObjectTable::Register.

Observação

Quando o objeto deixa de execução estado, lembre-se revogar registro do objeto com o ROT por chamado Fechar.

Observação

Se documento contêiner do objeto é renomeado enquanto o objeto está execução, você deve revogar registro do objeto e registrá-lo novamente com o ROT, usando seu novo nome.

Observação

O contêiner deve informar o objeto de sua nova moniker por chamado IOleObject::SetMoniker ou responder a chamado o objeto IOleClientSite::GetMoniker.

Quando mostrando uma janela as a result of DoVerb, é muito importante para o objeto para chamar explicitamente SetForegroundWindow No seu janela de edição. Isso assegura que janela do objeto fique visível para o usuário mesmo se outro processo originalmente obscurecida-lo.

Para obter mais informações sobre SetForegroundWindow e SetActiveWindow, consulte o Windows SDK.

Requirements

Header	Oleidl.h, oleidl.idl
Library	oleaut32.lib, uuid.lib
Windows Embedded CE	Windows CE 2.0 and later
Windows Mobile	Windows Mobile Version 5.0 and later

See Also

Reference

IOleObject
GetRunningObjectTable
IOleClientSite
IOleClientSite::GetMoniker
IOleObject::EnumVerbs
IOleObject::SetClientSite
IOleObject::SetHostNames
IRunningObjectTable::Register
OLEVERB

Concepts

Determining Supported COM APIs

Other Resources