OLE Logo

The IE Browser Object Model

PRELIMINARY DRAFT
Last Updated: March 9, 1996
Distribution: Public

Copyright © 1995-1996 Microsoft Corporation. All Rights Reserved.

This document describes an OLE Automation compatible Object Model for the Microsoft Internet Explorer Browser Component ("IExplorer").

NOTE: THIS DOCUMENT IS AN EARLY RELEASE OF THE FINAL SPECIFICATION. IT IS MEANT TO SPECIFY AND ACCOMPANY SOFTWARE THAT IS STILL IN DEVELOPMENT. SOME OF THE INFORMATION IN THIS DOCUMENTATION MAY BE INACCURATE OR MAY NOT BE AN ACCURATE REPRESENTATION OF THE FUNCTIONALITY OF THE FINAL SPECIFICATION OR SOFTWARE. MICROSOFT ASSUMES NO RESPONSIBILITY FOR ANY DAMAGES THAT MIGHT OCCUR EITHER DIRECTLY OR INDIRECTLY FROM THESE INACCURACIES. MICROSOFT MAY HAVE TRADEMARKS, COPYRIGHTS, PATENTS OR PENDING PATENT APPLICATIONS, OR OTHER INTELLECTUAL PROPERTY RIGHTS COVERING SUBJECT MATTER IN THIS DOCUMENT. THE FURNISHING OF THIS DOCUMENT DOES NOT GIVE YOU A LICENSE TO THESE TRADEMARKS, COPYRIGHTS, PATENTS, OR OTHER INTELLECTUAL PROPERTY RIGHTS.


Introduction

This document describes a set of OLE Automation compatible interfaces and objects that allow scripts and other clients to automate internet activities through the Internet Explorer. The Object Model for the IExplorer Browser has been modeled after the Microsoft Office '95 Binder for consistency.

This document is only one part of the whole ActiveX (TM) Object Model. See The ActiveX Object Model Overview for the big picture.


Overview

The IExplorer Browser is the core of what customers will perceive as "The Internet Explorer 3.0 Product." Because it is implemented as an in-process COM server, it must be "hosted" within some other process in order to be used in a standalone manner. On Nashville this process will be the Windows shell. For the IE 3.0 product this process will be a super simple EXE (IEXPLORE.EXE) which does not much more than provide a message pump.

The IExplorer Browser is a DocObject host and implements the full hyperlink interface suite (see OLE Hyperlinks). So from one perspective IExplorer is a container. But it is also a COM class object. As a COM class object it implements all the interfaces necessary to be called an OLE Control.

As a rich DocObj host, the IExplorer Browser can host any OLE Document Object, including MSHTML, with the added benefit of fully supporting hyperlinking to any document type. Those who really think they need a "simple" HTML OLE Control that does not provide these hyperlinking and DocObj host capabilities can use MSHTML directly.

As an OLE Control, the IExplorer Browser can be contained within any OLE Control container. Two very special OLE Control containers which are coded to specifically host the browser are the Nashville shell (which hosts the browser as an additional "view") and the Internet Explorer 3.0 standalone executable ("the frame").

The IExplorer Browser implements an OLE Automation object model that allows clients to programmatically control browsing. The IExplorer Browser object model is described below. The Nashville shell exposes this object model via the Views collection property. The IExplorer 3.0 Frame simply exposes the browser's object model as though it were it's own (with some minor additions) (the IExplorer 3.0 frame's "Application" object is the browser object).

There is actually one other object that plays a part in this, and it only makes sense to group it with the browser component: the component that implements the Automation interface to OLE Hyperlinks. CLSID_OAHyperLink is an in-proc class object that wraps the "COM level" hyperlinks accessed via CreateHLinkFromData() etc..). Various methods and properties in the browser object model pass references to OAHyperlinks.

PDC NOTE: For the Internet PDC Release, the object model actually implemented is somewhat different from what is specified here. The properties and methods are basically the same, they are just organized a bit differently. Readers who are interested in programming against the PDC release should use a type library browser, such as OLEViewer or Visual Basic 4.0 provides to view the actual model.


The IShellExplorer and IInternetExplorer Interfaces

The IShellExplorer interface is the primary OLE Automation compatible (dual) interface exposed by the IExplorer Browser OLE Control. IShellExplorer is also the logical 'base' interface for IInternetExplorer. In otherwords, IInternetExplorer is a super-set (although not a strict super-set) of IShellExplorer.

Methods And Properties Common to Both Interfaces

Open

[helpstring("Opens a file."), helpcontext(0x0000)]

HRESULT Open( [in] BSTR Target,

[in,optional]VARIANT* Location,

[in,optional] VARIANT* NoHistory);

Close

GoBack

[helpstring("Navigates to the previous item in the history list."), helpcontext(0x0000)]

HRESULT GoBack();

GoForward

[helpstring("Navigates to the next item in the history list."), helpcontext(0x0000)]

HRESULT GoForward();

GoHome

[helpstring("Go home/start page."), helpcontext(0x0000)]

HRESULT GoHome();

GoSearch

[helpstring("Go Search Page."), helpcontext(0x0000)]

HRESULT GoSearch();

Navigate

[helpstring("Navigates to a hyperlink."), helpcontext(0x0000)]

HRESULT Navigate([in]DHyperLink* Hlink,

[in,optional]VARIANT* OpenInNewWindow,

[in,optional] VARIANT* NoHistory);

Refresh

[helpstring("Refreshes the current file."), helpcontext(0x0000)]

HRESULT Refresh();

Stop

[helpstring("Stops opening a file."), helpcontext(0x0000)]

HRESULT Stop();

PrintOut

[helpstring("Prints the current document."), helpcontext(0x0000)]

HRESULT PrintOut([in] long What,

[in] VARIANT Numbering,

[in, optional] VARIANT FirstPage,

[in, optional] VARIANT Sections,

[in, optional] VARIANT FileName,

[in, optional] VARIANT PrinterName,

[in, optional] VARIANT DriverName,

[in, optional] VARIANT PortName,

[in, optional] VARIANT NoPrinting);

Application

[propget, helpstring("Returns a pointer to this OC."), helpcontext(0x0000)]

HRESULT Application([out,retval] IDispatch** ppDisp);

Container

[propget, helpstring("Returns a pointer to the container."), helpcontext(0x0000)]

HRESULT Container([out,retval] IDispatch** ppDisp);

Document

[propget, helpstring("Returns the active Document."), helpcontext(0x0000)]

HRESULT Document([out,retval] IDispatch** ppDisp);

Parent

[propget, helpstring("Returns a pointer to the parent Object."), helpcontext(0x0000)]

HRESULT Parent([out,retval] IDispatch** ppDisp);

TopLevelContainer

[propget, helpstring("Huh? -- always FALSE for an OC..."), helpcontext(0x0000)]

HRESULT TopLevelContainer([out, retval] boolean* pBool);

Type

[propget, helpstring("Returns the type of the contained object."), helpcontext(0x0000)]

HRESULT Type([out,retval] BSTR* pbstrType);

Visible

[propget, helpstring("Determines whether this OC is visible or hidden."), helpcontext(0x0000)]

HRESULT Visible([out, retval] boolean* pBool);

[propput]

HRESULT Visible([in] boolean Value);

Width

[propget, helpstring("The horizontal dimension (pixels) of the frame window"), helpcontext(0x0000)]

HRESULT Width([out, retval] long *pl);

[propput]

HRESULT Width([in] long Width);

Height

[propget, helpstring("The vertical dimension (pixels) of the frame window"), helpcontext(0x0000)]

HRESULT Height([out, retval] long *pl);

[propput]

HRESULT Height([in] long Height);

Busy

[propget, helpstring("Query to see if something is still in progress."), helpcontext(0x0000)]

HRESULT Busy([out,retval] boolean *pBool);

Shell Specific Methods/Properties

Value

[id(0), propget, helpstring("Returns the friendly name of the Location")]

HRESULT Value([out, retval] BSTR *pbstrLocation);

Location

[id(DISPID_LOCATION), propget, helpstring("Returns/sets location in namespace to view")]

HRESULT Location([out, retval] BSTR *pbstrLocation);

[id(DISPID_LOCATION), propput]

HRESULT Location([in] BSTR bstrLocation);

FolderFlags

[id(DISPID_FOLDERFLAGS), propget, helpstring("Returns/sets FWF_ folder flags")]

HRESULT FolderFlags([out, retval] int *pfFlags);

[id(DISPID_FOLDERFLAGS), propput]

HRESULT FolderFlags([in] int fFlags);

FolderViewMode

[id(DISPID_FOLDERVIEWMODE), propget, helpstring("Returns/sets FVM_ folder view mode")]

HRESULT FolderViewMode([out, retval] int *pnViewMode);

[id(DISPID_FOLDERVIEWMODE), propput]

HRESULT FolderViewMode([in] int nViewMode);

AutoSize

[id(DISPID_AUTOSIZE), propget, helpstring("Returns/sets auto-size mode")]

HRESULT AutoSize([out, retval] boolean *pfAutoSize);

[id(DISPID_AUTOSIZE), propput]

HRESULT AutoSize([in] boolean fAutoSize);

BorderVisible

[id(DISPID_BORDERVISIBLE), propget, helpstring("Returns/sets border-visible flag")]

HRESULT BorderVisible([out, retval] boolean *pfBorderVisible);

[id(DISPID_BORDERVISIBLE), propput]

HRESULT BorderVisible([in] boolean fBorderVisible);

Browse

[id(DISPID_BROWSE), helpstring("Browse for a new folder to view")]

HRESULT Browse(void);

Navigate

[id(DISPID_NAVIGATE), helpstring("Navigate through the history list")]

HRESULT Navigate([in] int nDirection);

Internet Explorer Specific Methods/Properties

Below are the methods/properties that are specific to IExplorer.EXE. These elements must also be available via the object returned from the shell View property.

Quit

[helpstring("Exits Shell Explorer and closes the open window."), helpcontext(0x0000)]

HRESULT Quit();

FileName

[propget, helpstring("Returns the file name (sans path) of <what?>."), helpcontext(0x0000)]

HRESULT FileName([out,retval] BSTR* pbstrFileName);

FullName

[propget, helpstring("Returns the full pathname to <what?>."), helpcontext(0x0000)]

HRESULT FullName([out,retval] BSTR* pbstrFullName);

FullScreen

[propget, helpstring("Determines whether this control is full screen or not."), helpcontext(0x0000)]

HRESULT FullScreen([out, retval] boolean* pBool);

[propput, helpstring("Sets this control to be full screen or not."), helpcontext(0x0000)]

HRESULT FullScreen([in] boolean Value);

StatusBar

[propget, helpstring("Turn on or off the statusbar."), helpcontext(0x0000)]

HRESULT StatusBar([out, retval] boolean* pBool);

[propput, helpstring("Turn on or off the statusbar."), helpcontext(0x0000)]

HRESULT StatusBar([in] boolean Value);

StatusText

[propget, helpstring("Text of Status window."), helpcontext(0x0000)]

HRESULT StatusText([out, retval] BSTR *pbstr);

[propput, helpstring("Turn on or off the toolbar."), helpcontext(0x0000)]

HRESULT StatusText([in] BSTR bstr);

ToolBar

[propget, helpstring("Turn on or off the toolbar."), helpcontext(0x0000)]

HRESULT ToolBar([out, retval] boolean* pBool);

[propput, helpstring("Turn on or off the toolbar."), helpcontext(0x0000)]

HRESULT ToolBar([in] boolean Value);

Name

[id(0), propget, helpstring("Returns name of the application."), helpcontext(0x0000)]

HRESULT Name([out,retval] BSTR* pbstrName);

Left

[propget, helpstring("The horizontal position (pixels) of the frame window relative to the screen"), helpcontext(0x0000)]

HRESULT Left([out, retval] long *pl);

[propput]

HRESULT Left([in] long Left);

Top

[propget, helpstring("The vertical position (pixels) of the frame window relative to the screen"), helpcontext(0x0000)]

HRESULT Top([out, retval] long *pl);

[propput]

HRESULT Top([in] long Top);

Events

[
    uuid(EAB22AC2-30C1-11CF-A7EB-0000C05BAE0B),
    helpstring("Event interface for Shell Explorer Control"),
    hidden
]
dispinterface DShellExplorerEvents {
methods:
[id(DISPID_ON_BEGIN_NAVIGATE), helpstring("Fired when a new hyperlink is being navigated to."), helpcontext(0x0000)]
        void OnBeginNavigate([in]IDispatch * HLink, [in, out]boolean * Cancel);
[id(DISPID_ON_NAVIGATE), helpstring("Fired when a new hyperlink is being navigated to."), helpcontext(0x0000)]
        void OnNavigate([in]IDispatch * HLink);
[id(DISPID_ON_STATUSTEXTCHANGE), helpstring("Statusbar text changed."), helpcontext(0x0000)]
        void OnStatusTextChange([in]BSTR bstrText);
[id(0xfffffda0), helpstring("Fired when an error occurs."), helpcontext(0x0000)]
        void OnError([in] long Number,
             [in,out] BSTR* Description,
             [in]BSTR Source,
             [in]BSTR HelpFile,
             [in] long HelpContext,
             [in, out] boolean* CancelDisplay);
[id(DISPID_ON_QUIT),helpstring("Fired when application is quiting."), helpcontext(0x0000)]
        void OnQuit([in, out] boolean * Cancel);
};



The HypeLink Object

/****************************************************************************
 *  Hyperlink definition
 ***************************************************************************/
        [
                uuid(0002DF07-0000-0000-C000-000000000046),
                helpstring("HyperLink Object."),
                helpcontext(0x0000),
                hidden,
                oleautomation,
                dual
        ]
        interface DHyperLink : IDispatch
        {
                // id(0) indicates that this is the "value" member.
                [id(0), propget, helpstring("Returns or sets the Friendly Name for the HyperLink."), helpcontext(0x0000)]
                HRESULT FriendlyName([out, retval] BSTR* pbstrName);
                [id(0), propput, helpstring("Returns or sets the Friendly Name for the HyperLink."), helpcontext(0x0000)]
                HRESULT FriendlyName([in] BSTR bstrName);
                [propget, helpstring("Returns or sets the string reference for the HyperLink."), helpcontext(0x0000)]
                HRESULT Source([out,retval] BSTR* pbstrSource);
                [propput, helpstring("Returns or sets the string reference for the HyperLink."), helpcontext(0x0000)]
                HRESULT Source([in] BSTR bstrSource);
                [helpstring("Jumps to the hyperlink."), helpcontext(0x0000)]
                        HRESULT Navigate([in,optional]VARIANT* OpenInNewWindow, [in,optional] VARIANT* NoHistory);
                [propget, helpstring("Returns a pointer to the IExplorer Object."), helpcontext(0x0000)]
                HRESULT Parent([out,retval] IDispatch** ppDisp);