API _Version _Revision | ;Description |
---|---|
_Agnos _version 3.5.20 _revision 23770 | Agnos Interface is an abstraction of EMVCo Book I, II, and III. It relies on 3 components:
|
EMV Engine | ||
---|---|---|
See agnos..h | ||
| #include "agnoserrors.h" //---- Agnos Framework Headers ---- #include "agnosdatabase.h" //---- Global Headers ---- #include "gpi_agnos_framework_globals.h" | -- |
| typedef struct { /** If bTRUE, TAC/IAC default processing is skipped if unable to go online*/ tBoolean mSkipTACIACDefault; /** If bTRUE, TAC processing is performed*/ tBoolean mTAC; /** If bTRUE, Floor Limit Checking is performed*/ tBoolean mFloorLimitChecking; /** If bTRUE, RTS is performed*/ tBoolean mRandomTransactionSelection; /** If bTRUE, Velocity Checking is performed*/ tBoolean mVelocityChecking; /** If bTRUE, Default TDOL is supported*/ tBoolean mDefaultTDOL; /** TDOL length*/ tByte mDefaultTDOLLen; /**Tag 0x97*/ tByte mDefaultTDOLValue[TDOL_MAX_LENGTH]; /** If bTRUE, Default DDOL is supported*/ tBoolean mDefaultDDOL; /** DDOL length*/ tByte mDefaultDDOLLen; /**Tag 0x9F49 or 0x9F69 (UDOL for contactless)*/ tByte mDefaultDDOLValue[DDOL_MAX_LENGTH]; /**Terminal Action Code - Denial*/ tTVR mTACDenial; /**Terminal Action Code - Online*/ tTVR mTACOnline; /**Terminal Action Code - Default*/ tTVR mTACDefault; /**Tag 0x9F1B*/ tAmount mTerminalFloorLimit; /**See EMV Book III, TRM section - Random Transaction Selection*/ tPercentage mTargetPercentage; /**See EMV Book III, TRM section - Random Transaction Selection. Same transaction currency exponent as 0x9F02*/ tAmount mThresholdValue; /**See EMV Book III, TRM section - Random Transaction Selection*/ tPercentage mMaxTargetPercentage; /**if bTRUE, pin may be bypassed when requested*/ tBoolean mPINByPass; /**bTRUE when merchant manually requested transaction to go online*/ tBoolean mForcedOnline; /**Tag 0x9A*/ tNumericDate mTransactionDate[3]; /**Tag 0x9F21*/ tNumericDate mTransactionTime[3]; /**Tag 0x9F35*/ tTerminalType mTerminalType; /** Transaction language*/ tByte mLanguage; /** PIN entry delay in second*/ tCounter mPinTimeOut; /** CDAMode1, CDAMode2 and CDAMode3 only*/ tCDAType mCDAType; /**if bTRUE, Terminal Risk Management is performed even if ICC doesn't request it*/ tBoolean mForceTRM; /**Tag 0x5F57*/ tByte mAccountType; /**Tag 0x9F39*/ tByte mPOSEntryMode; /**Tag 0x9F41*/ tCounter mTransactionSequenceCounter; /**Tag 0x9F1D*/ tByte mTerminalRiskManagementData[8]; /**Tag 0x9F3A*/ tAmount mAmountReferenceCurrency; /**Tag 0x9F3C*/ tByte mTransactionReferenceCurrencyCode[2]; /**Tag 0x9F3D*/ tByte mTransactionReferenceCurrencyExponent; /**Tag 0x9F1A*/ tByte mTerminalCountryCode[2]; /**Tag 0x5F2A*/ tByte mTransactionCurrencyCode[2]; /**Tag 0x5F36*/ tByte mTransactionCurrencyExponent; /**Tag 0x9F33*/ tByte mTerminalCapabilities[3]; /**Tag 0x9F40*/ tByte mAdditionalTerminalCapabilities[5]; /**Tag 0x9F09*/ tByte mApplicationVersionNumber[2]; /**Tag 0x9C*/ tByte mTxnType; /**Tag 0x9F1C*/ tByte mTerminalIdentification[8]; /**Tag 0x9F1E*/ tByte mIFDSerialNumber[8]; /**Tag 0x9F01*/ tByte mAcquirerIdentifier[6]; } tTransactionalContext; | |
| DLLEXPORT tString agnGetVersionNumber(void); | Get EMV core engine version. |
| DLLEXPORT tAgnosError agnOpenSession( const tString smartcardReaderName, const tString pinPadName, const tString applicationId, const tTransactionalContext *txnContext, tBoolean DirectExecution, tBoolean setEMVTag, tSessionId *session, tBoolean clipping, tBoolean sred ); | Open a CT session to initiate an EMV transaction flow. |
| DLLEXPORT tAgnosError agnInitiateEMVTransaction ( tSessionId session, const tAmount *amount, const tAmount *cashBack, const tByte *AID, tByte AIDLen, tByte *CID ); | Initiate/Resume an EMV transaction |
| DLLEXPORT tAgnosError agnCompleteEMVTransaction ( tSessionId session, tARC ARC, tByte *CID, const tByte *issuerResponse, tWord issuerResponseLen, tBoolean unableToGoOnline ); | Complete a transaction as per EMVCo definition |
| DLLEXPORT tTagDataBase* agnGetDatabase(const tSessionId session); | |
| DLLEXPORT tBoolean agnIsEMVTagKnown( tWord tag // In: Tag to search in db storing referenced tags ); | Return bTRUE is tag statically known. |
| DLLEXPORT tBoolean agnIsEMVTagPresent( tSessionId session, // In: Kernel's session tWord tag // In: Tag to search in current session ); | Return bTRUE if tag is present whatever its length. |
| DLLEXPORT tBoolean agnIsEMVTagEmpty( tSessionId session, // In: Kernel's session tWord tag // In: Tag to assess length ); | Return bTRUE if tag’s length is 0. |
| DLLEXPORT tBoolean agnIsEMVTagNotEmpty( tSessionId session, // In: Kernel's session tWord tag // In: Tag to assess length ); | Return bTRUE if tag’s length is not 0. |
| DLLEXPORT tAgnosError agnGetEMVTag( tSessionId session, // In: Kernel's session tWord tag, // In: See agnostypes.h. Tags values are word values (unsigned short) tByte *length, // Out: Tag's length tByte *value // Out: Value shall be allocated by calling application ) | Get a specific tag from Agnos database. |
| DLLEXPORT tAgnosError agnSetEMVTag( tSessionId session, // In: Kernel's session tWord tag, // In: See agnostypes.h. Tags values are word values (unsigned short) tByte length, // In: Length of tag's value const tByte *value // In: Tag's length ); | Add a tag into Agnos database without checking tag’s update condition. |
| DLLEXPORT tAgnosError agnOverwriteEMVTag( tSessionId session, // In: Kernel's session tWord tag, // In: See agnostypes.h. Tags values are word values (unsigned short) tByte length, // In: Length of tag's value const tByte *value // In: Tag's length ); | Overwrite an existing tag. If it doesn’t exist, create it (no garbage collection if sizes don’t match). |
| DLLEXPORT tAgnosError agnRemoveEMVTag( tSessionId session, // In: Kernel's session tWord tag // In: See agnostypes.h. Tags values are word values (unsigned short) ); | Remove a tag from Agnos database (no garbage collection). |
| DLLEXPORT tAgnosError agnORTVR( tSessionId session, // In: Kernel's session tByte TVRPosition, // In: 0 based position tByte value // In: Value to OR ); | OR a specific TVR’s bit to 1. |
| DLLEXPORT tAgnosError agnORAgnosTVR( tSessionId session, // In: Kernel's session tByte AgnosTVRPosition, // In: 0 based position tByte value // In: Value to OR ) | OR a specific Agnos TVR’s bit to 1. |
| DLLEXPORT tAgnosError agnSetAgnosTVR( tSessionId session, // In: Kernel's session tByte AgnosTVRPosition, // In: 0 based position tByte value // In: Value to Set ); | Set a specific Agnos TVR byte value. |
| DLLEXPORT tAgnosError agnOpenSessionCL( const tString smartcardReaderName, // In: Smartcard device name const tString pinPadName, // In: Secured PIN entry device name const tString applicationId, // In: Application Id const tTransactionalContext *txnContext, // In: Context provided by the payment application tBoolean setEMVTag, // In: set EMV data in kernel database (from transacitonal context) tSessionId *session, // Out: Session returned by the kernel to be used when primitives are called tBoolean clipping, // In: activate software clipping into Agnos tBoolean sred // In: activate low level clipping ); | Open a CL session to initiate an EMV transaction flow |
| DLLEXPORT tAgnosError agnCloseSession ( tSessionId session ); | Close a transaction flow. |
agnSetAgnosDatabase | Add a series of tags. Each tag is statically indexed and ruled by an update condition. Use an appropriate update condition to store tags directly into Agnos database | |
agnSetKernelStatus | Set core engine to a specific state. Use this primitive to skip a state in State Machine mode | |
Get all tags from Agnos database | ||
agnGetAllTags |
Application Selection Routines | ||
---|---|---|
See selection..h | ||
| #include "agnoserrors.h" //---- Global Headers ---- #include "gpi_agnos_framework_globals.h" | -- |
| typedef struct { tByte mNumberOfADF; tADF mList[MAX_SUPPORTED_ADF]; tBoolean mEliminatedADF[MAX_SUPPORTED_ADF]; tBoolean mCardBlocked; tBoolean mAnyBlockedApplication; tByte mSelectionIndex; } tADFList; | |
| typedef struct { tByte mADFName[MAX_AID_LENGTH]; //0x4F tByte mADFLen; tByte mLabel[MAX_AID_LENGTH]; //0x50 tByte mLabelLen; tByte mPreferredName[MAX_AID_LENGTH]; //0x9F12 tByte mPreferredNameLen; tByte mPriorityIndicator; //0x87 tByte mLangagePreference[8]; //0x5F2D tByte mLangagePreferenceLen; tByte mIssuerCodeTableIndex; //0x9F11 tByte mRemainingFCI[MAX_REMAINING_FCI_LENGTH]; //0xBF0C. May contain Issuer Country Code 5F56 AND/OR Application Selection Flag DF62 tByte mRemainingFCILen; tByte mBlocked; tByte mCorrespondingAIDOrderNumber; // Order of the ADF in the AID list (application supported by terminal) // Extension to support PPSE tByte mKernelIdentifier[8]; //0x9F2A tByte mKernelIdentifierLen; tByte mRequestedKernelId; tByte mExtendedSelection[MAX_AID_LENGTH]; //0x9F29 tByte mExtendedSelectionLen; } tADF; | |
| typedef struct { tByte mPSEName[MAX_AID_LENGTH]; //0x84 tByte mPSELen; tByte mSFI; //0x88 tByte mLangagePreference[8]; //0x5F2D tByte mLangagePreferenceLen; tByte mIssuerCodeTableIndex; //0x9F11 tByte mRemainingFCI[MAX_REMAINING_FCI_LENGTH]; //0xBF0C. May contain Issuer Country Code 5F56 AND/OR Application Selection Flag DF62 tByte mRemainingFCILen; } tPSE; |
EMV Tags Database | ||
---|---|---|
See emvtag.h, agnosdatabase.h | ||
-- | ||
adbGetVersionNumber | Provide Agnos database version. Get all pointers on shared RAM spaces provided by SAL/HAL and set adbAddTag strategy to STANDARD (i.e. EMVCo rule where update conditions are not checked) | |
adbResetDataBase | Reserved to Agnos core engine. Reset database structure | |
adbSetStrategy | Reserved to Agnos core engine and contactless card processing. By default, Agnos databse uses EMVco tags storage strategy where no check is performed on tags' update conditions. If a storage strategy is defined (by a contactless card processing) then:
| |
adbAddTag | Reserved to Agnos core engine. Check whether a tag may be added into EMV tags database. In order to store EMV tags directly into Agnos database, use agnSetAgnosDataBase primitive instead | |
adbAddUnknownTag | Add any tags into EMV tags database in “UnknowTag” bucket | |
adbGetUnknowTags | Get all tags stored into unknown tags bucket | |
adbGetUnknownTagsLength | Get the bucket’s length | |
adbGetUnknownTagsCount | Get tags count from the bucket | |
adbGetAllTLV | Get all TLV stored in AgnosDB. tTagDataBase db; unsigned char buffer[100]=""; unsigned short maxLength=100, actualLength=0; aceOut(adbGetVersionNumber()); adbResetDataBase(&db); adbGetAllTLV(&db,buffer,maxLength,&actualLength); aceSendRawDD(buffer,actualLength); adbAddUnknownTag(&db,(const unsigned char*)"\x9F\x02\x06\x99\x99\x99\x99\x99\x99",0x09); adbGetAllTLV(&db,buffer,maxLength,&actualLength); aceSendRawDD(buffer,actualLength); |
Code Example |
---|
See emvco.c. and selectionlogic.h. They provide good examples on agnos.h and selection.h integration in the scope of contact card processing. |