IOleCommandTarget::ExecIOleCommandTarget::Exec*
*Contents  *Index  *Topic Contents

*Previous Topic: IOleCommandTarget
*Next Topic: IOleCommandTarget::QueryStatus

IOleCommandTarget::Exec

HRESULT Exec(
    const GUID *pguidCmdGroup,
    DWORD nCmdID,
    DWORD nCmdExecOpt,
    VARIANTARG *pvaIn,
    VARIANTARG *pvaOut
   );

Executes a specified command or displays help for a command.

pguidCmdGroup
[unique][in] Address of a globally unique identifier (GUID) of the command group; can be NULL to specify the standard group.
nCmdID
[in] Identifier of the command to be executed. This command must belong to the group specified in the pguidCmdGroup parameter.
nCmdExecOpt
[in] Values taken from the OLECMDEXECOPT enumeration, which describes how the object should execute the command.
pvaIn
[unique][in] Address of a VARIANTARG structure containing input arguments. Can be NULL.
pvaOut
[unique][in,out] Address of a VARIANTARG structure to receive command output. Can be NULL.

The list of input and output arguments of a command and how they are packaged is unique to each command. Such information should be documented with the specification of the command group. (See the description of OLECMDID_ZOOM in the OLECMDID enumeration.) In the absence of any specific information, the command is assumed to take no arguments and have no return value.

Notes to Callers

The pguidCmdGroup and nCmdID parameters together uniquely identify the command to invoke. The nCmdExecOpt parameter specifies the exact action to be taken. (For more details, see the OLECMDEXECOPT enumeration.)

Most commands neither take arguments nor return values. For such commands, the caller can pass NULL in pvaIn and pvaOut. For commands that expect one or more input values, the caller can declare and initialize a VARIANTARG structure and pass a pointer to that structure in pvaIn. If the input to the command is a single value, the argument can be stored directly in the VARIANTARG structure and passed to the function. If the command expects multiple arguments, those arguments must be packaged appropriately within the VARIANTARG structure, using one of the supported variant types (such as the IDispatch interface or the SAFEARRAY data type).

If a command returns one or more arguments, the caller is expected to declare a VARIANTARG, initialize it to VT_EMPTY, and pass its address in pvaOut. If the command returns a single value, the object can store that value directly in pvaOut. If the command has multiple output values, it will package those in some way appropriate for the VARIANTARG.

Because pvaIn and pvaOut are both caller-allocated, stack variables are permitted for both the caller and the object receiving the call. For commands that take zero or one argument on input and return zero or one value, no additional memory allocation is necessary. Most of the types supported by VARIANTARG do not require memory allocation. Exceptions include SAFEARRAY and BSTR. For a complete list, see the OLE documentation in the Microsoft® Platform SDK.

Notes to Implementers

A command target must implement this function; E_NOTIMPL is not a valid return value.

Up Top of Page
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.