This article may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist. To maintain the flow of the article, we've left these URLs in the text, but disabled the links.


MIND


This article assumes you're familiar with C++ and COM
Download the code (18KB)

Controlling Internet Explorer 4.0 with Browser Helper Objects
Scott Roberts

Ever want to drive Internet Explorer from your C/C++ program? With Browser Helper Objects, it's easier than you think.
Have you ever wanted to be able to control Microsoft® Internet Explorer fully from your programs? That would mean you could tell Internet Explorer where to go and what to do. You could also watch Internet Explorer to see what it is doing. Maybe you want to receive events or access the Internet Explorer object model or history list. You could control just about anything Internet Explorer can do.
      Prior to Internet Explorer 4.0 you could do this through the somewhat cumbersome dynamic data exchange (DDE). Not only was this difficult, but it had several limitations, one of which being that you cannot receive events from Internet Explorer using DDE. This makes it difficult for you to eavesdrop on Internet Explorer.
      If you could connect to each instance of Internet Explorer 4.0 as it was started, you would be able to control them and receive events from them. But Internet Explorer 4.0 is not like normal automation servers. It does not register itself in the Running Object table like other servers, so you cannot find and bind to running instances of Internet Explorer 4.0 as you would with other automation servers, such as Microsoft Excel or Word. (Although you can do some extra work and enumerate ShellWindows to find an instance of the browser.)
      How can you accomplish this binding using Internet Explorer 4.0? You can do this using Browser Helper Objects. Browser Helper Objects were introduced with Internet Explorer 4.0. A Browser Helper Object (helper or helper object for short) is a DLL that is loaded by Internet Explorer 4.0 whenever a new instance of the browser is started. This DLL is effectively connected to Internet Explorer 4.0, meaning the helper can control the browser's actions as well as listen to events that Internet Explorer 4.0 is firing.

Starting a Browser Helper Object
      Each time a new instance of Internet Explorer starts, it looks in the registry for a specific key, HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\
CurrentVersion\Explorer\Browser Helper Objects. If Internet Explorer finds this key in the registry, it then looks for CLSIDs listed below it (see Figure 1). You can create the CLSID keys for your helper object by editing the registry yourself, or you can have your helper insert this key for you. I'll discuss automatic key creation later.

Figure 1: Helper Object Registry Keys
Figure 1: Helper Object Registry Keys


      For each CLSID listed below the Browser Helper Objects key, Internet Explorer 4.0 calls CoCreateInstance to start an instance of the helper object in the same process space as the browser. In other words, Internet Explorer 4.0 starts the helper as an in-proc server. If the helper meets all the requirements that will be discussed in the following sections, it will be started by Internet Explorer 4.0 and passed a pointer to its IWebBrowser2 interface. Your helper object can control and receive events from Internet Explorer 4.0 through this interface.
      Remember that as long as the helper object was built correctly, it will be loaded each time a new instance of Internet Explorer 4.0 is started. If you have Active Desktop™ installed, your helper will be loaded each time you open a folder, as well as when you open a browser window. If you no longer want your helper object to be loaded, you must remove the registry keys associated with it.

Creating a Browser Helper Object
      To create a Browser Helper Object, you can use any development language that supports COM and the implementation of interfaces. I used C++ and ATL to create a helper object called IEHelper. When loaded, this helper creates a window that will display all the events that are fired by Internet Explorer 4.0.
Figure 2: IEHelper
Figure 2: IEHelper

In addition, IEHelper provides an edit box for you to enter the URL of a Web page you want to view. You enter the URL, then press the Navigate button to go there. You can also press the Go Back and Go Forward buttons to go back and forward in the navigation history (see Figure 2).
Figure 3: Start a New App
Figure 3: Start a New App

      First, create a new ATL COM Application using the Visual C++® App-Wiz-ard (see Figure 3). Given a choice of server types in Step 1, choose Dynamic Link Library (DLL) (see Figure 4).
Figure 4: Choosing the Server Type
Figure 4: Choosing the Server Type

A Browser Helper Object must be a DLL so it can be loaded into the same process space as Internet Explorer. Next create a simple ATL object. To do so, right-click on the IEHelper class from within the Class-View tab and choose New ATL Object. Then click on the Simple Object icon and press the Next button (see Figure 5). Enter the name IEHlprObj and press OK (see Figure 6). Keep the defaults for all other fields.
Figure 5: A Simple ATL Object
Figure 5: A Simple ATL Object

      For the remainder of this section, I will concentrate on the required aspects of a Browser Helper Object. Creating the window that displays the events from Internet Explorer 4.0 and provides the navigation buttons will be demonstrated in the code for IEHelper.
Figure 6: Name the App
Figure 6: Name the App

      After creating the IEHlprObj simple ATL object, you must change it to implement IObjectWithSite. You receive a pointer to the Internet Explorer IWebBrowser2 interface through the SetSite method of this interface. Without this interface, you will not be able to easily communicate with or control Internet Explorer 4.0. In fact, if you don't implement this interface, Internet Explorer 4.0 will not even load your Browser Helper Object.
      Implementing the IObjectWithSite interface in ATL is very easy. Just change the declaration of CIEHlprObj to inherit from IObjectWithSite-Impl, and add IObject-WithSite to your COM map by using the COM_INTERFACE_ENTRY_IMPL macro. (See Figure 7 for the changed declaration of CIEHlprObj.)
      Next, you must override the SetSite method of the IObjectWithSite class. When Internet Explorer 4.0 loads your Browser Helper Object, it calls your IObject-WithSite::SetSite method and passes a pointer to its IWeb-Browser2 interface. Thereafter, the implementation of the SetSite method is straightforward. All you need to do is save a copy of this IWebBrowser2 interface pointer so you can use it in the future. This is as easy as copying the pointer to a class member or global variable. (See Figure 8 for the implementation of the SetSite method.)

Receiving Events from
Internet Explorer

      In its implementation of the SetSite method, IEHelper advises Internet Explorer 4.0 that it wants to receive all events that Internet Explorer 4.0 fires. To receive events from Internet Explorer 4.0, you must implement the IDispatch interface. Since simple ATL objects inherit from IDispatchImpl by default, you can use AtlAdvise to have Internet Explorer 4.0 alert you of events that it fires. The only IDispatchImpl method that you need to override to receive events is the Invoke method (seeFigure 9). Internet Explorer 4.0 will call your Invoke method each time it fires an event.
      To stop receiving events, you can call AtlUnadvise. It's wise to call this method when Internet Explorer 4.0 tells you that it is quitting by passing DISPID_QUIT to your cInvoke method.

Controlling Internet Explorer
      In addition to receiving events from Internet Explorer 4.0 through a Browser Helper Object, you can also control the behavior of Internet Explorer. Using the pointer to the IWeb-Browser2 interface that you saved in the SetSite method, you can call any of the methods that IWebBrowser2 exposes. These include Navigate, GoBack, and GoForward, to name a few. IEHelper demonstrates how to control Internet Explorer 4.0 by providing you with navigation buttons. When you enter a URL in the Address edit box and press the Navigate button, IEHelper calls the Navigate method of IWebBrowser2:


 void CIEHlprObj::Navigate(LPTSTR szURL)
 {
    CComBSTR bstrURL(szURL);
    CComVariant vtEmpty;

    m_spWebBrowser2->Navigate(bstrURL, &vtEmpty, &vtEmpty,
                              &vtEmpty, &vtEmpty);
 }
      Additionally, you can press the Go Back and Go Forward buttons in order to navigate back and forth in the history list. When either of these buttons is pressed, IEHelper calls either the GoBack or GoForward methods of IWebBrowser2 as appropriate:

 void CIEHlprObj::GoBack()
 {
    m_spWebBrowser2->GoBack();
 }

 void CIEHlprObj::GoForward()
 {
    m_spWebBrowser2->GoForward();
 }

Registering and Unregistering
a Helper

      If you want Internet Explorer to load your helper object, it must be in the registry. You can do this manually by editing the registry, or you can change the default registry script that's created by the ATL Object Wizard to include the needed registry information. To make it easy, I'll show you how to change the default registry script. This way, any time you register or unregister your helper object through regsvr32, the registry is updated automatically.
      You must add information to the bottom of the IEHlpr-Obj.rgs file to create a key for the CLSID of IEHlprObj. This registry script will also remove these registry entries when your helper object is unregistered. Figure 10 shows what the completed registry script will look like. Replace the CLSID for IEHlprObj with the CLSID for your object.
      To register the helper object, type "regsvr32 IEHelper.dll" at the command line. To unregister it, type "regsvr32 /u IEHelper.dll" at the command line.

Conclusion
      Browser Helper Objects are a new and, for the most part, little known way to connect to Internet Explorer 4.0. They are a lot easier than using DDE and provide you with much greater functionality. You can tell Internet Explorer 4.0 what to do and even eavesdrop on what Internet Explorer 4.0 is doing at any time. Just remember that your helper object is loaded every time a new instance of Internet Explorer 4.0 is started. Don't forget to unregister your helper when you are finished with it or you may end up with hundreds of helper objects running on your system.
      But where should you go for help if you run into trouble? Your first place for information, besides the Internet Client SDK (which just happens to come on the SBN Web Snapshot CD included with this issue), should be the Internet Client SDK support site located at http://support.microsoft.com/support/default.asp. You will find information about the most common issues as well as a link to the FAQ Web page.

From the May 1998 issue of Microsoft Interactive Developer.