Método IOleCommandTarget::Exec (docobj.h)

  • Artigo

Executa o comando especificado ou exibe a ajuda para o comando .

Sintaxe

HRESULT Exec(
  [in]      const GUID *pguidCmdGroup,
  [in]      DWORD      nCmdID,
  [in]      DWORD      nCmdexecopt,
  [in]      VARIANT    *pvaIn,
  [in, out] VARIANT    *pvaOut
);

Parâmetros

[in] pguidCmdGroup

O identificador exclusivo do grupo de comandos; pode ser NULL para especificar o grupo padrão.

[in] nCmdID

O comando a ser executado. Esse comando deve pertencer ao grupo especificado com pguidCmdGroup.

[in] nCmdexecopt

Especifica como o objeto deve executar o comando. Os valores possíveis são obtidos das enumerações OLECMDEXECOPT e OLECMDID_WINDOWSTATE_FLAG .

[in] pvaIn

Um ponteiro para uma estrutura VARIANTARG que contém argumentos de entrada. Este parâmetro pode ser NULL.

[in, out] pvaOut

Ponteiro para uma estrutura VARIANTARG para receber a saída de comando. Este parâmetro pode ser NULL.

Valor retornado

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

Código de retorno Descrição
OLECMDERR_E_UNKNOWNGROUP
 O parâmetro pguidCmdGroup não é NULL , mas não especifica um grupo de comandos reconhecido.
OLECMDERR_E_NOTSUPPORTED
 O parâmetro nCmdID não é um comando válido no grupo identificado por pguidCmdGroup.
OLECMDERR_E_DISABLED
 O comando identificado por nCmdID está desabilitado no momento e não pode ser executado.
OLECMDERR_E_NOHELP
 O chamador solicitou ajuda no comando identificado por nCmdID, mas nenhuma ajuda está disponível.
OLECMDERR_E_CANCELED
 O usuário cancelou a execução do comando.

Comentários

A lista de argumentos de entrada e saída de um comando e como eles são empacotados é exclusiva para cada comando. Essas informações devem ser documentadas com a especificação do grupo de comandos. (Consulte a descrição de OLECMDID_ZOOM na enumeração OLECMDID .) Na ausência de informações específicas, supõe-se que o comando não tenha argumentos e não tenha nenhum valor retornado.

Anotações para chamadores

Os parâmetros pguidCmdGroup e nCmdID juntos identificam exclusivamente o comando a ser invocado. O parâmetro nCmdExecOpt especifica a ação exata a ser tomada. (Consulte a enumeração OLECMDEXECOPT para obter mais detalhes.)

A maioria dos comandos não aceita argumentos nem valores retornados. Para esses comandos, o chamador pode passar NULL em pvaIn e pvaOut. Para comandos que esperam um ou mais valores de entrada, o chamador pode declarar e inicializar uma variável VARIANTARG e passar um ponteiro para essa variável no pvaIn. Se a entrada para o comando for um único valor, o argumento poderá ser armazenado diretamente na estrutura VARIANTARG e passado para a função . Se o comando espera vários argumentos, esses argumentos devem ser empacotados adequadamente dentro do VARIANTARG, usando um dos tipos com suporte (como IDispatch ou SAFEARRAY).

Se um comando retornar um ou mais argumentos, espera-se que o chamador declare um VARIANTARG, inicialize-o para VT_EMPTY e passe seu endereço no pvaOut. Se o comando retornar um único valor, o objeto poderá armazenar esse valor diretamente no pvaOut. Se o comando tiver vários valores de saída, ele os empacotará de alguma forma apropriados para o VARIANTARG.

Como pvaIn e pvOut são alocados pelo chamador, as variáveis de pilha são permitidas tanto para o chamador quanto para o objeto que recebe a chamada. Para comandos que recebem zero ou um argumento na entrada e retornam zero ou um valor, nenhuma alocação de memória adicional é necessária. A maioria dos tipos compatíveis com VARIANTARG não exige alocação de memória. As exceções incluem SAFEARRAY e BSTR.

Anotações aos implementadores

Um destino de comando deve implementar essa função; E_NOTIMPL não é um valor retornado válido.

Requisitos

   
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 docobj.h

Confira também

IOleCommandTarget

OLECMDEXECOPT