IOleCommandTarget::QueryStatusIOleCommandTarget::QueryStatus*
*Contents  *Index  *Topic Contents

*Previous Topic: IOleCommandTarget::Exec
*Next Topic: IOleDocument

IOleCommandTarget::QueryStatus

[input_sync] HRESULT QueryStatus(
    const GUID *pguidCmdGroup,
    ULONG cCmds,
    OLECMD *prgCmds,
    OLECMDTEXT *pCmdText
   );

Queries the object for the status of one or more commands generated by user interface events.

pguidCmdGroup
[unique][in] Globally unique identifier of the command group; can be NULL to specify the standard group. All the commands that are passed in the prgCmds array must belong to the group specified by this parameter.
cCmds
[in] Number of commands in the prgCmds array.
prgCmds
[in,out] Caller-allocated array of OLECMD structures that indicates the commands for which the caller needs status information. This method fills the cmdf member of each structure with values taken from the OLECMDF enumeration.
pCmdText
[unique][in,out] Address of an OLECMDTEXT structure in which to return name and/or status information of a single command. Can be NULL to indicate that the caller does not need this information.

Callers use this method to determine which commands are supported by a target object. The caller can then disable unavailable commands that would otherwise be routed to the object. The caller can also use this method to get the name or status of a single command.

Notes to Callers

The caller passes an array of OLECMD structures in prgCmds that describes the commands of interest from the group specified in pguidCmdGroup, where each structure's cmdID member is set to a command identifier and the cmdf member is set to zero.

Notes to Implementers

The object receiving the call fills the cmdf member for each command with values taken from the OLECMDF enumeration to describe the status of each command.

The called object should first mark the command as described above. Then, if the command is supported (OLECMDF_SUPPORTED), the object should check the OLECMDTEXTF_ flags in the cmdtextf member of pCmdText. If the OLECMDTEXTF_NAME flag is specified, the object should copy the localized name of the command (for example, "Open", "Copy", and so on) into the rgwz member of pCmdText. Attention should be paid to the size specified by the cwBuf member of pCmdText.

If the caller sets the OLECMDTEXTF_STATUS flag, the object should instead write a localized status string for the command into the rgwz member. The status string is typically contextual and depends on the state of the command—enabled/disabled, for example. If the buffer is not big enough, the object should zero-terminate the buffer. Whether the buffer is big enough or not, the object must return the total actual size of the string that it attempted to copy in the cwActual member of pCmdText.

If the command array contains more than one command, the textual information should be returned for the first command in the array that the object supports. Typically, this functionality is used to show the status text of a command. The caller can use either a stack or a global variable for rgwz, because memory for this parameter is not dynamically allocated.

Because IOleCommandTarget::QueryStatus is defined with the [input_sync] attribute, the implementing object cannot yield or make another non-input_sync RPC call while executing it.

A command target must implement this function; E_NOTIMPL is not an acceptable return value.

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