Table of Contents | ||||||||
---|---|---|---|---|---|---|---|---|
|
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).
...