Amadis

Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

Version 1 Next »

Languages

Languages, strings, and lists management depends on projects' requirements and need to be adapted. However, most of the code that is provided may be reuse as is. This section aims to explain the standard GPI mechanism to help the integration.

The examples are provided managing the languages through a .ini file (lang.ini). The string table structure is:

typedef struct {
	char code[LANGUAGE_CODE_LENGTH+1];
	char label[MAX_STRING_LENGTH+1];
	char emvString[NB_EMV_STRINGS][MAX_STRING_LENGTH+1];
	char individualString[NB_INDIVIDUAL_STRINGS][MAX_STRING_LENGTH+1];
	char acquirerString[NB_ACQUIRER_STRINGS][MAX_STRING_LENGTH+1];
	char issuerString[NB_ISSUER_STRINGS][MAX_STRING_LENGTH+1];
} tLanguageData;
typedef struct {
	int nbLanguage;
	tLanguageData language[MAX_NB_LANGUAGE];
} tStringTable;

Important:

  • Reduce the structure size to address RAM issue when instantiating static tStringTable stringTable.

  • It is also possible to use a simple matrix [MAX_NB_LANGUAGE][MAX_STRING_PER_LANGUAGE] in flash memory depending of the platform that is targeted.

The very first thing that is performed when running Agnos is the GPI initialization. From gpiInitializeDisplay, the string table above is set up and the number of supported languages calculated:

  • *count = loadStringTable(inifile);

More details on the behavior corresponding to the structure above:

tGPIError gpiGetNbLanguage(unsigned char * count)

Once the string table is up in memory, that primitive returns the number of language stored in string table.

tGPIError gpiGetLanguage(const unsigned char *languagePreference, const unsigned char languagePreferenceLen, unsigned char * lang)

Once an EMV card has been selected, it may provide a list of supported languages to the terminal. That primitive calculates the mutual supported languages between the card (tag 5F2D) and the terminal (string table).

tGPIError gpiGetLanguageCodeOfId(const unsigned char langId, const char ** code)

Once the string table is up in memory, that primitive returns the code language. Example: if English is stored in slot 1 then it returns “en”.

Note that an integrity checksum maybe integrated or not to make sure that string are not corrupted. All the existing code maybe used as is. Study lang.ini file, the string table structure and the code to learn on the mechanism. Example of a lang.ini supporting one language:

[Language]
; Language at position 1 acts as Default
1=en

[en]
Label=ENGLISH

; Standard Messages EMVCo Book IV, section 11.2
01=AMOUNT
02=AMOUNT OK?
03=APPROVED
04=CALL YOUR BANK
05=CANCEL OR ENTER
06=CARD ERROR
07=DECLINED
08=ENTER AMOUNT
09=ENTER PIN
0A=INCORRECT PIN
0B=INSERT CARD
0C=NOT ACCEPTED
0D=PIN OK
0E=PLEASE WAIT…
0F=PROCESSING ERROR
10=REMOVE CARD
11=USE CHIP READER
12=USE MAGSTRIPE
13=TRY AGAIN

; Contactless Specific Messages EMVCo Book A, section 9.4
14=WELCOME
15=PRESENT CARD
16=PROCESSING
17=CARD READ OK - REMOVE CARD
18=INSERT OR SWIPE CARD
19=PRESENT ONE CARD ONLY
1A=APPROVED - SIGN
1B=AUTHORIZING WAIT
1C=ERROR - USE OTHER CARD
1D=PRESENT CARD AGAIN
1E=CLEAR DISPLAY
20=SEE PHONE
21=TRY AGAIN
22=INSERT/SWIPE/TRY OTHER CARD

; Acquirer Specific Messages
81=SELECT ACCOUNT
82=MAG PROCESSING
83=SELECT LANGUAGE
84=CANCELLED
85=SWIPE CARD
86=FAILED
87=CASHBACK
88=CASHBACK OK?
89=REFERRAL?
8A=THANK YOU
8B=TRANSACTION NOT PERMITTED

check=325829E28E2CDB90

Strings

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

There are many string related primitives in the GPI. Basically, all primitives using a string identifier are meant to use the string table. Use an identifier and a language keys to find the actual string from the string table up in memory.

Important: If a string table in flash memory is used, it’s important to use a cache to avoid latency at display time because some strings are displayed by the CL payment application within the time frames measurements.

Lists

Lists are used for the purposed of the EMV CT applications (to support EMV and language selection) but there use may be extended for any purpose to support a choice (referral management for example). The GPI example provides a generic implementation that takes into account the physical size of a screen and allows scrolling into a list.

The list structure is:

typedef struct
{
	int positionOfFirstLine;
	int positionOfLastLine;
	int firstIndexToDisplay;
	int lastIndexToDisplay;
	int selectedIndex;
} tDisplayControl;

typedef struct
{
	unsigned char id;
	char name[MAX_ITEM_NAME_LENGTH];
} tItem;

typedef struct
{
	int nbItems;
	tItem item[MAX_NUMBER_ITEMS];
} tItemList;

Important: Reduce the structure size to address RAM issue when instantiating:

static tItemList itemList

.

The very first thing that is performed when running Agnos is the GPI initialization. From gpiInitializeDisplay, the physical size of the screen is set up:

  • maxLines = MAX_LINES

  • maxCharacters = 16

  • currentLine=FIRST_LINE_INDEX

More details on the behaviour corresponding to the structure above:

tGPIError gpiClearList(void)

This primitive shall be called to initialize a list.

tGPIError gpiAddItemInList(const unsigned char id, const char *name);

This primitive adds a new item into the list (at the bottom).

tGPIError gpiSelectItemFromList(const char *title, const int timeout, unsigned char *selectedId);

This primitive displays the list according the physical parameters previously initialized. It manages scrolling and selection during a maximum amount of time (timeout). Then, it returns the list’s selected identifier if any. This means that the mapping between identifiers and list’s items shall be managed by calling level. User may use down/up/cancel/ok keys. Wire gpiGetKeYIn to make it work.

tGPIError gpiSelectItemFromListByID(const char *title, const int timeout, unsigned char *selectedId)

This primitive is the same as gpiSelectItemFromList excepted that the list title name is calculated from a string identifier.

tGPIError gpiGetIdFromManualLanguageSelection(char *message, int timeout, unsigned char * id)

This primitive is the same as gpiSelectItemFromList excepted that it dedicated to language selection (it encapsulates the list initialization and its displays because the mapping between identifiers and list’s items is known by the GPI). The title is defined by the calling level.

tGPIError gpiGetIdFromManualLanguageSelectionByID(char *message, int timeout, unsigned char * id)

This primitive is the same as gpiGetIdFromManualLanguageSelection excepted that the list title name is calculated from a string identifier.

  • No labels