Extending the WAB Toolbar and Context Menu Actions

  • Article

New applications should not use this set of interfaces. These interfaces exist for backward compatibility with legacy applications. These interfaces will be unavailable in the future.

Note

In Windows Vista, Windows Contacts replaces Windows Address Book (WAB). For more information about this new mechanism for storing and retrieving contact information, see Windows Contacts.

 

Clients wishing to extend the WAB's set of "Actions" on contacts (such as "Send Mail") can do so by implementing the IContextMenu Interface and the IWABExtInit interfaces and then registering them with the WAB.

Registering Your Context Menu Extension CLSID

Register your extension's DLL CLSID in the registry.

HKEY_CLASSES_ROOT
   CLSID

Then register that CLSID under the following WAB registry key.

HKEY_LOCAL_MACHINE
   Software
      Microsoft
         WAB
            WAB4
               ExtContext

Create a String Key Value under this key whose name is the full CLSID identifying your IContextMenu Interface implementation. The Value data part of the entry will be ignored.

Initializing the Context Menu

The WAB calls CoCreateInstance with your registered CLSID and requests an IContextMenu Interface object. It then calls IUnknown::QueryInterface on the IContextMenu Interface object to get the IWABExtInit interface.

Prior to calling IContextMenu::QueryContextMenu Method, the WAB calls Initialize and passes a pointer to a WABEXTDISPLAY structure. You can determine if this is a precursor to a context menu extension or a property sheet extension by looking at the ulFlags member of the WABEXTDISPLAY structure. If ulFlags contains the WAB_CONTEXT_ADRLIST flag, WABEXTDISPLAY is a precursor to an IContextMenu Interface operation. The lpv member contains a pointer to an ADRLIST whose contents correspond to the properties of all the selected items on which this Context Menu action is being performed. Each entry in the ADRLIST contains information about a selected item in the WAB user interface (UI).

If you want to make sure that the data passed into Initialize stays valid and consistent until the WAB calls IContextMenu::InvokeCommand Method, call IUnknown::AddRef on the lpPropObj member of WABEXTDISPLAY. If you do not call IUnknown::AddRef on lpPropObj at the time Initialize is called, the data may not stay valid when IContextMenu::InvokeCommand Method is called. If you do call IUnknown::AddRef, remember to call IUnknown::Release when you have finished to prevent memory leaks.

Populating the Context Menu and the WAB Toolbar

Use your implementation of IContextMenu::QueryContextMenu Method to populate the passed menu with your entry. At this point, you have information about the items the user has selected from the ADRLIST stored in lpv. Use that information to decide whether you want to add or disable any of your menu items.

When the user selects your menu item, the WAB calls IContextMenu::InvokeCommand Method.

The WAB uses your IContextMenu Interface implementation to populate its Tools menu, all of its context menus, and the Toolbar|Actions menu item.

If the user right-clicks a Lightweight Directory Access Protocol (LDAP) search result in the WAB, the WAB creates an LDAP URL for the selected LDAP entry and passes this LDAP URL to the Context Menu extensions. This gives the context menu extensions additional information about the selected entry. In some cases, the context menu extensions can retrieve further information about the selected entry by looking up the LDAP URL. The LDAP URL is passed to the context extension by adding the WAB_DISPLAY_LDAPURL flag to ulFlags and setting lpsz to the LDAP URL.

Extending the WAB Property Sheets