Queries the object for the status of one or more commands generated by user interface events.
[input_sync] HRESULT QueryStatus(
const GUID *
pguidCmdGroup, // Pointer to command group
ULONG cCmds, // Number of commands in prgCmds array
OLECMD *prgCmds, // Array of OLECMD structures
OLECMDTEXT *pCmdText // Pointer to structure containing name or status of command
);
Parameters
pguidCmdGroup
[unique][in] 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 pguidCmdGroup.
cCmds
[in] The number of commands in the prgCmds array.
prgCmds
[in,out][size_is(cCmds)] A caller-allocated array of OLECMD structures, where the object receiving the call fills the cmdID field of each command with bits taken from the OLECMDF enumeration, specifying the status of each command.
pCmdText
[unique][in,out] Pointer to the structure in which to return name and/or status information. Can be NULL to indicate that the caller is not interested in such information.
Return Values
S_OK
The command status as any optional strings were returned successfully.
E_POINTER
The prgCmds argument is NULL.
E_UNEXPECTED
An unexpected error occurred.
E_FAIL
An error occurred
OLECMDERR_E_UNKNOWNGROUP
The pguidCmdGroup parameter is non-NULL but does not specify a recognized command group.
Remarks
Callers use IOleCommandTarget::QueryStatus 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 describe the commands of interest from the group specified in pguidCmdGroup, where each structureÆs cmdID is set to a command identifier and the cmdf field is set to zero.
Notes to Implementers
The object receiving the call the fills the cmdf field for each command with bits 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 OLECMDTEXT structure. If the OLECMDFTEXF_NAME flag is specified, then the object should copy the localized name of the command (for example, ôOpenö, ôCopyö, etc.) into the rgwz field of OLECMDTEXT, paying attention to the size specified by the cwBuf field in that same structure.
If the caller specifies OLECMDFTEXTF_STATUS, the object should copy a localized status string for the command into the rgwz field. 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 then 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(s), that it attempted to copy, via the cwActual field.
If the command array contains more than one command, the textual information should be returned for the first command in the command array that the object supports. Typically, this functionality is used to show the status text of a command. Note that the caller can use a either stack or a global variable for rgwz because memory for this parameter is not dynamically allocated.
Because 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. Therefore, E_NOTIMPL is not a valid return value.
See Also