How to build a minimal Exchange Client Extension with VC++ (285999)

MORE INFORMATION

Outlook supports Exchange Client Extensions, which are used to host Messaging Application Programming Interface (MAPI), Collaboration Data Objects (CDO), and Outlook Object Model code.

To write a very simple Client Extension DLL, the developer declares a class that inherits from the IExchExt interface and implements the Install method of that interface. The developer also implements the ExchEntryPoint function and the DllMain function. The DLL exports the ExchEntryPoint function, either with a Define (.def) file or by declaration with the __declspec(dllexport) macro.

Step-by-step:

1. In Developer Studio, create a new Win32 DLL project. For this example, place all the code in one .cpp file, and save the file as SimplestExt.cpp.
2. Include the following header files.

   #include <STDIO.h>
   #include <WINDOWS.H> 
   #include <COMMCTRL.H>
   #include <MAPIX.H>
   #include <MAPIUTIL.H>
   #include <MAPIFORM.H>
   #include <INITGUID.h>
   #include <EXCHEXT.H>
   					

   Note The Exchext.h file contains all of the Client Extension Architecture definitions for your Extension DLL to use. It is installed with Visual C++, and can be found in the Visual C++ Include folder.
3. On the menu bar, click Project, click Settings, click the Link tab, and then add Mapi32.lib to the list of Object/Library modules.
4. Add the Extern Declaration for the ExchEntryPoint callback function.

   extern "C" _declspec(dllexport) LPEXCHEXT CALLBACK ExchEntryPoint(void);
   					

5. Declare the Extension Object Class. To serve as an Extension Object, this class at minimum must singly inherit from the IExchExt interface, which contains the Install method that Outlook uses to obtain a new instance of the Extension Object Class. Also, because the IExchExt interface inherits from IUnknown, Component Object Model (COM) rules require that this class declare and implement the QueryInterface, AddRef and Release methods.
   
   In this example, the IUnknown methods are implemented inline to demonstrate the technique, although this is not necessary.

   //Declarations
   class CMyExt:public IExchExt
   {
   public:
      CMyExt() { refcount = 0;};
      ~CMyExt(){};
   
      //Methods of IUnknown
      inline STDMETHODIMP QueryInterface(REFIID riid,void** ppvObj)
      { 
         *ppvObj=NULL;
         IUnknown* punk=NULL;
         if ((IID_IUnknown == riid) || (IID_IExchExt ==riid))
         {
            punk=(IExchExt*) this;
         }
         else return E_NOINTERFACE;
   
         if (NULL!=punk)
         {
            *ppvObj = punk;
            AddRef();
         }
         return S_OK;
      }
   
      inline STDMETHODIMP_(ULONG) AddRef()
      {
         refcount++;
         return refcount;
      }
   
      inline STDMETHODIMP_(ULONG) Release()
      {
         ULONG ulCount = refcount--;
         if (!ulCount) 
         {
            delete this;
         }
         return ulCount;
      }
   
   	//This is one method of IExchExt.
      STDMETHODIMP Install(
         IExchExtCallback *pmecb,
         ULONG mcontext,
         ULONG ulFlags);
   
   private:
      ULONG refcount;
   };
   					

6. Implement the DllMain function. When the program design calls for specific initialization work to happen just after the DLL loads, it occurs in this function.

   //implementation
   
   BOOL WINAPI DllMain(
      HINSTANCE  hinstDLL,
      DWORD  fdwReason,   
      LPVOID  lpvReserved) 
   {
      return TRUE;
   }
   					

7. Implement the ExchEntryPoint function. The sole purpose of ExchEntryPoint is to return a new instance of the Extension Interface to Outlook or Exchange.

   LPEXCHEXT CALLBACK ExchEntryPoint()
   {
      return new CMyExt;
   }
   					

8. Implement the Install method. Place code here that evaluates the current context.

   STDMETHODIMP CMyExt::Install(
      IExchExtCallback *pmecb,
      ULONG mcontext,
      ULONG ulFlags)
   {
      char buffer[12];
      itoa(mcontext,buffer,10);
      MessageBox(NULL,buffer,"Test Extension",MB_OK);
      return S_OK;
   }
   					

9. Build the DLL and copy it to the same folder as Outlook.exe.
10. Register the DLL under the following registry key:

    HKEY_LOCAL_MACHINE\Software\Microsoft\Exchange\Client\Extensions

    with a string value named TestExtension and the following string in the Data field:

    4.0;SimplestExt.DLL;1

11. Start Outlook. Note that the extension DLL posts a message box immediately after Outlook loads.
12. To investigate further, perform some normal tasks in Outlook, and observe which tasks cause Outlook to call the Extension Object Install method. As an exercise, compare the context number in the message box with the constant names that are defined in the Exchext.h file.
13. As a debugging aid, Outlook can be specified as the debug executable for the extension project, which allows direct debugging into the extension code.