Contactless API
Functions
- For CPU card, the follow api calling sequence is open>search_target_begin>attach_target>transmit>detach_target>close,but Filicard don't need to do attach.
- For memory card such as Mifare1 card, the follow api calling sequence is open>search_target_begin>verify>read or write>close
- For eletronic wallet card, the follow api calling sequence is open>search_target_begin>verify>read_value or write_value or [increment/decrement]>transfer>close, the [increment/decrement] includes the flows:restore>increment/decrement>transfer.
open
void* contactless_card_open(CONTACTLESS_CARD_NOTIFIER fNotifier, void* pUserData, int* pErrorCode)
Initialize the contactless card reader.
Parameters
| fNotifier | CONTACTLESS_CARD_NOTIFIER | Notifier of contactless card |
| pUserData | void* | User data |
| pErrorCode | int* | 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 | int | Handle of this device, returned from open |
| nCardMode | int | Mode to search |
| nFlagSearchAll | int | Not used |
| nTimeout_MS | int | 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 | int | 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 | int | 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 | int | Handle of this device, returned from open |
| pHasMoreCards | int* | Card quantity |
| pCardType | int* | 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 | int | Handle of this device, returned from open |
| pATRBuffer | unsigned char* | ATR buffer, if null, you can not get data. |
| nATRBufferLength | int | 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 | int | 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 | int | Handle of this device, returned from open |
| pAPDU | unsigned char* | Command of APDU |
| nAPDULength | unsigned int | Length of command |
| pResponse | unsigned char* | Response buffer of APDU command |
| pResponseLength | unsigned int | 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 | int | Handle of this device, returned from open |
| nSectorIndex | unsigned int | Sector index |
| nPinType | unsigned int | Key type:0—Key A; 1—Key B |
| strPin | unsigned char* | Password of this sector |
| nPinLength | unsigned int | 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 | int | Handle of this device, returned from open |
| nSectorIndex | unsigned int | Sector index |
| nBlockIndex | unsigned int | Block index of the specified sector |
| pDataBuffer | unsigned char* | Data buffer to read |
| nDataBufferLength | unsigned int | 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 | int | Handle of this device, returned from open |
| nSectorIndex | unsigned int | Sector index |
| nBlockIndex | unsigned int | Block index of the specified sector |
| pData | unsigned char* | Data buffer to write |
| nDataLength | unsigned int | 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 | int | Handle of this device, returned from open |
| nSectorIndex | unsigned int | Sector index |
| nBlockIndex | unsigned int | Block index of the specified sector |
| pValue | unsigned char* | money value to write |
| nValueBufLength | unsigned int | Buffer length |
| pAddrData | unsigned char | 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 | int | Handle of this device, returned from open |
| nSectorIndex | unsigned int | Sector index |
| nBlockIndex | unsigned int | Block index of the specified sector |
| pValue | unsigned char* | buffer for saving value. LSB, 4 bytes |
| nValueBufLength | unsigned int | Buffer length |
| pAddrData | unsigned char* | 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 | int | Handle of this device, returned from open |
| nSectorIndex | unsigned int | Sector index |
| nBlockIndex | unsigned int | Block index of the specified sector |
| pValue | unsigned char* | money value to write |
| nValueBufLength | unsigned int | 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 | int | Handle of this device, returned from open |
| nSectorIndex | unsigned int | Sector index |
| nBlockIndex | unsigned int | Block index of the specified sector |
| pValue | unsigned char* | money value to write |
| nValueBufLength | unsigned int | 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 | int | Handle of this device, returned from open |
| nSectorIndex | unsigned int | Sector index |
| nBlockIndex | unsigned int | Block index of the specified sector |
Returns
The result code, >= 0, success; <0 error code.