Contactless API: Difference between revisions

From wizarPOS
No edit summary
No edit summary
Line 1: Line 1:
== Functions ==
== Functions ==
* For CPU card, the follow api calling sequence is [[#open|open]]>[[#search_target_begin|search_target_begin]]>[[#attach_target|attach_target]]>[[#transmit|transmit]]>[[#detach_target|detach_target]]>[[#close|close]],but Filicard don't need to do attach.
* For memory card such as Mifare1 card, the follow api calling sequence is [[#open|open]]>[[#search_target_bego in|search_target_begin]]>[[#verify|verify]]>[[#read|read]] or [[#write|write]]>[[#close|close]]
* For eletronic wallet card, the follow api calling sequence is [[#open|open]]>[[#search_target_begin|search_target_begin]]>[[#verify|verify]]>[[#read_value|read_value]] or [[#write_value|write_value]] or [increment/decrement]>[[#transfer|transfer]]>[[#close|close]], the [increment/decrement] includes the flows:[[#restore|restore]]>[[#increment|increment]]/[[#decrement|decrement]]>[[#transfer|transfer]].
=== open ===
=== open ===
   void* contactless_card_open(CONTACTLESS_CARD_NOTIFIER fNotifier, void* pUserData, int* pErrorCode)
   void* contactless_card_open(CONTACTLESS_CARD_NOTIFIER fNotifier, void* pUserData, int* pErrorCode)

Revision as of 09:41, 12 April 2018

Functions

open

 void* contactless_card_open(CONTACTLESS_CARD_NOTIFIER fNotifier, void* pUserData, int* pErrorCode)

Initialize the contactless card reader.

Parameters

fNotifier Notifier of contactless card
pUserData User data
pErrorCode error code if return value is equals to 0

Returns

The result code, != 0, success, value is the handle of contactless card device; <0 failed.

search_target_begin

 int contactless_card_search_target_begin(int nHandle, int nCardMode, int nFlagSearchAll, int nTimeout_MS)

Start searching the contactless card. If you set the nCardMode is auto, reader will try to activate card in type A, type B and type successively; If you set the nCardMode is type A, type B, or type C, reader only try to activate card in the specified way. You can terminate it using function search_target_end.


Parameters

nHandle Handle of this device, returned from open
nCardMode Mode to search
nFlagSearchAll Not used
nTimeout_MS Time out in millseconds. If it is less than 0, then wait forever.

Possible value of nCardMode :

  • define CONTACTLESS_CARD_MODE_AUTO 0
  • define CONTACTLESS_CARD_MODE_TYPE_A 1
  • define CONTACTLESS_CARD_MODE_TYPE_B 2
  • define CONTACTLESS_CARD_MODE_TYPE_C 3

Returns

The result code, >= 0, success; <0 error code.


search_target_end

 int contactless_card_search_target_end(int nHandle)

Stop the process of searching card.

The search_target_begin and search_target_end apis are pair operations.

Parameters

nHandle Handle of this device, returned from open

Returns

The result code, >= 0, success; <0 error code.

close

 int contactless_card_close(int nHandle)

Close the contactless card reader. open and close are pair operations. If you don’t want to use the device, you should call close to release the device.

Parameters

nHandle Handle of this device, returned from open

Returns

The result code, >= 0, success; <0 error code.

query_info

 int contactless_card_query_info(int nHandle, unsigned int* pHasMoreCards, unsigned int* pCardType)

Query the quantity and type of cards on the contactless card reader.

Parameters

nHandle Handle of this device, returned from open
pHasMoreCards Card quantity
pCardType Card type

Returns

The result code, >= 0, success; <0 error code.

pHasMoreCards:

  • 0 : only one PICC in the field
  • 0x0A : more cards in the field(type A)
  • 0x0B : more cards in the field(type B)
  • 0xAB : more cards in the field(type A and type B)

pCardType:

  • CONTACTLESS_CARD_TYPE_A_CPU 0x0000
  • CONTACTLESS_CARD_TYPE_B_CPU 0x0100
  • CONTACTLESS_CARD_TYPE_A_CLASSIC_MINI 0x0001
  • CONTACTLESS_CARD_TYPE_A_CLASSIC_1K 0x0002
  • CONTACTLESS_CARD_TYPE_A_CLASSIC_4K 0x0003
  • CONTACTLESS_CARD_TYPE_A_UL_64 0x0004
  • CONTACTLESS_CARD_TYPE_A_UL_192 0x0005
  • CONTACTLESS_CARD_TYPE_A_MP_2K_SL1 0x0006
  • CONTACTLESS_CARD_TYPE_A_MP_4K_SL1 0x0007
  • CONTACTLESS_CARD_TYPE_A_MP_2K_SL2 0x0008
  • CONTACTLESS_CARD_TYPE_A_MP_4K_SL2 0x0009
  • CONTACTLESS_CARD_UNKNOWN 0x00FF

attach_target

 int contactless_card_attach_target(int nHandle, unsigned char* pATRBuffer, unsigned int nATRBufferLength)

Attach the target before transmitting APDU command. In this process, the target(card) is activated and return ATR. If the card is a CPU card, the attach_target, detach_target and transmit apis are used to get informations from the card.

Parameters

nHandle Handle of this device, returned from open
pATRBuffer ATR buffer, if null, you can not get data.
nATRBufferLength Length of ATR buffer

Returns

The result code, >= 0, success,length of ATR; <0 error code.

detach_target

 int contactless_card_detach_target(int nHandle)

Detach the target. If you want to send APDU again, you should attach it. The detach is a block method, only when you remove the card can you get the return value of this api.

Parameters

nHandle Handle of this device, returned from open

Returns

The result code, >= 0, success; <0 error code.

transmit

 int contactless_card_transmit(int nHandle, unsigned char* pAPDU, unsigned int nAPDULength, unsigned char* pResponse, unsigned int *pResponseLength)

Transmit APDU command and get the response. The APDU command of contactless card is the same as the IC card normally.

Parameters

nHandle Handle of this device, returned from open
pAPDU Command of APDU
nAPDULength Length of command
pResponse Response buffer of APDU command
pResponseLength buffer length of response

Returns

The result code, >= 0, success; <0 error code.

verify

 int contactless_card_mc_verify_pin(int nHandle, unsigned int nSectorIndex, unsigned int nPinType, unsigned char* strPin, unsigned int nPinLength)

Verify the key of the contactless card. You should firstly know the key and corresponding key type(key A or key B). If the card is a Mifare card, the verify, read and write apis are used to get informations from the card.

Parameters

nHandle Handle of this device, returned from open
nSectorIndex Sector index
nPinType Key type:0—Key A; 1—Key B
strPin Password of this sector
nPinLength Length of password

Returns

The result code, >= 0, success; <0 error code.

read

 int contactless_card_mc_read(int nHandle, unsigned int nSectorIndex, unsigned int nBlockIndex, unsigned char* pDataBuffer, unsigned int nDataBufferLength)

Read data from the contactless card. You should verify the key at first. You should firstly know the card format(how many sectors, blocks and block size) from the card producer.

Parameters

nHandle Handle of this device, returned from open
nSectorIndex Sector index
nBlockIndex Block index of the specified sector
pDataBuffer Data buffer to read
nDataBufferLength Buffer length

Returns

The result code, >= 0, success; <0 error code.

write

 int contactless_card_mc_write(int nHandle, unsigned int nSectorIndex, unsigned int nBlockIndex, unsigned char* pData, unsigned int nDataLength)

Write data to the contactless card. You should verify the key at first.

Parameters

nHandle Handle of this device, returned from open
nSectorIndex Sector index
nBlockIndex Block index of the specified sector
pData Data buffer to write
nDataLength Buffer length

Returns

The result code, >= 0, success; <0 error code.

write_value

 int contactless_card_mc_write_value(int nHandle, unsigned int nSectorIndex, unsigned int nBlockIndex, unsigned char* pValue, unsigned int nValueLength, unsigned char pAddrData)

Write money value and user data to the specified block if the card is an electronic wallet format card. This api will format the MC card as an electronic wallet format card. If you want to use the following apis, you should firstly confirm that the card is an electronic wallet format card.

Parameters

nHandle Handle of this device, returned from open
nSectorIndex Sector index
nBlockIndex Block index of the specified sector
pValue money value to write
nValueBufLength Buffer length
pAddrData User data

Returns

The result code, >= 0, success; <0 error code.

read_value

 int contactless_card_mc_read_value(int nHandle, unsigned int nSectorIndex, unsigned int nBlockIndex, unsigned char* pValue, unsigned int nValueBufLength, unsigned char* pAddrData)

Parameters

nHandle Handle of this device, returned from open
nSectorIndex Sector index
nBlockIndex Block index of the specified sector
pValue [out]buffer for saving value. LSB, 4 bytes
nValueBufLength Buffer length
pAddrData [out]buffer for saving a user data, 1 byte

Returns

The result code, >= 0, success; <0 error code.

increment

 int contactless_card_mc_increment(int nHandle, unsigned int nSectorIndex, unsigned int nBlockIndex, unsigned char* pValue, unsigned int nValueLength)

Increase value to a block. This api should be used with restore and transfer. Parameters

nHandle Handle of this device, returned from open
nSectorIndex Sector index
nBlockIndex Block index of the specified sector
pValue money value to write
nValueBufLength Buffer length, must be greater than 4

Returns

The result code, >= 0, success; <0 error code.

decrement

 int contactless_card_mc_decrement(int nHandle, unsigned int nSectorIndex, unsigned int nBlockIndex, unsigned char* pValue, unsigned int nValueLength)

Decrease value to a block. This api should be used with restore and transfer.

Parameters

nHandle Handle of this device, returned from open
nSectorIndex Sector index
nBlockIndex Block index of the specified sector
pValue money value to write
nValueBufLength Buffer length, must be greater than 4

Returns

The result code, >= 0, success; <0 error code.

restore

 int contactless_card_mc_restore(int nHandle,unsigned int nSectorIndex, unsigned int nBlockIndex)

Read the money value to the temporary from a block. This is a necessary step if you want to increase or decrease the value of the electronic wallet card. Parameters

nHandle Handle of this device, returned from open
nSectorIndex Sector index
nBlockIndex Block index of the specified sector

Returns

The result code, >= 0, success; <0 error code.

transfer

 int contactless_card_mc_restore(int nHandle,unsigned int nSectorIndex, unsigned int nBlockIndex)

This api should be used after increment or decrement. Parameters

nHandle Handle of this device, returned from open
nSectorIndex Sector index
nBlockIndex Block index of the specified sector

Returns

The result code, >= 0, success; <0 error code.