INFO: The Basics of Exchange Client Extensions

ID: Q199343

The information in this article applies to:

Exchange Development Kit (EDK), versions 5.0, 5.5
Microsoft Exchange Windows 95/98 client, versions 4.0, 5.0
Microsoft Exchange Windows NT client, versions 4.0, 5.0
Microsoft Windows Messaging
Microsoft Outlook 97
Microsoft Outlook 98

SUMMARY

The purpose of this article is to answer some basic questions about Exchange Client Extensions and how they relate to Outlook.

What is a Client Extension?

Why use a Client Extension?

What goes into a Client Extension?

How does the Outlook Client handle an Exchange Client Extension?

Where is more information available?

This subject is very broad, and where appropriate, this article provides pointers to more information about specific areas.

MORE INFORMATION

What is a Client Extension?

A Client Extension is a Dynamic-Link Library (DLL) that provides at least one Extension Object that the Client can load into its process space. These Extension Objects expose COM interfaces, which the Client then uses to call methods that can add new, customized features or that might change the Client's default behavior. Outlook calls these interfaces through the Exchange Client Extension Architecture.

With the original release of the Exchange Client, Microsoft included a very capable extensibility architecture. When the Outlook Client was released, it provided support for the Exchange Client Extension Architecture so as to be compatible with existing Client Extension DLLs. The purpose of Client Extensions has from the first been to present to developers an orderly and predictable means to change the default behavior of the Exchange Client.

Over several releases of Outlook, problems with that support were identified, and many were corrected. Confusion resulted when the term "Outlook Add-In" was used as a synonym for "Exchange Client Extension." Investigation has revealed that they aren't the same thing. The term "Outlook Add-In" refers to COM-based objects, which Outlook will employ for extensibility. The term does not refer to Exchange Client Extensions.

It is very important to note that Outlook supports Client Extensions for backward compatibility purposes. Many companies have invested in development of Exchange Client Extensions, and Microsoft has made every effort to respect that investment. The future direction for customizing the Outlook Client will be more toward the Component Object Model (COM), and away from the DLL model when possible. However, for doing advanced menu handling and catching events in Outlook, the Client Extension will still be the preferred architecture. Therefore, in this article, "the Client" refers to both Microsoft Outlook and Microsoft Exchange Client.

Why Use a Client Extension?

As already noted, developers use Client Extensions to change the default behavior of the Client. The advantages of an Extension include the substantial convenience provided by the Extension Architecture, and the ability to integrate customized features and new behavior directly into the Client, rather than write a separate MAPI application.

Client Extensions can be used to accomplish a wide variety of messaging tasks. These can include at least the following examples:

Add custom commands to Outlook menus.

Add custom buttons to Outlook toolbars.

Pre-process outgoing and incoming messages.

Scan for viruses on message attachments.

Provide transparent e-mail message auditing.

Add custom Property tabs to Outlook Property sheets.

Provide support for custom MAPI Forms.

What Goes Into a Client Extension?

There are three basic pieces to the Client Extension. The Extension Object, the DLL file that implements it, and the registry string value. The registry value, located at the following registry key

HKEY_LOCAL_MACHINE\Software\Microsoft\Exchange\Client\Extensions

informs the Client about the Extension:

The version of Extension object implemented in the DLL (this is always 4.0)

The location of the DLL

The ExchExtEntryPoint ordinal

The list of contexts for which Outlook should install an Extension object

The list of interfaces that the Extension object exposes

The particular mail service that an Extension might use

For example, the following registry value explicitly tells the Client to look for the MyExtension.dll in the root directory of the C: drive, to load the Extension object into all 14 contexts, that 7 interfaces are available, and to load only for the MumblyTwink mail service.


Name:         Value:
-----------   ----------------------------------------------
MyExtension   4.0;C:\MyExtension.dll;1;11111111111111;1111111;"MumblyTwink"

Immediately after it starts up, the Client reads both the Context Map and Interface Map to learn which Contexts interest the Extension and which Interfaces the Extension offers to the Client. The chances are very slim that an Extension will load in all contexts and offer all interfaces, so the example is a bit fanciful. More likely, an Extension will be interested in only a few contexts, and offer only a few interfaces. In that case, the developer would place a 0 at the correct points in each map to instruct the Client not to load and Extension object into that context. Likewise, a 0 in any of the 7 entries in the interface map tells the Client not to query the Extension object or that interface.

To make an extension available to all mail services noted in a MAPI profile, simply omit the last entry in the registry value.

The Name is used to uniquely identify this registry entry from all the others under this key.

So, What's a Context? An Extension Context is simply the means used by the Client to inform an Extension about what the user is doing at the time. Each context has an associated constant name, which describes a general activity.


Context               Map Position   Indicates
-------------         ------------   ---------------------------
EE_CONTEXT_SESSION            1      Logged on to MAPI
EE_CONTEXT_VIEWER             2      Looking at an object(Folder, perhaps)
EE_CONTEXT_REMOTEVIEWER       3      Using Remote Mail feature
EE_CONTEXT_SEARCHVIEWER       4      Using Find feature
EE_CONTEXT_ADDRBOOK           5      Address book is open
EE_CONTEXT_SENDNOTEMESSAGE    6      Composing a Send message
EE_CONTEXT_READNOTEMESSAGE    7      Reading a message
EE_CONTEXT_SENDPOSTMESSAGE    8      Composing a Post message
EE_CONTEXT_READPOSTMESSAGE    9      Reading a Post message
EE_CONTEXT_READREPORTMESSAGE  10     Reading a delivery report, read report
EE_CONTEXT_SENDRESENDMESSAGE  11     Re-sending a returned message
EE_CONTEXT_PROPERTYSHEETS     12     Viewing the properties of an object
EE_CONTEXT_ADVANCEDCRITERIA   13     Using Advanced Search
EE_CONTEXT_TASK               14     The Client is running

Most of these are self-explanatory, with the exception of Task. This context belongs to the Client Program and is available immediately after the Client program starts, even before a logon to MAPI occurs. It stays available until the Client program ends, even after logging off of MAPI. The Client uses this context to call the Install method of an Extension Object whenever necessary.

The context value is passed into a client extension as a parameter through Install Method interfaces exposed by an Extension object.

What is an Interface? It sounds like COM. It is. An Extension Object is a COM object that inherits first from IUnknown. Therefore, it will always implement QueryInterface, AddRef, and Release. The Extension Object part happens by implementing one or more of the following interfaces:


Interface               Map Position
-------------           ------------
IExchExtCommands              1
IExchExtUserEvents            2
IExchExtSessionEvents         3
IExchExtMessageEvents         4
IExchExtAttachedFileEvents    5
IExchExtPropertySheets        6
IExchExtAdvancedCriteria      7
IExchExt                  Not Mapped
IExchExtModeless          Not Mapped
IExchExtModelessCallback  Not Mapped

The interfaces IExchExt, IExchExtModeless, and IExchExtModelessCallback are not included in the interface map of the registry value. The Client calls these at its own discretion. An Extension Object class will always inherit from IExchExt because that interface has the Install method the Client calls to obtain new instances of the Extension Object.

How Does the Outlook Client Handle an Exchange Client Extension?

The first thing the Client does before loading the Extension is to check the sixth field of the registry entry for a mail service requirement. The Client loads the DLL if the service is present in the profile, or if the field is empty. Then the Client obtains a pointer to the ExchEntryPoint function, calls it, and receives an ExchExt object pointer in return.

At this point, the Client tries to load the Extension Object into every context noted in the interface map by calling the Extension's Install method. If the Install method succeeds, the Client then calls QueryInterface for each entry in the interface map, to learn what the Extension Object can do in this context.

When the Client has finished loading the Extension Object, it will keep the Extension Object advised of the context changes, the current context ID, and any events that occur in that context. The notifications occur when the Client calls into the Extension Object through one of the interface pointers returned to the Client during the installation process.

VERY IMPORTANT NOTE: Outlook supports the Exchange Client Extension architecture for backward compatibility purposes, so there are some very particular limitations to the ability of an Extension to directly affect Outlook. For example, from an Extension, it is not possible to add menu items to the context menu that appears with a right-click in a view. To avoid this and other limitations, it is possible to use the Outlook Object Model from within a client extension. Future Knowledge Base articles will address this subject separately.

Where Is More Information Available?

This article has addressed some basic questions about Exchange Client Extensions and how they relate to the Outlook Client. To learn more about Exchange Client Extensions, search for the topic "Extending the Exchange Client" in the Platform SDK documentation.

REFERENCES

"Developing Applications for Microsoft Exchange with C++" by Ben Goetter

MSDN Platform SDK Topic "Extending the Exchange Client"

Additional query words: kbMsg kbXchge kbEDK550 kbEDK500 kbEDK kbOutlook97 kbOutlook98

Keywords : kbEDK kbXchge kbMsg kbOutlook97 kbOutlook98 kbEDK500 kbEDK550 kbfaq
Version : WINDOWS:4.0,5.0,5.5,97
Platform : WINDOWS
Issue type : kbinfo