NCSA Mosaic for MS Windows User Guide: Client Communication Interface

OLE Automation

OLE automation is a robust object-oriented way for your application to control and communicate with Mosaic. There are several ways to make use of OLE Automation.

CCI is implemented as an OLE 2.0 Automation Server. This means that any application that can act as an OLE Automation Client can access Mosaic through this interface.

The easiest way to use OLE Automation to access Mosaic is by using a product that has OLE Automation capabilities built-in. Microsoft Excel, for example, has a subset of Visual Basic built into it. There are many other applications (e.g., the Microsoft Office package) that provide OLE Automation control. Check the application documentation to see if it supports OLE Automation.

If you're interested in writing stand-alone applications, one option is to use Visual Basic 3.0 that has OLE Automation built-in. Applications can also be written using Visual C++. However, this requires more extensive knowledge of the inner workings of OLE.

CCI Function Calls

The list of functions that are currently implemented in the latest release of NCSA Mosaic for Windows are listed below. The function headers are taken directly from the Mosaic source code.

 afx_msg BOOL ResolveUrl (LPCTSTR szURL)
 afx_msg BOOL DownloadUrl (LPCTSTR szURL, LPCTSTR szPath)
 afx_msg CVariant GetVersion ()
 afx_msg CVariant GetLastLaunchedAnchor (LPCTSTR szName)
 afx_msg CVariant DOACTIVATE ( )
 afx_msg CVariant GetAnchorCount ()
 afx_msg CVariant GetAnchorTitle (short index)
 afx_msg CVariant GetAnchorUrl (short index)
 afx_msg CVariant GetHistoryCount ()
 afx_msg CVariant GetHistoryItem (short index)
 afx_msg CVariant GetCurrentDocTitle ()
 afx_msg CVariant GetCurrentDocUrl ()

Function Call Actions

ResolveUrl (URLSTRING)
This function causes Mosaic to jump to a given URL just as if you had clicked on a link for that URL. An example: ResolveUrl ("http://www.ncsa.uiuc.edu") tells Mosaic to go to NCSA's home page.
DownloadUrl (URLSTRING, FILESTRING)

This function allows an external program to use Mosaic to access files over the Internet and save the files to local disk. The function takes two arguments: the URL to be downloaded and the filename to save it to.
VERSIONSTRING GetVersion ()

The GetVersion() function returns version information for Mosaic and the CCI. For this release, the GetVersion function returns the following string:
NCSA Mosaic/2.0.0b3 (Windows x86)/CCI 0.11

URLSTRING GetLastLaunchedAnchor (FILESTRING)

This function helps an external program find out the complete anchor for a file that was launched. If FILESTRING is empty, Mosaic returns the URL for the last launched file. If FILESTRING is a filename, then Mosaic checks to see if the last launched anchor is associated with the given file. If so, Mosaic returns the URL. If the filename passed is not the last launched file, then Mosaic returns an empty string.
For example, suppose you click on the URL
http://sdg.ncsa.uiuc.edu/bigfilename.xyz. The xyz viewer is launched and passed the name bigfilen.xyz. The xyz viewer can determine where bigfilen.xyz came from by calling GetLastLaunchedAnchor("bigfilen.xyz"). Mosaic returns the full URL
(i.e., http://sdg.ncsa.uiuc.edu/bigfilename.xyz).

DOACTIVATE ( )
This function forces the Mosaic window to the foreground.
ITEMCOUNT GetAnchorCount (), GetAnchorUrl (ITEMINDEX), GetAnchorTitle (ITEMINDEX)

These three functions provide information about all the links that are on the page that Mosaic is currently displaying. The index is 1 based, so a call to GetAnchorUrl(1) returns the URL for the first link on the page.
ITEMCOUNT GetHistoryCount () and ITEMSTRING GetHistoryItem (ITEMINDEX)

This pair of functions is used to retrieve the information in Mosaic's History list. Currently Mosaic only stores the URL, so that is the information returned by GetHistoryItem(n). The index is 1 based, so a call to GetHistoryItem(1) returns the first URL in the history list. First find out how many items are in the history list by calling GetHistoryCount().
TITLESTRING GetCurrentDocTitle () and URLSTRING GetCurrentDocUrl ()

These two functions are used to retrieve information about the current document being displayed by Mosaic.