AT-NFC 2.1 (win) AT-NFC kernel set

Typedefs | Functions
Entry Point library export functons

Performs Entry Point initialization. More...

## Typedefs
typedef struct tag_EP_TRAN | EP_TRAN
| EP transaction handle. More...

## Functions
KER_RES KER_API | epNfcDeInit (KER_CTX_SINGLE_PARAM)
| Performs kernel de-initialization. More...
KER_BOOL KER_API | epNfcVerInfo (KER_CTX_PARAM const KER_CHAR **ppchEmvVer, KER_INT16U *pusEmvVerLen, const KER_CHAR **ppchLibVer, KER_INT16U *pusLibVerLen)
| Obtains emv kernel library version info. More...
KER_RES KER_API | epPosPrepareNewTran (KER_CTX_PARAM const NFC_EXT_TERM_TRAN_DATA *pTermTranData, EP_TRAN **ppTran, NFC_OUTCOME **ppOutcome)
| Prepares new transaction. More...
KER_RES KER_API | epPosTran (KER_CTX_PARAM EP_TRAN *pTran, KER_INT32U ulTimeout, KER_INT16U usExtCardTypes, KER_INT16U *pusCardType, KER_BYTE *pbtUID, KER_INT16U *pusUIDLen, NFC_OUTCOME **ppOutcome)
| Initiates new transaction. More...
KER_RES KER_API | epPosTranRestart (KER_CTX_PARAM EP_TRAN *pTran, const NFC_EXT_TERM_RESTART_DATA *pTermRestartData, KER_INT32U ulTimeout, KER_INT16U usExtCardTypes, KER_INT16U *pusCardType, KER_BYTE *pbtUID, KER_INT16U *pusUIDLen, NFC_OUTCOME **ppOutcome)
| Restarts transaction for issuer update, cv-cvm confirmation, etc... More...
KER_RES KER_API | epPosTranRelease (KER_CTX_PARAM EP_TRAN *pTran)
| Releases transaction context. More...
KER_RES KER_API | epNfcGetData (KER_CTX_PARAM EP_TRAN *pTran, KER_INT16U usOptions, KER_BYTE *pbtData, KER_INT16U *pusDataLen)
| Transaction data request. More...
KER_RES KER_API | epNfcGetDataByTagList (KER_CTX_PARAM EP_TRAN *pTran, KER_INT16U usOptions, const KER_BYTE *pbtTagList, KER_INT16U usTagListSize, KER_BYTE *pbtData, KER_INT16U *pusDataSize)
| transaction data request More...
KER_RES KER_API | epNfcGetDataByID (KER_CTX_PARAM EP_TRAN *pTran, KER_INT16U usID, KER_BYTE *pbtData, KER_INT16U *pusDataSize)
| Obtain emv data by ID. More...
KER_BOOL KER_API | epCheckOption (KER_CTX_PARAM EP_TRAN *pTran, KER_INT16U usOption, KER_INT16U usParam, KER_VOID *pParam)
| Check options callback Define this function outside the lib to provide EP options. More...
#define | NFC_EP_OPT_DEBUG 0x0001
| Check option definitions. More...
#define | NFC_EP_OPT_RRP 0x0002

## Detailed Description

Performs Entry Point initialization.

Parameters

  [in] | pConfigID | Buffer with configuration ID obtained from Terminal Application (in HAL recognized format)
  [in] | usConfigIDLen | pConfigID buffer length
  [in] | pchEPFiles | buffer with EP binary file names (for checksum calculation) - set of nul terminated strings ended by nul.
  [in] | usEPFilesLen | length of pchKernelFiles including nul-terminating sym

Returns
  KER_OK Success.
  Other - failure.

Terminal Application should init EP by this function before calling any other kernel functions

Warning
  If epNfcInit returns KER_OK, Terminal Application should call epNfcDeInit finally to release allocated resources.

## Macro Definition Documentation

## ◆ NFC_EP_OPT_DEBUG

#define NFC_EP_OPT_DEBUG 0x0001

Check option definitions.

Debug mode check

## ◆ NFC_EP_OPT_RRP

#define NFC_EP_OPT_RRP 0x0002

RRP mode check

## Typedef Documentation

## ◆ EP_TRAN

typedef struct tag_EP_TRAN EP_TRAN

EP transaction handle.

Termial application should not parse it directly.

## Function Documentation

## ◆ epCheckOption()

KER_BOOL KER_API epCheckOption | ( | KER_CTX_PARAM EP_TRAN * | pTran,
|  | KER_INT16U | usOption,
|  | KER_INT16U | usParam,
|  | KER_VOID * | pParam
| ) |  |

Check options callback Define this function outside the lib to provide EP options.

Parameters

  [in] | pTran | - pointer to the transaction structure (obtained by epPosPrepareNewTran)
  [in] | usOption | - option to check (NFC_EP_OPT_DEBUG, NFC_EP_OPT_RRP)
  [in] | usParam | - reserved.
  [in] | pParam | - reserved.

Returns
  KER_TRUE - option enabled
  KER_FALSE - option disabled

## ◆ epNfcDeInit()

KER_RES KER_API epNfcDeInit | ( | KER_CTX_SINGLE_PARAM |  | ) |

Performs kernel de-initialization.

Returns
  KER_OK Success.
  Other - failure.

Terminal Application should de-init EP by this function

Warning
  Do not call this function if epNfcInit failed.

## ◆ epNfcGetData()

KER_RES KER_API epNfcGetData | ( | KER_CTX_PARAM EP_TRAN * | pTran,
|  | KER_INT16U | usOptions,
|  | KER_BYTE * | pbtData,
|  | KER_INT16U * | pusDataLen
| ) |  |

Transaction data request.

call this function to obtain transaction data from kernel (as a flat TLV with all data available)

Parameters

  [in] | pTran | - pointer to the transaction structure (obtained by epPosPrepareNewTran)
  [in] | usOptions | - get options (bitmask), reserved
  [out] | pbtData | - Buffer to obtain transaction data (in TLV) (path KER_NULL if you need to calculate tran data length only)
  [in,out] | pusDataLen | - Size of Buffer pbtData as input, data length as output

Returns
  KER_OK Success
  Other Failure

## ◆ epNfcGetDataByID()

KER_RES KER_API epNfcGetDataByID | ( | KER_CTX_PARAM EP_TRAN * | pTran,
|  | KER_INT16U | usID,
|  | KER_BYTE * | pbtData,
|  | KER_INT16U * | pusDataSize
| ) |  |

Obtain emv data by ID.

call this function to obtain kernel nfc data by ID

Parameters

  [in] | pTran | - pointer to the transaction structure (obtained by epPosPrepareNewTran) Optional, set KER_NULL if you request data not associated with particular transaction
  [in] | usID | - requested data ID (see hal_config.h & hal_nfc_config.h)
  [out] | pbtData | - buffer to obtain provided ID value
  [in,out] | pusDataSize | - pbtData buffer size as input, output containes result data length

Returns
  KER_OK - Success, requested data provided
  KER_ERR_COMMON_NOT_FOUND - Data not found
  Other - Failure...

## ◆ epNfcGetDataByTagList()

KER_RES KER_API epNfcGetDataByTagList | ( | KER_CTX_PARAM EP_TRAN * | pTran,
|  | KER_INT16U | usOptions,
|  | const KER_BYTE * | pbtTagList,
|  | KER_INT16U | usTagListSize,
|  | KER_BYTE * | pbtData,
|  | KER_INT16U * | pusDataSize
| ) |  |

transaction data request

call this function to obtain transaction data by tag list from kernel

Parameters

  [in] | pTran | - pointer to the transaction structure (obtained by epPosPrepareNewTran)
  [in] | usOptions | - get options (bitmask), reserved
  [in] | pbtTagList | - buffer with tag list
  [in] | usTagListSize | - pbtTagList value length
  [out] | pbtData | - buffer to obtain provided tag list in TLV format
  [in,out] | pusDataSize | - pbtData buffer size as input, output containes result data length

Returns
  KER_OK Success
  Other Failure

## ◆ epNfcVerInfo()

KER_BOOL KER_API epNfcVerInfo | ( | KER_CTX_PARAM const KER_CHAR ** | ppchEmvVer,
|  | KER_INT16U * | pusEmvVerLen,
|  | const KER_CHAR ** | ppchLibVer,
|  | KER_INT16U * | pusLibVerLen
| ) |  |

Obtains emv kernel library version info.

Parameters

  [out] | ppchEmvVer | pointer to obtain reference to Entry Point specification version info (optional, set KER_NULL if you don't need it)
  [out] | pusEmvVerLen | length of data, including nul-terminated symbol (optional, set KER_NULL if you don't need it)
  [out] | ppchLibVer | pointer to obtain reference to Entry Point library version info (optional, set KER_NULL if you don't need it)
  [out] | pusLibVerLen | length of data, including nul-terminated symbol (optional, set KER_NULL if you don't need it)

Returns
  KER_TRUE Success.
  KER_FALSE Failure. Execution failed due to invalid param.

## ◆ epPosPrepareNewTran()

KER_RES KER_API epPosPrepareNewTran | ( | KER_CTX_PARAM const NFC_EXT_TERM_TRAN_DATA * | pTermTranData,
|  | EP_TRAN ** | ppTran,
|  | NFC_OUTCOME ** | ppOutcome
| ) |  |

Prepares new transaction.

This function creates transaction context, loads configuration
and initiates EP transaction pre-processing (EMV Book A, 8.1.1.4) Preprocessing peformed only if transaction data provided, otherwise autorun mode assumed

Parameters

  [in] | pTermTranData | - transaction data, obtained from terminal (optional, set KER_NULL for fixed tran data)
  [out] | ppTran | - pointer to obtain transaction context (set KER_NULL for fixed tran data)
  [out] | ppOutcome | - pointer to obtain transaction outcome

Returns
  KER_OK Success.
  NFC_INF_OUTCOME (Try another interface) see outcome for details. (no active combinations)
  EP_ERR_POS_TRAN_POLLING_CANCELLED Card polling cancelled by external
  EP_ERR_POS_TRAN_POLLING_TIMEOUT Card polling timeout
  Other errors - abort transaction.

Warning
  When tranaction context (ppTran) no longer required call epPosTranRelease. Do it despite of result code retuned.
  TLV list referenced by pTranData should be released externally in any time after epPosPrepareNewTran completion.

## ◆ epPosTran()

KER_RES KER_API epPosTran | ( | KER_CTX_PARAM EP_TRAN * | pTran,
|  | KER_INT32U | ulTimeout,
|  | KER_INT16U | usExtCardTypes,
|  | KER_INT16U * | pusCardType,
|  | KER_BYTE * | pbtUID,
|  | KER_INT16U * | pusUIDLen,
|  | NFC_OUTCOME ** | ppOutcome
| ) |  |

Initiates new transaction.

This function makes nfc transaction, sarting from polling request

Parameters

  [in] | pTran | - pointer to the transaction context (obtained by epPosPrepareNewTran)
  [in] | ulTimeout | - card polling timeout in ms (4 days max) (use 0 for single polling request)
  [in] | usExtCardTypes | Card types for external processing bitmask (set KER_NFCL1_PHISICAL_CARD_TYPE_NONE to process all cards by EP),
  [in,out] | pusCardType | Card type polling for bitmask as input (set KER_NFCL1_PHISICAL_CARD_TYPE_DEFAULT to use internal PCD configuration), located card type as output (optional, set KER_NULL for PCD default settings), see KER_NFCL1_PHISICAL_CARD_TYPE_DEFAULT, KER_NFCL1_PHISICAL_CARD_TYPE_NONE, KER_NFCL1_PHISICAL_CARD_TYPE_ISO14443_A KER_NFCL1_PHISICAL_CARD_TYPE_ISO14443_B KER_NFCL1_PHISICAL_CARD_TYPE_ISO14443_4_A KER_NFCL1_PHISICAL_CARD_TYPE_ISO14443_4_B KER_NFCL1_PHISICAL_CARD_TYPE_MIFARE_A_STD KER_NFCL1_PHISICAL_CARD_TYPE_MIFARE_A_UL KER_NFCL1_PHISICAL_CARD_TYPE_ISO14443_AND_MIFARE KER_NFCL1_PHISICAL_CARD_TYPE_UNKNOWN
  [out] | pbtUID | - located card UID (optional, set KER_NULL if you don't need it)
  [in,out] | pusUIDLen | - located card UID length (optional, set KER_NULL if you don't need it)
  [out] | ppOutcome | - pointer to obtain transaction outcome

Returns
  NFC_INF_OUTCOME See outcome for details.
  EP_ERR_POS_TRAN_EXT_PROCESSING card located, card type match usExtCardTypes, process it externally
  EP_ERR_POS_TRAN_POLLING_CANCELLED card polling cancelled from outside
  EP_ERR_POS_TRAN_POLLING_TIMEOUT card polling timeout
  EP_ERR_POS_TRAN_PCD_FAILURE pcd failure - card or pcd fatal error
  EP_ERR_POS_TRAN_INV_OUTCOME invalid restart Outcome data
  Other errors - abort transaction.

Warning
  When tranaction context (ppTran) no longer required call kerTranRelease. Do it despite of result code retuned.
  TLV list referenced by pTranData should be released externally in any time after epPosNewTran completion.

## ◆ epPosTranRelease()

KER_RES KER_API epPosTranRelease | ( | KER_CTX_PARAM EP_TRAN * | pTran | ) |

Releases transaction context.

This function releases EP transaction context

Parameters

  [in] | pTran | - pointer to the transaction context to release (obtained by epPosPrepareNewTran)

Returns
  KER_OK Success.
  Other errors - Failure.

Warning
  When tranaction context (ppTran) no longer required call kerTranRelease. Do it despite of result code retuned.
  TLV list referenced by pTranData should be released externally in any time after epPosNewTran completion.

## ◆ epPosTranRestart()

KER_RES KER_API epPosTranRestart | ( | KER_CTX_PARAM EP_TRAN * | pTran,
|  | const NFC_EXT_TERM_RESTART_DATA * | pTermRestartData,
|  | KER_INT32U | ulTimeout,
|  | KER_INT16U | usExtCardTypes,
|  | KER_INT16U * | pusCardType,
|  | KER_BYTE * | pbtUID,
|  | KER_INT16U * | pusUIDLen,
|  | NFC_OUTCOME ** | ppOutcome
| ) |  |

Restarts transaction for issuer update, cv-cvm confirmation, etc...

This function restarts nfc transaction, sarting from position, indicated by previous Outcome

Parameters

  [in] | pTran | - pointer to the transaction context (obtained by epPosPrepareNewTran)
  [in] | pTermRestartData | - restart data (with issuer update data) (optional, set KER_NULL if no restart data provided)
  [in] | ulTimeout | - card polling timeout in ms (4 days max) (use 0 for single polling request) This param used for processing Outcome with start type B only, otherwise set 0 value
  [in] | usExtCardTypes | Card types for external processing bitmask (set KER_NFCL1_PHISICAL_CARD_TYPE_NONE to process all cards by EP), This param used for processing Outcome with start type B only, otherwise set 0 value
  [in,out] | pusCardType | Card type polling for bitmask as input (set KER_NFCL1_PHISICAL_CARD_TYPE_DEFAULT to use internal PCD configuration), located card type as output (optional, set KER_NULL for PCD default settings), see KER_NFCL1_PHISICAL_CARD_TYPE_DEFAULT, KER_NFCL1_PHISICAL_CARD_TYPE_NONE, KER_NFCL1_PHISICAL_CARD_TYPE_ISO14443_A KER_NFCL1_PHISICAL_CARD_TYPE_ISO14443_B KER_NFCL1_PHISICAL_CARD_TYPE_ISO14443_4_A KER_NFCL1_PHISICAL_CARD_TYPE_ISO14443_4_B KER_NFCL1_PHISICAL_CARD_TYPE_MIFARE_A_STD KER_NFCL1_PHISICAL_CARD_TYPE_MIFARE_A_UL KER_NFCL1_PHISICAL_CARD_TYPE_ISO14443_AND_MIFARE KER_NFCL1_PHISICAL_CARD_TYPE_UNKNOWN This param used for processing Outcome with start type B only, otherwise set KER_NULL value
  [out] | pbtUID | - located card UID (optional, set KER_NULL if you don't need it) This param used for processing Outcome with start type B only, otherwise set KER_NULL value
  [in,out] | pusUIDLen | - located card UID length (optional, set KER_NULL if you don't need it) This param used for processing Outcome with start type B only, otherwise set KER_NULL value
  [out] | ppOutcome | - pointer to obtain transaction outcome

Returns
  NFC_INF_OUTCOME See outcome for details.
  EP_ERR_POS_TRAN_RESTART_CANCELLED Card polling cancelled by external
  EP_ERR_POS_TRAN_RESTART_TIMEOUT Card polling timeout
  EP_ERR_POS_TRAN_RESTART_FIELDOFF_TIMEOUT not enaugh time to complete field off timeout
  EP_ERR_POS_TRAN_RESTART_REMOVAL_TIMEOUT card removal procedure timeout
  EP_ERR_POS_TRAN_RESTART_REMOVAL_FAILURE card removal procedure failure
  EP_ERR_POS_TRAN_RESTART_PCD_FAILURE pcd failure - card or pcd fatal error
  EP_ERR_POS_TRAN_RESTART_INV_OUTCOME invalid restart Outcome data
  Other errors - abort transaction.

Warning
  When tranaction context (ppTran) no longer required call kerTranRelease. Do it despite of result code retuned.
  TLV list referenced by pIssuerData should be released externally in any time after epPosTranRestart completion.