IOleCommandTarget::QueryStatus

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 commands
  OLECMDTEXT *pCmdText  // Pointer to 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] A caller-allocated array of OLECMD structures that indicate 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] Pointer to 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.

Return Values

This method supports the standard return values E_FAIL and E_UNEXPECTED, as well as the following:

S_OK: The command status as any optional strings were returned successfully.
E_POINTER: The prgCmds argument is NULL.
OLECMDERR_E_UNKNOWNGROUP: The pguidCmdGroup parameter is not 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 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 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 sets the OLECMDFTEXTF_STATUS flag, the object should instead write 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 that it attempted to copy in the cwActual member of the OLECMDTEXT structure.

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

QuickInfo

  Windows NT: Use version 5.0 or later.
  Windows: Unsupported.
  Windows CE: Unsupported.
  Header: Declared in docobj.h.