Метод IOleCommandTarget::Exec (docobj.h)

Статья
08/23/2023

Выполняет указанную команду или отображает справку для нее.

Синтаксис

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

Параметры

[in] pguidCmdGroup

Уникальный идентификатор группы команд; Может иметь значение NULL , чтобы указать стандартную группу.

[in] nCmdID

Команда для выполнения. Эта команда должна принадлежать группе, указанной с помощью pguidCmdGroup.

[in] nCmdexecopt

Определяет, каким образом объект должен выполнить команду. Возможные значения берутся из перечислений OLECMDEXECOPT и OLECMDID_WINDOWSTATE_FLAG .

[in] pvaIn

Указатель на структуру VARIANTARG, содержащую входные аргументы. Этот параметр может принимать значение NULL.

[in, out] pvaOut

Указатель на структуру VARIANTARG для получения выходных данных команды. Этот параметр может принимать значение NULL.

Возвращаемое значение

Этот метод возвращает значение S_OK при успешном завершении. Другие возможные возвращаемые значения включают следующее.

Код возврата	Описание
OLECMDERR_E_UNKNOWNGROUP	Параметр pguidCmdGroup не имеет значения NULL , но не указывает распознаваемую группу команд.
OLECMDERR_E_NOTSUPPORTED	Параметр nCmdID не является допустимой командой в группе, определяемой pguidCmdGroup.
OLECMDERR_E_DISABLED	Команда, определяемая nCmdID , в настоящее время отключена и не может быть выполнена.
OLECMDERR_E_NOHELP	Вызывающий объект обратился за помощью к команде, определяемой nCmdID, но справка недоступна.
OLECMDERR_E_CANCELED	Пользователь отменил выполнение команды.

Список входных и выходных аргументов команды и способ их упаковки уникален для каждой команды. Эти сведения должны быть задокументированы в спецификации группы команд. (См. описание OLECMDID_ZOOM в перечислении OLECMDID .) При отсутствии каких-либо конкретных сведений предполагается, что команда не принимает аргументов и не имеет возвращаемого значения.

Примечания к вызывающим абонентам

Параметры pguidCmdGroup и nCmdID вместе однозначно определяют вызываемую команду. Параметр nCmdExecOpt указывает точное действие, которое необходимо выполнить. (Дополнительные сведения см. в перечислении OLECMDEXECOPT .)

Большинство команд не принимают ни аргументы, ни возвращаемые значения. Для таких команд вызывающий объект может передавать значение NULL в pvaIn и pvaOut. Для команд, которые ожидают одно или несколько входных значений, вызывающий объект может объявить и инициализировать переменную VARIANTARG и передать указатель на нее в pvaIn. Если входные данные команды являются одним значением, аргумент может храниться непосредственно в структуре VARIANTARG и передаваться в функцию. Если команда ожидает несколько аргументов, эти аргументы должны быть упаковываны соответствующим образом в VARIANTARG с использованием одного из поддерживаемых типов (например, IDispatch или SAFEARRAY).

Если команда возвращает один или несколько аргументов, вызывающий объект должен объявить VARIANTARG, инициализировать его для VT_EMPTY и передать свой адрес в pvaOut. Если команда возвращает одно значение, объект может сохранить это значение непосредственно в pvaOut. Если команда имеет несколько выходных значений, она будет упаковывала их в какой-то способ, подходящий для VARIANTARG.

Так как pvaIn и pvOut выделены вызывающим объектом, переменные стека разрешены как для вызывающего объекта, так и для объекта, получающего вызов. Для команд, которые принимают ноль или один аргумент на входных данных и возвращают ноль или одно значение, дополнительное выделение памяти не требуется. Большинство типов, поддерживаемых VARIANTARG, не требуют выделения памяти. Исключения включают SAFEARRAY и BSTR.

Примечания для разработчиков

Целевой объект команды должен реализовывать эту функцию; E_NOTIMPL не является допустимым возвращаемым значением.

Требования


Минимальная версия клиента	Windows 2000 Professional [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Целевая платформа	Windows
Header	docobj.h

См. также раздел

IOleCommandTarget

OLECMDEXECOPT

Поделиться через