Platform SDK: Exchange Server

IExchExtCommands::InstallCommands

Enables an extension object to install its menu commands and toolbar command buttons into a Microsoft Exchange window.

Quick Info

See IExchExtCommands : IUnknown.

HRESULT InstallCommands(
  LPEXCHEXTCALLBACK lpeecb,              
  HWND hwnd,                             
  HMENU hmenu; UINT FAR * lpcmdidBase,   
  LPTBENTRY lptbeArray,                  
  UINT ctbe,                             
  ULONG ulFlags                          
);
 

Parameters

lpeecb
[in] Pointer to an IExchExtCallback interface.
hwnd
[in] Handle of the top-level Microsoft Exchange window.
hmenu
[in] Microsoft Exchange menu handle.
lpcmdidBase
[in, out] Pointer to the first command identifier the extension object can use. This is also the command identifier for a menu item or toolbar button.
lptbeArray
[in] Pointer to an array of toolbars.
ctbe
[in] Count of toolbars in the lptbeArray parameter.
ulFlags
Reserved; must be zero.

The following members are used with the TBENTRY structure, which is defined in the EXCHEXT.H header file:

hwnd
Input member indicating the window handle of the toolbar.
tbid
Input member indicating the toolbar identifier. A toolbar identifier distinguishes between multiple toolbars, such as the standard toolbar and the format toolbar. Currently, only the standard toolbar is defined with the EETB_STANDARD value identifier.
ulFlags
Reserved; must be zero.
itbbBase
Input-output member indicating the index of the extension’s first toolbar button in the set of available buttons.

Return Values

S_OK
No error occurred.

Remarks

Microsoft Exchange calls the IExchExtCommands::InstallCommands method to enable an extension object to install its menu commands and toolbar command buttons into a Microsoft Exchange window. Microsoft Exchange invokes InstallCommands before a top level Microsoft Exchange window, such as the Viewer, is made visible.

To prevent identifier collisions, the lpcmdidBase parameter points to the first identifier the extension object can use for a command identifier. The extension must update the contents of the lpcmdidBase parameter, so that on return it contains the first identifier the next extension can use. The lptbeArray parameter contains a list of toolbars with the number of toolbars in the ctbe parameter.

To prevent identifier collisions, the itbbBase parameter contains the index of the extension’s first toolbar button in the set of available buttons. This index is not the same as the position of the extension’s first button displayed in the toolbar.

The extension object must use the Windows API to add menus, popup menus, and top-level menus. Windows 95 toolbar messages are used on all platforms to register and add toolbar buttons. If an extension object elects to place its toolbar buttons on the toolbar by default, the extension object must add them to the toolbar’s set of available buttons when InstallCommands is called and then position those buttons on the toolbar when the IExchExtCommands::ResetToolbar method is called.

If an error is returned, Microsoft Exchange will not try to install another extension and will fail to create the window associated with the context.