The OnConnection Method

Home Page (Add-ins) |  Overview |  How Do I Topics |  FAQ |  Reference

To load an add-in, the Visual C++ Developer Studio environment calls the add-in's OnConnection method. If you use the Developer Studio Add-in Wizard to create an add-in, the wizard automatically creates the code that implements the OnConnection method. In this code, the OnConnection method is in the CDSAddIn class located in the Dsaddin.cpp file.

The syntax for the OnConnection method is:

VARIANT BOOL OnConnection ( Application* pApp, VARIANT BOOL bFirstTime, Long dwCookie )

Developer Studio first passes a pointer (Application*) to the dual interface on the Developer Studio Application object.

Additionally, Developer Studio provides a cookie. The add-in uses this cookie to identify itself in subsequent calls to Developer Studio. For example, the add-in uses this cookie to call the AddCommand method.

To connect, the add-in takes the following steps. If you use the Developer Studio Add-in Wizard, it automatically implements these steps:

  1. Uses the pApp parameter to ensure that required objects in the Developer Studio object model are installed. If required objects are not available, the add-in returns VARIANT_FALSE, indicating that it should not be loaded.

    Note   Because OnConnection is a COM method, it does not use the typical Visual C++ BOOL type (TRUE or FALSE). Instead it uses the VARIANT_BOOL type (VARIANT_TRUE or VARIANT_FALSE).

  2. Uses the bFirstTime parameter to determine if this is the first time the add-in has been loaded into the environment. If it is the first time, bFirstTime is VARIANT_TRUE, and the add-in can add new toolbar buttons or key sequences for carrying out its commands. Note that if you disconnect the add-in and then reconnect it, bFirstTime is also VARIANT_TRUE.

    Tip   You only need to add toolbar buttons and keybindings the first time an add-in is loaded because the environment keeps track of them in subsequent loads.

  3. Provides information about itself by calling the SetAddInInfo method. If the add-in fails to provide the required information, the environment unloads the add-in by calling the add-in's OnDisconnection method. Then, the environment displays a message box describing what the add-in failed to do.

  4. Connects to events. The add-in locates the appropriate Developer Studio objects and then connects to their events. The Developer Studio Add-in Wizard automatically generates the code for handling events if you choose the Responds to Developer Studio events option.

  5. Adds commands by calling the AddCommand method.

  6. Stores the cookie and the pointer (Application*) to the Application object for future use. To store the pointer, the add-in must explicitly call the AddRef function. Storing is recommended because the environment will not pass the pointer to the add-in again.

  7. Returns VARIANT_TRUE, indicating that the add-in loaded successfully.