HOWTO: Attach to a Running Instance of an Office Application

ID: Q238975

The information in this article applies to:

Microsoft Visual C++, 32-bit Editions, versions 4.0, 5.0, 6.0
Microsoft Outlook 98
Microsoft Office for Windows 95, versions 7.0, 7.0a, 7.0b
Microsoft Office 97 for Windows
Microsoft Office 2000 Developer

SUMMARY

To automate an Office application that is already running, you can use the GetActiveObject() API function to obtain the IDispatch pointer. Once you have the IDispatch pointer for the running instance, you can then call its methods and properties.

MORE INFORMATION

Automation servers register themselves in the Running Object Table (ROT) through the RegisterActiveObject() API. Automation clients can attach to the running instance with code such as the following:


      ::CoInitialize(NULL);

      // Translate server ProgID into a CLSID. ClsidFromProgID
      // gets this information from the registry.
      CLSID clsid;
      CLSIDFromProgID(L"Excel.Application", &clsid);  

      // Get an interface to the running instance, if any..
      IUnknown *pUnk;
      HRESULT hr = GetActiveObject(clsid, NULL, (IUnknown**)&pUnk);
      ASSERT(!FAILED(hr));

      // Get IDispatch interface for Automation...
      IDispatch *pDisp;
      hr = pUnk->QueryInterface(IID_IDispatch, (void **)&pDisp);
      ASSERT(!FAILED(hr));

      // Release the no-longer-needed IUnknown...
      pUnk->Release();

     // ----------------------------------------------------
     // Your automation code here-
     // ----------------------------------------------------

     ::CoUnintialize();

NOTE: Note that if there are multiple instances of an automation server running at once, the GetActiveObject() API function returns the IDispatch pointer to the instance that was first running.

Theoretically, you can iterate the ROT for each individual instance, but the Office applications do not register themselves if another instance is already in the ROT because the moniker for itself is always the same, and cannot be distinguished. This means that you cannot attach to any instance except for the first. However, because the Office applications also register their documents in the ROT, you can successfully attach to other instances by iterating the ROT looking for a specific document, attaching to it, then getting the Application object from it. For a code example of iterating the ROT and looking for a document name, please click the article number below to view the article in the Microsoft Knowledge Base:

Q190985 HOWTO: Get IDispatch of an Excel or Word Document From an OCX

Note that this solution is not necessary for single-instance applications since those applications can have only one instance running at a given time. PowerPoint is an example of a single-instance application.

Additional query words:

Keywords : kbVC kbVC400 kbVC500 kbVC600 kbWord kbGrpDSO kbDSupport kbOffice
Version : WINDOWS:7.0,7.0a,7.0b,97,98; winnt:4.0,5.0,6.0; :
Platform : WINDOWS winnt
Issue type : kbhowto