Next: , Previous: Importing the functions defined in the ARTE Core, Up: The ARTE Plugins

6.3 Exporting the plugin dictionary

As already explained, the main purpose of the Plugin is to create new commands that can be used within the TCL scripts of the ARTE RTAs. These set of new commands exported by a Plugin is known as the ‘PLUGIN dictionary’.

The new commands in a plugin are also named as ‘command-function’, because they are composed of a TCL-side (command) and a C-side (function). This can be seen in the arte_command_t structure which defines a given ‘command-function’, available in arte.h: 

     
     /** Struct to link the TCL command to a given C function */
     typedef struct
     {
       /** Command token to be used in the TCL scripts */
       const char *command_token;
       /** Command function to execute in the C side */
       int        (* command_func) (ClientData clientdata,
                                    Tcl_Interp *interprete,
                                    int argc,
                                    char **argv);
     } arte_command_t;

The Plugin will define an internal NUL-pointer-terminated array of ‘arte_command_t’ structures, with the exported ‘PLUGIN dictionary’: 

     
     /** Array with all the specific commands exported by the Generic
      *   Plugin */
     static arte_command_t _arte_ts_generic_commands[] = {
       { "helloworld",   __arte_ts_generic_command_helloworld   },
       { "byeworld",     __arte_ts_generic_command_byeworld     },
       { NULL,           NULL                                   }
     };

This array will be returned to the ARTE Core in the pointer returned by the previously shown arte_plugin_get_commands function.

Once the plugin is integrated at runtime with ARTE, you will be able to use the new commands exported in the ‘PLUGIN Dictionary’ directly in the TCL tests:

  1. The following script will just set the title of the Test (to be shown in the results report), print a debug message in the output ARTE log, and call the new helloworld command). 

              
          #testplugin1.tcl
          
          # Set test title...
          settitle "Dummy test trying the new commands"
          
          # Print a debug message...
          debug "Show a pretty log..."
          
          # It should print Hello World and continue
          helloworld
          
          # If any extra parameter is passed, it will fail
          helloworld Peter

  2. And yet another example using both the built-in ARTE Core commands and the new ones exported by the Plugin. 

              
          #testplugin2.tcl
          
          # Set test title...
          settitle "Built-in and new commands in action"
          
          # Print a debug message...
          debug "Show a pretty log..."
          
          # It should fail if the printed string is not the one expected
          failifdifferent [helloworld] "Hello World" "Not a hello world?"

Implementing new commands in the ‘PLUGIN Dictionary’ is a very good idea when you really need your own C code to perform an operation. You may for example, want to test an HTTP client library developed in C. For that, you may create new commands in the dictionary which internally use the API of the C library.