Метод IOleObject::D oVerb (oleidl.h)

Статья
03/15/2023

Требует выполнения действия объектом в ответ на действие пользователя. Возможные действия перечисляются для объекта в IOleObject::EnumVerbs.

Синтаксис

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

Параметры

[in] iVerb

Номер, назначенный команде в структуре OLEVERB , возвращаемой методом IOleObject::EnumVerbs.

[in] lpmsg

Указатель на структуру MSG , описывающую событие (например, двойной щелчок), который вызвал команду. Вызывающий объект должен передавать структуру MSG без изменений, не пытаясь интерпретировать или изменять значения любого из элементов структуры.

[in] pActiveSite

Указатель на интерфейс IOleClientSite на активном клиентском сайте объекта, где произошло событие, вызваввшее команду.

[in] lindex

Этот параметр зарезервирован и должен быть равен нулю.

[in] hwndParent

Дескриптор окна документа, содержащего объект. Это и lprcPosRect вместе позволяют открыть временное окно для объекта , где hwndParent является родительским окном, в котором должно отображаться окно объекта, а lprcPosRect определяет область, доступную для отображения окна объекта в этом родительском элементе. Временное окно полезно, например, для мультимедийного объекта, который открывается для воспроизведения, но не для редактирования.

[in] lprcPosRect

Указатель на структуру RECT , содержащую координаты в пикселях, которые определяют ограничивающий прямоугольник объекта в hwndParent. Это и hwndParent вместе позволяют открывать мультимедийные объекты для воспроизведения, но не для редактирования.

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

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

Код возврата	Описание
OLE_E_NOT_INPLACEACTIVE	Для iVerb задано значение OLEIVERB_UIACTIVATE или OLEIVERB_INPLACEACTIVATE, а объект еще не виден.
OLE_E_CANT_BINDTOSOURCE	Обработчик объектов или объект ссылки не могут подключиться к источнику ссылки.
DV_E_LINDEX	Недопустимый lindex.
OLEOBJ_S_CANNOT_DOVERB_NOW	Команда допустима, но в текущем состоянии объекта она не может выполнить соответствующее действие.
OLEOBJ_S_INVALIDHWND	DoVerb выполнено успешно, но hwndParent является недопустимым.
OLEOBJ_E_NOVERBS	Объект не поддерживает команды.
OLEOBJ_S_INVALIDVERB	Источник связи находится в сети, которая не подключена к диску на этом компьютере.
MK_E_CONNECT	Источник связи находится в сети, которая не подключена к диску на этом компьютере.
OLE_E_CLASSDIFF	Класс для источника ссылки подвергся преобразованию.
E_NOTIMPL	Объект не поддерживает активацию на месте или не распознает отрицательный номер команды.

"Глагол" — это действие, которое объект OLE выполняет в ответ на сообщение из своего контейнера. Контейнер объекта или клиент, связанный с объектом, обычно вызывает IOleObject::D oVerb в ответ на какое-либо действие конечного пользователя, например двойной щелчок по объекту. Различные действия, доступные для данного объекта, перечисляются в структуре OLEVERB , которую контейнер получает путем вызова IOleObject::EnumVerbs. IOleObject::D oVerb сопоставляет значение iVerb с элементом iVerb структуры, чтобы определить, какую команду вызывать.

С помощью IOleObject::EnumVerbs объект, а не его контейнер, определяет, какие глаголы (т. е. действия) он поддерживает. OLE 2 определяет семь глаголов, которые доступны, но не обязательно полезны для всех объектов. Кроме того, каждый объект может определять дополнительные команды, которые являются уникальными для него. В следующей таблице описаны глаголы, определенные OLE.

Команда	Описание
OLEIVERB_PRIMARY (0L)	Указывает действие, выполняемое, когда пользователь дважды щелкает объект в его контейнере. Это действие определяет объект, а не контейнер. Если объект поддерживает активацию на месте, основная команда обычно активирует объект на месте.
OLEIVERB_SHOW (-1)	Указывает объекту показать себя для редактирования или просмотра. Вызывается для отображения вновь вставленных объектов для первоначального редактирования и отображения источников ссылок. Обычно является псевдонимом для некоторых других определяемых объектом глаголов.
OLEIVERB_OPEN (-2)	Указывает объекту, в том числе объекту, который в противном случае поддерживает активацию на месте, открыться для редактирования в окне, отдельном от окна контейнера. Если объект не поддерживает активацию на месте, эта команда имеет ту же семантику, что и OLEIVERB_SHOW.
OLEIVERB_HIDE (-3)	Вызывает удаление пользовательского интерфейса объекта из представления. Применяется только к объектам, активируемым на месте.
OLEIVERB_UIACTIVATE (-4)	Активирует объект на месте вместе с его полным набором средств пользовательского интерфейса, включая меню, панели инструментов и его имя в строке заголовка окна контейнера. Если объект не поддерживает активацию на месте, он должен вернуть E_NOTIMPL.
OLEIVERB_INPLACEACTIVATE (-5)	Активирует объект на месте без отображения таких инструментов, как меню и панели инструментов, которые конечные пользователи должны изменить поведение или внешний вид объекта. Одиночный щелчок такого объекта приводит к согласованию отображения средств пользовательского интерфейса с контейнером. Если контейнер отказывается, объект остается активным, но без отображения его инструментов.
OLEIVERB_DISCARDUNDOSTATE (-6)	Используется для того, чтобы указать объектам отменить любое состояние отмены, которое они могут поддерживать, без деактивации объекта.

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

Контейнеры вызывают IOleObject::D oVerb при инициализации только что созданного объекта. Перед выполнением вызова контейнеры должны сначала вызвать IOleObject::SetClientSite , чтобы сообщить объекту о его расположении отображения, и IOleObject::SetHostNames , чтобы предупредить объект о том, что он является внедренным объектом, и активировать соответствующие изменения в пользовательском интерфейсе объектного приложения при подготовке к открытию окна редактирования.

IOleObject::D oVerb автоматически запускает приложение сервера OLE. Если во время выполнения команды возникает ошибка, приложение-объект завершает работу.

Если пользователь вызывает глагол не с помощью выбора команды в меню (например, двойным щелчком или, реже, одним щелчком объекта), контейнер объекта должен передать указатель на структуру Windows MSG , содержащую соответствующее сообщение. Например, если пользователь вызывает команду, дважды щелкнув объект, контейнер должен передать структуру MSG , содержащую WM_LBUTTONDBLCLK, WM_MBUTTONDBLCLK или WM_RBUTTONDBLCLK. Если контейнер не передает сообщение, lpmsg должен иметь значение NULL. Объект должен игнорировать элемент hwnd переданной структуры MSG , но может использовать все остальные члены MSG.

Если контейнер внедрения объекта вызывает IOleObject::D oVerb, указатель сайта клиента (pClientSite), передаваемый в IOleObject::D oVerb , совпадает с указателем сайта внедрения. Если внедренный объект является источником ссылки, указатель, передаваемый в IOleObject::D oVerb , соответствует указателю сайта клиента связывания.

При вызове IOleObject::D oVerb для ссылки OLE он может возвращать OLE_E_CLASSDIFF или MK_CONNECTMANUALLY. Объект link возвращает предыдущую ошибку, когда источник ссылки подвергся определенному преобразованию, когда ссылка была пассивной. Объект link возвращает последнюю ошибку, если источник ссылки находится на сетевом диске, который в настоящее время не подключен к компьютеру вызывающей стороны. Единственный способ подключить ссылку в этих условиях — сначала вызвать IUnknown::QueryInterface, запросить IOleLink, выделить контекст привязки и запустить источник ссылки, вызвав IOleLink::BindToSource.

Контейнерные приложения, которые не поддерживают общую активацию на месте, по-прежнему могут использовать параметры hwndParent и lprcPosRect для поддержки воспроизведения мультимедийных файлов на месте. Контейнеры должны передавать допустимые параметры hwndParent и lprcPosRectв IOleObject::D oVerb.

В некоторых примерах кода передается значение lindex , равное -1, а не ноль. Значение -1 работает, но его следует избегать в пользу нуля. Параметр lindex является зарезервированным параметром, и для обеспечения согласованности корпорация Майкрософт рекомендует назначить нулевое значение всем зарезервированным параметрам.

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

В дополнение к приведенным выше командам, объект может определить в своей структуре OLEVERB дополнительные команды, относящиеся к самому себе. Положительные числа обозначают эти объектные глаголы. Объект должен обрабатывать любой неизвестный положительный номер команды как основной глагол и возвращать OLEOBJ_S_INVALIDVERB вызывающей функции. Объект должен игнорировать глаголы с отрицательными числами, которые он не распознает, и возвращать E_NOTIMPL.

Если выполняемая команда переводит объект в запущенное состояние, следует зарегистрировать объект в таблице выполняющихся объектов (ROT), даже если его серверное приложение не поддерживает связывание. Регистрация важна, так как объект в какой-то момент может служить источником ссылки в контейнере, поддерживающем ссылки на внедрения. Регистрация объекта в ROT позволяет клиенту ссылки получить указатель на объект напрямую, а не проходить через контейнер объекта. Чтобы выполнить регистрацию, вызовите IOleClientSite::GetMoniker , чтобы получить полный моникер объекта, вызовите функцию GetRunningObjectTable , чтобы получить указатель на ROT, а затем вызовите IRunningObjectTable::Register.

Примечание Когда объект выходит из состояния выполнения, не забудьте отменить регистрацию объекта с помощью ROT, вызвав IOleObject::Close. Если документ контейнера объекта переименовывался во время выполнения объекта, следует отозвать регистрацию объекта и повторно зарегистрировать его в ROT, используя его новое имя. Контейнер должен сообщить объекту о новом моникере, вызвав метод IOleObject::SetMoniker или ответив на вызов объекта IOleClientSite::GetMoniker.

При отображении окна в результате IOleObject::D oVerb очень важно, чтобы объект явно вызывал SetForegroundWindow в окне редактирования. Это гарантирует, что окно объекта будет видимым для пользователя, даже если его изначально скрывал другой процесс. Дополнительные сведения см. в разделах SetForegroundWindow и SetActiveWindow.

Требования

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