gpiCleanUp
Description
Clean up device's specific stuff. A clean up should be performed only once during the system's life cycle.
Pre-Condition(s)
N/A
Post-Condition(s)
N/A (i.e. specific to any given hardware platform).
Signature
Prototype
tGPIError gpiCleanUp (void);
Parameters
void
Returned Values
tGPIError: admNO_ERROR // Normal case of execution
Example
N/A
gpiCloseLibrary
Description
Close a dynamic library. Library closing is performed by the entry point to manage AFS services at disconnection time.
Pre-Condition(s)
A dynamic library must be loaded to working memory, and a valid library pointer is available (subsequently to a gpiOpenLibrary).
Post-Condition(s)
A dynamic library has been removed from working memory.
Signature
Prototype
void gpiCloseLibrary (void *library);
Parameters
void* library: in // Pointer to a system's dynamic library
Returned Values
void
Example
N/A
gpiFileClose
Description
Close a GPI file.
Pre-Condition(s)
A GPI file is opened, and a valid GPI file handler is available (subsequently to a gpiOpenFile).
Post-Condition(s)
A GPI file has been closed.
Signature
Prototype
tGPIError gpiFileClose (tFileHandler ifp);
Parameters
tFileHandler ifp: in // A GPI file handler provided at opening time
Returned Values
tGPIError: filNO_ERROR // Normal case of execution
Example
N/A
gpiFileDelete
Description
Delete a GPI file.
Pre-Condition(s)
A GPI file exits.
Post-Condition(s)
A GPI file has been deleted.
Signature
Prototype
tGPIError gpiFileDelete (const char* fileName);
Parameters
const char* fileName: in // A file's name to be deleted
Returned Values
tGPIError: filNO_ERROR // File deleted tGPIError: filFAILURE // Invalid file name or file not deleted
Example
N/A
gpiFileGetSize
Description
Get a GPI file's size.
Pre-Condition(s)
A GPI file exists.
Post-Condition(s)
A GPI file's length has been provided.
Signature
Prototype
tGPIError gpiFileGetSize (const char *fileName, tDataFileSize *length);
Parameters
const char* fileName: in // A file's name tDataFileSize* length: out // File's length
Returned Values
tGPIError: filNO_ERROR // File found and length has been set accordingly tGPIError: filFAILURE // Invalid file name or file not found
Example
N/A
gpiFileOpen
Description
Open a GPI file. Agnos persistent data model uses only BINARY files (TERMINAL, PROCESSING, ENTRY_POINT, CAKeys, CRL, and EFL). GPI files are used by Agnos Framework to manage configurations corresponding to acquirer/processor requirements.
Pre-Condition(s)
A GPI file exists.
Post-Condition(s)
A GPI file has been opened in a specific access mode, and a valid GPI file handler has been provided. File's seek cursor has been set to BEGIN.
Signature
Prototype
tGPIError gpiFileOpen (const char* fileName, tFileHandler* ifp, unsigned char openMode);
Parameters
const char* fileName: in // A file's name to be openned tFileHandler* ifp: out // GPI file handler between 1 and MAX. MAX file handler value depends on RAM availability. Default value is 5. unsigned char openMode: in // Opening mode to access the file
Returned Values
tGPIError: filNOT_FOUND // No more free GPI handlers tGPIError: filNO_ERROR // File found and handler has been set accordingly tGPIError: filFAILURE // Invalid file name
Example
#include "gpiplatform.h" tFileHandler ifp=0; char workingString[500]="", path[100]=""; strcpy(path,"/AGNOS"); sprintf(workingString,"%s/TERMINAL",path); gpiFileOpen(workingString,&ifp,CREATE|BINARY);
gpiFileRead
Description
Read a GPI file. Agnos persistent data model uses only BINARY files (TERMINAL, PROCESSING, ENTRY_POINT, CAKeys, CRL, and EFL). GPI files are used by Agnos Framework to manage configurations corresponding to acquirer/processor requirements.
Pre-Condition(s)
A GPI file is opened with read access, and a valid GPI file handler is available.
Post-Condition(s)
A buffer has been set from file' s data. GPI file's seek cursor has been updated to the last read position.
Signature
Prototype
tGPIError gpiFileRead (tFileHandler ifp, unsigned char *buffer, tDataFileSize *length);
Parameters
tFileHandler* ifp: in // GPI file handler provided at opening time unsigned char* buffer: out // A pointer to a buffer receiving data to be read tDataFileSize* length: in/out // Size to read (in), and actual size read (out)
Returned Values
tGPIError: filNO_ERROR // Data read tGPIError: filFAILURE // Invalid file name and read data length 0
Example
#include "gpiplatform.h"
char name[500]="", path=[100]="";
tByte buffer[100];
tFileHandler ifp = 0;
tDataFileSize sizeToRead = 50; // arbitrary value for the purpose of the example
strcpy(path,"/AGNOS");
sprintf(name,"%s/TERMINAL",path);
gpiFileOpen(name,&ifp,READ|BINARY);
if(ifp) {
gpiFileRead(ifp,buffer,&sizeToRead);
gpiFileClose(ifp);
}
gpiFileWrite
Description
Write a GPI file. Agnos persistent data model uses only BINARY files (TERMINAL, PROCESSING, ENTRY_POINT, CAKeys, CRL, and EFL). GPI files are used by Agnos Framework to manage configurations corresponding to acquirer/processor requirements.
Pre-Condition(s)
A GPI file is opened with write access, and a valid GPI file handler is available.
Post-Condition(s)
A GPI file has been set to buffer data. GPI file's seek cursor has been set to the last write position.
Signature
Prototype
tGPIError gpiFileWrite (tFileHandler ifp, unsigned char *buffer, tDataFileSize length);
Parameters
tFileHandler* ifp: in // GPI file handler provided at opening time unsigned char* buffer: in // A pointer to a buffer containing data to be written tDataFileSize length: in // Size to write
Returned Values
tGPIError: filNO_ERROR // Data written tGPIError: filFAILURE // Invalid file name and no data written
Example
N/A
gpiFreeTimer
Description
Free a GPI timer.
Pre-Condition(s)
A valid GPI timer handler is available (subsequently to a gpiGetTimer).
Post-Condition(s)
A GPI timer has been freed.
Signature
Prototype
tGPIError gpiFreeTimer (tTimerHandler timer);
Parameters
tTimerHandler timer: in // A GPI timer handler provided at creation time
Returned Values
tGPIError: admNO_ERROR // Normal case of execution tGPIError: admSYSTEM_ERROR // Invalid timer handler
Example
N/A
gpiGetDataObjectRAM
Description
Get available RAM address in order to store CL combinations. This primitive is used by the framework to manage transient data model.
Pre-Condition(s)
Data object RAM memory is statically available.
Post-Condition(s)
RAM has been reset to 0x00 (depends on GPI implementation).
Signature
Prototype
tGPIError gpiGetDataObjectRAM (unsigned char** ram, unsigned long* ramSize);
Parameters
unsigned char** ram: out // Pointer's address to fetch data object RAM address unsigned long* ramSize: out // Corresponding available size
Returned Values
tGPIError: admNO_ERROR // Normal case of execution tGPIError: admSYTEM_ERROR // Invalid pointer
Example
#include "gpiplatform.h" tByte *dataObjectBuffer=NULL; tDataFileSize maxDataObjectSize=0; gpiGetDataObjectRAM(&dataObjectBuffer,&maxDataObjectSize);
gpiGetDate
Description
Get system's date. Date is mandatory to set a payment context prior to a transaction triggering.
Pre-Condition(s)
N/A
Post-Condition(s)
N/A
Signature
Prototype
tGPIError gpiGetDate (unsigned char* currentDate);
Parameters
unsigned char* currentDate: out // YYYYMMDD - 4 byte long buffer
Returned Values
tGPIError: admNO_ERROR
Example
#include "gpiplatform.h" #include "paymentMW.h" tPaymentContext ctx; tByte data[4]; gpiGetDate(date); ctx.mTransactionDate[0] = toNumeric(date[1]); ctx.mTransactionDate[1] = toNumeric(date[2]); ctx.mTransactionDate[2] = toNumeric(date[3]);
gpiGetFreeRAM
Description
Get available RAM address in order to store free. This primitive is used by the Level3 so that RAM can be mutualized.
Pre-Condition(s)
Free RAM memory is statically available.
Post-Condition(s)
RAM has been reset to 0x00 (depends on GPI implementation).
Signature
Prototype
tGPIError gpiGetFreeRAM (unsigned char** ram, unsigned long* ramSize);
Parameters
unsigned char** ram: out // Pointer's address to fetch free RAM address unsigned long* ramSize: out // Corresponding available size
Returned Values
tGPIError: admNO_ERROR // Normal case of execution tGPIError: admSYSTEM_ERROR // Invalid pointer
Example
N/A
gpiGetLibraryFunction
Description
Get a dynamic library function's pointer. Library functions are managed by the entry point to support CL kernels activation.
Pre-Condition(s)
A dynamic library must be opened, and a valid library pointer is available (subsequently to a gpiOpenLibrary).
Post-Condition(s)
A pointer to a library's function has been provided (if function's name valid).
Signature
Prototype
void* gpiGetLibraryFunction (void *library, char *name);
Parameters
void *library: in // Dynamic library pointer provided at opening time char *name: in // Function's name
Returned Values
void*: function pointer // Function's address or 0 if invalid call
Example
N/A
gpiGetMaxTimer
Description
Get maximum timer supported by the GPI.
Pre-Condition(s)
N/A
Post-Condition(s)
N/A
Signature
Prototype
tGPIError gpiGetMaxTimer (tTimerHandler* timer)
Parameters
tTimerHandler* timer: in // Number of maximum timers
Returned Values
tGPIError: admNO_ERROR // Normal case of execution tGPIError: admSYSTEM_ERROR // Invalid timer
Example
N/A
gpiGetPrivateScratchPAD
Description
Get a private scratch pad to store proprietary and private information. This primitive is used by CL kernels to store torn information so that torn records are persistent between 2 different transactions.
Pre-Condition(s)
Scratch PAD RAM memory is statically available.
Post-Condition(s)
RAM has been reset to 0x00 (depends on GPI implementation).
Signature
Prototype
tGPIError gpiGetPrivateScratchPAD (unsigned char slot, unsigned char** ram, unsigned long* ramSize);
Parameters
unsigned char slot: in // Pad's proprietary identifier (i.e. kernel id) unsigned char** ram: out // Pointer's address to fetch scratch Pad RAM address unsigned long* ramSize: out // Corresponding available size
Returned Values
tGPIError: admNO_ERROR // Normal case of execution
Example
#include "gpiplatform.h" unsigned long ramSize=0; tByte *pRAM = NULL; tMCWTornTransaction* gTornTransaction = NULL; gpiGetPrivateScratchPAD(MASTERCARD_PAYPASS,&pRAM,&ramSize); if(ramSize >= (MAX_DEPTH * sizeof(tMCWTornTransaction)) && pRAM) gTornTransaction = (tMCWTornTransaction*)pRAM;
gpiGetRAMForTags
Description
Get available RAM address in order to store tags during a transaction (terminal's and card's EMV tags). This primitive is used by the framework when a new session is opened prior to an initiate.
Pre-Condition(s)
Tags RAM memory is statically available.
Post-Condition(s)
RAM has been reset to 0x00 (depends on GPI implementation).
Signature
Prototype
tGPIError gpiGetRAMForTags (unsigned char** ram, unsigned long* ramSize);
Parameters
unsigned char** ram: out // Pointer's address to fetch tags RAM address unsigned long* ramSize: out // Corresponding available size
Returned Values
tGPIError: admNO_ERROR // Normal case of execution tGPIError: admSYSTEM_ERROR // Invalid pointer
Example
N/A
gpiGetRAMForUnknownTags
Description
Get available RAM address in order to store unknown tags during a transaction (card's EMV tags). This primitive is used by the framework when a new session is opened prior to an initiate.
Pre-Condition(s)
Unknown tags RAM memory is statically available.
Post-Condition(s)
RAM has been reset to 0x00 (depends on GPI implementation).
Signature
Prototype
tGPIError gpiGetRAMForUnknownTags (unsigned char** ram, unsigned long* ramSize);
Parameters
unsigned char** ram: out // Pointer's address to fetch unknown tags RAM address unsigned long* ramSize: out // Corresponding available size
Returned Values
tGPIError: admNO_ERROR // Normal case of execution tGPIError: admSYSTEM_ERROR // Invalid pointer
Example
N/A
gpiGetTerminalIdentification
Description
Get terminal's identification (used to set 9F1C). This primitive is used by Agnos Framework to set terminal's profile in the scope of EMV contact Level2 TA.
Pre-Condition(s)
N/A
Post-Condition(s)
N/A
Signature
Prototype
tGPIError gpiGetTerminalIdentification (unsigned char* terminalId);
Parameters
unsigned char* terminalId: out // 9F1C as per EMVCo definition - 8 byte long buffer
Returned Values
tGPIError: admNO_ERROR // Normal case of execution
Example
N/A
gpiGetTime
Description
Get system's time. Time is mandatory to set a payment context prior to a transaction triggering.
Pre-Condition(s)
N/A
Post-Condition(s)
N/A
Signature
Prototype
tGPIError gpiGetTime (unsigned char* currentTime);
Parameters
unsigned char* currentDate: out // HHMMSS - 3 byte long buffer
Returned Values
tGPIError: admNO_ERROR
Example
#include "gpiplatform.h" #include "paymentMW.h" tPaymentContext ctx; tByte time[3]; gpiGetTime(time); ctx.mTransactionTime[0] = toNumeric(time[0]); ctx.mTransactionTime[1] = toNumeric(time[1]); ctx.mTransactionTime[2] = toNumeric(time[2]);
gpiGetTimer
Description
Get a GPI timer handler. A timer is a mechanism used by Agnos to measure elapsed time and to control timeouts. As Agnos is a synchroneous stack, timeout detection is managed through polling.
Pre-Condition(s)
At least one GPI timer handler is statically available.
Post-Condition(s)
A valid GPI timer handler has been provided.
Signature
Prototype
tGPIError gpiGetTimer(tTimerHandler* timer)
Parameters
tTimerHandler* timer: out // GPI time handler between 1 and MAX. MAX file handler value depends on RAM availability. Default value is 3.
Returned Values
tGPIError: admNO_ERROR // Normal case of execution tGPIError: admSYSTEM_ERROR // Invalid timer or no free handler available
Example
#include "gpiplatform.h"
tTimerHandler timerHandler=0;
tTimerState timerState=tsNONE;
tTimerTime timerElapsedSecond=0, timerElapsedMicrosecond=0;
gpiGetTimer(&timerHandler);
gpiGetTimerState(timerHandler,&timerState);
if(timerState!=tsRUNNING)
gpiStartTimer(timerHandler,2,0);
else
{
gpiGetTimerTime(timerHandler,&timerElapsedSecond,&timerElapsedMicrosecond);
gpiGetTimerState(timerHandler,&timerState);
if(timerState==tsTIMEOUT)
{
gpiStopTimer(timerHandler);
gpiFreeTimer(timerHandler);
}
}
ode>
gpiGetTimerState
Description
Get current timer's state.
Pre-Condition(s)
A GPI timer is running, and a valid timer handler is available (subsequently to a gpiGetTimer).
Post-Condition(s)
A GPI timer state has been provided.
Signature
Prototype
tGPIError gpiGetTimerState (tTimerHandler timer, tTimerState* state);
Parameters
tTimerHandler timer: in // GPI timer handler provided at creation time tTimerState* state: out // Current timer state
Returned Values
tGPIError: admNO_ERROR // Normal case of execution tGPIError: admSYSTEM_ERROR // Invalid GPI timer handler
Example
N/A
gpiGetTimerTime
Description
Get current timer's elapsed time.
Pre-Condition(s)
A GPI timer is running, and a valid timer handler is available (subsequently to a gpiGetTimer).
Post-Condition(s)
A GPI timer elapsed time is provided: elasped seconds + elpased micro-seconds. If timer is above timeout then its state has been set to tsTIMEOUT.
Signature
Prototype
tGPIError gpiGetTimerTime (tTimerHandler timer, tTimerTime* elapsed_second, tTimerTime* elapsed_microsecond)
Parameters
tTimerHandler timer: in // Timer handler tTimerTime* elapsed_second: out // Elapsed s time where timer's elapsed = (elapsed_second + elapsed_microsecond) tTimerTime* elapsed_microsecond: out // Elapsed us time where timer's elapsed = (elapsed_second + elapsed_microsecond)
Returned Values
tGPIError: admNO_ERROR // Normal case of execution tGPIError: admSYSTEM_ERROR // Invalid timer or elapsed parameters
Example
N/A
gpiGetTotalRAM
Description
Get total available RAM address in order to store huge amount of data (depending of platform's constraints). This primitive is used by the Level3 so that RAM can be mutualized.
Pre-Condition(s)
Total RAM memory is statically available.
Post-Condition(s)
RAM has been reset to 0x00 (depends on GPI implementation).
Signature
Prototype
tGPIError gpiGetTotalRAM (unsigned char** ram, unsigned long* ramSize);
Parameters
unsigned char** ram: out // Pointer's address to fetch total RAM address unsigned long* ramSize: out // Corresponding available size
Returned Values
tGPIError: admNO_ERROR // Normal case of execution tGPIError: admSYSTEM_ERROR // Invalid pointer
Example
N/A
gpiInitialize
Description
Initialize device's specific stuff and GPI internal mechanism (logger).
Pre-Condition(s)
N/A
Post-Condition(s)
N/A (i.e. specific to any given hardware platform).
Signature
Prototype
tGPIError gpiInitialize (const char* transactionLogName);
Parameters
const char* transactionLogName: in // Logger file's name
Returned Values
tGPIError: admNO_ERROR // Normal case of execution
Example
N/A
gpiMain
Description
Set GPI and corresponding device with proprietary parameters values.
Pre-Condition(s)
N/A
Post-Condition(s)
N/A (i.e. specific to any given hardware platform).
Signature
Prototype
tGPIError gpiMain (int argc, char ** argv);
Parameters
int argc: in // Number of parameters char ** argv: in // List of parameters
Returned Values
tGPIError: admNO_ERROR // Normal cas of execution
Example
#include "gpi.h"
char parameters[8/*number of parameters*/][5/*parameter max length*/];
char* sentParameters[] = {parameters[0],parameters[1],parameters[2],parameters[3],parameters[4],parameters[5],parameters[6],parameters[7]};
sprintf(parameters[0],"%d",traceDepth);
sprintf(parameters[1],"%d",automation);
sprintf(parameters[2],"%d",sDK);
sprintf(parameters[3],"%d",pollingTimeout);
sprintf(parameters[4],"%d",signal);
sprintf(parameters[5],"%d",APDULog);
sprintf(parameters[6],"%d",UIDisplay);
sprintf(parameters[7],"%d",Replay);
gpiMain(8,sentParameters); // Shall be called at the very beginning to allow specific initialization on the platform
gpiOpenLibrary
Description
Open a dynamic library. Library opening is performed by the entry point to manage AFS services at connection time.
Pre-Condition(s)
N/A
Post-Condition(s)
A dynamic library has been opened, and a valid library pointer has been provided (if library's name valid).
Signature
Prototype
void* gpiOpenLibrary(char *name)
Parameters
void* library: in // Dynamic library's name
Returned Values
void* library pointer // Pointer to a system's dynamic library provided at opening time or 0 if invalid call
Example
N/A
gpiRelease
Description
Release device's specific stuff and GPI internal mechanism (logger). This primitive may be called several times.
Pre-Condition(s)
N/A
Post-Condition(s)
N/A (i.e. specific to any given hardware platform).
Signature
Prototype
tGPIError gpiRelease (void);
Parameters
void
Returned Values
tGPIError: admNO_ERROR // Normal case of execution
Example
N/A
gpiResetTimers
Description
Reset all GPI timers.
Pre-Condition(s)
N/A
Post-Condition(s)
GPI timer(s) has(ve) been freed.
Signature
Prototype
tGPIError gpiResetTimers (void);
Parameters
void
Returned Values
tGPIError: admNO_ERROR // Normal case of execution
Example
N/A
gpiSetDateTime
Description
Set system's date and time.
Pre-Condition(s)
N/A
Post-Condition(s)
New system's date and time have been set.
Signature
Prototype
tGPIError gpiSetDateTime(unsigned char* currentDateTime);
Parameters
unsigned char* currentDateTime: in // YYMMDDHHMMSS
Returned Values
tGPIError: admNO_ERROR
Example
#include "platform.h" #include "paymentMW.h" tPaymentContext ctx; tByte datetime[6]; datetime[0] = bcdToDecimal(ctx.mTransactionDate[0]); datetime[1] = bcdToDecimal(ctx.mTransactionDate[1]); datetime[2] = bcdToDecimal(ctx.mTransactionDate[2]); gpiGetTime(time); memcpy(datetime+3,time,3); gpiSetDateTime(datetime);
gpiSleep
Description
Sleep during a specific time. This primitive is used to pace a transaction allocating enough time to allow the cardholder to read a message for example.
Pre-Condition(s)
N/A
Post-Condition(s)
N/A
Signature
Prototype
tGPIError gpiSleep (unsigned long ms)
Parameters
unsigned long ms: in // Sleeping time in ms
Returned Values
tGPIError: admNO_ERROR
Example
N/A
gpiStartTimer
Description
Start a GPI timer.
Pre-Condition(s)
A GPI timer is running, and a valid GPI timer handler is available (subsequently to a gpiGetTimer).
Post-Condition(s)
A GPI timer has been started, and its state is set to tsRUNNING.
Signature
Prototype
tGPIError gpiStartTimer (tTimerHandler timer, tTimerTimeout timeout_second, tTimerTimeout timeout_microsecond);
Parameters
tTimerHandler timer: in // GPI timer handler provided at creation time tTimerTimeout timeout_second: in // Timeout s where timer's timeout = (timeout_second + timeout_microsecond) tTimerTimeout timeout_microsecond: in // Timeout us where timer's timeout = (timeout_second + timeout_microsecond)
Returned Values
tGPIError: admNO_ERROR // Normal ase of execution tGPIError: admSYSTEM_ERROR // Invalid GPI timer handler or timer in tsRUNNING state or timer in tsTIMEOUT state
Example
N/A
gpiStopTimer
Description
Stop a GPI timer.
Pre-Condition(s)
A GPI timer is running, and a valid GPI timer handler is available (subsequently to a gpiGetTimer).
Post-Condition(s)
A GPI timer has been stopped, and its state has been set to tsSTOPPED. If timer is above timeout then its state has been set to tsTIMEOUT.
Signature
Prototype
tGPIError gpiStopTimer (tTimerHandler timer);
Parameters
tTimerHandler timer: in // GPI timer handler provided at creation time
Returned Values
tGPIError: admNO_ERROR // Normal case of execution tGPIError: admSYSTEM_ERROR // Invalid GPI timer handler or timer already in tsSTOPPED state
Example
N/A