Besides external Prolog clauses it is also possible to create external Prolog classes. An external Prolog class is a Prolog class in which the methods of the class are inside the external library, the declaration of the class is in a Prolog text file.
A Trinc-Prolog class can be declared external by the compile directive external_class/2. The declaration of the class must be in the same text file.
| class myClass. public. do0/0. %No parameters do1/1. %A single parameter endclass myClass. :- external_class('class.dll', [myClass]). |
It is possible to create 'normal' Prolog classes which are derived from external Prolog classes and external Prolog classes can also be derived from 'normal' Prolog classes.
An external class must have two functions inside an external library for creating and deleting instances. The function to create instances of a class must be named 'new_<classname>' and the function to delete instances must be named 'delete_<classname>'. For instance: an external class is called 'wWindow', the names of the new and delete functions must then be 'new_wWindow' and 'delete_wWindow'.
A function to create instances for a class must be declared as:
| TPINT TP_API new_<my_classname>( TPINT32 Version,
TPINT32 EngineId, TPINT TPInstance, TPEXCEPTION *Exc ) Delphi example |
The first parameter is the version of the function call, second is the identifier of the Trinc-Prolog engine that calls the external function. The third parameter 'TPInstance' is the internal Trinc-Prolog instance identifier. Before the new_<classname> function is called an internal object for storing information about the Prolog instance is created and the value 'TPInstance' is the identifier for this internal object. The last parameter is a TPEXCEPTION structure, if allocating the instance by the extension library failed then can this parameter be used to throw an exception.
If the function returns 0 then Trinc-Prolog interprets that value as a failure to allocate an instance and an exception is thrown, else the returned value is stored by Trinc-Prolog as the identifier of the external library for the instance. So each instance of an external class has two identifiers associated with it; an internal Trinc-Prolog identifier and an external library identifier.
A function to delete instances must be declared as:
| TPBOOL TP_API delete_<my_classname>( TPINT32 Version,
TPINT32 EngineId, TPINT TrincPrologId, TPINT YourId ) Delphi example |
The first parameter is the version of the function call, second is the identifier of the Trinc-Prolog engine that calls the external function. The third parameter 'TrincPrologId' is the Trinc-Prolog instance identifier. The last parameter is the identifier that was assigned to the instance by the external library function that created the instance.
The function declaration of an external class method is identical to a function of an external clause except that the name of the method is comprised of the method and class name; <methodname>_<classname>. For instance: the class name is 'myClass' and the method name is 'mul', the function in the library must be called: 'mul_myClass'.
The second difference between external methods and clauses is that in the TPCALL structure the internal and external instance identifiers are stored in the attributes _TPId and _ExtId.
If an extension library detects an asynchronous event then it is possible to create a Prolog query that sends a message to a specific instance. The only thing that differs from sending 'normal' events is to fill the _TPId attribute of a TPEXTEXVENT structure with the Trinc-Prolog identifier for an instance.