Extending techexplorer via Add-ins

The techexplorer add-in API

A techexplorer add-in is implemented as a dynamically linked code module. In the Microsoft Windows 98/95/NT platform this module is a dynamic link library, also known as a DLL. This section provides an overview of the techexplorer add-in API, the communication channel between add-ins and techexplorer. In particular we describe how add-in and techexplorer functions are called within an add-in DLL through entry points defined during compile time. Via a discussion of the DLL entry points, you learn that the techexplorer add-in API provides three classes of functions.

We begin with a discussion of the techexplorer API functions, the techexplorer functions callable by an add-in. We then detail the add-in API routines, those functions provided by the add-in and callable by techexplorer. We finish our discussion of the add-in API by detailing the Document Object Model (DOM) API. The section concludes with a brief explanation of all of the techexplorer add-in API functions and set the stage for the annotated techexplorer add-in API Reference Guide.

Add-in API entry points

The three types of add-in API functions are

• functions whose names begin with "AddIn" and are implemented by add-in developers and are callable from techexplorer,
• functions whose names begin with "techexplorer" and are routines implemented by techexplorer and callable from within an add-in, and
• methods on the C++ classes that implement the W3C Consortium Document Object Model.

Much like the Netscape plug-in API, the techexplorer add-in API uses three entry points for managing the connection between an add-in and techexplorer. These are TA_GetEntryPoints, TA_Initialize and TA_Shutdown.

Immediately after an add-in is loaded, the DLL routine TA_Initialize is called. This routine checks for add-in API compatibility and initializes a global pointer to all the techexplorer entry points. After TA_Initialize is called and returns a successful result, the DLL entry point routine TA_GetEntryPoints is called. TA_GetEntryPoints provides techexplorer with the ability to call routines defined by the add-in. Since the connection between techexplorer and the add-in has been made, no other DLL entry point is used until the add-in is unloaded from memory. At that point, TA_Shutdown is called and used to invoke the AddInShutdown routine and clear all global pointers.

As an add-in developer, you do not need to concern yourself with techexplorer's use of function tables and DLL entry points. The underlying DLL initialization and shutdown phases are transparent to the add-in. The only visible and useful routines are the add-in API routines implemented by both techexplorer and add-ins.

There are four categories of add-in API functions:

We next discuss and categorize each of the techexplorer add-in API routines.

techexplorer API functions

The techexplorerGetLocalFileNameForURL function is categorized as an Asynchronous operation. An add-in uses this to request the content of a URL. When the URL content arrives, the add-in receives notification. This call is non blocking and is matched with the add-in API call AddInLocalFileIsReady.

The techexplorerDisableEvaluate and techexplorerEnableEvaluate routines are part of the Evaluation API. They are used to enable and disable \evalLink execution, respectively. These functions are often used in conjunction with techexplorerGetLocalFileNameForURL and AddInLocalFileIsReady in order to disable an \evalLink when a URL is being fetched over the Internet.

The techexplorerVersion is a Utility routine for retrieving add-in API information.

Add-in API functions

The add-in API functions begin with the AddIn convention and are routines implemented by an add-in and callable by techexplorer. The techexplorer add-in API provides seven functions that are to be implemented by a techexplorer add-in:

• AddInInitialize,
• AddInShutdown,
• AddInNew,
• AddInDestroy,
• AddInLocalFileIsReady,
• AddInEvaluate,
• AddInBlockingEvaluate, and
• AddInGetMIMEDescription.

The AddInInitialize function is called by techexplorer when the add-in code is first loaded. The AddInNew function is used to notify an add-in that a new instance has been created. When a particular instance is no longer needed and is to be deleted, techexplorer calls the AddInDestroy routine. The AddInShutdown function is called when the last instance of an add-in is deleted and the add-in code about to be removed from memory. Each of the aforementioned functions are categorizes as Initialization and destruction routines.

The AddInLocalFileIsReady is an Asynchronous operation that is called when the contents of a requested URL (via techexplorerGetLocalFileNameForURL) is available as a local file.

The AddInEvaluate routine is used to request that an add-in process a piece of data and is part of the Evaluation API.

The AddInBlockingEvaluate routine is used to request that an add-in process a piece of data and return an value. It is part of the Evaluation API.

The AddInGetMIMEDescription provides techexplorer with the MIME type, file extension, and description associated with an add-in and is part of the Utility category of routines. Note that on Windows 98/95/NT, techexplorer uses the AddInGetMIMEDescription function in conjunction with information provided by the add-in in the "version resource block" of the DLL.

Document Object Model (DOM) API

The Document Object Model provides a standard set of objects for representing documents, a standard model of how these objects can be combined, and a standard interface for accessing and manipulating objects. The techexplorer add-in interface supports the DOM by providing a C++ language binding. Each of the DOM objects are represented as C++ classes where class methods provide the functionality defined by the corresponding DOM interface.

When an add-in is first loaded, the TA_Initialize function creates and stores an instance of the TEDOMFactory class in the global g_pDOMFactory variable. The getDocumentNode method, defined in TEDOMFactory, provides access to the currently loaded techexplorer Document object. With a Document object in hand, an add-in can access and mutate objects in the techexplorer document tree.

The TEDOMFactory and C++ language binding of the DOM interface provide a thin layer to the internal techexplorer document structure. The TEDOMFactory serves as a marshal that manages the creation and destruction of C++ DOM objects. As a consequence, there is no need to delete objects that result from DOM operations. They will simply be garbage collected by the TEDOMFactory.

A quick look at the techexplorer add-in API

Here is a brief overview and link for each function used in the techexplorer add-in API.

IBM techexplorer Hypermedia Browser is a trademark of the IBM Corporation. Send comments and questions to techexpl@us.ibm.com.