Syntax
typedef short TAError;
Description
TAError is used for relaying status information as return values from add-in functions. Currently, the following errors are defined as numeric constants:
| Constant name | Description |
| TAERROR_OK | Successful result |
| TAERROR_FAIL | Generic failure result |
| TAERROR_INVALID_FUNCTABLE | Failure in binding techexplorer and/or add-in callback functions |
| TAERROR_INCOMPATIBLE_VERSION | Incompatible add-in APIs |
| TAERROR_INITIALIZE_ADDIN | Cannot initialize add-in | TAERROR_INVALID_INSTANCE | NULL or invalid AddInInstance parameter |
Syntax
typedef unsigned char TABool;
Description
TABool is used in evaluating and constructing boolean expressions. The two
values that are manipulated (defined as numeric constants) are detailed below:
| Constant name | Initial value |
| TRUE | 1 |
| FALSE | 0 |
Syntax
typedef struct _AddInInstance {
uint16 size;
uint16 version;
void *pAddIn;
void *pTechExpl;
} AddInInstance;
Description
When a new add-in instance is initialized, techexplorer creates an
AddInInstance structure. A pointer to this structure is
delivered to the add-in via a parameter to the AddInNew API call.
All subsequent function calls between techexplorer and add-ins use the
AddInInstance pointer to identify a particular instance. The
AddInInstance pointer becomes invalid when an add-in instance is
to be deleted. The AddInDestroy API call informs the
add-in that a particular instance is about to be deleted.
The fields of the
AddInInstance structure are defined as follows:
| Field name | Description |
| size | The size of the AddInInstance structure |
| version | Version of the add-in API used by techexplorer |
| pAddIn | This value is not used or changed by techexplorer. It can be used by an add-in to point to a piece of data that identifies a particular add-in instance. |
| pTechExpl | This value should not be used or changed by the add-in. It is used by techexplorer to associate an add-in instance with internal techexplorer data structures. |
Syntax
TAError AddInInitialize( )
Description
This function is called by techexplorer only once and prior to any other add-in API method being invoked. This function is called after the add-in code has been dynamically loaded into memory and should be used for "global" initializations. Here the term "global" is used to refer to initializations that are shared across add-in instances and are not tied to a particular instance. Instance initialization should occur in the AddInNew method.
Syntax
void AddInShutdown( )
Description
This function is invoked immediately before an add-in is unloaded from memory. This routine enables an add-in developer to free any resources created in the AddInInitializefunction. Add-in instance specific data and resources should be released in the AddInDestroy function.
Syntax
TAError AddInNew(AddInInstance *pAddInInstance, LPCSTR sMimeType)
Description
After the add-in has completed initialization, one or more instances of the add-in can exist. For each instance, techexplorer calls the AddInNew function. For version 2.0 of the add-in API, this can occur if there are multiple active \evalLink control sequences or several Netscape windows are open with an active \evalLink.
The parameters of the AddInNew function are defined as follows:
| Parameter | Description |
| pAddInInstance | A structure created by techexplorer that uniquely identifies this instance. |
| sMimeType | The MIME type that caused the creation of the add-in instance. |
The first parameter to AddInNew is a pointer to the AddInInstance
structure. This pointer uniquely identifies a particular add-in instance and is used
in subsequent function calls between techexplorer and add-ins to identify
a particular instance. techexplorer sets the add-in specific
data handle pAddIn in the AddInInstance structure to NULL.
It is the responsibility of the add-in to set this pointer to a block of add-in
specific instance data. techexplorer will not use or change the pAddIn
pointer.
The sMimeType string indicates the MIME type that was used to cause
the creation of a particular add-in instance. A single add-in can support multiple
data types. This parameter can be used by the add-in to distinguish between data
types.
Syntax
TAError AddInDestroy(AddInInstance *pAddInInstance)
Description
Add-in instance creation results in a call to the AddInNew
function. When an instance is destroyed, the AddInDestroy function is
invoked. techexplorer destroys an instance of an add-in when a user has exited
the web browser or closed a window containing the instance. When the last instance of
an add-in is destroyed, techexplorer calls AddInShutdown.
The parameters of the AddInDestroy function are defined as follows:
| Parameter | Description |
| pAddInInstance | A structure created by techexplorer that uniquely identifies this instance. |
The pAddInInstance pointer uniquely identifies a particular add-in instance
and may contain add-in specific data. If necessary, the pAddIn member of the
AddInInstance data structure, as well as any other add-in
specific resources should be deleted at this point.
Syntax
TAError techexplorerGetLocalFileNameForURL(AddInInstance *pAddInInstance, LPCSTR sURL)
Description
Use the techexplorerGetLocalFileNameForURL to fetch a piece of data
specified by a URL. The result of the request is passed to the current instance of
an add-in in the form of a file that contains the contents of the URL.
techexplorer notifies the add-in that the requested piece of data is available by
issuing a call to the AddInLocalFileIsReady function.
The add-in does not receive notification in the case that techexplorer can not
locate or retrieve the URL data.
The parameters of the techexplorerGetLocalFileNameForURL function are defined as follows:
| Parameter | Description |
| pAddInInstance | A structure created by techexplorer that uniquely identifies this instance. |
| sURL | The URL of the request. Valid URL types may include http, ftp, news, mailto and gopher. |
The techexplorerGetLocalFileNameForURL function is asynchronous in that it
returns immediately and only later handles the request. Note that some URL types such
as mailto will not result in a data being forwarded to the add-in.
Syntax
TAError AddInLocalFileIsReady(AddInInstance *pAddInInstance, LPCSTR sFileName)
Description
The AddInLocalFileIsReady function is called in response to a
techexplorerGetLocalFileNameForURL invocation.
techexplorer save the requested data as a file and provide this method with
the full path name to this file, as well as an a add-in instance identifier.
The parameters of the AddInLocalFileIsReady function are defined as follows:
| Parameter | Description |
| pAddInInstance | A structure created by techexplorer that uniquely identifies this instance. |
| sFileName | Specifies the full path to the local file containing the requested data. |
Syntax
TAError AddInEvaluate(AddInInstance *pAddInInstance, LPCSTR sMimeType, LPCSTR sAppInput)
Description
The AddInEvaluate function is used for transmitting application specific data
from a techexplorer document or Java applet to an add-in. The pAddInInstance
and smimeType identifies a particular add-in instance and data type respectively.
The sAppInput is the verbatim string corresponding to the add-in input. The
exact nature of the sAppInput string depends on the smimeType.
For example, the data may be contained in the sAppInput string or the string
could represent a URL where the data resides.
Current Restriction: Version 2.0 of the techexplorer Java API does
not support multiple instances of techexplorer add-ins. As a result a call
to AddInEvaluate from Java or JavaScript will result in a NULL
pAddInInstance parameter.
The parameters of the AddInEvaluate function are defined as follows:
| Parameter | Description |
| pAddInInstance | A structure created by techexplorer that uniquely identifies this instance. |
| smimeType | Type of data found in the sAppInput string. |
| sAppInput | Verbatim string corresponding to the add-in input. |
Syntax
TAError AddInBlockingEvaluate(AddInInstance *pAddInInstance,
LPCSTR sMimeType,
LPCSTR sAppInput,
LPSTR sValue,
int nValueLength)
Description
The AddInBlockingEvaluate function is used for transmitting application specific
data from a techexplorer document or Java applet to an add-in, and allow the add-in to return a
string value. The pAddInInstance and smimeType identifies a particular
add-in instance and data type respectively. The sAppInput is the verbatim string
corresponding to the add-in input. The exact nature of the sAppInput string depends
on the smimeType. For example, the data may be contained in the sAppInput
string or the string could represent a URL where the data resides. The sValue string
is the return value from the add-in. The nValueLength is the string length of the
returned string.
Current Restriction: Version 2.0 of the techexplorer Java API does
not support multiple instances of techexplorer add-ins. As a result a call
to AddInEvaluate from Java or JavaScript will result in a NULL
pAddInInstance parameter.
The parameters of the AddInBlockingEvaluate function are defined as follows:
| Parameter | Description |
| pAddInInstance | A structure created by techexplorer that uniquely identifies this instance. |
| smimeType | Type of data found in the sAppInput string. |
| sAppInput | Verbatim string corresponding to the add-in input. |
| sValue | Verbatim string corresponding to the add-in output. |
| nValueLength | Length of the output string. |
Syntax
TAError techexplorerDisableEvaluate(AddInInstance *pAddInInstance )
Description
Use the techexplorerDisableEvaluate to disallow the \evalLink
associated with a particular add-in from being executed. This is often used to disable
an \evalLink while techexplorer fetches a piece of data
over the Internet (for example, during a
techexplorerGetLocalFileNameForURL
call).
The parameters of the techexplorerDisableEvaluate function are defined as follows:
| Parameter | Description |
| pAddInInstance | A structure created by techexplorer that uniquely identifies this instance. |
Syntax
TAError techexplorerEnableEvaluate(AddInInstance *pAddInInstance )
Description
Use the techexplorerEnableEvaluate to enable the \evalLink
associated with a particular add-in.
The parameters of the techexplorerEnableEvaluate function are defined as follows:
| Parameter | Description |
| pAddInInstance | A structure created by techexplorer that uniquely identifies this instance. |
Implements
Description
Document Object Model operations only raise exceptions in "exceptional" circumstances. For
the techexplorer implementation of the DOM this occurs when an operation
is impossible to perform or invalid. For example, the over node can only have two
children, namely a top and bottom. Inserting any other kind of node
as a direct child of over will raise an exception (DOM_HIERARCHY_REQUEST_ERR).
| Exception | Value |
| DOM_NO_EXCEPTION | 0 |
| DOM_INDEX_SIZE_ERR | -1 |
| DOM_DOMSTRING_SIZE_ERR | -2 |
| DOM_HIERARCHY_REQUEST_ERR | -3 |
| DOM_WRONG_DOCUMENT_ERR | -4 |
| DOM_INVALID_CHARACTER_ERR | -5 |
| DOM_NO_DATA_ALLOWED_ERR | -6 |
| DOM_NO_MODIFICATION_ALLOWED_ERR | -7 |
| DOM_NOT_FOUND_ERR | -8 |
| DOM_NOT_SUPPORTED_ERR | -9 |
| DOM_INUSE_ATTRIBUTE_ERR | -10 |
| DOM_PLUGIN_OBJECT_ERR | -20 |
| DOM_TE_INTERNAL_ERR | -21 |
Implements
Description
The TEDOMImplementation provides a number of methods for performing operations that are independent of any particular instance of the document object model.
Implements
Description
TEDocumentFragment is a" lightweight" Document object aimed at providing an "efficient" way of creating document portions that can be latter inserted to the Document.
Implements
Description
TEDocumentType provides an interface to the list of entities that are defined for the document. It is an attribute of Document.Implements
Description
TEDocument represents the entire techexplorer document. TEDocument extends the Document interface by adding the following methods.
| Method | Description |
void recomposeAndRedraw() |
Flow and display the document |
void recomposeAndRedrawNode( Node * ) |
Flow and display a Node |
void scrollToNode( Node * ) |
Scroll to a Node |
void invalidate() |
Display the document (with outout composing) |
void getValidateNodes() |
Flag that controls whether DOM nodes should be tested as "valid" before each DOM operation |
BOOL setValidateNodes( BOOL ) |
Flag that controls whether DOM nodes should be tested as "valid" before each DOM operation |
LPCTSTR getTexString( Node * ) |
Retrieve the LaTeX/TeX representation of a Node |
LPCTSTR getMmlString( Node * ) |
Retrieve the MathML representation of a Node |
LPCTSTR getXmlString( Node * ) |
Retrieve the techexplorer XML representation of a Node |
Node * createFromTexString( LPCTSTR ) |
Return a Node from a given LaTeX string |
Node * createFromMmlString( LPCTSTR ) |
Return a Node from a given MathML string |
Node * createFromXmlString( LPCTSTR ) |
Return a Node from a given techexplorer XML string |
Implements
Description
The TENode implementation is the primary datatype for the entire Document Object Model. It represents a single node in the techexplorer tree.
Implements
Description
The TENodeList implementation provides an ordered collection of nodes.
Implements
Description
The TENamedNodeMap implementation provides a collections of nodes that can be accessed by name.
Implements
Description
The TECharacterData implementation extends Node with a set of attributes and methods for accessing character data in the DOM.
Implements
Description
The TEAttribute implementation represents an attribute in an Element object.
Implements
Description
TEElement represents basic techexplorer objects (eg. root, paragraph, ...).
Implements
Description
The TEText implementation if the textual content of an TEElement or TEAttribute.
Implements
Description
The TEComment implementation represents the content of a comment.
Implements
Description
TECDATASection allows escape blocks of text containing characters that would otherwise be regarded as markup
Implements
Description
TENotation holds notations declared in the DTD
Implements
Description
The TEEntity represents an entity, either parsed or unparsed, in an XML document.
Implements
Description
A TEEntityReference objects may be inserted into the techexplorer when an entity reference is in the source document, or when the user wishes to insert an entity reference.
Implements
Description
The TEProcessingInstruction implementation allows for housing processor-specific information
Syntax
LPCSTR AddInGetMIMEDescription( )
Description
The Multipurpose Internet Mail Extensions (MIME) type is a mechanism for describing data. An add-in associates the data that it can process with techexplorer by supplying MIME type information. techexplorer calls the AddInGetMIMEDescription add-in function to retrieve the MIME type(s) supported by an add-in, as well as descriptive information about the add-in. This informatoin is encoded by the add-in as a character string and parsed by techexplorer.
For each data type supported by an add-in, three pieces of information must be supplied namely, MIME type, file extension, and description. The information is encoded as a triple delimited by semicolons as follows:
MIME type; file extension; add-in description
Multiple data types can be specified by concatenating each data type triple and using the vertical bar as a delimiter character as follows:
MIME type; file extension; add-in description|MIME type; file extension; add-in description|...
For example, the string returned by the "Simple" add-in associates two data types with the add-in as follows:
application/x-simple-string;.smp;IBM techexplorer Simple files | application/x-simple-url;.smp;IBM techexplorer Simple files
Important Note: The add-in description triple must be defined in the add-in version resource information as the value of the MIMEDescription attribute (see TASimple.rc). It is necessary that the language for the version information be specified as "English (United States)" and the Code Page set to "Windows, Multilingual" (040904e4). If either of these specifications are not implemented, the add-in will not be registered with techexplorer.
Syntax
void techexplorerVersion(int* nAddInMajor, int* nAddInMinor, int* ntechexplorerMajor, int* ntechexplorerMinor)
Description
This is method is used to retrieve the add-in API major and minor number for both the add-in and techexplorer. The major version is a major add-in release and the minor version is a point release. For example, the techexplorer add-in API version 2.0 would result in a major 2 and minor 0.
| Parameter | Description |
| nAddInMajor | An integer pointer to the add-in API major number. |
| nAddInMinor | An integer pointer to the add-in API minor number. |
| ntechexplorerMajor | An integer pointer to techexplorer's add-in API major number. |
| ntechexplorerMinor | An integer pointer to techexplorer's add-in API minor number. |
IBM techexplorer Hypermedia Browser is a trademark of the IBM Corporation. Send comments and questions to techexpl@us.ibm.com.