Article ID: 286408 - View products that this article applies to.
This article was previously published under Q286408
Important The white paper in this article was originally written when Microsoft Outlook 98 was released and has not been updated to reflect newer information that may apply to later versions of Outlook. Additionally, the list of additional resources provided at the end of the white paper has not been updated and may be out of date. This article will not be updated to correct outdated or incorrect misinformation.
This article contains the text of the "Microsoft Outlook and Exchange Client Extensions" white paper, dated March 1998, which was previously available on the MSDN Web site.
IntroductionMicrosoft Outlook is Microsoft Office's premier messaging and collaboration client for the Internet and Microsoft Exchange Server.
Outlook helps users communicate with others through e-mail, telephone, group scheduling, and real-time Microsoft NetMeeting conferencing software. It allows users to share information with others via Internet connectivity, Microsoft Exchange Server, and electronic forms, and as a component of customized collaborative solutions. Outlook also integrates and organizes all this communication and shared information in one application.
The ability of developers to extend the Outlook application greatly enhances its usefulness. Adding custom features, overriding default behaviors, using existing Outlook features, and integrating existing Exchange client extensions make it possible to fully customize the already fabulous potential of Outlook.
This article will provide you with a brief introduction to the Messaging Application Programming Interface (MAPI) and a high-level understanding of its role in scenarios that include Microsoft Exchange Server. Following an explanation of the Exchange and Outlook clients is a discussion of client extensions and information about the hosting of Exchange client extensions by Outlook.
Helpful, but not required to comprehend this article, is an intermediate-level knowledge of C++ object-oriented programming techniques, Component Object Model (COM), and the Microsoft Win32 application programming interface (API). Although an introduction to MAPI is included, it is helpful if you already have some messaging-development experience.
To create a client extension, you should thoroughly understand and be able to implement the Microsoft Exchange IExchExt extensibility interfaces. You should have access to reference material for C++ object-oriented programming techniques, COM, and MAPI. To write an extension for Outlook, you should have a complete understanding of the Outlook object model.
Background InformationAn explanation of Exchange client extensions must begin with a brief introduction to MAPI, and how it interacts with the Exchange Server.
MAPI is not just a library of functions, but a specification for an entire messaging subsystem and all its interacting components. MAPI is designed to fulfill three principle requirements:
The extended MAPI specification includes definitions of various external components, descriptions of what they do, and a list of the interfaces they expose. The interfaces between components are not APIs, but COM interfaces. COM components are bound together to form applications and can be extended to develop custom-application extensions. All MAPI components use or implement MAPI objects, and all MAPI objects are COM objects.
MAPI is available on all Microsoft Windows-based desktops. The Windows Messaging Subsystem (WMS) is the MAPI standard user interface. WMS originally was referred to as the Exchange client, but was renamed to alleviate confusion. As a complicated structure, MAPI offers a number of different architectural perspectives:
When Microsoft Exchange Server sends a message, it relies on the MAPI subsystem to direct client requests to one or more transport-service providers. Microsoft Windows dynamic-link libraries (DLLs) serve as drivers for each transport provider. They also provide the interface between the MAPI spooler and the underlying messaging system or services.
Exchange Server will continue to support the widest possible array of network protocols (such as RPC, IMAP4, POP3, NNTP, HTTP, and so on), and it will continue to support MAPI as a programming interface.
What is the Exchange Client?The Microsoft Exchange Client, included with Microsoft Exchange Server version 4.0 through version 5.0, is an application (Exchng32.exe) that employs Microsoft Exchange Server as its service provider. It offers a user interface that provides a method for browsing and manipulating the universal Inbox. There is a folder hierarchy table in the left pane and a folder contents list in the right pane. The Exchange Client offers the user an opportunity to request different views of these tables, create and send messages, and use many other features. It is limited in its capabilities, but because it was designed for flexibility and extensibility, it allows developers to build systems that more accurately reflect the needs of their users.
The Exchange Client is supported by, but is not included with, Microsoft Exchange Server 5.5. Future changes to the code base will be limited to customer-requested, quick-fix engineering modifications for issues that affect use, interoperability, and/or deployment.
What is the Outlook Client?Outlook is the client fully optimized for Microsoft Exchange Server 5.0 and later. Released with version 5.0 of Microsoft Exchange Server and included in Microsoft Office 97, Outlook 97 combines e-mail, calendar and scheduling features, contact and task management, journalizing, and custom forms-based applications in a single interface. Outlook 98 also includes complete, native support for major Internet mail, news, and directory standards, such as IMAP4, LDAP, HTML, NNTP, MIME, and S/MIME, and also supports these Internet calendar and contact standards: vCard, vCalendar, and iCalendar Free-Busy lookup. Outlook is designed for use with Internet protocols (SMTP/POP3 and IMAP4), Microsoft Exchange Server, or any other standards-based communication system that supports MAPI, including voice mail.
Outlook enables complete access to its data by other Microsoft Office applications. With its object library, you can enable access by other applications to Outlook e-mail, appointments, tasks, journal items, and notes. The Outlook object library, because of its integration with the Microsoft Office product family, allows programmatic access to Office command bars and the Office Assistant. The object library supports separation of the user interface and data; the root Application object enables you to create a new mail message with a single line of code. For example, in Microsoft Visual Basic Scripting Edition (VBScript):
The Application object is also the main entry point into the rest of the data store. Using the MAPI NameSpace object, you can access all the information stored on the Exchange Server computer.
You can extend the functionality of Outlook Forms by using VBScript, which is a subset of Visual Basic for Applications (VBA). Outlook does not host VBA.
You can access an information store by using Outlook objects through Automation. You do this by writing Visual Basic or Visual Basic for Applications code in Visual, Microsoft Excel, Microsoft Access, Microsoft Word, or Microsoft PowerPoint.
Outlook is a platform for extensibility and third-party solutions that enables enterprise developers, solution providers, and third-party software developers to build add-on applications that extend the functionality of Outlook. Outlook is the premier e-mail client for Microsoft Office and the upgrade to the Microsoft Exchange Client and Schedule+.
Outlook 98 builds on the role of Outlook 97 as the client fully optimized for the fast-growing number of companies that rely on the scalable and advanced e-mail capabilities of Microsoft Exchange Server, and its group calendar and collaboration features, for their business-critical intranets. Outlook 98 interoperates with Outlook 97 and earlier versions of Microsoft Mail, Microsoft Exchange Client, or Schedule+, without requiring a Microsoft Exchange Server upgrade.
What is an Exchange Client Extension?An Exchange Client extension is a component object that implements the Exchange IExchExt interface and complies with the Microsoft Windows Component Object Model. This interface is defined in the Win32 Software Development Kit (SDK) header file Exchext.h, and allows the client to load extension objects in all contexts. The client loads the object server and then creates an instance of the extension object for every extensible context of the client. Search for the title "About Client Extensions" in the MSDN Library, Platform SDK documentation for more information about interface contexts.
Client extensions are created to take advantage of the existing abilities of the client. These inherent abilities are used and custom interfaces are added by the extension. Instead of developing an entirely new user interface and messaging service, the extension expands and utilizes existing features.
An Exchange Client extension differs from a standard COM in-process server in that it does not identify its class with a CLSID and does not register its server under the
HKEY_CLASSES_ROOTkey of the system registry. Instead, an extension class identifies itself with a printable string that serves to tag its registration string under the registry key
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Exchange\Client\Extensions. The extension server exports an entry point that returns a new instance of an extension object. The client queries additional interfaces off this object as needed.
There are four main types of extensions:
How to Make an Exchange Client Extension Work in OutlookWhile Outlook recognizes, loads, and runs extensions that conform to specifications for Microsoft Exchange Client extensions, methods exist for improving performance and creating added functionality.
A client extension registry entry is a string value consisting of a series of semicolon (;)-separated fields. The entry is identified with a unique tag name that differentiates the entry from other values beneath the registry key. The entry consists of six fields. The first two are required, and identify the version number of the registry entry and the path to the extension's DLL. The next four fields are optional, identifying the ordinal entry point, context map, interface map, and service name of a service provider accompanying the client extension. If these four fields are empty, the client supplies a suitable default value for each empty field.
Client extensions export their names and entry points in their registry entries in
Each string value within this key constitutes a single client extension. When the client starts, it reads the contents of the key to find all the extensions available to the client.
By default, the Exchange Client reads the extension registry key when it starts, and loads every extension having an entry in this key. After loading every extension library, the client creates an extension object from each of these libraries for every extensibility context that it encounters, unless the extension library has specified in its context map that it does not handle a particular context.
Outlook uses the same profile and other configuration information as the Exchange Client and can use all Microsoft Exchange Client extensions and custom forms. While Outlook recognizes, loads, and runs extensions that conform to specifications for Microsoft Exchange Client extensions, you can improve an extension's performance and increase its functionality under Outlook by providing an Extension Configuration File (ECF). Using an ECF, Outlook knows ahead of time the contexts under which an extension needs to be loaded, which commands the extension contributes, the Outlook modules to which the extension applies, and so on. This enables Outlook to delay loading the extension until it is needed.
Without an ECF, an extension registers itself in the registry only. In the registry entry, the information an extension can specify is limited to a DLL, an entry point, a binary context map, a binary interface map, and a provider if applicable. An ECF, however, allows an extension to register itself with much more complete and detailed data. If an ECF is loaded for an extension, registry entries for the extension are not used. Therefore, the ECF must contain a complete description of the extension. The ECF provides textual information, using the standard INI file format. There is only one ECF per extension, and only one extension per ECF. For more information about writing an ECF, search for the topic, "Outlook Extension Configuration File Document," in the MSDN Library, Microsoft Office Development documentation.
The Outlook client reads the registry information only once for an extension, and for performance reasons, transfers it to an internal cache. This internal cache is the extend.dat file, located in the Windows directory. Outlook uses the extend.dat file to record paths to DLLs for all extensions loaded into Outlook.
The first time you begin an Outlook session, or any time after an extension is installed, uninstalled, or upgraded, Extend.dat will be rewritten with the new DLL paths. Deleted extensions will no longer have an entry in the Extend.dat file. If unwanted extensions have been loaded into Outlook, you will need to manually remove them using the Add-In Manager. In Outlook 97, the Add-In Manager is accessible from the Tools menu by clicking Options, selecting the General tab, and clicking Add-In Manager. To remove an extension, simply scroll down until you locate the extension, clear the check box next to its name, click Remove, and then click OK. In Outlook 98, the Add-In Manager is accessed from the Tools menu by clinking Options, then selecting the Other tab, clicking on Advanced Options, and selecting Add-In Manager.
The Exchange Client does not have an Extend.dat file, nor does it have an Add-In Manager that uses ECFs.
Note One of the major differences between the two clients is the fact that Outlook does not enable an extension to access the product's user interface; that is, to directly manipulate HWNDs. If the Exchange Client extension manipulates the window handles in Exchange Server, it is likely that this extension will not work properly in Outlook.
The method of installing extensions differs in Exchange Server and Outlook. In Exchange Server, you simply add a new registry entry for the extension in:
In Outlook, in addition to the traditional registry entry for the extension, you must add an entry called "Outlook Setup Extension" (do not localize this string). The value must be:
It must be in:
This entry signals Outlook that new extensions have been added or removed. Outlook will remove this entry the next time it is launched.
Note In Windows Vista, Outlook will not be able to delete this key running under a normal user account. Therefore, when installing your Exchange Client Extension you should check for the existence of the key:
and delete it. Outlook will not load your extension if this key exists.
HKEY_CURRENT_USER\Software\Microsoft\Office\<version>\Outlook\Exchange Client Extension
How to Access the Outlook Object ModelIf you want to access the Outlook object model from within an extension, Microsoft publishes an interface called IOutlookExtCallback for this purpose. The following code is the header file:
In the header file for the extension, you must include the following code:
The following code fragment obtains access to an IDispatch for the current context:
This function returns two pointers-the pointer to IOutlookExtCallback and the pointer to IDispatch. The first is returned in case the user wants to perform other functions. Microsoft provides only the GetOfficeCharacter function. If this function returns NULL in ppdisp, the extension is not running in Outlook. This is an acceptable method of determining if the client that is running the extension is indeed Outlook and not Exchange Client. The caller is responsible for releasing the returned pointers.
Recommended ReadingThe best resource for learning about the Outlook object model is the Microsoft Outlook Visual Basic Reference. This Help file is available as part of the Development Tools Add-In that also includes the Outlook Object Browser and Script Debugger.
Also take a look at the following:
Article ID: 286408 - Last Review: November 19, 2008 - Revision: 4.1