COM-API Extensions

The following article offers an introduction to COM-API Extensions for Equilla (note: available in Tradesignal 6.3 and above)

What are COM-Extension objects

Equilla COM-Extensions are COM-Objects that implement a special set of interfaces. Each COM-Object can provide one or more Extension objects by implementing one or more interfaces derived from the IEquillaExtension Interface. These objects are referenced from equilla by using the Prog-ID or the CLSID and an optional interface name. Extension COM-Objects need to be registered with the system so they can be instantiated via the Windows CoCreateInstance mechanism. For a detailed step-by-step guide to create COM-Extensions read the section How to write a COM Extension and check out the samples projects installed with Tradesignal.

How to use COM-Extension objects

Equilla objects are created similar to Variables, by adding an Objects:-Block to the script and declaring the objects you want to use. For every object within a script one extension object will be instantiated. If you use the same indicator multiple times separate extension objects will be created for every script instance.

Objects:
    myObject("ProgID");


myObject.MyMethod();
For a detailed description of the Object syntax see the Equilla help.

Important Note: COM API Extension modules must be enabled in the options by selecting the setting at File > Options > Advanced > Equilla Extension.

Lifetime of an extension object

All extension objects go through a common life cycle.
  • Creation
  • There are multiple reasons why an extension object can be created.
    1. By the equilla editor to provide auto completion support.
    2. By the compiler to validate that the script is correct.
    3. Because the compiled script is loaded (e.g. indicator added to a chart)
  • If the extension object was loaded by the compile or editor no further actions will be performed and the object will be released shortly after. In case it was created by loading script the following actions will occur.
    • Attach Session (optional)
  • After loading a compiled script the virtual machine will first attach a session object. This is an optional step that is only performed if your extension implements the ISupportSessions Interface.
    • Attach Host Object (IEquillaExtension)
  • This call on the IEquillaExtension Interface is done before the actual script evaluation starts. It supplies the extension object with a thread safe Host-Object that can be used to trigger reevaluation of the script an provides information about the executing context.
    • Script Evaluation Phase
  • While a script is evaluated bar-by-bar, methods will be called and signals will be passed to the extension object.
    1. Methods called by script evaluation
      Once the script evaluation has started the virtual machine will call methods of your object as instructed by the script. These methods can contain multiple arguments of different type and a return value, as explained in Extension Supported Parameter Types.
    2. Signals received (optional)
      If your COM-Object implements any one of the Signal-Sink interfaces (Extension Signals and Sinks) signals will be passed to your extension after a bar is evaluated. SymbolStateChanged and interactive script alerts can be received at any time.
    • Detach (IEquillaExtension)
  • After script evaluation has stopped (e.g. indicator was removed from a chart) the Detach() method will be called on the IEquillaExtension Interface. Shortly after this the COM object will be released. All necessary clean up work should be performed at this point.

    Your Extension Interface

    The extension interface has to be derived from IEquillaExtension Interface and it should be the default interface of your COM-Object. If it is not the default interface the user will have to explicitly name it every time he wants to instantiate an equilla object.

    Equilla extension interfaces requirements and limitations:
    • Limited set of return and argument types (see Extension Supported Parameter Types)
    • Properties are not supported
    • default values are not supported
    • only 'dual' interfaces are supported

    Example Projects

    A few sample projects are shipped with Tradesignal. They are located in the install folder of Tradesignal.
    • ExcelOrderTracker (C#)
  • Demonstrates direct data transfer to Microsoft-Excel.
    • RSSExtension (C#)
  • Query of RSS 2.0 and Atom 1.0 data feeds, reacting on user interaction and display of custom user interface elements. This Extension is accompanied by the RSS-Indicator that can be found int the standard Tradesignal package.
  • Reading and processing of text file from an equilla script.