Article ID: 230689 - Last Review: August 9, 2004 - Revision: 5.4

SAMPLE: Comaddin.exe Office 2000 COM Add-In Written in Visual C++

View products that this article applies to.

System TipThis article applies to a different operating system than the one you are using. Article content that may not be relevant to you is disabled.

This article was previously published under Q230689

SUMMARY

Comaddin.exe is a self-extracting executable that demonstrates building an Office 2000 or Office XP Component Object Model (COM) add-in using Visual C++. A COM add-in is an in-process COM server specifically designed to run within the context of one or more Office 2000 or Office XP applications. COM add-ins provide a flexible, efficient, and uniform method of extending the Office environment.

COM add-ins are built using any programming language that can create COM components, such as Visual Basic, C/C++, C# , and the Office 2000 Developer or Office XP Developer edition of Microsoft Visual Basic for Applications (VBA).

This sample demonstrates the necessary steps to build a COM add-in in Visual C++. The sample creates a basic add-in shell that you can extend to build your own Office add-in.

Back to the top

MORE INFORMATION

The following file is available for download from the Microsoft Download Center:

Comaddin.exe (http://download.microsoft.com/download/office2000dev/update/1/win98/en-us/comaddin.exe)

Release Date: January 4, 1999

For additional information about how to download Microsoft Support files, click the following article number to view the article in the Microsoft Knowledge Base:

119591 (http://support.microsoft.com/kb/119591/EN-US/ ) How to Obtain Microsoft Support Files from Online Services

Microsoft scanned this file for viruses. Microsoft used the most current virus-detection software that was available on the date that the file was posted. The file is stored on security-enhanced servers that help to prevent any unauthorized changes to the file.

Back to the top

Sample File Information

Comaddin.exe extracts the following files to a folder of your choosing:

   FileName                    Size
   ----------------------------------------
   
   TestAddin.dsw               541 bytes
   TestAddin.dsp               4.11 KB 
   ComAddin.h                  6.19 KB
   ComAddin.cpp                8.38 KB
   ComAddin.def                205 bytes
   MyAddin.cpp                 10.6 KB
   MyAddinCF.cpp               2.18 KB
   BttnHandler.cpp             6.27 KB

Back to the top

IDTExensibility2

For a COM object to be an Office add-in, it must support the IDTExensibility2 interface as described in the Microsoft Add-In Designer Type Library (Msaddndr.dll). This interface has been declared for you in ComAddin.h so no import is necessary. All COM add-ins inherit from this interface and must implement each of its five methods:

OnConnection
OnDisconnection
OnAddInsUpdate
OnStartupComplete
OnBeginShutdown

When a COM add-in is first loaded, a QueryInterface call is made for IDTExtensibility2. If this call fails, the add-in is unloaded. If the call succeeds, the host application will use the reference returned to notify the add-in of changes made to its state. A description of each method follows.

OnConnection

The OnConnection event fires whenever the COM add-in is connected. The add-in may be connected on startup, by the end user, or through automation. If OnConnection returns S_OK, the add-in is said to be loaded. If any other value is returned, the host application will immediately release its reference to the add-in and the object will be destroyed.

OnConnection takes the following four parameters:

Application - A reference to the IDispatch interface of the host application.
ConnectMode - A constant that specifies how the add-in was connected.
- ext_cm_AfterStartup - Started by the end user from the COM add-ins dialog.
- ext_cm_CommandLine - Connected from the command line.
- ext_cm_External - Connected by an external application through Automation.
- ext_cm_Startup - Started by the host at application startup. This behavior can be controlled by a setting in the registry.
AddInInst - A reference to the COMAddIn object that refers to this add-in in the COMAddIns Collection for the host application.
Custom - An array of Variants that can hold user-defined data.

OnDisconnection

The OnDisconnection event fires when the COM add-in is disconnected and just before it unloads from memory. The add-in should perform any cleanup of resources in this event, and restore any changes made to the host application.

OnDisconnection takes the following two parameters:

RemoveMode - A constant that specifies how the add-in was disconnected.
- ext_dm_HostShutdown - Disconnected when the host application closed.
- ext_dm_UserClosed - Disconnected by the end user or an Automation controller.
Custom - An array of Variants that can hold user-defined data.

OnAddInsUpdate

The OnAddInsUpdate event fires when the set of registered COM add-ins changes. In other words, whenever a COM add-in is installed or removed from the host application, this event fires.

OnStartupComplete and OnBeginShutdown

Both the OnStartupComplete and OnBeginShutdown events notify the add-in when the host application has left or is entering a state where user-interaction should be avoided because the application is busy loading or unloading itself from memory. OnStartupComplete will only fire if your add-in was connected during startup, and OnBeginShutdown will only fire if your add-in is disconnected by the host during shutdown.

Because the user-interface for the host application is fully active when these events fire, they may be the only way to perform certain actions that otherwise would be unavailable from OnConnection and OnDisconnection.

Back to the top

Registering the COM Add-In

In addition to normal COM registration, a COM add-in needs to register itself with each Office 2000 application in which it can safely run. To register itself with a particular application, the add-in creates a subkey, using its ProgID as the name for the key, under the following location:

HKEY_CURRENT_USER\Software\Microsoft\Office\<AppName>\Addins\<AddInProgID>

The add-in can provide values at this key location for both a friendly display name and a full description. In addition, the add-in should specify its desired load behavior using a DWORD value called "LoadBehavior." This value determines how the add-in will be loaded by the host application, and is made up of a combination of the following values:

0x00 = Disconnect - Is not loaded.
0x01 = Connected - Is loaded.
0x02 = Bootload - Load on application Startup.
0x08 = DemandLoad - Load only when requested by user.
0x16 = ConnectFirstTime - Load only once (on next startup).

The typical value specified is 0x03 (Connected | Bootload).

Add-ins that implement IDTExtensibility2 should also specify a DWORD value called "CommandLineSafe" to indicate whether they are safe for operations that do not support a user interface. A value of 0x00 means False, 0x01 is True. Because this sample displays a message box, it is not safe for command line execution, and therefore sets the value to 0x00.

Back to the top

Getting Started

To get started writing add-ins, compile the sample project, run regsvr32.exe on the built DLL, and then launch Microsoft Word, Excel, Powerpoint and/or Frontpage 2000. You should see a dialog box open as the add-in gets loaded that says "Hello" and tells you what application it is in.

(c) Microsoft Corporation 1999, All Rights Reserved. Contributions by Richard R. Taylor, Microsoft Corporation.

Back to the top