Amadis
GPI SPED Primitives
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
Parameters
Returned Values
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
Parameters
Returned Values
Example
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
Parameters
Returned Values
Example
N/A
gpiClearScreen
Description
Clear display.
Pre-Condition(s)
N/A
Post-Condition(s)
Display has been cleared.
Signature
Prototype
Parameters
Returned Values
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
Parameters
Returned Values
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
Parameters
Returned Values
Example
N/A
gpiEmptyKeyPadCache
Description
Empty keypad's cache.
Pre-Condition(s)
N/A
Post-Condition(s)
N/A
Signature
Prototype
Parameters
Returned Values
Example
N/A
gpiGetCurrentDisplayLine
Description
Get display's current available line.
Pre-Condition(s)
N/A
Post-Condition(s)
N/A
Signature
Prototype
Parameters
Returned Values
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
Parameters
Returned Values
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
Parameters
Returned Values
Example
N/A
gpiGetLastDisplayLine
Description
Get display's last available line.
Pre-Condition(s)
N/A
Post-Condition(s)
N/A
Signature
Prototype
Parameters
Returned Values
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
Parameters
Returned Values
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
Parameters
Returned Values
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
Parameters
Returned Values
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
Parameters
Returned Values
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
Parameters
Returned Values
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.
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
Parameters
Returned Values
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
Parameters
Returned Values
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
Parameters
Returned Values
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
Parameters
Returned Values
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
Parameters
Returned Values
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
Parameters
Returned Values
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
Parameters
Returned Values
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).
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