Menu

Accessing API through Plugin Interface

 
      A plugin is a program extension module that is not part of the main application, but which can be accessed by the application to extend its functionality. The Gtuner plugin interface is a simple Windows API that Windows programmers will find straightforward to use. The effort involved writing a Gtuner plugin depends on the sophistication of the processing done by the plugin code. A programmer experienced in Microsoft Visual C++ programming can write an elementary plugin in a matter of minutes.
 
      All is needed to make a plugin is an understanding of Windows programming using Microsoft Visual C++, or an equivalent development tool. You can download the Microsoft Visual C++ 2010 Express Edition for free.
 
  Plugin Interface Functions:
 
gpp_PluginName   Provides to Gtuner the name of the plugin
gpp_Load         Called when plugin is loaded
gpp_Unload       Called when plugin is unloaded
gpp_ReportUpdate Called when a new set of data is avaliable
 
  Creating a Gtuner Plugin:
 
 
Don't forget to define GPPAPI_PLUGIN before include the gppapi.h header.
#define GPPAPI_PLUGIN
#include "gcapi.h"
 

  1. gpp_PluginName (mandatory)

      Provides to Gtuner application the name of the plugin, this is the string that will be showed in the application menu.
 
  Prototype:
 
const char * _stdcall gpp_PluginName (  )
 
  Parameters:
 
None
 
  Return:
 
Returns a zero-ended string with the name of plugin
 
  Example:
 
const char * _stdcall gpp_PluginName() {
  return("Gtuner Plugin Template");
}
 

  2. gpp_Load (mandatory)

      The Gtuner software calls the plugin API function gpp_Load when the plugin dll is loaded. Use this function to set up the callback functions, allocate the memory and resources needed by your plug-in.
 
  Prototype:
 
uint8_t _stdcall gpp_Load ( HMODULE hmodule, uint16_t sw_version, GPPAPI_CALLBACKS *callbacks )
 
  Parameters:
 
<HMODULE>          : the hmodule of DLL
<uint16_t>         : the software version
<GPPAPI_CALLBACKS> : pointers to callback functions
 
  Return:
 
1 on success, or return 0 on failure
 
  Example:
 
uint8_t _stdcall gpp_Load(HMODULE hmodule, uint16_t sw_version, GPPAPI_CALLBACKS *callbacks) {
  if(sw_version < 0x0205) return(0);
 
  gcapi_IsConnected = callbacks->IsConnected;
  gcapi_GetFWVer = callbacks->GetFWVer;
  gcapi_Read = callbacks->Read;
  gcapi_Write = callbacks->Write;
  gcapi_GetTimeVal = callbacks->GetTimeVal;
  gcapi_CalcPressTime = callbacks->CalcPressTime;
  gpp_Exit = callbacks->Exit;
  gpp_Proc = callbacks->Proc;
 
  // TODO: Allocate memory and resources
 
  return(1);
}
 

  3. gpp_Unload

      The Gtuner software calls the plugin API function gpp_Unload (if defined) when is need to immediately quit the plugin, for example, in case the user has closed the Gtuner application. Use this function to free the memory and resources.
 
  Prototype:
 
void _stdcall gpp_Unload (  )
 
  Parameters:
 
None
 
  Return:
 
None
 
  Example:
 
void _stdcall gpp_Unload() {
  // TODO: Free memory and resources
  return;
}
 

  4. gpp_ReportUpdate

      The Gtuner software calls the plugin API function gpp_ReportUpdate (if defined) whenever it receives a new set of data from device. You can use this function to read the input data (from controller) and/or to set the output data (which will be sent to the console).
 
  Prototype:
 
void _stdcall gpp_ReportUpdate (  )
 
  Parameters:
 
None
 
  Return:
 
None
 
  Example:
 
void _stdcall gpp_ReportUpdate() {
  GCAPI_REPORT report;
  int8_t output[GCAPI_OUTPUT_TOTAL] = {0};
 
  if(gcapi_Read) {
      gcapi_Read(&report);
      for(uint8_t i=0; i<GCAPI_INPUT_TOTAL; i++) {
        output[i] = report.input[i].value;
      }
      if(gcapi_Write) {
        gcapi_Write(output);
      }
  }
  return;
}

 

Step-by-step to create a new VC++ project

 

Start up the Visual C++ IDE

 
 

From the File menu

click New -> Project...
 

In the New Project dialog

select Win32 Project and enter a project name.
 

In the Win32 Application Wizard

click next to go to "Application Settings Tab", and select:
  • Application type: DLL
  • Additional options: Empty project
 

Copy the gcapi.h file into the project directory

 
 

In the Solution Explorer

right click on Header Files -> Add -> Existing Item...
  • select the file gcapi.h
 

In the Solution Explorer

right click on Source Files -> Add -> New Item...
  • select: C++ File (.cpp)
  • enter a file name (eg. <gtuner_plugin>.cpp)
 

Double click on the <gtuner_plugin>.cpp file

to open it in the Source Editor. Copy-paste the following code:
 
#define GPPAPI_PLUGIN
#include "gcapi.h"
 
GCAPI_IsConnected gcapi_IsConnected = NULL;
GCAPI_GetFWVer gcapi_GetFWVer = NULL;
GCAPI_Read gcapi_Read = NULL;
GCAPI_Write gcapi_Write = NULL;
GCAPI_GetTimeVal gcapi_GetTimeVal = NULL;
GCAPI_CalcPressTime gcapi_CalcPressTime = NULL;
GPPAPI_Exit gpp_Exit = NULL;
GPPAPI_Proc gpp_Proc = NULL;
 
const char * _stdcall gpp_PluginName() {
  return("Plugin Name");
}
 
uint8_t _stdcall gpp_Load(HMODULE hmodule, uint16_t sw_version, GPPAPI_CALLBACKS *callbacks) {
  if(sw_version < 0x0131) return(0);
   
  gcapi_IsConnected = callbacks->IsConnected;
  gcapi_GetFWVer = callbacks->GetFWVer;
  gcapi_Read = callbacks->Read;
  gcapi_Write = callbacks->Write;
  gcapi_GetTimeVal = callbacks->GetTimeVal;
  gcapi_CalcPressTime = callbacks->CalcPressTime;
  gpp_Exit = callbacks->Exit;
  gpp_Proc = callbacks->Proc;
 
  // TODO: Allocate memory and resources
 
  return(1);
}
 
void _stdcall gpp_Unload() {
  // TODO: Free memory and resources
  return;
}
 
void _stdcall gpp_ReportUpdate() {
  GCAPI_REPORT report;
  int8_t output[GCAPI_OUTPUT_TOTAL] = {0};
 
  if(gcapi_Read) {
      gcapi_Read(&report);
      for(uint8_t i=0; i<GCAPI_INPUT_TOTAL; i++) {
        output[i] = report.input[i].value;
      }
      if(gcapi_Write) {
        gcapi_Write(output);
    }
  }
  return;
}
 

Create a file called <project_name>.def

into the project directory. Copy-paste the following lines:
 
LIBRARY   "<project_name>"
 
EXPORTS
      gpp_PluginName   @1
      gpp_Load         @2
      gpp_Unload       @3
      gpp_ReportUpdate @4
 

The <project_name>.def file should be given as an option to the linker

Add <project_name>.def as a linker option, or provide "<project_name>.def" in the "Module definition file" field (Input category) in the project properties (Linker options).
 

Gtuner Plugin Template

You can use the Gtuner plugin template to create the basic project container and a preliminary setups for your plugin. Unzip and open the "Gtuner Plugin Template.sln" with Visual C++ 2010 (or newer).
 
• Download: Gtuner Plugin Template