GInsData Library

Introduction

The libraries and examples are included in the GI.bench setup. By default, these files are installed in the following directory: C:\Users\Public\Documents\Gantner Instruments\GI.bench\api.

• Windows x86, amd64
• Linux x86, amd64
• Q.series Classic and X controllers

• C-style API utilizing primitive data types exclusively.
• C++ object-oriented API employing interface classes (C++11 support is necessary).

Types of data access

• Online data (reading, writing).

• Time-equidistant buffered data (reading).

• Stored data files (transferring, decoding, deleting, etc.). 

• Diagnostic data/states Real-time clock (reading, writing).

The subsequent chapters provide detailed instructions on utilizing these features with the GInsData API.

Online data communication means reading/writing actual values on the controller (live data/process image) through TCP/IP.

Init an online communication interface
If initialization succeeds, the library internally keeps all relevant information about the connected controller.

• C - API: use the function eGateHighSpeedPort_init with the correct mode (HSP_ONLINE), the controller's IP address, and the connection timeout. If successful, the function returns 2 handles to access the internal connection object with all the following functions. Don't forget to close the connection when finished, otherwise, the connection will stay alive until the DLL is unloaded.
• C++ API: create an interface object IGInsDevice using the factory method which takes the IP address as a parameter. If the returned shared pointer is valid, the connection was successful. The connection is closed automatically when no copy of the shared pointer is in scope anymore. Example:

GIns::Data::GInsDevicePtr device = GIns::Data::IGInsDevice::CreateIGInsDevicePtr(192.168.1.18,10);

Read controller or variable information

• C API: use eGateHighSpeedPort_GetDeviceInfo to read all needed controller information like location, version, channel count, and sample rate, …
• C++ API: read info using the header information of the controller interface.

std::string location   = device->HeaderInterface()->GetLocation();
std::string firmware   = device->HeaderInterface()->GetFirmwareVersion();
uint16_t channelcnt    = device->HeaderInterface()->GetVariableCount();
...

3. Access Data

Access either single variables directly or read the complete controller data frame simultaneously.

Examples

• GInsData_C_API_Online (C)
• GInsData_HighSpeedPort_Online (C++)

Buffered data communication

Buffered data communication means reading the data stream of a controller's circular buffer through TCP/IP.

1. Init / Connect

Init a buffered communication interface to a specific buffer. If initialization succeeds, the library internally keeps all relevant information about the connected controller.

• C - API: use the function eGateHighSpeedPort_Init with the correct mode (HSP_BUFFER), the controller's IP address, and the connection timeout. If successful, the function returns two handles to access the internal connection object with all the following functions. For buffered communication, a second initialization step is required; eGateHighSpeedPort_InitBuffer has to be used to select a buffer on the controller by index. Don't forget to close the connection when finished, otherwise, the connection will stay live until the DLL is unloaded.
• C++ API: create an interface object IGInsDataSource using the factory method which takes the IP address and a buffer index as parameters. If the returned shared pointer is valid, the connection was successful. There are several other types of IGInsDataSource available:

• • Connect to a circular buffer on the controller (see Q.Station plugin development)
  • Connect to a PostProcess buffer on the controller or PC
  • Connect to a data file
  • …

The interface class IGInsDataSource abstracts these different data source types providing a uniform interface on any platform.

The connection is closed automatically when no copy of the shared pointer is in scope anymore.

2. Get info

Read necessary controller or variable information

Load block of data, iterate through data frames and decode single values or let the library decode all data to a double array.

• GInsData_C_API_Buffer (C)
• GInsData_HighSpeedPort_Buffer (C++)

Read data from the controller or server via TCP/IP to a local directory.

Initialize an online communication interface.

2. Find / List Files

List available files (maybe by specifying limits)

3. Read Files

Read a file from the controller to a local directory.

4. Delete Files

Delete file

Examples

• GInsData_C_API_FileTransfer (C)
• GInsData_HighSpeedPort_FileTransfer (C++)

Access and decode binary measurement data from a local path.

1. Init/load
   Load the file header (like initialization of a buffered data communication)

2. Get info
   Read controller or variable information

3. Access data
   Load block of data, iterate through data frames and decode single values or let the library decode all data to a double array

• GInsData_C_API_File (C)
• GInsData_File (C++)

Read module communication diagnostic through TCP/IP.

• GInsData_C_API_Diagnostic (C)
• GInsData_HighSpeedPort_Diagnostic (C++)

Under construction
This interface should give direct (time range-based) data access to file archives.

eGateHighSpeedPort (C API)

The C-API of the GInsData library was originally developed as a Windows-only library for online data communication (eGateHighSpeedPort.dll). It uses only primitive C-style functions that can easily be used from several other programming languages like C#, VB, LabView, and Delphi, ...

To remove limits like platform dependence or performance, but still keep compatibility with various programs using this DLL, the interface of eGateHighSpeedPort.dll is implemented identically on top of the new GInsData library and remains the C-style API implemented by simply wrapping the new C++ API.

Since there were a couple of bugs fixed during re-implementation, it makes sense to replace the old eGateHighSpeedPort.dll with the new compatible binary. Simply renaming the artifact GInsData-x86.dll to eGateHighSpeedPort.dll will be enough.

Some documentation about the C-API can be found in the header eGateHighSpeedPort.h or here.

C++ API

(under construction)