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:
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