IOleCommandTarget::Exec

Executes a specified command or displays help for a command.

HRESULT Exec(

const GUID *pguidCmdGroup,	// Pointer to command group
DWORD nCmdID,	// Identifier of command to execute
DWORD nCmdExecOpt,	// Options for executing the command
VARIANTARG *pvaIn,	// Input arguments
VARIANTARG *pvaOut	// Pointer to output return values
);

Parameters

pguidCmdGroup

[unique][in] Unique identifier of the command group; can be NULL to specify the standard group. The command passed in nCmdID must belong to this group.

nCmdID

[in] The command to execute, which must be in the group specified with pguidCmdGroup.

nCmdExecOpt

[in] One or more values from the OLECMDEXECOPT enumeration describing how the object should execute the command.

pvaIn

[unique][in] Pointer to a VARIANTARG containing input arguments. Can be NULL.

pvaOut

[unique][in,out] Pointer to a VARIANTARG to receive the output return values. Can be NULL.

Return Values

S_OK

The command was executed successfully.

E_UNEXPECTED

An unexpected error occurred.

E_FAIL

An error occurred

OLECMDERR_E_UNKNOWNGROUP

pguidCmdGroup is non-NULL but does not specify a recognized command group.

OLECMDERR_E_NOTSUPPORTED

The nCmdID argument is not recognized as a valid command in the group identified with pguidCmdGroup.

OLECMDERR_DISABLED

The command identified with nCmdID is currently disabled and cannot be executed.

OLECMDERR_NOHELP

The caller has asked for help on the command identified by nCmdID but no help is available.

OLECMDERR_CANCELED

The user canceled the execution of the action.

Remarks

The list of in and out 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 Zoom command later in this section). 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 arguments together uniquely identify the command to invoke. The nCmdExecOpt parameter specifies the exact action to take (see the OLECMDEXECOPT enumeration for more details).

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

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 then the object can store that value directly in pvaOut. If the command has multiple output values then it will package those in some way appropriate for the VARIANTARG.

Because pvaIn and pvOut 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 OLE documentation in the Win32 SDK.

Notes to Implementers

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

See Also

OLECMDEXECOPT