gpiCardInserted
Description
Get smart card insertion status. Multiple smart card readers may be supported.
Pre-Condition(s)
N/A
Post-Condition(s)
N/A
Signature
Prototype
tGPIError gpiCardInserted (const char* smartcardReaderName);
Parameters
const char* smartcardReaderName: in // Reader
Returned Values
tGPIError: scrNO_ERROR // No card inserted tGPIError: scrCARD_INSERTED // Card inserted tGPIError: scrSYSTEM_ERROR // Card reader error
Example
N/A
gpiCardSwiped
Description
Get magstripe card swipe status. Multiple magstripe card readers may be supported.
Pre-Condition(s)
N/A
Post-Condition(s)
N/A
Signature
Prototype
tGPIError gpiCardSwiped (const char* magstripeReaderName);
Parameters
const char* magstripeReaderName: in // Reader
Returned Values
tGPIError: msrNO_SWIPE // No card swiped tGPIError: msrCARD_SWIPED // Card swiped tGPIError: msrSYSTEM_ERROR // Card reader error
Example
N/A
gpiExchangeAPDU
Description
Send a C-APDU and receive a R-APDU. Each APDU exchange is stored until the next exchange to allow a specific parsing in between on subsequent to a flow interruption.
Pre-Condition(s)
Reader and card must be powered on.
Post-Condition(s)
Last C-APDU and R-APDU have been set with the APDU exchange that has been performed.
Signature
Prototype
tGPIError gpiExchangeAPDU(const char* smartcardReaderName, unsigned char* apduReq, unsigned char* Le, unsigned char* apduResp, unsigned short* lenResp);
Parameters
const char* smartcardReaderName: in // Reader unsigned char* apduReq: in // CLA, INS, P1, P2, Lc, and dataIn (of Lc length) unsigned char* Le: in // Null when Le not present. Else 0x00. unsigned char* apduResp: out // Response with MAX_APDU_LENGTH byte length at maximum unsigned short* lenResp: out // Response length with last 2 bytes set to SW1 SW2
Returned Values
tGPIError: scrNO_ERROR // Normal case of execution tGPIError: scrINTERRUPTED // Transaction interrupted while exchanging APDU tGPIError: scrAPDU_ERROR // Invalid status word (on Ox61xx and 0x6Cxx cases) tGPIError: scrSYSTEM_ERROR // Invalid input parameters or card mute, i.e. APDU response cannnot be fetched
Example
#include "gpicad.h" #define CLA apduReq[0] #define INS apduReq[1] #define P1 apduReq[2] #define P2 apduReq[3] #define Lc apduReq[4] tByte apduReq[MAX_APDU_LENGTH]="", Le=0x00; tByte FCI[MAX_APDU_LENGTH]=""; tWord FCILen=0; tGPIError gpiError; //Prepare Select command CLA = 0x00; INS = 0xA4; P1 = 0x04; P2 = 0x00; Lc = 7; memcpy(&apduReq[5],"\xA0\x00\x00\x00\x03\x10\x10",7); //Send Select command gpiError = gpiExchangeAPDU(smartcardReaderName, apduReq, &Le, FCI, &FCILen); if(gpiError != scrNO_ERROR) return agnSYSTEM_ERROR;
gpiGetCardStatus
Description
Get smart card status to know whether the card is mute or not (i.e. activated, not activated, or not present).
Pre-Condition(s)
N/A
Post-Condition(s)
N/A
Signature
Prototype
tGPIError tGPIError gpiGetCardStatus (const char* smartcardReaderName, tCardStatus* status);
Parameters
const char* smartcardReaderName: in // Reader
tCardStatus* status: out // Card status within {CARD_ACTIVATED, CARD_NOT_PRESENT, CARD_NOT_ACTIVATED, CARD_MUTE}
Returned Values
tGPIError: scrNO_ERROR // Normal case of execution
Example
N/A
gpiGetSerialNumber
Description
Get terminal's serial number (used to set 9F1E). This primitive is used by Agnos Framework to set terminal's profile in the scope of Level2 TA.
Pre-Condition(s)
N/A
Post-Condition(s)
N/A
Signature
Prototype
tGPIError gpiGetSerialNumber (unsigned char* serialNumBuf);
Parameters
unsigned char* serialNumBuf: out // 9F1E as per EMVCo definition - 8 byte long buffer
Returned Values
tGPIError: admNO_ERROR // Normal case of execution
Example
N/A
gpiInitPolling
Description
Initialize antenna before system's operations.
Pre-Condition(s)
N/A
Post-Condition(s)
N/A (i.e. specific to any given hardware platform).
Signature
Prototype
tGPIError gpiInitPolling (const char* contactlessCardReaderName);
Parameters
const char* smartcardReaderName: in // Reader
Returned Values
tGPIError: clcNO_ERROR // Normal case of execution
Example
N/A
gpiPolling
Description
initiate a polling on a contactless reader during a specific time duration. Multiple readers may be supported.
Pre-Condition(s)
N/A
Post-Condition(s)
If a card has been detected, gContactlessTransactionInProgress has been set to gpi_true.
Signature
Prototype
tGPIError gpiPolling(const char* contactlessCardReaderName);
Parameters
const char* smartcardReaderName: in // Reader
Returned Values
tGPIError: clcEMV_CARD // CL card detected tGPIError: clcNO_ERROR // CL card detected (gpiPolling has been called twice in a row. Card already detected) tGPIError: scrINTERRUPTED // Polling canccelled tGPIError: polTIMEOUT // Polling time out tGPIError: clcCOLLISION // Two cards detected tGPIError: scrCARD_INSERTED // CT card inserted tGPIError: msrCARD_SWIPED // Magstripe card swiped tGPIError: clcOTHER_CARD // Not type A/type B card detected tGPIError: scrSYSTEM_ERROR // Polling issue
Example
#include "gpicad.h"
#include "paymentMW.h"
if(!gSkipCardDetection) // If L3 performs a polling to detect transport cards then gSkipCardDetection avoid double tap
gCardDetectionStatus = gpiPolling(gTerminalCtx->mDeviceName);
else
gSkipCardDetection = bFALSE;
switch (gCardDetectionStatus) {
case clcNO_ERROR:
case clcEMV_CARD:
break; // CL card present !!!
case clcCOLLISION:
LOG( clcCOLLISION, "", "Card Collision Detected" );
gpiBeep(BEEP_NOK,NO_FREQUENCY);
gpiSleep(1500);
break;
case polTIMEOUT:
LOG( polTIMEOUT, "", "Transaction Timed Out" );
break;
case scrINTERRUPTED:
LOG( scrINTERRUPTED, "", "Transaction Stopped" );
break;
case scrCARD_INSERTED:
LOG( gCardDetectionStatus, "", "Card Inserted" );
break;
case msrCARD_SWIPED:
LOG( gCardDetectionStatus, "", "Card Swiped" );
break;
case clcOTHER_CARD:
LOG( clcOTHER_CARD, "", "Not EMV Card" );
break;
case scrSYSTEM_ERROR:
default:
LOG( gCardDetectionStatus, "", "Unexpected Polling Result" );
break;
}
gpiPowerOff
Description
Power off a reader.
Pre-Condition(s)
N/A
Post-Condition(s)
gContactlessTransactionInProgress has been set to gpi_false.
Signature
Prototype
tGPIError gpiPowerOff (const char* device);
Parameters
const char* device: in // Reader
Returned Values
tGPIError: scrNO_ERROR // Normal case of execution
Example
gpiPowerOff is always called from the entry point (contactless), or a payment application (contact). However, there is one exception. For performance reason, gpiPowerOff is also called from kernel C-3/Visa (SEE_PHONE cases - a.k.a. 0x6986 cases - requiring immediate field off). At that time. *device is set to “qVSDCPath” to notify that exception to the GPI (discrimination mean).
gpiPowerOffAllDevices
Description
Power off all readers at the same time.
Pre-Condition(s)
N/A
Post-Condition(s)
gContactlessTransactionInProgress has been set to gpi_false.
Signature
Prototype
tGPIError gpiPowerOffAllDevices(void);
Parameters
void
Returned Values
tGPIError: scrNO_ERROR // Normal case of execution
Example
N/A
gpiPowerOn
Description
Power on a reader (and the card) before initiating a transaction.
Pre-Condition(s)
N/A
Post-Condition(s)
A reader context has been initialized (i.e. specific to any given hardware platform).
Signature
Prototype
tGPIError gpiPowerOn (const char* smartcardReaderName, tCardStatus* status, unsigned char* ATRBuffer, unsigned char* ATRLen);
Parameters
const char* smartcardReaderName: in // Reader
tCardStatus* status: out // Card status within {CARD_ACTIVATED, CARD_MUTE}
unsigned char* ATRBuffer: out // ATR
unsigned char* ATRLen: out // ATR length
Returned Values
tGPIError: scrNO_ERROR // Normal case of execution tGPIError: scrSYSTEM_ERROR // Card reader error
Example
N/A
gpiReadMagstripe
Description
Get tracks from magstripe reader.
Pre-Condition(s)
A card must be swiped.
Post-Condition(s)
N/A
Signature
Prototype
tGPIError gpiReadMagstripe ( const char* magstripeReaderName, unsigned char* track1Buffer, unsigned short* track1Len, unsigned char* track2Buffer, unsigned short* track2Len, unsigned char* track3Buffer, unsigned short* track3Len );
Parameters
const char* magstripeReaderName: in // Reader unsigned char* track1Buffer: out // Track1 unsigned short* track1Len: out // Track1's length unsigned char* track2Buffer: out // Track2 unsigned short* track2Len: out// Track2's length unsigned char* track3Buffer: out // Track3 unsigned short* track3Len): out// Track3's length
Returned Values
tGPIError: msrNO_ERROR // Normal case of execution tGPIError: msrSYSTEM_ERROR // Invalid tracks or tracks lengths or reader error
Example
N/A
gpiRemovalProcedure
Description
Initiate a CL removal procedure.
Pre-Condition(s)
N/A
Post-Condition(s)
N/A
Signature
Prototype
tGPIError gpiRemovalProcedure(const char* contactlessCardReaderName, unsigned char holdtime);
Parameters
const char* contactlessReaderName: in // Reader unsigned char holdtime: in // Maximum holding time in ms
Returned Values
tGPIError: clcNO_ERROR // Normal case of execution
Example
N/A
gpiResetContactless
Description
Reset reader's antenna.
Pre-Condition(s)
Antenna is powered on or off.
Post-Condition(s)
Antenna has been powered off.
Signature
Prototype
tGPIError gpiResetContactless(const char* contactlessCardReaderName);
Parameters
const char* contactlessCardReaderName: in // Reader
Returned Values
tGPIError: clcNO_ERROR // Normal case of execution
Example
N/A
gpiSetTechnoToDetect
Description
Set technologies to detect.
Pre-Condition(s)
N/A
Post-Condition(s)
A list of technologies to poll on has been set.
Signature
Prototype
tGPIError gpiSetTechnoToDetect (const unsigned char technologies);
Parameters
const unsigned char technologies: in // Technologies to detect where: //#define TECHNO_CL_TYPE_A 0x01 //#define TECHNO_CL_TYPE_B 0x02 //#define TECHNO_CL_TYPE_EMV 0x04 //#define TECHNO_MANUAL 0x20 //#define TECHNO_CONTACT 0x40 //#define TECHNO_MAGSTRIPE 0x80
Returned Values
tGPIError: polNO_ERROR // Normal case of execution
Example
#include "gpicad.h" gpiSetTechnoToDetect(TECHNO_CONTACT | TECHNO_MAGSTRIPE); // Polling on contact and magstripe
gpiTechnoPolling
Description
Poll for a specific set of technologies, for a specific time out.
Pre-Condition(s)
N/A
Post-Condition(s)
N/A
Signature
Prototype
tGPIError tGPIError gpiTechnoPolling (const unsigned char technologies, const unsigned int timeout, unsigned char *technologyDetected);
Parameters
const unsigned char technologies: in // List of technologies to poll on const unsigned int timeout: in // Polling timeout in s unsigned char *technologyDetected: out // Detected technology
Returned Values
tGPIError: polNO_ERROR // Normal case of execution. A card has been detected tGPIError: polTIMEOUT // Timeout reached tGPIError: scrINTERRUPTED // Polling cancelled tGPIError: polSYSTEM_ERROR // Invalid call
Example
#include "gpicad.h"
unsigned char technoDetected = 0;
unsigned int scanTimeout = 10;
tWord error = 0;
technoDetected = 0;
error = polNO_ERROR;
while(!technoDetected && (error != polSYSTEM_ERROR) && (error != polTIMEOUT))// polling conditions
error = gpiTechnoPolling(TECHNO_CONTACT | TECHNO_MAGSTRIPE, scanTimeout, &technoDetected);
switch (error)
{
case polTIMEOUT:
return TIMEOUT;
case scrINTERRUPTED:
return CANCEL;
case polSYSTEM_ERROR:
return CANCEL;
default:
if (technoDetected == TECHNO_CONTACT)
*entryMode = CHIP_MODE;
else if(technoDetected == TECHNO_CL_TYPE_EMV)
*entryMode = EMV_CL_MODE | MAG_CL_MODE;
else if(technoDetected == TECHNO_MAGSTRIPE)
*entryMode = MAG_MODE;
else
return ERROR;
break;
}