Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

IOleCommandTarget::QueryStatus method

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

Syntax


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

Parameters

pguidCmdGroup [in]

The 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 [in, out]

A pointer to an OLECMDTEXT structure in which to return name and/or status information of a single command. This parameter can be NULL to indicate that the caller does not need this information.

Return value

This method returns S_OK on success. Other possible return values include the following.

Return codeDescription
E_FAIL

The operation failed.

E_UNEXPECTED

An unexpected error has occurred.

E_POINTER

The prgCmds argument is NULL.

OLECMDERR_E_UNKNOWNGROUP

The pguidCmdGroup parameter is not NULL but does not specify a recognized command group.

 

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 member is set to zero.

Notes to Implementers

The object receiving the call the 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 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 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, 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.

Remarks

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

Requirements

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

DocObj.h

IDL

DocObj.Idl

IID

IID_IOleCommandTarget is defined as b722bccb-4e68-101b-a2bc-00aa00404770

See also

IOleCommandTarget
OLECMD
OLECMDF
OLECMDTEXT

 

 

Community Additions

Show:
© 2014 Microsoft. All rights reserved.