Page Comparison

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

Code Block
tGPIError gpiAdvancedDisplay (tUIRequestData* UIRequestData);

Parameters

Code Block
tUIRequestData* UIRequestData: in // UI signal

Returned Values

Code Block
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

Code Block
tGPIError gpiAdvancedDisplayAsOutcome (tUIRequestData* UIRequestData);

Parameters

Code Block
tUIRequestData* UIRequestData: in // UI signal

Returned Values

Code Block
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

Code Block
tGPIError gpiBeep(unsigned short duration, unsigned short frequency);

Parameters

Code Block
unsigned short duration: in // in ms unsigned short frequency: in // in ms

Returned Values

Code Block
tGPIError: admNO_ERROR // Normal case of execution

Example

Code Block

#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;
}

...

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

Code Block
unsigned char gpiCancelledTransaction (void);

Parameters

Code Block
void

Returned Values

Code Block
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

Code Block
tGPIError gpiClearScreen (void);

Parameters

Code Block
void

Returned Values

Code Block
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

Code Block
tGPIError gpiDisplayMessage (unsigned char clearScreen, const char* message);

Parameters

Code Block
unsigned char clearScreen: in // Flag indicating to clear the screen prior the message display const char* message // String to display

Returned Values

Code Block
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

Code Block
tGPIError gpiDisplayPollingMessage (void);

Parameters

Code Block
void

Returned Values

Code Block
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

Code Block
tGPIError gpiEmptyKeyPadCache (void);

Parameters

Code Block
void

Returned Values

Code Block
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

Code Block
tGPIError gpiGetCurrentDisplayLine (int* line)

Parameters

Code Block
int* line: out // Available line identifier

Returned Values

Code Block
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

Code Block
tGPIError gpiInitializeDisplay (const char* inifile, unsigned char * count, void* arg);

Parameters

Code Block

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

Code Block
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

Code Block
tGPIError gpiGetLanguageCodeOfId (const unsigned char langId, const char ** code);

Parameters

Code Block
const unsigned char langId: in // Language code as defined by ISO const char ** code: out // String table's language identifier

Returned Values

Code Block
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

Code Block
tGPIError gpiGetLastDisplayLine(int * line)

Parameters

Code Block
int* line: out // Last available line identifier

Returned Values

Code Block
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

Code Block
tGPIError gpiGetKeyIn (unsigned char* key)

Parameters

Code Block
unsigned char* key: out // Key code corresponding to keypad's key

Returned Values

Code Block
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

Code Block
tGPIError gpiGetLanguage (const unsigned char languagePreference, const unsigned char languagePreferenceLen, unsigned char lang);

Parameters

Code Block

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

Code Block
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

Code Block
tGPIError gpiGetNbLanguage (unsigned char * count);

Parameters

Code Block
unsigned char * count: out // Number of languages available

Returned Values

Code Block
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

Code Block
tGPIError gpiGetString (const unsigned char langId, const unsigned char stringId, char ** string);

Parameters

Code Block
const unsigned char langId: in // Language const unsigned char stringId: in // String identifier char ** string: out // String

Returned Values

Code Block
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

Code Block
tGPIError gpiPINEnter (const char* pinPadName, unsigned int lan, unsigned char* encryptedPIN, unsigned char* encryptedLen, int timeout, unsigned char sred);

Parameters

Code Block

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

Code Block

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:

...

Code Block

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

Code Block
tGPIError gpiPINVerifyPlaintext (const char* deviceName, const char* pinPadName, unsigned int lan, char verifyOnly, int timeout, int remainingAttempt);

Parameters

Code Block

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

Code Block

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

Code Block
tGPIError gpiPINVerifyCiphered (const char* deviceName, const char* pinPadName, unsigned int lan, char verifyOnly, tEMVPubKey* key, int timeout, int remainingAttempt);

Parameters

Code Block

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

Code Block

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

Code Block
tGPIError gpiSetKeypadTimeout(int timeout)

Parameters

Code Block
int timeout: in // Time out in s

Returned Values

Code Block
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

Code Block
tGPIError gpiScanKeyIn (unsigned char* key);

Parameters

Code Block
unsigned char* key: out // Key code corresponding to keypad's key

Returned Values

Code Block
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

Code Block
tGPIError gpiSetPollingMessage (const char* line1, const char* line2, const char* line3);

Parameters

Code Block
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

Code Block
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

Code Block
tGPIErrortGPIError gpiSwitchDisplayBacklight (unsigned char flag);

Parameters

Code Block
unsigned char flag: in // Flag is within {gpi_false, gpi_true}

Returned Values

Code Block
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

Code Block
tGPIError gpiSwitchLED (unsigned char led, unsigned char flag, unsigned char colour);

Parameters

Code Block

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

Code Block
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).

...

Page Comparison

Versions Compared

Old Version 2

New Version 3

Key

Description

Pre-Condition(s)

Post-Condition(s)

Signature

Prototype

Parameters

Returned Values

Example

gpiAdvancedDisplayAsOutcome

Description

Pre-Condition(s)

Post-Condition(s)

Signature

Prototype

Parameters

Returned Values

Example

gpiBeep

Description

Pre-Condition(s)

Post-Condition(s)

Signature

Prototype

Parameters

Returned Values

Example

gpiCancelledTransaction

Description

Pre-Condition(s)

Post-Condition(s)

Signature

Prototype

Parameters

Returned Values

Example

gpiClearScreen

Description

Pre-Condition(s)

Post-Condition(s)

Signature

Prototype

Parameters

Returned Values

Example

gpiDisplayMessage

Description

Pre-Condition(s)

Post-Condition(s)

Signature

Prototype

Parameters

Returned Values

Example

gpiDisplayPollingMessage

Description

Pre-Condition(s)

Post-Condition(s)

Signature

Prototype

Parameters

Returned Values

Example

gpiEmptyKeyPadCache

Description

Pre-Condition(s)

Post-Condition(s)

Signature

Prototype

Parameters

Returned Values

Example

gpiGetCurrentDisplayLine

Description

Pre-Condition(s)

Post-Condition(s)