IOleObject ::D oVerb, méthode (oleidl.h)

Article
03/04/2024

Demande qu'un objet exécute une action en réponse à une action de l'utilisateur final. Les actions possibles sont énumérées pour l’objet dans IOleObject ::EnumVerbs.

Syntaxe

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

Paramètres

[in] iVerb

Nombre attribué au verbe dans la structure OLEVERB retournée par IOleObject ::EnumVerbs.

[in] lpmsg

Pointeur vers la structure MSG décrivant l’événement (par exemple, un double-clic) qui a appelé le verbe. L’appelant doit passer la structure MSG sans modification, sans tenter d’interpréter ou de modifier les valeurs des membres de la structure.

[in] pActiveSite

Pointeur vers l’interface IOleClientSite sur le site client actif de l’objet, où l’événement qui a appelé le verbe s’est produit.

[in] lindex

Ce paramètre est réservé et doit être égal à zéro.

[in] hwndParent

Handle de la fenêtre de document contenant l'objet. Ceci et lprcPosRect permettent d’ouvrir une fenêtre temporaire pour un objet, où hwndParent est la fenêtre parente dans laquelle la fenêtre de l’objet doit être affichée, et lprcPosRect définit la zone disponible pour afficher la fenêtre d’objet dans ce parent. Une fenêtre temporaire est utile, par exemple, pour un objet multimédia qui s’ouvre pour la lecture, mais pas pour la modification.

[in] lprcPosRect

Pointeur vers la structure RECT contenant les coordonnées, en pixels, qui définissent le rectangle englobant d’un objet dans hwndParent. Cette fonctionnalité et hwndParent permettent d’ouvrir des objets multimédias pour la lecture, mais pas pour la modification.

Valeur retournée

Cette méthode retourne S_OK en cas de réussite. Les autres valeurs de retour possibles sont les suivantes.

Code de retour	Description
OLE_E_NOT_INPLACEACTIVE	iVerb défini sur OLEIVERB_UIACTIVATE ou OLEIVERB_INPLACEACTIVATE et l’objet n’est pas déjà visible.
OLE_E_CANT_BINDTOSOURCE	Le gestionnaire d’objets ou l’objet de lien ne peut pas se connecter à la source du lien.
DV_E_LINDEX	Lindex non valide.
OLEOBJ_S_CANNOT_DOVERB_NOW	Le verbe est valide, mais dans l’état actuel de l’objet, il ne peut pas effectuer l’action correspondante.
OLEOBJ_S_INVALIDHWND	DoVerb a réussi, mais hwndParent n’est pas valide.
OLEOBJ_E_NOVERBS	L’objet ne prend pas en charge les verbes.
OLEOBJ_S_INVALIDVERB	La source de lien se trouve sur un réseau qui n’est pas connecté à un lecteur sur cet ordinateur.
MK_E_CONNECT	La source de lien se trouve sur un réseau qui n’est pas connecté à un lecteur sur cet ordinateur.
OLE_E_CLASSDIFF	La classe pour la source de lien a subi une conversion.
E_NOTIMPL	L’objet ne prend pas en charge l’activation sur place ou ne reconnaît pas un nombre de verbe négatif.

Remarques

Un « verbe » est une action qu’un objet OLE prend en réponse à un message de son conteneur. Le conteneur d’un objet, ou un client lié à l’objet, appelle normalement IOleObject ::D oVerb en réponse à une action de l’utilisateur final, telle que le double-clic sur l’objet. Les différentes actions disponibles pour un objet donné sont énumérées dans une structure OLEVERB , que le conteneur obtient en appelant IOleObject ::EnumVerbs. IOleObject ::D oVerb correspond à la valeur d’iVerb par rapport au membre iVerb de la structure pour déterminer le verbe à appeler.

Grâce à IOleObject ::EnumVerbs, un objet, plutôt que son conteneur, détermine les verbes (c’est-à-dire les actions) qu’il prend en charge. OLE 2 définit sept verbes disponibles, mais pas nécessairement utiles, pour tous les objets. En outre, chaque objet peut définir des verbes supplémentaires qui lui sont propres. Le tableau suivant décrit les verbes définis par OLE.

Verbe	Description
OLEIVERB_PRIMARY (0L)	Spécifie l’action qui se produit lorsqu’un utilisateur final double-clique sur l’objet dans son conteneur. L’objet, et non le conteneur, détermine cette action. Si l’objet prend en charge l’activation sur place, le verbe principal active généralement l’objet sur place.
OLEIVERB_SHOW (-1)	Indique à un objet de s’afficher pour la modification ou l’affichage. Appelé pour afficher les objets nouvellement insérés pour la modification initiale et pour afficher les sources de lien. Généralement un alias pour un autre verbe défini par un objet.
OLEIVERB_OPEN (-2)	Demande à un objet, y compris un autre qui prend en charge l’activation sur place, de s’ouvrir pour la modification dans une fenêtre distincte de celle de son conteneur. Si l’objet ne prend pas en charge l’activation sur place, ce verbe a la même sémantique que OLEIVERB_SHOW.
OLEIVERB_HIDE (-3)	Provoque la suppression de l’interface utilisateur d’un objet de la vue. S’applique uniquement aux objets activés sur place.
OLEIVERB_UIACTIVATE (-4)	Active un objet en place, ainsi que son ensemble complet d’outils d’interface utilisateur, y compris les menus, les barres d’outils et son nom dans la barre de titre de la fenêtre conteneur. Si l’objet ne prend pas en charge l’activation sur place, il doit retourner E_NOTIMPL.
OLEIVERB_INPLACEACTIVATE (-5)	Active un objet en place sans afficher d’outils, tels que des menus et des barres d’outils, que les utilisateurs finaux doivent modifier le comportement ou l’apparence de l’objet. Le simple clic sur un tel objet l’amène à négocier l’affichage de ses outils d’interface utilisateur avec son conteneur. Si le conteneur refuse, l’objet reste actif, mais sans ses outils affichés.
OLEIVERB_DISCARDUNDOSTATE (-6)	Utilisé pour indiquer aux objets d’ignorer tout état d’annulation qu’ils peuvent conserver sans désactiver l’objet.

Notes aux appelants

Les conteneurs appellent IOleObject ::D oVerb dans le cadre de l’initialisation d’un objet nouvellement créé. Avant d’effectuer l’appel, les conteneurs doivent d’abord appeler IOleObject ::SetClientSite pour informer l’objet de son emplacement d’affichage et IOleObject ::SetHostNames pour avertir l’objet qu’il s’agit d’un objet incorporé et déclencher les modifications appropriées à l’interface utilisateur de l’application objet en vue de l’ouverture d’une fenêtre de modification.

IOleObject ::D oVerb exécute automatiquement l’application serveur OLE. Si une erreur se produit pendant l’exécution du verbe, l’application d’objet est arrêtée.

Si un utilisateur final appelle un verbe par d’autres moyens que la sélection d’une commande dans un menu (par exemple, en double-cliquant ou, plus rarement, en cliquant un seul clic sur un objet), le conteneur de l’objet doit passer un pointeur vers une structure MSG Windows contenant le message approprié. Par exemple, si l’utilisateur final appelle un verbe en double-cliquant sur l’objet, le conteneur doit passer une structure MSG contenant WM_LBUTTONDBLCLK, WM_MBUTTONDBLCLK ou WM_RBUTTONDBLCLK. Si le conteneur ne transmet aucun message, lpmsg doit être défini sur NULL. L’objet doit ignorer le membre hwnd de la structure MSG passée, mais peut utiliser tous les autres membres MSG.

Si le conteneur d’incorporation de l’objet appelle IOleObject ::D oVerb, le pointeur de site client (pClientSite) passé à IOleObject ::D oVerb est identique à celui du site d’incorporation. Si l’objet incorporé est une source de lien, le pointeur passé à IOleObject ::D oVerb est celui du site client du client de liaison.

Lorsque IOleObject ::D oVerb est appelé sur un lien OLE, il peut retourner OLE_E_CLASSDIFF ou MK_CONNECTMANUALLY. L’objet link retourne l’erreur précédente lorsque la source de lien a été soumise à une sorte de conversion alors que le lien était passif. L’objet link retourne cette dernière erreur lorsque la source de lien se trouve sur un lecteur réseau qui n’est pas actuellement connecté à l’ordinateur de l’appelant. La seule façon de connecter un lien dans ces conditions est d’abord d’appeler IUnknown ::QueryInterface, de demander IOleLink, d’allouer un contexte de liaison et d’exécuter la source de lien en appelant IOleLink ::BindToSource.

Les applications conteneur qui ne prennent pas en charge l’activation générale sur place peuvent toujours utiliser les paramètres hwndParent et lprcPosRect pour prendre en charge la lecture sur place des fichiers multimédias. Les conteneurs doivent passer les paramètres hwndParent et lprcPosRect valides à IOleObject ::D oVerb.

Certains exemples de code passent une valeur lindex de -1 au lieu de zéro. La valeur -1 fonctionne, mais doit être évitée au profit de zéro. Le paramètre lindex est un paramètre réservé et, pour des raisons de cohérence, Microsoft recommande d’affecter une valeur zéro à tous les paramètres réservés.

Notes aux implémenteurs

En plus des verbes ci-dessus, un objet peut définir dans sa structure OLEVERB des verbes supplémentaires qui sont spécifiques à lui-même. Les nombres positifs désignent ces verbes spécifiques à l’objet. Un objet doit traiter tout nombre de verbes positif inconnu comme s’il s’agissait du verbe principal et retourner OLEOBJ_S_INVALIDVERB à la fonction appelante. L’objet doit ignorer les verbes avec des nombres négatifs qu’il ne reconnaît pas et retourner E_NOTIMPL.

Si le verbe en cours d’exécution place l’objet dans l’état d’exécution, vous devez inscrire l’objet dans la table d’objets en cours d’exécution (ROT) même si son application serveur ne prend pas en charge la liaison. L’inscription est importante, car l’objet à un moment donné peut servir de source d’un lien dans un conteneur qui prend en charge les liens vers les incorporations. L’inscription de l’objet auprès du rot permet au client de liaison d’obtenir directement un pointeur vers l’objet, au lieu d’avoir à passer par le conteneur de l’objet. Pour effectuer l’inscription, appelez IOleClientSite ::GetMoniker pour obtenir le moniker complet de l’objet, appelez la fonction GetRunningObjectTable pour obtenir un pointeur vers le ROT, puis appelez IRunningObjectTable ::Register.

Note Lorsque l’objet quitte l’état d’exécution, n’oubliez pas de révoquer l’inscription de l’objet auprès du ROT en appelant IOleObject ::Close. Si le document conteneur de l’objet est renommé pendant l’exécution de l’objet, vous devez révoquer l’inscription de l’objet et le réinscrire auprès du ROT, en utilisant son nouveau nom. Le conteneur doit informer l’objet de son nouveau moniker en appelant IOleObject ::SetMoniker ou en répondant à l’appel de l’objet IOleClientSite ::GetMoniker.

Lorsque vous affichez une fenêtre à la suite de IOleObject ::D oVerb, il est très important que l’objet appelle explicitement SetForegroundWindow dans sa fenêtre d’édition. Cela garantit que la fenêtre de l’objet sera visible par l’utilisateur même si un autre processus l’a masquée à l’origine. Pour plus d’informations, consultez SetForegroundWindow et SetActiveWindow.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 2000 Professionnel [applications de bureau uniquement]
Serveur minimal pris en charge	Windows 2000 Server [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	oleidl.h