IMessageFormEx2

4/8/2010

The IMessageFormEx2 interface extends the IMessageFormEx interface with an alternate mechanism for querying Message Forms for supported menu items—using an approach that supports hundreds of menu items.

Methods in Vtable Order

• IUnknown for MAPI methods
• IMessageFormEx methods

Remarks

Since the mechanism used by IMessageFormEx limits the number of possible menu items to 32, IMessageFormEx2 was created to expand that limit by more than ten times.

Like IMessageFormEx::GetMenuCapabilities, IMessageFormEx2::GetMenuCapability is called by the Messaging Application to query a Messaging add-in to determine which menu commands it can process (that is, which form menu commands to enable and which to disable).

A Messaging add-in must implement the IMessageFormEx2 interface in order to add menu capabilities beyond the Standard set of MESSAGEFORMHOST2_CMDBARCAP flags. For information on the Extended set of command bar capability constants, see Message Form Host Command Bar Capability Flags.

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

The new behavior of the Messaging Application (Form Host) is demonstrated in the following code example.

#define MENU_CAPABILITY_MASK 0xfffffff
IForm->GetMenuCapabilites(dwFlags, &dwEnable);  // For Region 0 (pre-Windows Mobile 6) menu items.
...

if (SUCCEEDED(IForm->GetMenuCapabilites(0x10000000, &dwEnable)) && (dwEnable & MENU_CAPABILITY_MASK == MENU_CAPABILITY_MASK))
{
   // Loop through the extend menu capabilites.
   for (i = 1; i < 16; i++)
   {
      IForm->GetMenuCapabilites(dwFlags | (i << 28), &dwEnable);
      ...
   }
}

Requirements

See Also

Reference

IMessageFormEx

Other Resources

MAPI Interfaces
Messaging
Pocket Outlook Object Model (POOM)