Smart Card API

API Overview

query_max_number and query_presence are independent of open and close .

If the card inserted is a CPU card, the normally calling sequence is: open>power_on>transmit>power_off>close

If the card inserted is a memory card, the normally calling sequence is: open>power_on>mc_verify>mc_read/mc_write>power_off>close

open

int smart_card_open(int nSlotIndex, SMART_CARD_NOTIFIER pNotify, void* pUserData)

Open the specified slot of the smart card reader. This operation should be used before other operations. A notifier is registered after this API is called.

Parameters
nSlotIndex	int: Slot index, from 0 to MAX - 1
pNotify	SMART_CARD_NOTIFIER: Notifier of smart card reader
pUserData	void*: User data

Definite is as follows:

typedef void (*SMART_CARD_NOTIFIER)

//nEvent:	
define SMART_CARD_EVENT_INSERT_CARD		0
define SMART_CARD_EVENT_REMOVE_CARD		1
define SMART_CARD_EVENT_POWER_ON		2
define SMART_CARD_EVENT_POWER_OFF		3

Returns
int	The result code, >= 0, success,value as handle of this device; <0 error code.

close

int smart_card_close(int nHandle)

Close the specified slot of the smart card reader which is opened before. The open and close apis are pair operations. If you don’t want to use this device, you should call the close api to release this device. The nSlotIndex of open and close should be all the same.

Parameters
nHandle	int: Handle of this device, returned from open

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

query_max_number

int smart_card_query_max_number()

Query the max slot in this smart card reader. Normally the IC card slot index is 0, other slots are used for PSAM card.

Returns
int	The result code, > 0, number of slot; = 0, not defined; <0 error code.

query_presence

int smart_card_query_presence(int nSlotIndex)

Query whether the smart card is existent in the selected slot. Attention: not every slot can support this function. This API can be used before open operation.

Parameters
nSlotIndex	int: Slot index, from 0 to MAX - 1

Returns
int	The result code, > 0, exist; = 0, not exist; <0 error code.

set_slot_info

int smart_card_set_slot_info(int nHandle, SMART_CARD_SLOT_INFO* pSlotInfo)

The function set the slot control information.

Parameters
nHandle	int: Handle of this device, returned from open
pSlotInfo	SMART_CARD_SLOT_INFO*: slot information

typedef struct smart_card_slot_info
{
    /** \show initializer Speed communication (parameter TA1 of ISO 7816-3) */
    unsigned char FIDI;

    /** \show initializer Extra Guard Time (parameter TC1 or N of ISO 7816-3) */
    unsigned char EGT;

    /**  \show initializer
     * If protocol T=0 is selected, the parameter indicates the Waiting
     * Integer (parameter TC2 of ISO 7816-3 - the default value is 10)
     * If the protocol T=1 is selected, the parameter indicates the
     * Block and Character Waiting Time Integer (parameter TB3 of ISO 7816-3)
     */
    unsigned char WI;

     /** \show initializer If the protocol T=1 is selected, the parameter indicates the
      * Waiting Time Extention (the default value is 1). */
    unsigned char WTX;

    /** \show initializer If the protocol T=1 is selected, the parameter indicates the computing
     * mode for EDC : HAL_SCS_EDC_LRC or HAL_SCS_EDC_CRC (The default value
     * is an LRC) */
    unsigned char EDC;

    /** \show initializer The parameter indicates the selected protocol :
     *  HAL_SCS_PROTOCOL_T0
     *  HAL_SCS_PROTOCOL_T1 */
    unsigned char protocol;


    /** \show initializer The power supply value :
     *  HAL_SCS_POWER_1_8V
     *  HAL_SCS_POWER_3V
     *  HAL_SCS_POWER_5V
     */
    unsigned char power;

    /** \show initializer Convention used to transfer byte :
     *  HAL_SCS_CONV_DIRECT
     *  HAL_SCS_CONV_INVERSE */
    unsigned char conv;

    /** \show initializer If the protocol T=1 is selected, the parameter indicates the Information
     * Field Size for the Card (parameter TA3 of ISO 7816-3). */
    unsigned char IFSC;
    unsigned char reserved[3];
    /** \show initializer Possibility to set Character Waiting Time */
    unsigned int cwt;
    /** \show initializer Possibility to set Block Waiting Time */
    unsigned int bwt;
    /*
     * OR of these items:
     * 		SMART_CARD_SLOT_INFO_FIDI		(1 << 0)
	 *		SMART_CARD_SLOT_INFO_EGT		(1 << 1)
	 *		SMART_CARD_SLOT_INFO_WI			(1 << 2)
	 *		SMART_CARD_SLOT_INFO_WTX		(1 << 3)
	 *		SMART_CARD_SLOT_INFO_EDC		(1 << 4)
	 *		SMART_CARD_SLOT_INFO_PROTOCOL	(1 << 5)
	 *		SMART_CARD_SLOT_INFO_POWER		(1 << 6)
	 *		SMART_CARD_SLOT_INFO_CONV		(1 << 7)
	 *		SMART_CARD_SLOT_INFO_IFSC		(1 << 8)
	 * 		SMART_CARD_SLOT_INFO_CWT		(1 << 9)
	 *		SMART_CARD_SLOT_INFO_BWT		(1 << 10)
     *
     */
    unsigned int nSlotInfoItem;
}SMART_CARD_SLOT_INFO;

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

power_on

int smart_card_power_on(int nHandle, unsigned char* pATR, unsigned int* pATRLength, SMART_CARD_SLOT_INFO* pSlotInfo)

Power on the smart card in the slot opened before.

Parameters
nHandle	int: Handle of this device, returned from open
pATR	unsigned char*: ATR from IC card
pATRLength	unsigned int*: Length of ATR
pSlotInfo	SMART_CARD_SLOT_INFO*: slot information

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

power_off

int smart_card_power_off(int nHandle)

Power off the smart card in the slot opened before. This API should be used after power_on. Power_on and power_off are pair operations.

Parameters
nHandle	int: Handle of this device, returned from open

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

transmit

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

The function sends a command Application Protocol Data Unit(APDU) to a card and retrieve the response APDU, plus the status words SW1 and SW2. This API should be used between power_on and power_off. If the inserted card is a CPU card, call power_on, transmit, power_off after open.

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*: Card response of APDU command
pResponseLength	unsigned int: Length of response

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

mc_verify

int smart_card_mc_verify_data(int nHandle, unsigned char* pData, unsigned int nDataLength)

If the inserted card is a memory card, verify its password.

Parameters
nHandle	int: Handle of this device, returned from open
pData	unsigned char*: Key data
nDataLength	unsigned int: Length of key

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

mc_read

int smart_card_mc_read(int nHandle, unsigned int nAreaType, unsigned char* pDataBuffer, unsigned int nDataLength, unsigned char cStartAddress)

The function is responsible for reading memory card information.

Parameters
nHandle	int: Handle of this device, returned from open
nAreaType	unsigned int: Area type: 0-main memory; 1-protected memory; 2-security momory
pDataBuffer	unsigned char*: Data buffer
nDataLength	unsigned int: Data length of expecting reading
cStartAddress	unsigned char: Starting address to read

Returns
int	The result code, >= 0, success, the data length of read; <0 error code.

mc_write

int smart_card_mc_write(int nHandle, unsigned int nAreaType, unsigned char* pData, unsigned int nDataLength, unsigned char cStartAddress)

The function is responsible for writing data to memory card. The mc_read and mc_write APIs are used after mc_verify. If the inserted card is a memory card, call mc_verify, mc_read, mc_write after open

Parameters
nHandle	int: Handle of this device, returned from open
nAreaType	unsigned int: Area type: 0--main memory,1--protected memory,2--security momory
pData	unsigned char*: Data buffer
nDataLength	unsigned int: Data length of expecting writing
cStartAddress	unsigned char: Starting address to write

Returns
int	The result code, >= 0, success, the data length of written; <0 error code.