IMessageFormEx::GetMenuCapabilities

4/8/2010

The GetMenuCapabilities method is called by the Messaging Application to query the add-in and determine which menu commands it can process (that is, which Message form menu commands to enable and which to disable).

Syntax

HRESULT GetMenuCapabilities (
  DWORD dwFlags,
  DWORD * pdwEnable
);

Parameters

• dwFlags
  [in] Bitmask specifying the entire set of possible command capabilities.

  For information on all of the possible constants that can be combined to create dwFlags and pdwEnable (each constant represents one menu item that can appear on the menu bar) see Message Form Host Command Bar Capability Flags.

• pdwEnable
  [out] Reference to another bitmask that specifies the set of menu capabilities that the add-in supports.

  For information on all of the possible constants that can be combined to create dwFlags and pdwEnable (each constant represents one menu item that can appear on the menu bar) see Message Form Host Command Bar Capability Flags.

Return Value

This method returns the standard values E_INVALIDARG, E_OUTOFMEMORY, E_UNEXPECTED, and E_FAIL, as well as the following:

• S_OK
  Indicates success.

New Behavior for GetMenuCapabilities

When querying Message forms based on IMessageFormEx2 with IMessageFormEx::GetMenuCapabilities, the behavior of the dwFlags parameter differs from that used for Message forms created using IMessageFormEx. The changes are as follows:

• The top four bits of dwFlags become "Region" bits, and the remaining 28 bits are treated as the "Menu Capability" bits.
• This approach provides 16 x 28 = 448 different Menu Capabilities (IMessageFormEx supports a maximum of 32).
• The extended set of command bar capabilities introduced in Windows Mobile 6.5 are associated with Region 1. For a listing of the extended capabilities, see The Extended Set of Command Bar Capability Constants section in Message Form Host Command Bar Capability Flags.
• The capabilities in Region 1 are named as MESSAGEFORMHOST2_CMDBARCAP2_xxx, and in Region 2 as MESSAGEFORMHOST2_CMDBARCAP3_xxx, etc.

For backward compatibility, the way to determine whether a Message Form supports the extended menu capabilities is as follows:

• When dwFlags has any region bits set, but does not have any menu item bits set—IMessageFormEx::GetMenuCapabilities runs in an alternate mode known as Detection Mode.
• In Detection Mode, IMessageFormEx::GetMenuCapabilities returns (in the *pdwEnable out parameter) a bitmask with all of the Menu Capability bits set to one if extended capability is supported, all bits set to zero if not.

For example, the call GetMenuCapabilites(0x10000000, &dwEnable) returns 0x1fffffff if the Message Form supports the extended menu capabilities, and 0x10000000 if it does not.

Remarks

The Messaging Application calls the Message Form with GetMenuCapabilities passing in a list of all the menu items that can possibly appear in the menu. This list is passed in the dwFlags parameter and is a bitmask created by combining zero or more Message Form Host Command Bar Capability Flags using the bitwise OR. For example, use MESSAGEFORMHOST2_CMDBARCAP_CUT | MESSAGEFORMHOST2_CMDBARCAP_PASTE to include both the Cut and Paste menu commands. GetMenuCapabilities returns a second list that contains just those menu items that the add-in supports. The menu items that appear in the input list, but which are absent in the output list, appear grayed-out in the add-in's menu.

Requirements

See Also

Reference

IMessageFormEx
IMessageFormEx2
IMessageFormEx2::GetMenuCapability

Other Resources

Messaging