gpiAdvancedDisplay
Description
Send a UI signal, display message, and sleep for a specific time.
Pre-Condition(s)
N/A
Post-Condition(s)
A UI signal has been raised, and the corresponding message has been displayed followed by a sleeping time.
Signature
Prototype
tGPIError gpiAdvancedDisplay (tUIRequestData* UIRequestData);
Parameters
tUIRequestData* UIRequestData: in // UI signal
Returned Values
tGPIError: admNO_ERROR // Normal case of execution
Example
N/A
gpiAdvancedDisplayAsOutcome
Description
Send a UI signal as outcome.
Pre-Condition(s)
N/A
Post-Condition(s)
A UI signal as outcome has been raised.
Signature
Prototype
tGPIError gpiAdvancedDisplayAsOutcome (tUIRequestData* UIRequestData);
Parameters
tUIRequestData* UIRequestData: in // UI signal
Returned Values
tGPIError: admNO_ERROR // Normal case of execution
Example
N/A
gpiBeep
Description
Generate a beep at a specific frequency for a specific duration.
Pre-Condition(s)
N/A
Post-Condition(s)
A beep has been emitting for a specific duration at a specific frequency.
Signature
Prototype
tGPIError gpiBeep(unsigned short duration, unsigned short frequency);
Parameters
unsigned short duration: in // in ms unsigned short frequency: in // in ms
Returned Values
tGPIError: admNO_ERROR // Normal case of execution
Example
#include "paymentMW.h"
#include "gpisped.h"
tOutComeParameter out;
out.mOutCome = ocDECLINED;
switch(out.mOutCome)
{
case ocDECLINED :
gpiBeep(BEEP_NOK,NO_FREQUENCY);
break;
case ocAPPROVED :
gpiBeep(BEEP_OK,NO_FREQUENCY);
break;
default:
break;
}
If there is no analog LED on the platform then a beep shall be used to measure system's performance. gpiBeep primtive is called by CL kernels and Level3. Since most of the platforms do not support duration and/or frequency management, and considering that it is crucial to keep CL kernels implementations stable, Agnos framework uses the following calls:
gpiBeep(0,0) to emit a NOK beep
gpipBeep(1,0) to emit a OK beep
Hence, gpiBeep implementations shall always process these two specific cases where frequency is 0. Else, CL kernels won't generate a beep at the end of the EMV flow.
However, this constraint doesn't prevent a specific Level3 to manage duration and frequency parameters if a given platform supports them.
gpiCancelledTransaction
Description
Get cancellation status.
Pre-Condition(s)
N/A
Post-Condition(s)
N/A
Signature
Prototype
unsigned char gpiCancelledTransaction (void);
Parameters
void
Returned Values
unsigned char: cancellation status // gpi_true if transaction must be cancelled. Else, gpi_false
Example
N/A
gpiClearScreen
Description
Clear display.
Pre-Condition(s)
N/A
Post-Condition(s)
Display has been cleared.
Signature
Prototype
tGPIError gpiClearScreen (void);
Parameters
void
Returned Values
tGPIError: admNO_ERROR // Normal case of execution
Example
N/A
gpiDisplayMessage
Description
Display a message.
Pre-Condition(s)
Display's current line is lower than display's maximum lines available.
Post-Condition(s)
A message has been displayed on the display's current line, and the display's current line has been incremented.
Signature
Prototype
tGPIError gpiDisplayMessage (unsigned char clearScreen, const char* message);
Parameters
unsigned char clearScreen: in // Flag indicating to clear the screen prior the message display const char* message // String to display
Returned Values
tGPIError: admNO_ERROR // Normal case of execution
Example
N/A
gpiDisplayPollingMessage
Description
Display up to 3 messages dedicated to polling's prompt.
Pre-Condition(s)
0, 1, 2, and/or 3 polling message(s) are defined.
Post-Condition(s)
0, 1, 2, and/or 3 polling message(s) have been displayed before the polling has been initiated.
Signature
Prototype
tGPIError gpiDisplayPollingMessage (void);
Parameters
void
Returned Values
tGPIError: admNO_ERROR // Normal case of execution
Example
N/A
gpiEmptyKeyPadCache
Description
Empty keypad's cache.
Pre-Condition(s)
N/A
Post-Condition(s)
N/A
Signature
Prototype
tGPIError gpiEmptyKeyPadCache (void);
Parameters
void
Returned Values
tGPIError: admNO_ERROR // Normal case of execution
Example
N/A
gpiGetCurrentDisplayLine
Description
Get display's current available line.
Pre-Condition(s)
N/A
Post-Condition(s)
N/A
Signature
Prototype
tGPIError gpiGetCurrentDisplayLine (int* line)
Parameters
int* line: out // Available line identifier
Returned Values
tGPIError: admNO_ERROR // Normal case of execution
Example
N/A
gpiInitializeDisplay
Description
Initialize GPI display context.
Pre-Condition(s)
N/A
Post-Condition(s)
N/A (i.e. specific to any given hardware platform).
Signature
Prototype
tGPIError gpiInitializeDisplay (const char* inifile, unsigned char * count, void* arg);
Parameters
const char* inifile: in // File's name storing the string table (if supported) unsigned char * count: out // Number of languages supported void* arg: in // Generic structure to initialize GPI display depending on the platform constraints (if supported)
Returned Values
tGPIError: admNO_ERROR // Normal case of execution
Example
N/A
gpiGetLanguageCodeOfId
Description
Get language identifier from language code.
Pre-Condition(s)
A string table is loaded.
Post-Condition(s)
N/A
Signature
Prototype
tGPIError gpiGetLanguageCodeOfId (const unsigned char langId, const char ** code);
Parameters
const unsigned char langId: in // Language code as defined by ISO const char ** code: out // String table's language identifier
Returned Values
tGPIError: admNO_ERROR // Normal case of execution
Example
N/A
gpiGetLastDisplayLine
Description
Get display's last available line.
Pre-Condition(s)
N/A
Post-Condition(s)
N/A
Signature
Prototype
tGPIError gpiGetLastDisplayLine(int * line)
Parameters
int* line: out // Last available line identifier
Returned Values
tGPIError: admNO_ERROR // Normal case of execution
Example
N/A
gpiGetKeyIn
Description
Get key code that was hit on the keypad. This primitive call is blocking.
Pre-Condition(s)
N/A
Post-Condition(s)
N/A
Signature
Prototype
tGPIError gpiGetKeyIn (unsigned char* key)
Parameters
unsigned char* key: out // Key code corresponding to keypad's key
Returned Values
tGPIError: admNO_ERROR // Normal case of execution
Example
N/A
gpiGetLanguage
Description
Try to match a Language from languagePreference and the languages supported by the Terminal (ISO 639-1).
Pre-Condition(s)
A string table is loaded.
Post-Condition(s)
N/A
Signature
Prototype
tGPIError gpiGetLanguage (const unsigned char *languagePreference, const unsigned char languagePreferenceLen, unsigned char * lang);
Parameters
const unsigned char *languagePreference: in // EMV card's language preference by order of priority const unsigned char languagePreferenceLen: in // EMV card's language preference length unsigned char * lang: out // String table language identifier. Set to LANGUAGE_NOT_FOUND if no match
Returned Values
tGPIError: admNO_ERROR // Normal case of execution
Example
N/A
gpiGetNbLanguage
Description
Get number of languages supported by the current string table.
Pre-Condition(s)
A string table is loaded.
Post-Condition(s)
N/A
Signature
Prototype
tGPIError gpiGetNbLanguage (unsigned char * count);
Parameters
unsigned char * count: out // Number of languages available
Returned Values
tGPIError: admNO_ERROR // Normal case of execution
Example
N/A
gpiGetString
Description
Get string corresponding to a language and an identifier.
Pre-Condition(s)
A string table must be loaded.
Post-Condition(s)
N/A
Signature
Prototype
tGPIError gpiGetString (const unsigned char langId, const unsigned char stringId, char ** string);
Parameters
const unsigned char langId: in // Language const unsigned char stringId: in // String identifier char ** string: out // String
Returned Values
tGPIError: admNO_ERROR // Normal case of execution
Example
N/A
gpiPINEnter
Description
Capture a PIN block from a cardholder PIN entry.
Pre-Condition(s)
A card has been processed, an online PIN enciphering key must be defined, and an ISO encryption method must be chosen.
Post-Condition(s)
A PIN block has been calculated from cardholder PIN entry.
Signature
Prototype
tGPIError gpiPINEnter (const char* pinPadName, unsigned int lan, unsigned char* encryptedPIN, unsigned char* encryptedLen, int timeout, unsigned char sred);
Parameters
const char* pinPadName: in // PIN pad. Used also to flag a Level3 call to discriminate the gpiPINEnter request at the end of a transaction flow (EMV CL and magstripe transaction) unsigned int lan: in // Prompt language to be used unsigned char* encryptedPIN: in/out // PAN (in), and PIN block (out) unsigned char* encryptedLen: in/out // PAN lenght (in), and PIN block length (out) int timeout: in // PIN entry time out. -1 means no time limit unsigned char sred: in // If 1, PAN must be fetched and processed from a secure part
Returned Values
tGPIError: pinNO_ERROR // Normal case of execution tGPIError: pinTIMEOUT // PIN not entered during the elapse time tGPIError: pinPINPAD_MALFUNCTIONING tGPIError: pinPIN_BLOCK_RECOVERY_FAILED tGPIError: pinNO_REMAINING_PIN_TRIES // EMV offline PIN specific tGPIError: pinPIN_BLOCKED // EMV offline PIN specific tGPIError: pinABORT // User cancelled PIN entry tGPIError: pinPROCESSFAILED
Example
There are 4 different contexts of use for this primitive:
At the beginning of an EMV contact transaction, at an ATM: the pin shall be captured before the transaction flow (note that this use case might also be applied at a merchant store to parallelize pin entry and card processing)
During an EMV contact transaction, CVM online PIN execution: the pin shall be captured within the transaction flow
During an EMV contactless transaction, CVM online PIN execution: the pin shall not captured within the transaction flow
At the end of an EMV contactless or magstripe transaction, L3 call: the pin shall be captured after the transaction flow. For that case, it is up to Level3 to define a specific flag. Example codes use “AFTER_EMV_TRANSACTION” in place of pinPadName.
// Case 1
// See [[framework:atm|ATM]] page
// Case 2 and Case 3: typically, this call is encapsulated wityin the Agnos library
#include "agnosinternal.h"
#include "gpisped.h"
tInternalContext ctx;
tGPIError gpiError;
tByte encryptedlen = 0;
tByte encryptedPIN[MAX_ENCRYPTED_PIN_LEN];
encryptedlen = TAG_LENGTH(DATABASE, _5A); // Get PAN length from database
memcpy(encryptedPIN,TAG_INDEX(DATABASE, _5A),encryptedlen); // Get PAN from database
gpiError = gpiPINEnter(ctx->mPinPadName,ctx->mLanguage,encryptedPIN,&encryptedlen,ctx->mPinTimeOut,ctx->mSRED);
// Case 4: typically, this call is performed from Level3
#include "datamngr.h"
#include "paymentMW.h"
#include "agnos.h"
#include "gpisped.h"
tByte PINBlock[100]="";
tByte PINBlockLen=0;
tByte i;
tTerminalContext *terminalCtx = (tTerminalContext*)dtmGetData(TERMINAL_CTX);
tBoolean sredMode = bFALSE;
if(terminalCtx)
sredMode = terminalCtx->mSRED;
agnGetEMVTag(pay->mSession,0x5A,&PINBlockLen,PINBlock);
if (PINBlockLen==0) // Get PAN from PAN equivalent data if missing
{
agnGetEMVTag(pay->mSession,0x57,&PINBlockLen,PINBlock);
for (i=0;i<PINBlockLen;i++)
{ // Search for track2 separator 'D'
if ((PINBlock[i] & 0xF0) == 0xD0)
{
PINBlockLen = i;
break;
}
else if ((PINBlock[i] & 0x0F) == 0x0D)
{
PINBlockLen = i+1;
PINBlock[i] ^= 0x0F; // Set separator to F;
break;
}
}
}
gpiPINEnter("AFTER_EMV_TRANSACTION",pmwGetLanguage(pay),PINBlock,&PINBlockLen,0,sredMode); // Calling flag set to AFTER_EMV_TRANSACTION
agnSetEMVTag(pay->mSession,0x99,PINBlockLen,PINBlock);
gpiPINVerifyPlaintext
Description
Manage plain text offline PIN during CVM execution as per EMVCo specifications.
Pre-Condition(s)
A standard EMV contact transaction led to offline PIN processing state and gContactlessTransactionInProgress is set accordingly.
Post-Condition(s)
Offline PIN has been processed.
Signature
Prototype
tGPIError gpiPINVerifyPlaintext (const char* deviceName, const char* pinPadName, unsigned int lan, char verifyOnly, int timeout, int remainingAttempt);
Parameters
const char* deviceName: in // Reader const char* pinPadName: in // Pin pad unsigned int lan: in // Prompt's language char verifyOnly: in // RFU. Flag indicating that PIN has already been entered int timeout: in // PIN entry time out. -1 means no time limit int remainingAttempt: in // Remaining attempts before PIN entry
Returned Values
tGPIError: pinNO_ERROR // Normal case of execution tGPIError: pinTIMEOUT // PIN not entered during the elapse time tGPIError: pinPINPAD_MALFUNCTIONING tGPIError: pinPIN_BLOCK_RECOVERY_FAILED tGPIError: pinNO_REMAINING_PIN_TRIES // EMV offline PIN specific tGPIError: pinPIN_BLOCKED // EMV offline PIN specific tGPIError: pinABORT // User cancelled PIN entry tGPIError: pinPROCESSFAILED
Example
N/A
gpiPINVerifyCiphered
Description
Manage ciphered offline PIN during CVM execution as per EMVCo specifications.
Pre-Condition(s)
A standard EMV contact transaction led to offline PIN processing state.
Post-Condition(s)
Offline PIN has been processed.
Signature
Prototype
tGPIError gpiPINVerifyCiphered (const char* deviceName, const char* pinPadName, unsigned int lan, char verifyOnly, tEMVPubKey* key, int timeout, int remainingAttempt);
Parameters
const char* deviceName: in // Reader const char* pinPadName: in // Pin pad unsigned int lan: in // Prompt's language char verifyOnly: in // RFU. Flag indicating that PIN has already been entered tEMVPubKey* key: in // Public key used to cipher offline PIN int timeout: in // PIN entry time out. -1 means no time limit int remainingAttempt: in // Remaining attempts before PIN entry
Returned Values
tGPIError: pinNO_ERROR // Normal case of execution tGPIError: pinTIMEOUT // PIN not entered during the elapse time tGPIError: pinPINPAD_MALFUNCTIONING tGPIError: pinPIN_BLOCK_RECOVERY_FAILED tGPIError: pinNO_REMAINING_PIN_TRIES // EMV offline PIN specific tGPIError: pinPIN_BLOCKED // EMV offline PIN specific tGPIError: pinABORT // User cancelled PIN entry tGPIError: pinPROCESSFAILED
Example
N/A
gpiSetKeypadTimeout
Description
Set time out between two subsequent key hits.
Pre-Condition(s)
N/A
Post-Condition(s)
A Key pad time out has been set.
Signature
Prototype
tGPIError gpiSetKeypadTimeout(int timeout)
Parameters
int timeout: in // Time out in s
Returned Values
tGPIError: admNO_ERROR // Normal case of execution
Example
N/A
gpiScanKeyIn
Description
Get key code that was hit on the keypad. This primitive call is not blocking.
Pre-Condition(s)
N/A
Post-Condition(s)
N/A
Signature
Prototype
tGPIError gpiScanKeyIn (unsigned char* key);
Parameters
unsigned char* key: out // Key code corresponding to keypad's key
Returned Values
tGPIError: admNO_ERROR // Normal case of execution
Example
N/A
gpiSetPollingMessage
Description
Set messages to displayed at polling time.
Pre-Condition(s)
N/A
Post-Condition(s)
Up to 3 messages to be displayed at polling time have been set.
Signature
Prototype
tGPIError gpiSetPollingMessage (const char* line1, const char* line2, const char* line3);
Parameters
const char* line1: in // Message displayed on line 1 const char* line2: in // Message displayed on line 2 const char* line3: in // Message displayed on line 3
Returned Values
tGPIError: admNO_ERROR // Normal case of execution
Example
N/A
gpiSwitchDisplayBackLight
Description
Set back light to on/off.
Pre-Condition(s)
N/A
Post-Condition(s)
Display's backlight has been set to on or off.
Signature
Prototype
tGPIErrortGPIError gpiSwitchDisplayBacklight (unsigned char flag);
Parameters
unsigned char flag: in // Flag is within {gpi_false, gpi_true}
Returned Values
tGPIError: admNO_ERROR // Normal case of execution
Example
N/A
gpiSwitchLED
Description
Switch a specific LED to on/off at a specific color.
Pre-Condition(s)
N/A
Post-Condition(s)
A LED has been switched to on or off and to a specific color.
Signature
Prototype
tGPIError gpiSwitchLED (unsigned char led, unsigned char flag, unsigned char colour);
Parameters
unsigned char led: in // LED identifier is within {LED_1,LED_2,LED_3,LED_4}
unsigned char flag: in // Flag is within {gpi_false, gpi_true}
unsigned char colour: in // LED color is within {BLUE, ORANGE,RED,GREEN}
Returned Values
tGPIError: admNO_ERROR // Normal case of execution
Example
gpiSwitchLED is used by CL kernels to display transaction flow progression, and by Level3 to display final transaction status. There are no actual requirements but only recommendations (excepted for Visa AP however).
#include "paymentMW.h"
#include "gpisped.h"
tOutComeParameter out;
out.mOutCome = ocDECLINED;
switch(out.mOutCome)
{
case ocDECLINED :
gpiSwitchLED(LED_1,gpi_true,RED);
gpiSwitchLED(LED_2,gpi_true,RED);
gpiSwitchLED(LED_3,gpi_true,RED);
gpiSwitchLED(LED_4,gpi_true,RED);
break;
case ocAPPROVED :
gpiSwitchLED(LED_1,gpi_true,GREEN);
gpiSwitchLED(LED_2,gpi_true,GREEN);
gpiSwitchLED(LED_3,gpi_true,GREEN);
gpiSwitchLED(LED_4,gpi_true,GREEN);
break;
default:
break;
}
Even if LED may be used for contact transaction, this primitive is mainly designed for CL processing. Agnos Framework follows these rules:
When Agnos is ready to be triggered for a payment, all LED are off. It's the iddle state
When a CL transaction is triggered, the polling state shows LED_1 = ON = GREEN
During a CL transaction flow, subsequent LED are displayed . At the end of a flow, all 4 LED = ON = GREEN
On a start B or C, the polling state is restored whenever the start B or C was triggered (LED_2, LED_3 may be ON or OFF)
Level3 manages transaction final status and may use different colors. It's up to the integrator to adapt specific color vs spcecific status at this stage of the transaction
Blinking is not supported
At the end of a transaction flow, the iddle state is restored