Advanced Card Systems Ltd. Website: www.acs.com.hk Email: info

APPLICATION PROGRAMMING INTERFACE

@acs.com.hk

AACCRR3300

ACR30 API Version 2.6 January 2009

Page 2 of 29

A C R 3 0

Table of Contents

1.0. Introduction ............................................................................................................... 42.0. ACR30 ........................................................................................................................ 52.1. Overview ................................................................................................................................ 5

2.2. Communication Speed .......................................................................................................... 5

3.0. ACR30 API ................................................................................................................. 63.1. Interface Data Structure ......................................................................................................... 6

3.1.1. AC_APDU ..................................................................................................................... 6

3.1.2. AC_SESSION ............................................................................................................... 7

3.1.3. AC_INFO ....................................................................................................................... 7

3.2. Interface Function Prototypes ................................................................................................ 9

3.2.1. AC_RescanBus ............................................................................................................. 9

3.2.2. AC_Open ...................................................................................................................... 9

3.2.3. AC_Close .................................................................................................................... 10

3.2.4. AC_StartSession ......................................................................................................... 12

3.2.5. AC_EndSession .......................................................................................................... 13

3.2.6. AC_ExchangeAPDU ................................................................................................... 14

3.2.7. AC_GetInfo ................................................................................................................. 16

3.2.8. AC_SetOptions ........................................................................................................... 18

3.3. ACI Commands ................................................................................................................... 20

3.3.1. AC_GPM103 / AC_SLE4406 / AC_SLE4436 / AC_SLE5536 .................................... 20

3.3.1.1. ACI_Read .................................................................................................................... 20

3.3.1.2. ACI_Write .................................................................................................................... 20

3.3.1.3. ACI_WriteCarry ........................................................................................................... 21

3.3.1.4. ACI_Verify ................................................................................................................... 21

3.3.1.5. ACI_Authenticate (For SLE4436 and SLE5536) ........................................................ 22

3.3.2. AC_I2C_1K_16K / AC_I2C_32K_1024K .................................................................... 23

3.3.2.1. ACI_Read .................................................................................................................... 23

3.3.2.2. ACI_Write .................................................................................................................... 23

3.3.3. SLE4418 / SLE4428 ................................................................................................... 24

3.3.3.1. ACI_Read .................................................................................................................... 24

3.3.3.2. ACI_Write .................................................................................................................... 24

3.3.3.3. ACI_WritePr ................................................................................................................ 25

3.3.3.4. ACI_Verify [SLE4428 Only] ......................................................................................... 25

3.3.4. SLE4432 / SLE4442 ................................................................................................... 26

3.3.4.1. ACI_Read .................................................................................................................... 26

3.3.4.2. ACI_Write .................................................................................................................... 26

ACR30 API Version 2.6 January 2009

Page 3 of 29

A C R 3 0

3.3.4.3. ACI_WritePr ................................................................................................................ 27

3.3.4.4. ACI_Verify [SLE4442 Only] ......................................................................................... 27

3.3.4.5. ACI_ChangePIN [SLE4442 Only] ............................................................................... 28

Appendix A: Table of error codes ..................................................................................... 29

ACR30 API Version 2.6 January 2009

Page 4 of 29

A C R 3 0

1.0. Introduction This manual describes the use of ACR30 interface software to program the ACR30 smart card readers. It is a set of library functions implemented for the application programmers to operate the ACR30 smart card readers and the inserted smart cards. Currently, it is supplied in the form of 32-bit DLL (for Windows 95/98/NT). It can be programmed using the popular development tools like Visual C/C++, Borland C/C++, Visual Basic, Delphi, FoxPro, etc.

Depending on the reader model, ACR30 series of smart card readers can be connected to the PC via the RS/232 interface or USB interface. The connecting interfaces of different model of readers are summarized as follows:

Model Numbers Connecting interface

ACR30S, ACR30S-S

Serial RS/232

ACR30U

USB interface

Even though the hardware communication interface can be different, application programs can still use the same API (Application Programming Interface) for operating the smart card readers. Actually, the purpose of using the ACR30 library is to provide the programmer with a simple and consistent interface over all possible hardware. It is the responsibility of the ACR30 library to handle the communication details, parameter conversions and error handling. The architecture of the ACR30 library can be visualized as the following diagram:

RS-232 / USB

ACR30

Series of

Smart Card Reader

CardEasy

ACR30

Windows

Application Program

Driver Program

Operating System

PC Reader

Figure 1.1

Layer

ACR30 API Version 2.6 January 2009

Page 5 of 29

A C R 3 0

2.0. ACR30

2.1. Overview ACR30 is a set of high-level functions provided for the application software to use. It provides a consistent application programming interface (ACR30 API) for the application to operate on the card reader and the corresponding inserted card. ACR30 communicates with the ACR30 reader via the communication port facilities provided by the operating system. ACR30 is supposed to be platform independent provided that there is a minor modification on the communication module of the ACR30 to adapt to different operating environments.

2.2. Communication Speed The ACR30 library controls the communication speed between the reader and the PC. For those readers using the serial RS232 connection, the default communication baud rate (factory setting) is 9600bps, no parity, eight bits and one-stop bits. A higher speed of 115200bps can be achieved by using software command issuing from the host. Please notice that the above communication speed setting applies only on those readers using the RS232 connection. For the USB type of connection, the speed is fixed at 9600bps and 1.5Mbps respectively.

ACR30 API Version 2.6 January 2009

Page 6 of 29

A C R 3 0

3.0. ACR30 API The ACR30 Application Programming Interface (API) defines a common way of accessing the ACR30 reader. Application programs invoke ACR30 through the interface functions and perform operations on the inserted card through the use of ACI commands. The header file ACR30.H, which contains all the function prototypes and macros described below, is available for the program developer.

3.1. Interface Data Structure The ACR30 API makes use of several data structures to pass parameters between application programs and the library driver. These data structures are defined in the header file ACR30.H and they are discussed below:

3.1.1. AC_APDU typedef struct { BYTE CLA; BYTE INS; BYTE P1; BYTE P2; INT16 Lc; INT16 Le; BYTE DataIn[256]; BYTE DataOut[256]; WORD16 Status; } AC_APDU;

The AC_APDU data structure is used in the AC_ExchangeAPDU function for the passing of commands and data information into the smart card. For memory card ope