Método IOleObject::D oVerb (oleidl.h)
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 |
|---|---|
|
iVerb se establece en OLEIVERB_UIACTIVATE o OLEIVERB_INPLACEACTIVATE y el objeto aún no está visible. |
|
El controlador de objetos o el objeto de vínculo no se pueden conectar al origen del vínculo. |
|
Lindex no válido. |
|
El verbo es válido, pero en el estado actual del objeto no puede llevar a cabo la acción correspondiente. |
|
DoVerb se realizó correctamente, pero hwndParent no es válido. |
|
El objeto no admite verbos. |
|
El origen del vínculo está a través de una red que no está conectada a una unidad en este equipo. |
|
El origen del vínculo está a través de una red que no está conectada a una unidad en este equipo. |
|
La clase para el origen del vínculo se ha sometido a una conversión. |
|
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.
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 |