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

Artículo
03/15/2023

Solicita que un objeto realice una acción en respuesta a una acción del usuario final. Las posibles acciones se enumeran para el objeto en IOleObject::EnumVerbs.

Sintaxis

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 asignado al verbo en la estructura OLEVERB devuelta por IOleObject::EnumVerbs.

[in] lpmsg

Puntero a la estructura de MSG que describe el evento (por ejemplo, un doble clic) que invocó el verbo. El autor de la llamada debe pasar la estructura MSG sin modificar, sin intentar interpretar ni modificar los valores de ninguno de los miembros de la estructura.

[in] pActiveSite

Puntero a la interfaz IOleClientSite del sitio de cliente activo del objeto, donde se produjo el evento que invocó el verbo.

[in] lindex

Este parámetro está reservado y debe ser cero.

[in] hwndParent

Identificador de la ventana de documento que contiene el objeto. Esto y lprcPosRect juntos permiten abrir una ventana temporal para un objeto, donde hwndParent es la ventana primaria en la que se va a mostrar la ventana del objeto y lprcPosRect define el área disponible para mostrar la ventana del objeto dentro de ese elemento primario. Una ventana temporal es útil, por ejemplo, para un objeto multimedia que se abre para la reproducción, pero no para su edición.

[in] lprcPosRect

Puntero a la estructura RECT que contiene las coordenadas, en píxeles, que definen el rectángulo delimitador de un objeto en hwndParent. Este y hwndParent juntos permiten abrir objetos multimedia para la reproducción, pero no para su edición.

Valor devuelto

Este método devuelve S_OK cuando funciona correctamente. Otros posibles valores devueltos son los siguientes.

Código devuelto	Descripción
OLE_E_NOT_INPLACEACTIVE	iVerb se establece en OLEIVERB_UIACTIVATE o OLEIVERB_INPLACEACTIVATE y el objeto aún no está visible.
OLE_E_CANT_BINDTOSOURCE	El controlador de objetos o el objeto de vínculo no se pueden conectar al origen del vínculo.
DV_E_LINDEX	Lindex no válido.
OLEOBJ_S_CANNOT_DOVERB_NOW	El verbo es válido, pero en el estado actual del objeto no puede llevar a cabo la acción correspondiente.
OLEOBJ_S_INVALIDHWND	DoVerb se realizó correctamente, pero hwndParent no es válido.
OLEOBJ_E_NOVERBS	El objeto no admite verbos.
OLEOBJ_S_INVALIDVERB	El origen del vínculo está a través de una red que no está conectada a una unidad en este equipo.
MK_E_CONNECT	El origen del vínculo está a través de una red que no está conectada a una unidad en este equipo.
OLE_E_CLASSDIFF	La clase para el origen del vínculo se ha sometido a una conversión.
E_NOTIMPL	El objeto no admite la activación local o no reconoce un número de verbo negativo.

Comentarios

Un "verbo" es una acción que un objeto OLE realiza en respuesta a un mensaje de su contenedor. El contenedor de un objeto o un cliente vinculado al objeto normalmente llama a IOleObject::D oVerb en respuesta a alguna acción del usuario final, como hacer doble clic en el objeto. Las distintas acciones que están disponibles para un objeto determinado se enumeran en una estructura OLEVERB , que el contenedor obtiene mediante una llamada a IOleObject::EnumVerbs. IOleObject::D oVerb coincide con el valor de iVerb con el miembro iVerb de la estructura para determinar qué verbo invocar.

Mediante IOleObject::EnumVerbs, un objeto, en lugar de su contenedor, determina qué verbos (es decir, acciones) admite. OLE 2 define siete verbos que están disponibles, pero no necesariamente útiles, para todos los objetos. Además, cada objeto puede definir verbos adicionales que sean únicos para él. En la tabla siguiente se describen los verbos definidos por OLE.

Verbo	Descripción
OLEIVERB_PRIMARY (0L)	Especifica la acción que se produce cuando un usuario final hace doble clic en el objeto de su contenedor. El objeto, no el contenedor, determina esta acción. Si el objeto admite la activación local, el verbo principal normalmente activa el objeto en contexto.
OLEIVERB_SHOW (-1)	Indica a un objeto que se muestre para su edición o visualización. Se llama para mostrar los objetos recién insertados para la edición inicial y para mostrar los orígenes de vínculos. Normalmente, un alias para algún otro verbo definido por objetos.
OLEIVERB_OPEN (-2)	Indica a un objeto, incluido uno que, de lo contrario, admite la activación local, para abrirse para su edición en una ventana independiente de la de su contenedor. Si el objeto no admite la activación local, este verbo tiene la misma semántica que OLEIVERB_SHOW.
OLEIVERB_HIDE (-3)	Hace que un objeto quite su interfaz de usuario de la vista. Solo se aplica a los objetos que se activan en contexto.
OLEIVERB_UIACTIVATE (-4)	Activa un objeto en su lugar, junto con su conjunto completo de herramientas de interfaz de usuario, incluidos menús, barras de herramientas y su nombre en la barra de título de la ventana contenedora. Si el objeto no admite la activación local, debe devolver E_NOTIMPL.
OLEIVERB_INPLACEACTIVATE (-5)	Activa un objeto en contexto sin mostrar herramientas, como menús y barras de herramientas, que los usuarios finales necesitan cambiar el comportamiento o la apariencia del objeto. Al hacer clic un solo clic en este objeto, se negocia la visualización de sus herramientas de interfaz de usuario con su contenedor. Si el contenedor se rechaza, el objeto permanece activo pero sin sus herramientas mostradas.
OLEIVERB_DISCARDUNDOSTATE (-6)	Se usa para indicar a los objetos que descarten cualquier estado de deshacer que puedan mantenerse sin desactivar el objeto.

Notas a los autores de llamadas

Los contenedores llaman a IOleObject::D oVerb como parte de la inicialización de un objeto recién creado. Antes de realizar la llamada, los contenedores deben llamar primero a IOleObject::SetClientSite para informar al objeto de su ubicación para mostrar e IOleObject::SetHostNames para alertar al objeto de que es un objeto incrustado y desencadenar los cambios adecuados en la interfaz de usuario de la aplicación de objeto como preparación para abrir una ventana de edición.

IOleObject::D oVerb ejecuta automáticamente la aplicación de servidor OLE. Si se produce un error durante la ejecución del verbo, la aplicación de objeto se cierra.

Si un usuario final invoca un verbo por algún medio que no sea seleccionar un comando en un menú (por ejemplo, haciendo doble clic o, más raramente, haciendo clic con un solo clic en un objeto), el contenedor del objeto debe pasar un puntero a una estructura de MSG de Windows que contenga el mensaje adecuado. Por ejemplo, si el usuario final invoca un verbo haciendo doble clic en el objeto , el contenedor debe pasar una estructura MSG que contenga WM_LBUTTONDBLCLK, WM_MBUTTONDBLCLK o WM_RBUTTONDBLCLK. Si el contenedor no pasa ningún mensaje, lpmsg debe establecerse en NULL. El objeto debe omitir el miembro hwnd de la estructura MSG pasada, pero puede usar todos los demás miembros de MSG.

Si el contenedor de inserción del objeto llama a IOleObject::D oVerb, el puntero de sitio cliente (pClientSite) pasado a IOleObject::D oVerb es el mismo que el del sitio de inserción. Si el objeto incrustado es un origen de vínculo, el puntero pasado a IOleObject::D oVerb es el del sitio cliente de vinculación.

Cuando se invoca IOleObject::D oVerb en un vínculo OLE, puede devolver OLE_E_CLASSDIFF o MK_CONNECTMANUALLY. El objeto link devuelve el error anterior cuando el origen del vínculo se ha sometido a algún tipo de conversión mientras el vínculo era pasivo. El objeto de vínculo devuelve el último error cuando el origen del vínculo se encuentra en una unidad de red que no está conectada actualmente al equipo del autor de la llamada. La única manera de conectar un vínculo en estas condiciones es llamar primero a IUnknown::QueryInterface, pedir IOleLink, asignar un contexto de enlace y ejecutar el origen del vínculo mediante una llamada a IOleLink::BindToSource.

Las aplicaciones contenedoras que no admiten la activación local general pueden seguir usando los parámetros hwndParent y lprcPosRect para admitir la reproducción local de archivos multimedia. Los contenedores deben pasar parámetros hwndParent y lprcPosRect válidos a IOleObject::D oVerb.

Algunos ejemplos de código pasan un valor lindex de -1 en lugar de cero. El valor -1 funciona, pero debe evitarse en favor de cero. El parámetro lindex es un parámetro reservado y, por motivos de coherencia, Microsoft recomienda asignar un valor cero a todos los parámetros reservados.

Notas para los implementadores

Además de los verbos anteriores, un objeto puede definir en su estructura OLEVERB verbos adicionales específicos de sí mismos. Los números positivos designan estos verbos específicos del objeto. Un objeto debe tratar cualquier número de verbo positivo desconocido como si fuera el verbo principal y devolver OLEOBJ_S_INVALIDVERB a la función de llamada. El objeto debe omitir verbos con números negativos que no reconoce y devuelve E_NOTIMPL.

Si el verbo que se ejecuta coloca el objeto en estado de ejecución, debe registrar el objeto en la tabla de objetos en ejecución (ROT) incluso si su aplicación de servidor no admite la vinculación. El registro es importante porque el objeto en algún momento puede servir como origen de un vínculo en un contenedor que admite vínculos a incrustaciones. El registro del objeto con ROT permite al cliente de vínculo obtener un puntero al objeto directamente, en lugar de tener que pasar por el contenedor del objeto. Para realizar el registro, llame a IOleClientSite::GetMoniker para obtener el moniker completo del objeto, llame a la función GetRunningObjectTable para obtener un puntero a ROT y, a continuación, llame a IRunningObjectTable::Register.

Nota Cuando el objeto deja el estado en ejecución, recuerde revocar el registro del objeto con rot mediante una llamada a IOleObject::Close. Si se cambia el nombre del documento contenedor del objeto mientras se ejecuta el objeto, debe revocar el registro del objeto y volver a registrarlo con el ROT, con su nuevo nombre. El contenedor debe informar al objeto de su nuevo moniker llamando a IOleObject::SetMoniker o respondiendo a la llamada del objeto IOleClientSite::GetMoniker.

Cuando se muestra una ventana como resultado de IOleObject::D oVerb, es muy importante que el objeto llame explícitamente a SetForegroundWindow en su ventana de edición. Esto garantiza que la ventana del objeto será visible para el usuario aunque otro proceso lo oculte originalmente. Para obtener más información, vea SetForegroundWindow y SetActiveWindow.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 2000 Professional [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows 2000 Server [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	oleidl.h