Building An Outlook COM Add-In With VC /ATL - Getting started
(Page 2 of 7 )
An Office add-in is a COM Automation component that dynamically extends/enhances and controls any Office suite of applications. Microsoft Office 2000 and later versions support a new, uniform design architecture for building such application add-ins. Typically such add-ins are housed in ActiveX DLL's (in-process servers) and can be dynamically loaded and unloaded by the user through the main application.
An Office COM add-in must implement the _IDTExtensibility2 interface. The IDTExtensibility2 interface is defined in the MSADDin designer type library (MSADDNDR.dll/MSADDNDR.tlb) file, which usually exists in the c:\Program Files\Common Files\Designer folder.
The interface definition looks like this:
enum {
ext_cm_AfterStartup = 0,
ext_cm_Startup = 1,
ext_cm_External = 2,
ext_cm_CommandLine = 3
} ext_ConnectMode;
enum {
ext_dm_HostShutdown = 0,
ext_dm_UserClosed = 1
} ext_DisconnectMode;
...
...
...
interface _IDTExtensibility2 : IDispatch {
[id(0x00000001)]
HRESULT OnConnection(
[in] IDispatch* Application,
[in] ext_ConnectMode ConnectMode,
[in] IDispatch* AddInInst,
[in] SAFEARRAY(VARIANT)* custom);
[id(0x00000002)]
HRESULT OnDisconnection(
[in] ext_DisconnectMode RemoveMode,
[in] SAFEARRAY(VARIANT)* custom);
[id(0x00000003)]
HRESULT OnAddInsUpdate([in] SAFEARRAY(VARIANT)* custom);
[id(0x00000004)]
HRESULT OnStartupComplete([in] SAFEARRAY(VARIANT)* custom);
[id(0x00000005)]
HRESULT OnBeginShutdown([in] SAFEARRAY(VARIANT)* custom);
};All COM add-ins inherit from the IDTExtensibility2 interface, and must implement each of its five methods.
OnConnection and OnDisconnection, as their names suggest, are called when the add-in loads and unloads from memory. The add-in can be loaded either during application startup, by the user, or through automation. The enumerator ext_Connect denotes these connection modes. OnAddinsUpdate is called when a set of COM add-ins changes. OnStartupComplete is called only if the add-in was loaded during application startup, and OnBeginShutdown is called if the add-in was disconnected when the host application shutdown.
Registering an add-in To register the COM add-in with the host application, we also need to create a couple of registry sub keys under the hive
HKEY_CURRENT_USER\Software\Microsoft\Office\<TheOfficeApp>\Addins\<ProgID>... where ProgID refers to the add-in COM object's unique Programmatic Identifier. The other entries through which the add-in can provide information about itself and specify loading options to the host app are:
- FriendlyName: The add-in's name as displayed by the host app.
- Description: Description of the add-in.
- LoadBehavior: A DWORD combination of values that determine how the add-in will be loaded by the host app. Should be set to 0x03 to load on app startup or 0x08 for user controlled activation.
- CommandLineSafe: A DWORD value set to 0x01 (TRUE) or 0x00 (FALSE).
For a full description of the all values and options, please consult the MSDN documentation.
Next: Building a minimal COM add-in >>
More C++ Articles
More By Amit Dey
