IOleCommandTarget::Exec, méthode (docobj.h)

  • Article

Exécute la commande spécifiée ou affiche l’aide pour la commande.

Syntaxe

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

Paramètres

[in] pguidCmdGroup

Identificateur unique du groupe de commandes ; peut être NULL pour spécifier le groupe standard.

[in] nCmdID

Commande à exécuter. Cette commande doit appartenir au groupe spécifié avec pguidCmdGroup.

[in] nCmdexecopt

Spécifie la façon dont l'objet doit exécuter la commande. Les valeurs possibles proviennent des énumérations OLECMDEXECOPT et OLECMDID_WINDOWSTATE_FLAG .

[in] pvaIn

Pointeur vers une structure VARIANTARG contenant des arguments d’entrée. Ce paramètre peut être NULL.

[in, out] pvaOut

Pointeur vers une structure VARIANTARG pour recevoir la sortie de commande. Ce paramètre peut être NULL.

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
OLECMDERR_E_UNKNOWNGROUP
 Le paramètre pguidCmdGroup n’est pas NULL , mais ne spécifie pas de groupe de commandes reconnu.
OLECMDERR_E_NOTSUPPORTED
 Le paramètre nCmdID n’est pas une commande valide dans le groupe identifié par pguidCmdGroup.
OLECMDERR_E_DISABLED
 La commande identifiée par nCmdID est actuellement désactivée et ne peut pas être exécutée.
OLECMDERR_E_NOHELP
 L’appelant a demandé de l’aide sur la commande identifiée par nCmdID, mais aucune aide n’est disponible.
OLECMDERR_E_CANCELED
 Utilisateur a annulé l'exécution de la commande.

Notes

La liste des arguments d’entrée et de sortie d’une commande et la façon dont ils sont empaquetés sont propres à chaque commande. Ces informations doivent être documentées avec la spécification du groupe de commandes. (Consultez la description de OLECMDID_ZOOM dans l’énumération OLECMDID .) En l’absence d’informations spécifiques, la commande est supposée ne prendre aucun argument et n’avoir aucune valeur de retour.

Remarques aux appelants

Les paramètres pguidCmdGroup et nCmdID identifient de manière unique la commande à appeler. Le paramètre nCmdExecOpt spécifie l’action exacte à effectuer. (Pour plus d’informations, consultez l’énumération OLECMDEXECOPT .)

La plupart des commandes ne prennent ni arguments ni valeurs de retour. Pour ces commandes, l’appelant peut passer NULL dans pvaIn et pvaOut. Pour les commandes qui attendent une ou plusieurs valeurs d’entrée, l’appelant peut déclarer et initialiser une variable VARIANTARG et passer un pointeur vers cette variable dans pvaIn. Si l’entrée de la commande est une valeur unique, l’argument peut être stocké directement dans la structure VARIANTARG et transmis à la fonction . Si la commande attend plusieurs arguments, ces arguments doivent être empaquetés de manière appropriée dans variantARG, à l’aide de l’un des types pris en charge (par exemple , IDispatch ou SAFEARRAY).

Si une commande retourne un ou plusieurs arguments, l’appelant est censé déclarer un VARIANTARG, l’initialiser pour VT_EMPTY et passer son adresse dans pvaOut. Si la commande retourne une valeur unique, l’objet peut stocker cette valeur directement dans pvaOut. Si la commande a plusieurs valeurs de sortie, elle empaquetera celles-ci d’une manière appropriée pour variantARG.

Étant donné que pvaIn et pvOut sont tous deux alloués par l’appelant, les variables de pile sont autorisées pour l’appelant et l’objet recevant l’appel. Pour les commandes qui prennent zéro ou un argument en entrée et retournent zéro ou une valeur, aucune allocation de mémoire supplémentaire n’est nécessaire. La plupart des types pris en charge par VARIANTARG ne nécessitent pas d’allocation de mémoire. Les exceptions incluent SAFEARRAY et BSTR.

Remarques aux implémenteurs

Une cible de commande doit implémenter cette fonction ; E_NOTIMPL n’est pas une valeur de retour valide.

Spécifications

   
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 docobj.h

Voir aussi

IOleCommandTarget

OLECMDEXECOPT