PAX XXX Programming Guide Prolin+API+Programming+Guide(V2.1.1)
User Manual:
Open the PDF directly: View PDF .
Page Count: 243
Download | ![]() |
Open PDF In Browser | View PDF |
Prolin API Programming Guide V 2.1.1 PAX Computer Technology(Shenzhen)Co.,Ltd. Copyright © 2000-2015 PAX Computer Technology (Shenzhen) Co., Ltd. All rights reserved. No part of the contents of this document may be reproduced or transmitted in any form without the written permission of PAX Computer Technology (Shenzhen) Co., Ltd. The information contained in this document is subject to change without notice. Although PAX Computer Technology (Shenzhen) Co., Ltd. has attempted to ensure the accuracy of the contents of this document, this document may include errors or omissions. The examples and sample programs are for illustration only and may not be suited for your purpose. You should verify the applicability of any example or sample program before placing the software into productive use. I Revision History Date Version Note Author 2012-08-29 V1.0.0 Translated from Chinese standard version Prolin of ‗Prolin API Programming Guide Team v1.0.0‘. 2012-11-19 V1.0.1 Modified the interfaces. 1. 2012-12-26 2013-02-20 V1.0.2 V1.0.3 3. 4. Added the return code list in the System function; Added a new interface Prolin OsVerifySignExternal(); Team Added the WIFI module; Added the Register table in Appendix 1. Added descriptions in OsOpenFont (). 1. Modified the description of OsModemOpen(); Added two return values -3219 and -3220 in Modem; Added the instruction of DetectDailTone; Prolin Added a new function Team OsModemSwitchPower(); Modified the parameter description of OsPrnOpen(), it does not support the png format; Modified the sci_get_fd (). 2. 2. 3. 2013-03-06 V1.0.4 4. 5. 6. 1. 2. 3. 2013-04-17 V1.0.5 4. 2013-05-17 V1.0.6 Prolin Team 1. 2. 3. 4. Prolin Team Modified the 14.4.1 open() node; Updated the time setting code, Modify the ―pow-hwclock -w‖ to ―pow-hwclock -w -u‖; Updated the fifth term of OsWlInit() Prolin instruction; when the return value is Team ERR_WL_NOSIM (without SIM card), application can use some functions without SIM card. Updated the instruction of the OsCheckBattery (). Modified the description of ‗Timer‘. Added description of ‗Delay‘. Prolin Added description for registry table. Team Modified the parameter description of Value inOsRegGetValue (). II 5. 6. 7. 2013-08-09 V1.0.7 1. 2. 3. 4. Modified the Registry table. Modified the data structure of Font. Prolin Updated the OsCheckBattery() Team Updated the chapter 15 ICC Reader and chapter 16 RF Reader. 1. Added 4.11 Save the crash report for system function. Modified the brightness level to [0~10] in the chapter of LCD.In Prolin particular , 0 indicates closing the Team backlight Updated the key value definitions in the chapter of Keyboard. 2. 2013-10-22 V1.0.8 3. 1. 2. 2013-10-31 V1.0.9 3. 4. 1. 2. 3. 2013-11-20 V2.0.0 4. 5. 6. 7. 8. 9. 2014-2-25 V2.0.1 Modified the parameter description of ShaOut inOsSHA (). Updated the description of GUI. Added ‗1200, V22‘ and‗2400, FC‘ to the parts of synchronous variable for MODEM. 1. Updated the chapter of System function Modified the OsCodeConvert() in the character conversion. Prolin Added new interfaces OsPortReset() Team and OsPortCheckTx() in the Communication chapter. Updated the Audio chapter, add a new interface OsPlayWave(). Added the KeyVarType parameter associated with the description of 0x02 Modified the parameters value ranges in several chapters associated with PED. Modified the description of parameter ucATQ0 in OsPiccAntiSel (). Prolin Deleted OsPiccGetParam() and Team OsPiccSetParam(). Updated the instruction of OsRegGetValue(). Added notes of OsPortOpen(). Updated instructions of OsSysSleep() Updated the Return code list in chapter Network Configuration. Added instruction of OsNetDns(). Modified the OsWlSelSim(). III instruction of Prolin Team 2. Added a return value forOsMsrOpen(). 3. Added new interfaces OsWlLoginEx(), OsMount(), OsUmount(). 4. Add chapter 26 Barcode. 5. Add AES functions. 6. Updated the Appendix 4. 7. Modified the parameter Name in the OsInstallFile(). 8. Added an error code ―ERR_APP_MODE‖ for theOsInstallFile(). 9. Added a new interface OsCheckPowerSupply(). 10. Since Prolin2.4 upgrade, deleted the unsuccessful code in chapter 7 LCD. 2014-3-4 V2.0.2 1. 2. Updated the OsSysSleep(). Updated the WIFI module. Prolin Team 2014-3-24 V2.0.3 1. Modified the WIFI module. Prolin Team 1. Updated OsWifiConnect() and OsWifiCheck(). Added a new interface OsSysSleepEx(). Prolin Added new interface OsReboot() and Team OsPowerOff(). Removed the MS-MOVE in parameter MountFlags. 2. 2014-4-16 V2.0.4 3. 4. 1. 2. 3. 2014-6-3 V2.0.5 4. 5. 6. 7. 2014-07-10 V2.0.6 1. 2. 3. Modified the instruction of OsPrnSetIndent(). Modified the functionality description of OsModemCheck(). Modified the description of the parameter TimeoutMS in OsPortRecv(). Prolin Modified the value range of the Team parameter Volume in OsPlayWave(). Modified the OsMifareOperate(). Listed the corresponding relation between device node and serial port. Updated the instructions of OsWlSwitchSleep() and OsWifiSwitchPower(). Updated the instructions of OsLog(). Updated the return value of Prolin Team OsPedSetInterval(). Added a new interface IV 4. 5. 6. OsPedCancelPinEntry(). Added return values OsVerifySign() OsVerifySignExternal(). Updated the instruction OsCheckBattery(). Updated the Appendix 3 Appendix 4. for and of and V2.0.7 1. Updated the return value of OsWlLogin() and add the corresponding new instruction. Prolin 2. Modified int OsWifiClose(void) to Team void OsWifiClose(void); 3. Modified the nodes of LCD, keypad, touch screen devices. 2014-11-26 V2.0.8 1. Modified the instrunction of the OsRunApp(). 2. Added the U disk file format limitation in OsMount(). 3. Added the specification about S920 in parameter ‗Channel‘ in OsPortOpen(). 4. Added the instruction of OsNetPing(). 5. Modified the instruction of OsNetDns(). 6. Modified the instruction of OsNetSetConfig(). 7. Added the instruction of OsNetStartDhcp(). 8. Modified the function and added a Prolin new return value for Team OsNetSetRoute(). 9. Modified the function, return values and instruction of OsNetGetRoute(). 10. Modified the instruction of OsPppoeLogin(). 11. Modified the instruction of OsWILogin(). 12. Modified the instruction of OsWILoginEx(). 13. Added WAVE file sampling frequency limitation in OsPlayWave(). 14. Added new instructions for S920 models in appendix 4. 2014-12-18 V2.0.9 1. Added a new function OsNetPingEx() Prolin to check the the status of connection. 2014-10-09 V 2. Added some return code in 2.2 general Team return code. 3. Added a return value and instruction in OsPrnOpen(). 4. Added some return values and instruction in OsWlLock(). 5. Added a new return value and instruction in OsWlLogout(). 6. Modified the description of the return value in OsCheckBattery(). 7. Added a new instruction in OsNetSetRoute(). 8. Added a new system upgrade block with two functions OsFirmwareGetVersion() and OsFirmwareUpgrade() in the chapter of System Function. 2015-02-06 V2.1.0 1. Added a new return value ERR_APP_NOT_EXIST in OsRunApp(). 2. Modified the instruction of OsPedSetInterval(). 3. Updated the parameter DataIn in OsPedUpdatePinBlock(). 4. Modified the instruction of OsPedDesDukpt(). 5. Modified the parameter DataInLen in OsPedRsaRecover(). 6. Modified the Appendix 1. 7. Added a new return value ERR_WL_NOREG in OsWlInit() Prolin function indicating registering GPRS Team network failed. 8. Added a new note in wifi module like this: At present, Prolin WIFI only supports module with keyword ro.fac.wifi is ―RS9110-N-11-02‖ or ―01‖. 9. Added a new note in OsPortOpen() function: calling this function will functions of close software flow control and hardware flow control. 10. Added two lines of code in set the configuration parameters of communication port. VI 1. 2015-04-13 V2.1.1 2. Added the instruction of LCD size and rotation method of different POS models in Appendix 4. Added a new return value ERR_BATTERY_ABSENT in function OsWifiOpen() and its corresponding instruction. VII Prolin API Programming Guide Contents 1 2 Introduction ....................................................................................................................... 14 1.1 Purpose ................................................................................................................... 14 1.2 Readers ................................................................................................................... 14 1.3 Prerequisite ............................................................................................................ 15 1.4 Related Documents ................................................................................................ 15 1.5 Abbreviation .......................................................................................................... 15 1.6 Document Conventions .......................................................................................... 16 Return Code and Parameter ............................................................................................... 19 2.1 Return code classification ...................................................................................... 19 2.2 General return code ................................................................................................ 20 2.3 Parameter Specification ......................................................................................... 21 3 Thread ................................................................................................................................ 23 4 System Function ................................................................................................................ 25 4.1 Return code list ...................................................................................................... 25 4.2 Data Definition....................................................................................................... 26 4.3 Timeset ................................................................................................................... 27 4.3.1 OsSetTime ...................................................................................................... 27 4.3.2 OsGetTime...................................................................................................... 27 4.4 Timer ...................................................................................................................... 28 4.4.1 OsTimerSet ..................................................................................................... 28 4.4.2 OsTimerCheck ................................................................................................ 28 4.5 Delay ...................................................................................................................... 28 4.5.1 OsSleep ........................................................................................................... 28 4.6 Thread .................................................................................................................... 28 4.7 Log ......................................................................................................................... 29 4.7.1 OsLogSetTag .................................................................................................. 29 4.7.2 OsLog ............................................................................................................. 29 4.8 Get the count value ................................................................................................ 30 4.8.1 OsGetTickCount ............................................................................................. 30 PAX Computer Technology (Shenzhen) Co., Ltd. 1 Prolin API Programming Guide 4.9 Get Appliaction information .................................................................................. 30 4.9.1 OsGetAppInfo ................................................................................................ 30 4.10 Buzzer .................................................................................................................... 31 4.10.1 OsBeep ........................................................................................................ 31 4.11 Run Application ..................................................................................................... 31 4.11.1 OsRunApp................................................................................................... 31 4.12 Set and Read the registry table............................................................................... 32 4.12.1 OsRegSetValue ........................................................................................... 32 4.12.2 OsRegGetValue .......................................................................................... 32 4.13 Install and uninstall files ........................................................................................ 33 4.13.1 OsInstallFile ................................................................................................ 33 4.13.2 OsUninstallFile ........................................................................................... 34 4.14 System firmware upgrade ...................................................................................... 34 4.14.1 OsFirmwareGetVersion .............................................................................. 34 4.14.2 OsFirmwareUpgrade ................................................................................... 35 4.15 Verify signature ..................................................................................................... 35 4.15.1 OsVerifySign .............................................................................................. 35 4.15.2 OsVerifySignExternal ................................................................................. 36 4.16 Get system version ................................................................................................. 37 4.16.1 OsGetSysVer............................................................................................... 37 4.17 Determine whether on the base .............................................................................. 37 4.17.1 OsOnBase ................................................................................................... 38 4.18 Save the crash report .............................................................................................. 38 4.18.1 OsSaveCrashReport .................................................................................... 38 4.19 Mount and Unmount the external file system ........................................................ 39 4.19.1 OsMount ..................................................................................................... 39 4.19.2 OsUmount ................................................................................................... 40 5 Encryption and Decryption ................................................................................................ 41 5.1 Return code list ...................................................................................................... 41 5.2 Random number ..................................................................................................... 41 PAX Computer Technology (Shenzhen) Co., Ltd. 2 Prolin API Programming Guide 5.2.1 OsGetRandom ................................................................................................ 41 5.3 SHA algorithm ....................................................................................................... 42 5.3.1 OsSHA ............................................................................................................ 42 5.4 DES algorithm ....................................................................................................... 42 5.4.1 OsDES ............................................................................................................ 43 5.5 AES algorithm ....................................................................................................... 43 5.5.1 OsAES ............................................................................................................ 43 5.6 RSAalgorithm ........................................................................................................ 44 5.6.1 OsRSA ............................................................................................................ 44 5.6.2 OsRSAKeyGen ............................................................................................... 45 6 PED .................................................................................................................................... 47 6.1 Return code list ...................................................................................................... 47 6.2 Data Definition....................................................................................................... 49 6.2.1 Key type .......................................................................................................... 49 6.2.2 Display attribute of Asterisk ........................................................................... 49 6.3 Data Structure ........................................................................................................ 49 6.3.1 Structure of RSA key ...................................................................................... 49 6.3.2 RSA key structure for verifying the ciphertext IC card PIN .......................... 50 6.4 Basic PED .............................................................................................................. 50 6.4.1 OsPedOpen ..................................................................................................... 50 6.4.2 OsPedGetVer .................................................................................................. 51 6.4.3 OsPedSetInterval ............................................................................................ 51 6.4.4 OsPedVerifyPlainPin ...................................................................................... 51 6.4.5 OsPedVerifyCipherPin ................................................................................... 53 6.4.6 OsPedEraseKeys ............................................................................................. 54 6.4.7 OsPedSetFunctionKey .................................................................................... 55 6.4.8 OsPedClose ..................................................................................................... 55 6.4.9 OsPedCancelPinEntry .................................................................................... 56 6.5 MK/SK ................................................................................................................... 56 6.5.1 OsPedWriteKey .............................................................................................. 56 PAX Computer Technology (Shenzhen) Co., Ltd. 3 Prolin API Programming Guide 6.5.2 OsPedWriteTIK .............................................................................................. 58 6.5.3 OsPedWriteKeyVar ........................................................................................ 60 6.5.4 OsPedSetAsteriskLayout ................................................................................ 60 6.5.5 OsPedGetPinBlock ......................................................................................... 61 6.5.6 OsPedUpdatePinBlock ................................................................................... 62 6.5.7 OsPedGetMac ................................................................................................. 63 6.5.8 OsPedDes........................................................................................................ 64 6.5.9 OsPedGetKcv ................................................................................................. 65 6.5.10 OsPedDeriveKey......................................................................................... 66 6.6 DUKPT .................................................................................................................. 67 6.6.1 OsPedGetPinDukpt ......................................................................................... 67 6.6.2 OsPedGetMacDukpt ....................................................................................... 69 6.6.3 OsPedDesDukpt.............................................................................................. 70 6.6.4 OsPedGetKsnDukpt........................................................................................ 71 6.6.5 OsPedIncreaseKsnDukpt ................................................................................ 71 6.7 RSA ........................................................................................................................ 72 6.7.1 OsPedReadRsaKey ......................................................................................... 72 6.7.2 OsPedWriteRsaKey ........................................................................................ 72 6.7.3 OsPedRsaRecover .......................................................................................... 73 6.7.4 OsPedReadCipherRsaKey .............................................................................. 73 6.7.5 OsPedWriteCipherRsaKey ............................................................................. 74 6.8 AES ........................................................................................................................ 74 6.8.1 OsPedWriteAesKey ........................................................................................ 74 6.8.2 OsPedAes........................................................................................................ 76 7 8 LCD ................................................................................................................................... 79 7.1 OsScrContrast ........................................................................................................ 81 7.2 OsScrBrightness ..................................................................................................... 81 7.3 OsScrGetSize ......................................................................................................... 82 Keyboard ........................................................................................................................... 83 8.1 OsKbBacklight ....................................................................................................... 86 PAX Computer Technology (Shenzhen) Co., Ltd. 4 Prolin API Programming Guide 9 Touch Screen ..................................................................................................................... 87 10 Signature Pad................................................................................................................. 88 11 Printer ............................................................................................................................ 89 11.1 Return code list ...................................................................................................... 89 11.2 Open and Close ...................................................................................................... 90 11.2.1 OsPrnOpen .................................................................................................. 90 11.2.2 OsPrnReset .................................................................................................. 90 11.2.3 OsPrnClose ................................................................................................. 91 11.3 Printer settings ....................................................................................................... 91 11.3.1 OsPrnSetSize............................................................................................... 91 11.3.2 OsPrnSetDirection ...................................................................................... 91 11.3.3 OsPrnSetGray ............................................................................................. 92 11.4 TypeSetting ............................................................................................................ 92 11.4.1 OsPrnSetSpace ............................................................................................ 92 11.4.2 OsPrnSetReversal ....................................................................................... 92 11.4.3 OsPrnSetIndent ........................................................................................... 93 11.4.4 OsPrnCheck ................................................................................................ 93 11.4.5 OsPrnGetDotLine ....................................................................................... 93 11.4.6 OsPrnSetFont .............................................................................................. 94 11.4.7 OsPrnSelectFontSize................................................................................... 94 11.4.8 OsPrnFeed ................................................................................................... 95 11.4.9 OsPrnPrintf ................................................................................................. 95 11.4.10 OsPrnPutImage ........................................................................................... 95 11.4.11 OsPrnStart ................................................................................................... 96 11.5 POSIX .................................................................................................................... 97 11.5.1 open ............................................................................................................. 97 11.5.2 read .............................................................................................................. 97 11.5.3 Write ........................................................................................................... 97 11.5.4 Close ........................................................................................................... 99 12 Font Library................................................................................................................. 101 PAX Computer Technology (Shenzhen) Co., Ltd. 5 Prolin API Programming Guide 12.1 Data structure ....................................................................................................... 101 12.2 Font operation ...................................................................................................... 102 12.2.1 OsEnumFont ............................................................................................. 102 12.2.2 OsOpenFont .............................................................................................. 102 12.2.3 OsCloseFont .............................................................................................. 103 12.2.4 OsGetFontDot ........................................................................................... 103 13 Code ............................................................................................................................ 107 13.1 Code Convert ....................................................................................................... 107 13.1.1 OsCodeConvert ......................................................................................... 107 14 MSR ............................................................................................................................ 109 14.1 Return code list .................................................................................................... 109 14.2 Data structure ....................................................................................................... 110 14.3 MSR control interface .......................................................................................... 110 14.3.1 OsMsrOpen ............................................................................................... 110 14.3.2 OsMsrClose............................................................................................... 111 14.3.3 OsMsrReset ............................................................................................... 111 14.3.4 OsMsrSwiped ............................................................................................ 111 14.3.5 OsMsrRead ............................................................................................... 112 14.4 POSIX .................................................................................................................. 112 14.4.1 Open .......................................................................................................... 113 14.4.2 Read .......................................................................................................... 113 14.4.3 Close ......................................................................................................... 113 15 ICC Reader .................................................................................................................. 114 15.1 Return Code List .................................................................................................. 114 15.2 Data Structure ...................................................................................................... 116 15.2.1 IC card device control block ..................................................................... 116 15.2.2 ATR structure............................................................................................ 117 15.2.3 APDU Request Structure .......................................................................... 117 15.2.4 APDU Response Structure ........................................................................ 118 15.3 API index ............................................................................................................. 118 PAX Computer Technology (Shenzhen) Co., Ltd. 6 Prolin API Programming Guide 15.3.1 sci_open .................................................................................................... 119 15.3.2 sci_get_fd .................................................................................................. 119 15.3.3 sci_get_dcb ............................................................................................... 119 15.3.4 sci_set_dcb ................................................................................................ 119 15.3.5 sci_read ..................................................................................................... 120 15.3.6 sci_write .................................................................................................... 120 15.3.7 sci_close .................................................................................................... 120 15.3.8 sci_lock ..................................................................................................... 121 15.3.9 sci_unlock ................................................................................................. 121 15.3.10 sci_powerup .............................................................................................. 121 15.3.11 sci_powerdown ......................................................................................... 121 15.3.12 sci_detect .................................................................................................. 122 15.3.13 sci_cold_reset ........................................................................................... 122 15.3.14 sci_warm_reset ......................................................................................... 122 15.4 Protocol processing function................................................................................ 122 15.4.1 emv_atr_parse ........................................................................................... 122 15.4.2 iso7816_atr_parse ..................................................................................... 123 15.4.3 iso7816_pps .............................................................................................. 123 15.4.4 iso7816_ocs............................................................................................... 123 15.4.5 iso7816_t1_ifsd_request ........................................................................... 124 15.4.6 iso7816_t0_exchange ................................................................................ 124 15.4.7 iso7816_t1_exchange ................................................................................ 124 15.5 Encapsulated Interfaces ....................................................................................... 125 15.5.1 OslccOpen ................................................................................................. 125 15.5.2 OsIccDetect ............................................................................................... 125 15.5.3 OsIccInit .................................................................................................... 126 15.5.4 OsIccExchange ......................................................................................... 127 15.5.5 OsIccClose ................................................................................................ 127 16 RF Reader .................................................................................................................... 129 16.1 Return Code List .................................................................................................. 129 PAX Computer Technology (Shenzhen) Co., Ltd. 7 Prolin API Programming Guide 16.2 Data Structure ...................................................................................................... 130 16.2.1 User Configuration Structure .................................................................... 130 16.2.2 Configuration Parameter Definition ......................................................... 131 16.3 ISO14443 --- Type A ........................................................................................... 132 16.3.1 iso14443_3a_req ....................................................................................... 132 16.3.2 iso14443_3a_wup ..................................................................................... 132 16.3.3 iso14443_3a_antisel .................................................................................. 133 16.3.4 iso14443_3a_halt ...................................................................................... 133 16.3.5 iso14443_3a_rats ...................................................................................... 133 16.4 ISO14443 --- Type B ........................................................................................... 134 16.4.1 iso14443_3b_req ....................................................................................... 134 16.4.2 iso14443_3b_wup ..................................................................................... 134 16.4.3 iso14443_3b_attri ..................................................................................... 134 16.4.4 iso14443_3b_halt ...................................................................................... 134 16.5 Half-duplex transmission protocol ....................................................................... 135 16.5.1 iso14443_4_transfer .................................................................................. 135 16.6 Encapsulate Interfaces ......................................................................................... 135 16.6.1 OsPiccOpen............................................................................................... 135 16.6.2 OsPiccClose .............................................................................................. 136 16.6.3 OsPiccResetCarrier ................................................................................... 136 16.6.4 OsPiccPoll ................................................................................................. 136 16.6.5 OsPiccAntiSel ........................................................................................... 136 16.6.6 OsPiccActive............................................................................................. 137 16.6.7 OsPiccTransfer .......................................................................................... 138 16.6.8 OsPiccRemove .......................................................................................... 138 16.6.9 OsMifareAuthority .................................................................................... 138 16.6.10 OsMifareOperate ...................................................................................... 139 16.6.11 OsPiccInitFelica ........................................................................................ 140 16.6.12 OsPiccIsoCommand ................................................................................. 140 16.6.13 OsPiccSetUserConfig ............................................................................... 140 PAX Computer Technology (Shenzhen) Co., Ltd. 8 Prolin API Programming Guide 16.6.14 OsPiccGetUserConfig............................................................................... 141 16.7 Note of touch screen and RF reader programming .............................................. 141 17 Communication Port ................................................................................................... 143 17.1 Data Definition..................................................................................................... 143 17.2 Communication control ....................................................................................... 144 17.2.1 OsPortOpen ............................................................................................... 144 17.2.2 OsPortClose .............................................................................................. 145 17.2.3 OsPortSend ............................................................................................... 145 17.2.4 OsPortRecv ............................................................................................... 146 17.2.5 OsPortReset............................................................................................... 146 17.2.6 OsPortCheckTx ......................................................................................... 147 17.3 POSIX .................................................................................................................. 147 17.3.1 Open .......................................................................................................... 147 17.3.2 Read .......................................................................................................... 148 17.3.3 Write ......................................................................................................... 148 17.3.4 Close ......................................................................................................... 148 17.3.5 Query the buffer data of communication port........................................... 148 17.3.6 Clear the buffer data of communication port ............................................ 148 17.3.7 Set the configuration parameters of communication port ......................... 149 18 MODEM...................................................................................................................... 153 18.1 Return code list .................................................................................................... 153 18.2 Data structure ....................................................................................................... 161 18.3 OsModemOpen .................................................................................................... 166 18.4 OsModemClose.................................................................................................... 166 18.5 OsModemSwitchPower ....................................................................................... 166 18.6 OsModemConnect ............................................................................................... 167 18.7 OsModemCheck .................................................................................................. 168 18.8 OsModemExCmd ................................................................................................ 169 18.9 OsModemHangup ................................................................................................ 170 18.10 OsModemSend ................................................................................................. 170 PAX Computer Technology (Shenzhen) Co., Ltd. 9 Prolin API Programming Guide 19 18.11 OsModemRecv ................................................................................................. 170 18.12 OsPppomLogin................................................................................................. 171 18.13 OsPppomCheck ................................................................................................ 173 18.14 OsPppomLogout............................................................................................... 173 Network Communication ............................................................................................ 175 19.1 TCP programming ............................................................................................... 175 19.2 UDPprogramming ................................................................................................ 178 20 Network Configuration ............................................................................................... 181 20.1 Return code list .................................................................................................... 181 20.2 Data Definition..................................................................................................... 182 20.2.1 Physical channel list .................................................................................. 182 20.3 Network Configuration interface ......................................................................... 183 20.3.1 OsNetAddArp ........................................................................................... 183 20.3.2 OsNetPing ................................................................................................. 184 20.3.3 OsNetPingEx............................................................................................. 184 20.3.4 OsNetDns .................................................................................................. 185 20.3.5 OsNetSetConfig ........................................................................................ 186 20.3.6 OsNetGetConfig ....................................................................................... 187 20.3.7 OsNetStartDhcp ........................................................................................ 188 20.3.8 OsNetCheckDhcp ..................................................................................... 188 20.3.9 OsNetStopDhcp ........................................................................................ 189 20.3.10 OsNetSetRoute ......................................................................................... 189 20.3.11 OsNetGetRoute ......................................................................................... 190 20.3.12 OsPppoeLogin .......................................................................................... 190 20.3.13 OsPppoeCheck .......................................................................................... 190 20.3.14 OsPppoeLogout ........................................................................................ 191 21 GPRS/CDMA .............................................................................................................. 193 21.1 Return code list .................................................................................................... 193 21.2 Wireless module interface.................................................................................... 194 21.2.1 OsWlLock ................................................................................................. 194 PAX Computer Technology (Shenzhen) Co., Ltd. 10 Prolin API Programming Guide 21.2.2 OsWlUnLock ............................................................................................ 195 21.2.3 OsWlInit() ................................................................................................. 195 21.2.4 OsWlSwitchPower .................................................................................... 196 21.2.5 OsWlSwitchSleep ..................................................................................... 196 21.2.6 OsWlGetSignal ......................................................................................... 197 21.2.7 OsWlCheck ............................................................................................... 197 21.2.8 OsWlLogin ................................................................................................ 198 21.2.9 OsWlLoginEx ........................................................................................... 200 21.2.10 OsWlLogout ............................................................................................. 202 21.3 Wireless module information settings ................................................................. 202 21.3.1 OsWlSelSim .............................................................................................. 202 22 WIFI ............................................................................................................................ 204 22.1 Return Code List .................................................................................................. 204 22.2 Encryption type List ............................................................................................. 205 22.3 Data Structure ...................................................................................................... 205 22.4 OsWifiOpen ......................................................................................................... 207 22.5 OsWifiClose ......................................................................................................... 208 22.6 OsWifiSwitchPower ............................................................................................ 208 22.7 OsWifiScan .......................................................................................................... 208 22.8 OsWifiConnect .................................................................................................... 209 22.9 OsWifiDisconnect ................................................................................................ 210 22.10 OsWifiCheck .................................................................................................... 210 22.11 OsWifiCmd ...................................................................................................... 211 23 File System .................................................................................................................. 213 24 System Information ..................................................................................................... 214 25 Audio ........................................................................................................................... 217 25.1 OsPlayWave ......................................................................................................... 217 26 Barcode........................................................................................................................ 219 26.1 General Definiton................................................................................................. 219 26.2 OsScanOpen ......................................................................................................... 219 PAX Computer Technology (Shenzhen) Co., Ltd. 11 Prolin API Programming Guide 26.3 OsScanRead ......................................................................................................... 220 26.4 OsScanClose ........................................................................................................ 220 27 Power Management ..................................................................................................... 221 27.1 OsCheckBattery ................................................................................................... 221 27.2 OsCheckPowerSupply ......................................................................................... 222 27.3 OsSysSleep .......................................................................................................... 222 27.4 OsSysSleepEx ...................................................................................................... 223 27.5 OsReboot.............................................................................................................. 223 27.6 OsPowerOff ......................................................................................................... 224 Appendix 1 PIN Block Format............................................................................................... 225 Appendix 2 EPS PINBLOCK Format .................................................................................... 229 Appendix 3 Registry Table .................................................................................................... 230 Appendix 4 Validity of models and contents ......................................................................... 233 PAX Computer Technology (Shenzhen) Co., Ltd. 12 Prolin API Programming Guide Table List Table 1 Abbreviation ........................................................................................................ 15 Table 2 Return code classification List ............................................................................ 19 Table 3 General return code list ....................................................................................... 20 Table 4 System function return code list .......................................................................... 25 Table 5 Macro definitions of file types ............................................................................ 25 Table 6 Encryption and decryption return code list ......................................................... 41 Table 7 PED Return code list ........................................................................................... 47 Table 8 Key Types ........................................................................................................... 49 Table 9 Layout attributes of asterisk ................................................................................ 49 Table 10 The color values of asterisk............................................................................... 49 Table 11 Printer return code list ....................................................................................... 89 Table 12 MSR return code list ....................................................................................... 109 Table 13 ICC reader return code list .............................................................................. 114 Table 14 Return Code List ............................................................................................. 129 Table 15 Macro definition list of communication ports ................................................. 143 Table 16 Return code list of USB port functions ........................................................... 143 Table 17 Modem return code list ................................................................................... 153 Table 18 Variable definition of ST_MODEM_SETUP ................................................. 162 Table 19 Network Configuration return code list .......................................................... 181 Table 20 Physical Channel List ...................................................................................... 182 Table 21 GPRS/CDMA return code list ......................................................................... 193 Table 22 Return Code List ............................................................................................. 204 Table 23 Encryption type List ........................................................................................ 205 PAX Computer Technology (Shenzhen) Co., Ltd. 13 Prolin API Programming Guide 1 Introduction 1.1 Purpose This document was previously named as Prolin API Programming Guide. Prolin SDK supports necessary tools and resources to create Prolin applications, they are different from the application that running on the background of Prolin system. Based on the Prolin OS devices, they can run as an independent executive program. Local applications can access all features of Prolin OSsave data in the local file system and can even communicate with various installed programs through custom URL. It uses the default or customized GUI framework to develop the local GUI application program for Prolin OS and installs GUI system package. This framework not only provides a lot of default behaviors but also provides some connections. Developers can customize and extend its behavior through these connections. 1.2 Readers This document is primarily targeted for Prolin OS developers, who are expected to create Prolin applications. The purpose is to introduce the framework of Prolin application program; demonstrate some of the key customization points in GUI and other significant frameworks; and provide programming aid to the API interfaces, which support driver control to the Prolin OS hardware platform. It will also provide guidance to design. The interface provided by Prolin is based on Linux system calls or POSIX interface. Considering the compatibility requirements of the PaxME OS and applications, it will encapsulate a set of OSAL interface which begins with the prefix ―Os‖. The access of other devices and system functions will provide the demo code to guide developers how to use the POSIX or system library to program. For details, refer to the following document. PAX Computer Technology (Shenzhen) Co., Ltd. 14 Prolin API Programming Guide In this document, the interface that begins with the prefix ―Os‖ has been defined in osal.h of SDK, unless otherwise specified. 1.3 Prerequisite The prerequisites for this document are as follows: Basic understanding of Linux. Basic information about processes, threads and Linux system functions and their roles in application development. Familiar with memory management and process management. Familiar with Linux input subsystem and frame buffer. For the Linux user, you should use Linux kernel version greater than 2.6.22 to run the Prolin SDK. For the Windows user, you should use Windows XP or higher to run the Prolin SDK. You can get the Prolin SDK from PAX support team. 1.4 Related Documents Prolin Terminal Manager Operating Guide Prolin SDK Tutorial Prolin GUI Programming Guide Prolin App Development Guide Prolin PCKit Operating Guide 1.5 Abbreviation Table 1 Abbreviation Abbreviation Description API Application Programming Interface CDPD Cellular Digital Packet Data CHAP Challenge Handshake Authentication Protocol DHCP Dynamic Host Configuration Protocol DUKPT Derived unique key per transaction EMV Europay, MasterCard, Visa EMV is a global standard for credit and debit payment cards based on chip card technology PAX Computer Technology (Shenzhen) Co., Ltd. 15 Prolin API Programming Guide 1.6 GGSN Gateway GPRS Support Node GPRS General Packet Radio Service IC Integrated circuit IC Card Integrated Circuit Card IPCP IP Control Protocol KSN Key Serial Number KCV Validation of the key plaintext. LCP Link Control Protocol LRC Longitude Redundancy Check MODEM Modulator-demodulator. MSR Magnetic Stripe Reader NCP Network Control Protocol PAP Password Authentication Protocol PCD Proximity Coupling Device PED PIN Entry Device PICC Proximity Integrated Circuit Card POS Point of Sale PPP Point-to-Point Protocol PUK Public Key SAM Security Authentication Module SGSN Serving GPRS Support Node SIM Subscriber Identity Module SMS Short Message Service SSL Secure Sockets Layer TWK Transaction working key Document Conventions 【Used for labeling common notes.】 【Used for reminding the audience some place may have to pay attention to, which may lead to exceptions or errors.】 PAX Computer Technology (Shenzhen) Co., Ltd. 16 Prolin API Programming Guide 【Used for warning the audience some place must be very careful, which may lead to very serious errors or damages.】 PAX Computer Technology (Shenzhen) Co., Ltd. 17 { This page intentionally left blank } Prolin API Programming Guide 2 Return Code and Parameter 2.1 Return code classification List the types and values of the return code which appeared in this document. Table 2 Return code classification List Type Value(Decimal) General return code -1000~-1999 System function -2200~-2299 Power Management -2300~-2399 Encryption and Decryption -2400~-2499 Font library -2500~-2599 LED display -2600~-2699 MSR -2700~-2799 ICC Reader -2800~-2899 RF Reader -2900~-2999 Communication port -3000~-3099 MODEM -3100~-3299 IP Network Configuration -3300~-3399 PED -3800~-3899 PAX Computer Technology (Shenzhen) Co., Ltd. Description As general return code for API. 19 Prolin API Programming Guide 2.2 General return code Table 3 General return code list Macro RET_OK Value 0 Description Success ERR_INVALID_HANDLE -1000 Invalid handle ERR_TIME_OUT -1001 Timeout ERR_APP_NOT_EXIST -1002 Application does not exists ERR_INVALID_PARAM -1003 Invalid Parameters ERR_DEV_NOT_EXIST -1004 Device not exists. ERR_DEV_BUSY -1005 Device is busy. ERR_DEV_NOT_OPEN -1006 Device is not open. ERR_ACCESS_DENY -1007 Access denied. ERR_FONT_NOT_EXIST -1008 Font does not exist. ERR_FILE_FORMAT -1009 File format error. ERR_USER_CANCEL -1010 User cancels. ERR_NO_PORT -1011 No communication port available. ERR_NOT_CONNECT -1012 Not Connected ERR_MEM_FAULT -1013 Memory fault. ERR_SYS_BAD -1014 System configuration error. ERR_SYS_NOT_SUPPORT -1015 System does not support this function. ERR_STR_LEN -1016 Character string is too long. ERR_TOO_MANY_HANDLE -1017 Too many handle. ERR_APP_MODE -1018 Mode error. ERR_FILE_NOT_EXIST -1019 File does not exist. ERR_TS_DISABLE -1020 Touch screen is not open. PAX Computer Technology (Shenzhen) Co., Ltd. 20 Prolin API Programming Guide ERR_FONT_CODE -1021 Character encoding error ERR_VERSION_TOO_LOW -1022 The version number is too low ERR_BATTERY_ABSENT -1023 The batter is absent 2.3 Parameter Specification API parameters are divided into input parameters and output parameters. The type of the parameters has been labeled in the detailed API specification. All string input and output parameters end with "\x00", and String parameters must indicate the length limit. PAX Computer Technology (Shenzhen) Co., Ltd. 21 { This page intentionally left blank } Prolin API Programming Guide 3 Thread Prolin supports multithread development. The platform provides standard POSIX thread library (pthread) for developers to use. The pthread header file is located in the installation directory of Prolin SDK: tool chains\arm-linux\arm-softfloat-linux-gnu\include\pthread.h PAX Computer Technology (Shenzhen) Co., Ltd. 23 { This page intentionally left blank } Prolin API Programming Guide 4 System Function 4.1 Return code list Table 4 System function return code list Macro Value Description ERR_FILE_NOT_FOUND -2201 File can‘t be found. ERR_VERIFY_SIGN_FAIL -2204 Verify signature failed. ERR_NO_SPACE -2205 No enough system space. ERR_NEED_ADMIN -2207 Permission denied. (Need higher permissions.) Table 5 Macro definitions of file types Macro Value Description FILE_TYPE_APP 1 Application package FILE_TYPE_APP_PARAM 2 Application data file FILE_TYPE_SYS_LIB 3 System dynamic library file FILE_TYPE_PUB_KEY 4 User public key file PAX Computer Technology (Shenzhen) Co., Ltd. 25 Prolin API Programming Guide 5 FILE_TYPE_AUP Application upgrade package 4.2 Data Definition LOG_T(Enumerate LOG types): LOG_T: typedef enum{ LOG_DEBUG, LOG_INFO, LOG_WARN, LOG_ERROR, } LOG_T; //Display debugging information // Display prompt information // Display warning information // Display error information ST_TIME (structure of time) ST_TIME: typedef struct{ int Year; //year 1970– 2037 int Month; //month 1 –12 int Day; //day 1 –31 int Hour; //hour 0 – 23 int Minute; //minute 0 –59 int Second; //second 0 –59 int DayOfWeek; //Monday–Sunday(Only effective for reading time) } ST_TIME; ST_TIMER (structure of timer) ST_TIMER: typedef struct{ unsigned long Start; unsigned long Stop; unsigned long TimeLeft; } ST_TIMER; PAX Computer Technology (Shenzhen) Co., Ltd. 26 Prolin API Programming Guide ST_APP_INFO (structure of application information) ST_APP_INFO: typedef struct{ char Id[32]; char Name[64]; char Bin[64]; char Artwork[64]; char Desc[64]; char Vender[32]; char Version[32] ; } ST_APP_INFO; 4.3 Timeset 4.3.1 OsSetTime Prototype int OsSetTime(const ST_TIME *Time); Function Set the system time, the week value will not work. 【Input】 Time structure Parameters Time Return Instruction RET_OK Success ERR_NEED_ADMI N Need higher permissions. ERR_INVALID_PA RAM Invalid parameter Only the main application has permission to set the time, otherwise, it will return ERR_NEED_ADMIN. 4.3.2 OsGetTime Prototype void OsGetTime(ST_TIME *Time); Function Get the system time. Parameters Time Return 【Output】 Time structure None Instruction PAX Computer Technology (Shenzhen) Co., Ltd. 27 Prolin API Programming Guide 4.4 Timer 4.4.1 OsTimerSet Prototype int OsTimerSet(ST_TIMER *Timer, unsigned long Ms); Function Set the timer. Timer Parameters Return 【Output】 Timer 【Input】 Time【unit:ms】 Ms RET_OK Success ERR_INVALID_PAR AM Invalid parameter Instruction 4.4.2 OsTimerCheck Prototype unsigned long OsTimerCheck(ST_TIMER *Timer); Function Check the remaining time of a specified time. Parameters Timer Return 【Input】 Timer >=0 The remaining time.【unit:ms】 ERR_INVALID_PA RAM Invalid parameter Instruction 4.5 Delay 4.5.1 OsSleep Prototype voidOsSleep(unsigned int Ms); Function System delay, the delay process will not be interrupted by signal. Parameters Ms 【Input】 Return The delay time【unit:ms】 None Instruction 4.6 Thread To implement the thread management, please refer to the following code. PAX Computer Technology (Shenzhen) Co., Ltd. 28 Prolin API Programming Guide Example: #includestatic pthread_t ntid; static void *thread_fn(void *arg) { printf("This is child thread\n"); return ((void *)0); } int main() { printf("This is main thread\n"); if(pthread_create(&ntid, NULL, thread_fn, NULL) != 0) printf("can't create thread\n"); sleep(5); return 0; } 4.7 Log 4.7.1 OsLogSetTag Prototype void OsLogSetTag(const char *Tag); Function Set the LOG tag. Parameters Return Instruction Tag【Input】 LOG information tag None Set the LOG tag, and the default tag is null. Suggest setting Tag to be an application name. It supports up to 32 bytes, when - it is greater than 32 bytes, just use the first 32 bytes. When the Tag is an empty string or NULL, the OsLog () will not work. 4.7.2 OsLog Prototype int OsLog(LOG_T Prio, PAX Computer Technology (Shenzhen) Co., Ltd. 29 Prolin API Programming Guide const char *fmt, …); Function Parameters Return Instruction Record the LOG information. Prio【Input】 LOG type fmt 【Input】 Format of log information RET_OK Success ERR_INVALID_PAR AM Invalid parameter If you forget to call OsLogSetTag(), the OsLog() function won‘t work. 4.8 Get the count value 4.8.1 OsGetTickCount Prototype unsigned long OsGetTickCount(void); Function Get the system count value. Parameters Return Instruction None >0 Count value.【unit:ms】 The value represents the time from the boot to the present time. 4.9 Get Appliaction information 4.9.1 OsGetAppInfo Prototype int OsGetAppInfo(ST_APP_INFO AppInfo[], int InfoCnt); Function Get the application information. AppInfo 【Output】 Array of AppInfo structure. Parameters Return Instruction InfoCnt 【Input】 The number of Apps that can be stored in the array. >=0 Returns the number of obtained App information ERR_NEED_ADMI N Need higher permission ERR_INVALID_PA RAM Invalid parameter 1. Only the main application has permission to get the information. 2. When the number of existing applications is more than InfoCnt, the InfoCnt shall prevail. PAX Computer Technology (Shenzhen) Co., Ltd. 30 Prolin API Programming Guide 4.10 Buzzer 4.10.1 OsBeep Prototype void OsBeep(int ToneType, int DurationMs); Function The buzzer. ToneType Parameters Return Instruction 【Input】 Tone type. The value ranges from 1 to 7. DurationMs 【Input】 Duration: the value ranges from 10 to 10000. 【unit:ms】 None If ToneType<1, set it to 1, if ToneType>7, set it as 7. If DurationMs<10, set it to 10, if DurationMs>10000, set it to 10000. 4.11 Run Application 4.11.1 OsRunApp int OsRunApp(char *AppId, char **Argv, void *Data, RUNAPP_CB CbOut, RUNAPP_CB CbErr); Prototype Function Switch to a specified sub-application. AppId 【Input】 sub-application ID Parameters Argv 【Input】 Argument list, it can be NULL if we do not need that. Data 【Input】 Custom data, it will be passed to CbOut() and CbErr() to call back. CbOut 【Input】 Callback function of the standard output information. CbErr Return Instruction 【Input】 Callback functions of the standard error information. RET_OK Success ERR_APP_NOT_EXIST Sub-application does not exist. ERR_ACCESS_DENY Access denied ERR_APP_MODE Mode Error ERR_INVALID_PARAM Invalid parameter ERR_NEED_ADMIN Need higher permission. 1. Only the main application has permission to switch application, otherwise, it will return ERR_NEED_ADMIN. PAX Computer Technology (Shenzhen) Co., Ltd. 31 Prolin API Programming Guide 2. 3. Switch to a specified sub-application, but switching to the main application is not allowed, if ―MAINAPP‖ is passed in to AppId, ERR_INVALID_PARAM will be returned. This will output the standard output information and standard error information of the sub-application to CbOut () and CbErr (), respectively. For the multi-line standard output and standard error, the callback function will be called multiple times.The callback function is defined as follows: typedef void (*RUNAPP_CB)(char *appid, char *str, void *data); 4.12 Set and Read the registry table OsGetTerminalInfo() and OsReadSn() which applied to Prolin 2.3 have been deleted, and the related functions can be implemented by calling OsRegGetValue(). 4.12.1 OsRegSetValue int OsRegSetValue(const char *Key, Prototype const char *Value); Function Parameters Return Instruction Set system parameters. Key 【Input】 System configuration name, it needs ending with'\0'. Value 【Input】 The parameter value cannot be null and should be less than 64 bytes. It needs ending with '\0'. RET_OK Success ERR_INVALID_PARAM Invalid Parameters ERR_NEED_ADMIN Need higher permissions. The system configuration name can only be set beginning with ―persist.sys.‖ For example, ―persist.sys.app0.pic‖. 4.12.2 OsRegGetValue int OsRegGetValue(const char *Key, Prototype Function char *Value); Read system parameters. Key 【Input】 System configuration name, it needs ending with'\0'. Value 【Output】 The parameter value cannot be null and it must be more than 64 bytes. Parameters Return >=0 Read the string length ERR_INVALID_PARAM Invalid Parameters PAX Computer Technology (Shenzhen) Co., Ltd. 32 Prolin API Programming Guide Instruction The system configuration name can only be set beginning with ―ro.fac.‖ or ―persist.sys.‖ About the ―ro.fac.‖, users can refer to registry table. If the query parameter does not exist or the parameter value is empty, it‘ll return 0 and the output parameter Value will be ―‖. 4.13 Install and uninstall files 4.13.1 OsInstallFile Prototype int OsInstallFile(const char *Name, const char *FileName,int FileType); Function Install application and system files. Name 【Input】 Parameters FileName 【Input】 The filename which needs to be installed. FileType Return Instruction When FileType is FILE_TYPE_PUB_KEY, assign the value from "uspuk0" to "uspuk8" to Name and it represents the user public key ranging from 0 to 8. When FileType is FILE_TYPE_APP_PARAM N Name is the corresponding ID of the parameter files. When FileType is the other type, Name is invalid, and it can be NULL. FILE_TYPE_APP (the application package) FILE_TYPE_APP_PARAM (the application data file) FILE_TYPE_SYS_LIB (the dynamic library file) FILE_TYPE_PUB_KEY (the user public key file) FILE_TYPE_AUP(the application update package) RET_OK Success ERR_PUK_NOT_EXIST The specified user public key does not exist. ERR_FILE_NOT_FOUN D FileName does not exist. ERR_FILE_FORMAT FileName format error. ERR_INVALID_PARA M Invalid Parameters ERR_VERIFY_SIGN_F AIL Signature verification failed. ERR_APP_MODE Mode error Name will be valid only when the FileType is FILE_TYPE_PUB_KEY or FILE_TYPE_APP_PARAM, other types are invalid. PAX Computer Technology (Shenzhen) Co., Ltd. 33 Prolin API Programming Guide 4.13.2 OsUninstallFile Prototype int OsUninstallFile(const char *AppName, int FileType); Function Uninstall applications and system files. AppName【Input】 Parameters FileType Return Instruction When the FileType is FILE_TYPE_APP, it means AppName is the Application ID which needs to be deleted. When the FileType is FILE_TYPE_SYS_LIB, AppName is the name of system library. FILE_TYPE_APP (Application package, application has installed all the files.) FILE_TYPE_SYS_LIB (System library file) RET_OK Success ERR_APP_NOT_EXIST The application specified by AppName does not exist. ERR_FONT_NOT_EXIST The font library does not exist. the This function is only used for unloading application and parts of system files. After calling this function to uninstall all files that need to uninstall, the application will prompt the user to restart the terminal to complete the uninstallation. 4.14 System firmware upgrade 4.14.1 OsFirmwareGetVersion Prototype int OsFirmwareGetVersion(char *Version, int Size); Function Acquire system firmware version. Version【output】 Parameters Size 【Input】 RET_OK Return Instruction Pointer to the buffer, 64 bytes is recommended for the buffer length. Buffer length Success ERR_INVALID_P Invalid parameter ARAM 1. The acquired version information is MAIN_VERSION-SVN_VERSION Take ―2.6.26-r1789‖ as an example, MAIN_VERSION is"2.6.26" and SVN_VERSION is "r1789". 2. The user can decide whether the firmware needs upgrading by judging the SVN_VERSION. PAX Computer Technology (Shenzhen) Co., Ltd. 34 Prolin API Programming Guide 4.14.2 OsFirmwareUpgrade Prototype int OsFirmwareUpgrade(const char *FwFileName); Function Upgrade system firmware. Parameters Return Instruction FwFileName 【Input】 Firmware filename, an example of filename format could be: prolin-2.4.26-CCV-r1918.zip RET_OK Update succeeded RR_FILE_NOT_FOUND ‗FwFileName‘ file doesn‘t exist ERR_VERSIN_TOO_LOW System package version is too low ERR_VERIFY_SIGN_FAIL Verify signature failed ERR_AP_MODE Application mode error ERR_INVALID_PARAM Invalid parameter 1. Only the main application gets the permission to upgrade the system firmware. 2. The function will be obstructed during the upgrade process, if an interface prompt is needed, then it has to be done by starting another process. 3. The power should never be cut off during the upgrade process, otherwise the device won‘t be able to run again. 4. The upgrade will only take effect after reboot. 4.15 Verify signature The Prolin provides a function to verify the file signature. Use this interface to verify the signature before using the files. 4.15.1 OsVerifySign Prototype int OsVerifySign(const char *FileName, int PUKType); Function Verify the file signature specified by FileName to see whether it is legal or not, the signature data is included in the file. FileName 【Input】 The file name which contains the path. Parameters PUKType【Input】 PAX Computer Technology (Shenzhen) Co., Ltd. PUK_TYPE_M The public key of manufacturers. It is used to do the signature verification for firmware released by manufacturer. PUK_TYPE_US_PUK The public key of user signature certificate, it is used to do the signature verification for the public key certificate. PUK_TYPE_USER0~PUK_TYPE_USER8 The public key of users, it is used to do the signature 35 Prolin API Programming Guide verification for user application. Return RET_OK Success ERR_VERIFY_SIGN_FAIL Illegal signature. ERR_FILE_NOT_EXIST The file does not exist. ERR_DEV_BUSY Device is busy. ERR_INVALID_PARAM Invalid parameter 1. Instruction 2. This function is only used for the application to verify the application parameter file, for example, to verify the root certificate defined by the application. In order to avoid validation repetition, it should not use this function to verify the legitimacy of the file until the file is installed. (System will verify automatically in OsInstallFile()). 4.15.2 OsVerifySignExternal int OsVerifySignExternal(const char *FileName, Prototype const void *SignData, int PUKType); Function Verify the file signature specified by FileName to see whether it is legal or not. The file does not include the signature data. FileName 【Input】 The file name which contains the path. SignData 【Input】 Signature data, it has 284 bytes. Parameters PUKType【Input】 Return RET_OK Success ERR_VERIFY_SIGN_FAIL Illegal signature. ERR_FILE_NOT_EXIST The file does not exist. ERR_DEV_BUSY Device is busy. ERR_INVALID_PARAM Invalid parameter 1. Instruction PUK_TYPE_M The public key of Manufacturers. It is used to do the signature verification for firmware released by manufacturer. PUK_TYPE_US_PUK The public key of user signature certificate, it is used to do the signature verification for the public key certificate. PUK_TYPE_USER The public key of users, it is used to do the signature verification for user application. This function is only used for the application to verify the application parameter file, for example, to verify the root certificate defined by the application. PAX Computer Technology (Shenzhen) Co., Ltd. 36 Prolin API Programming Guide 2. In order to avoid repeating validation, –the user should use this function to verify the legitimacy of the file before installing the file. (System will verify automatically in OsInstallFile ()). 4.16 Get system version This interface is reserved for future use. 4.16.1 OsGetSysVer Prototype void OsGetSysVer(int VerType, char *Version); Function Read information of the system version. Version types: VerType Parameters Version【Output】 Return TYPE_OS_VER Operating system version TYPE_OSAL_VERAPI Library version TYPE_DRIVER_VER Driver version TYPE_PED_VER built-in PED version TYPE_MSR_VER MSR version TYPE_ICC_VER ICC Reader version TYPE_PCD_VER PCD Reader version TYPE_EMVL1_VER EMV Level1 version TYPE_PRINTER_VER Printer version TYPE _MODEM_VER Modem version TYPE_ETH_VER Netcard version TYPE_GPRS_VER GPRS version TYPE_CDMA_VER CDMA version TYPE_TD_VER TD version TYPE_WIFI_VER WIFI version TYPE_BT_VER Bluetooth version Version information. (Ending with ―\0‖, and length <=31 bytes) None 1. Instruction 2. If Version[0] is equal to 0x00,it means the corresponding module does not exist, The buffer size of version must be greater than31 bytes. 4.17 Determine whether on the base Prolin can determine whether the handset is on the base or not. Since the S series doesn‘t have any bases, so it can‘t support this function. PAX Computer Technology (Shenzhen) Co., Ltd. 37 Prolin API Programming Guide 4.17.1 OsOnBase Prototype int OsOnBase(void); Function Determines whether the handset is on the base. Parameters Return Instruction None 1 yes 0 no This function is only applicable to handset with base. 4.18 Save the crash report Prolin supports monitoring program state. Once the program crashes, it will generate crash report in the directory‗/data/tombstones‘ after calling this function. 4.18.1 OsSaveCrashReport Prototype void OsSaveCrashReport(ing sig); Function Save the crash report. Parameters Return Sig Signal value None Instruction Method one Through the function signal(SIG_XXX, OsSaveCrashReport); OsSaveCrashReport will be registered as signal handler, for example: signal(SIGILL, OsSaveCrashReport); signal(SIGABRT, OsSaveCrashReport); signal(SIGBUS, OsSaveCrashReport); signal(SIGFPE, OsSaveCrashReport); signal(SIGSEGV, OsSaveCrashReport); signal(SIGSTKFLT, OsSaveCrashReport); Method two During the signal handler process, call OsSaveCrashReport (sig) to save the error message. For example: int mysighandler(int sig) { do_something(); OsSaveCrashReport(sig); } The recommended signals are SIGILL, SIGABRT, SIGBUS, SIGFPE, SIGSEGV and SIGSTKFLT. After calling this function, it will ignore the signal that corresponds to sig. That is, it calls the signal (sig, SIG_IGN) in function OsSaveCrashReport (). In Terminal Manager(TM), it can export the report to U disk. PAX Computer Technology (Shenzhen) Co., Ltd. 38 Prolin API Programming Guide 4.19 Mount and Unmount the external file system 4.19.1 OsMount intOsMount(const char *Source, const char *Target, const char *FileSystemType, unsigned long MountFlags, const void *Data); Prototype Function Mount the source file system to the target file system. Source 【Input】 The file system that needs to be mounted, it is usually a device that locates in /dev/block/directory and the path length cannot exceed 128 bytes. Target 【Input】 The target file directory that the file system will mount to must be in the /mnt/ directory-whose length cannot exceed 128 bytes. FileSystemType 【Input】 File system type that needs to be mounted- can be signed as vfat― MountFlags 【Input】 Mount flag, it can be the combinations of the following flags: Parameters PAX Computer Technology (Shenzhen) Co., Ltd. MS_DIRSYNC: Synchronize the directory updates. MS_MANDLOCK: Allow the mandatory locks on files. MS_NOATIME: Need not to update the access time. MS_NODEV: Don't allow accessing to device file. MS_NODIRATIME: Don't allow updating the access time on directory. MS_NOEXEC: Don't allow execute programs on the mounted file system. MS_NOSUID: When executing program, do not follow to the set-user-ID and set-group-ID. MS_RDONLY: read-only. MS_RELATIME: When a file is accessed, if the last access time (atime) is less than or equal to the last modification time (mtime) or last status change time (ctime), then update the last access time (atime) values. MS_SILENT: Stop writing warning information to the system kernel log Specify the file system as 39 Prolin API Programming Guide Return Instruction MS_STRICTATIME: Always updating the last access time(atime). MS_SYNCHRONOUS: updates. Data【Input】 The user-defined additional data. RET_OK Success ERR_INVALID_P ARAM Invalid parameter ERR_STR_LEN The string is overlength. ERR_NEED_AD MIN Need higher permissions. Synchronize the file Only the main application can mount, otherwise it will fail to mount and return ERR_NEED_ADMIN. Note: currently the only supported U disk format is FAT32; 4.19.2 OsUmount Prototype Function intOsUmount(const char *Target, int Flags); Unmount the file system. Target 【Input】 The file system that needs to unmount, it must be in the /mnt/ directory, and the path length cannot exceed128 bytes. Flags 【Input】 Unmount flag, it can be combination of the following flags: MNT_DETACH: Lazy umount, the mount point is inaccessible after execution; it will unmount only when the mount point is not busy. MNT_EXPIRE:The mount point is marked as expired UMOUNT_NOFOLLOW: If the target is a symbolic link, do not reduce the reference count. Parameters Return Instruction RET_OK Success ERR_INVALID_PA RAM Invalid parameter ERR_STR_LEN The string is overlength. ERR_NEED_ADMI N Need higher permissions. Only the main application can unmount, otherwise it fails to unmount and returns ERR_NEED_ADMIN. PAX Computer Technology (Shenzhen) Co., Ltd. 40 Prolin API Programming Guide 5 Encryption and Decryption 5.1 Return code list Table 6 Encryption and decryption return code list Macro Value Description ERR_DATA_TOO_BIG -2400 The encrypted data of RSA is greater than module. ERR_GEN_RANDOM -2401 Fail to generate random numbers. ERR_GEN_FAIL -2402 Fail to generate RSA key pairs. 5.2 Random number Prolin supports true random number, and provides the application interface to generate true random number. 5.2.1 OsGetRandom Prototype void OsGetRandom(unsigned char *Random, int RandomLen); Function Read the true random number. Parameters Random 【Output】 Storing the pointer of random number. PAX Computer Technology (Shenzhen) Co., Ltd. 41 Prolin API Programming Guide RandomLen Return Length of random number which needs to be read. (<=4096bytes) None Instruction 5.3 SHA algorithm Prolin supports the SHA algorithms, such as SHA-1, SHA-2(SHA-256, SHA-512) and truncates form of the SHA-2(SHA-224, SHA-384). 5.3.1 OsSHA Prototype void OsSHA(int Mode, const void *Data, int DataLen, unsigned char* ShaOut); Function Calculate the Secure Hash value. Mode Data Parameters Return Instruction SHA_TYPE_1 SHA_TYPE_224 SHA_TYPE_256 SHA_TYPE_384 SHA_TYPE_512 【Input】 the input data buffer DataLen the input data length ShaOut Output value of SHA, the array should be equal to or more than 64 bytes. The corresponding relations between Mode value and ShaOut length are listed as following: SHA_TYPE_1 20 SHA_TYPE_224 28 SHA_TYPE_256 32 SHA_TYPE_38 48 SHA_TYPE_512 64 None Calculate the hash values of SHA family. 5.4 DES algorithm Prolin supports DES & TDES algorithms. PAX Computer Technology (Shenzhen) Co., Ltd. 42 Prolin API Programming Guide 5.4.1 OsDES void OsDES(const unsigned char *Input, unsigned char *Output, Prototype const unsigned char *DesKey, int KeyLen, int Mode); Function Do DES / TDES encryption and decryption with 8bytes. Input 【Input】 8-byte input data Output【Output】 8-byte output data Parameters Return Instruction DesKey 【Input】 DES/TDES key KeyLen 8, 16 or 24 (bytes) Mode 0- Decryption; 1- Encryption. None Do the encryption or decryption according to the mode selection. If the parameters are invalid, there will be no operation. 5.5 AES algorithm Prolin supports AES algorithm, including AES-128, AES-192, AES-256. 5.5.1 OsAES void OsAES(const unsigned char *Input, unsigned char *Output, Prototype const unsigned char *AesKey, int KeyLen, int Mode); Function Perform AES encryption and decryption operation. Input Parameters 【Input】 16-byte input data Output【Output】 16-byte output data PAX Computer Technology (Shenzhen) Co., Ltd. 43 Prolin API Programming Guide AesKey【Input】 Key Return Instruction KeyLen 16, 24 or 32 (bytes) Mode 0- Decryption; 1- Encryption. None This function supports 128, 192 or 256 (bits) AES encryption and decryption. If the parameter is invalid, there will be no any operations. 5.6 RSAalgorithm Prolin supports RSA algorithm, including public/private key-pair generation, RSA encryption and RSA decryption. Currently, Prolin supports a maximum length of 2048 bits. 5.6.1 OsRSA int OsRSA(const unsigned char * Module, int ModulusLen, const unsigned char *Exp, Prototype int ExpLen, const unsigned char *DataIn, unsigned char *DataOut); Function Perform RSA encryption and decryption operation. 【Input】 Modulus ModulusLen Exp Parameters DataOut Return Modulus length(byte) 【Input】 ExpLen DataIn Pointer to the RSA algorithm modulus buffer (n=p*q). In the order of highest to lowest byte. Pointer to the exponent buffer in RSA operation. In the order of highest to lowest byte. Exponent length.(byte) 【Input】 【Output】 Pointer to the input data buffer, its length is the same as module. Pointer to the output data buffer, its length is the same as module. RET_OK Success ERR_INVALID_PAR AM Invalid parameter. PAX Computer Technology (Shenzhen) Co., Ltd. 44 Prolin API Programming Guide ERR_DATA_TOO_B IG 1. Instruction 2. ExpLen is bigger than ModulusLen. This function performs RSA encryption/decryption operations; encryption and decryption are performed by selecting different keys. If select a private key, such as Modulus, Exp, it will do encryption; or a public key, it will do decryption. This function can perform RSA operation with the length of less than or equal to 2048 bits. 5.6.2 OsRSAKeyGen Int OsRSAKeyGen(unsigned char *Modulus, unsigned char *PriExp, Prototype int ModulusLen, const unsigned char * PubExp); Function Generate RSA Key pair. Modulus 【Output】 The key modulus. (High byte first) PriExp Parameters ModulusLen PubExp Return Instruction 【Output】 Private key exponent. (High byte first) Module length. (It can be 64, 128, and 256 (bytes)). Public key exponent. 【Input】 It only can be:‖\x00\x00\x00\x03‖ or ―\x00\x01\x00\x01‖ RET_OK Success ERR_INVALID_PA RAM Invalid Parameters ERR_GEN_RAND OM Fail to generate random data. ERR_GEN_FAIL Fail to generate RSA Key pair. By calling this interface, it will randomly generate a RSA Key pair with a specified exponent and modulus. PAX Computer Technology (Shenzhen) Co., Ltd. 45 { This page intentionally left blank } Prolin API Programming Guide 6 PED Prolin provides a series of PED interface, including built-in PED, MK / SK, DUKPT, RSA and other related interfaces. 6.1 Return code list Table 7 PED Return code list Macro Value Description ERR_PED_NO_KEY -3801 Key does not exist. ERR_PED_KEY_IDX_ERR -3802 Key index error. ERR_PED_DERIVE_ERR -3803 Key level error: When key is written, the source key level is lower than the destination level. ERR_PED_CHECK_KEY_FAIL -3804 Key verification failed. ERR_PED_NO_PIN_INPUT -3805 No PIN input. ERR_PED_INPUT_CANCEL -3806 Cancel PIN input ERR_PED_WAIT_INTERVAL -3807 Calling function –time is less than the minimum interval.(Calculate PINBLOCK/MAC) ERR_PED_KCV_MODE_ERR -3808 KCV mode error. ERR_PED_KEY_TAG_ERR -3809 Key tag error, the key can‘t be used. ERR_PED_KEY_TYPE_ERR -3810 Key type error. PAX Computer Technology (Shenzhen) Co., Ltd. 47 Prolin API Programming Guide ERR_PED_PIN_LEN_ERR -3811 The input PIN length is not equal to the expected PIN length. ERR_PED_DSTKEY_IDX_ERR -3812 Destination key index error. ERR_PED_SRCKEY_IDX_ERR -3813 Source key index error. ERR_PED_KEY_LEN_ERR -3814 Key length error. ERR_PED_INPUT_PIN_TIMEOUT -3815 PIN input timeout. ERR_PED_NO_ICC -3816 IC card does not exist. ERR_PED_ICC_INIT_ERR -3817 ERR_PED_GROUP_IDX_ERR -3818 DUKPT group index error. ERR_PED_LOCKED -3819 PED locked. ERR_PED_NOMORE_BUF -3820 No free buffer. ERR_PED_NORMAL_ERR -3821 PED general error. ERR_PED_NEED_ADMIN -3822 Not administration. ERR_PED_DUKPT_KSN_OVERFLOW -3823 DUKPT overflow. ERR_PED_KCV_CHECK_FAIL -3824 KCV check failed. ERR_PED_SRCKEY_TYPE_ERR -3825 Source key type error. ERR_PED_UNSPT_CMD -3826 Command does not support. ERR_PED_ADMIN_ERR -3827 Administration error ERR_PED_DOWNLOAD_INACTIVE -3828 PED download inactive. ERR_PED_KCV_ODD_CHECK_FAIL -3829 KCV parity check failed. ERR_PED_PED_DATA_RW_FAIL -3830 Read PED data failed. ERR_PED_ICC_CMD_ERR -3831 ICC operation failed. ERR_PED_DUKPT_NEED_INC_KSN -3832 DUKPT KSN needs to plus 1 first. ERR_PED_DUKPT_NO_KCV -3833 NO KCV. ERR_PED_NO_FREE_FLASH -3834 PED has not enough space. ERR_PED_INPUT_CLEAR -3835 Press [CLEAR] key to exit PIN input. ERR_PED_INPUT_BYPASS_BYFUNCTION -3836 Press FN/ATM4 to cancel PIN input. ERR_PED_NO_PIN_MODE -3837 PIN input mode is not set. ERR_PED_DATA_MAC_ERR -3838 Data MAC check error. ERR_PED_DATA_CRC_ERR -3839 Data CRC check error. ERR_PED_KEY_VALUE_INVALID -3840 The work key value already exists or does not match the requirements. PAX Computer Technology (Shenzhen) Co., Ltd. IC card is not initialized. 48 Prolin API Programming Guide 6.2 Data Definition 6.2.1 Key type Table 8 Key Types Macro Value Description PED_TLK 0x01 Loading Key PED_TMK 0x02 Master Key PED_TPK 0x03 PIN Key PED_TAK 0x04 MAC Key PED_TDK 0x05 Data Key PED_TIK 0x10 DUKPT Initial Key PED_TRK 0x07 MSR Key PED_TAESK 0x20 AES Key 6.2.2 Display attribute of Asterisk Table 9 Layout attributes of asterisk Macro Value Description PED_ASTERISK_ALIGN_LEFT 0 left-aligned PED_ASTERISK_ALIGN_CENTER 1 center-aligned PED_ASTERISK_ALIGN_RIGHT 2 right-aligned Table 10 The color values of asterisk Macro RGB(_r, _g, _b) Value ... Description According to the input of three-primary colors to generate color value with 16-bit. 6.3 Data Structure 6.3.1 Structure of RSA key ST_RSA_KEY typedef struct{ PAX Computer Technology (Shenzhen) Co., Ltd. 49 Prolin API Programming Guide int ModulusLen; /*Modulus length(bits) */ unsigned char Modulus[512]; /*Modulus, if the modulus length<512 bytes, store from right, add 0x00 in left. */ int ExponentLen; /* ExponentLength (bits) */ unsigned char Exponent [512]; /*When exponent <512 bytes, add 0x00 in left.*/ unsigned char KeyInfo[128]; /* RSA key information */ }ST_RSA_KEY; 6.3.2 RSA key structure for verifying the ciphertext IC card PIN ST_RSA_PINKEY typedef struct{ int ModulusLen; /*Modulus length(bits) */ unsigned char Modulus[256]; /*Modulus of PIN public key*/ unsigned char Exponent [4]; /* Exponent of PIN public key*/ int IccRandomLen; /*Length of random data gets from IC card*/ unsigned char IccRandom[8]; /*Random data gets from IC card*/ }ST_RSA_PINKEY; 6.4 Basic PED 6.4.1 OsPedOpen Prototype int OsPedOpen(void); Function Open PED device. Parameters Return Instruction None RET_OK Success ERR_DEV_BUSY Device is busy. Other PED series functions can be called only after successfully opening the PAX Computer Technology (Shenzhen) Co., Ltd. 50 Prolin API Programming Guide PED device. 6.4.2 OsPedGetVer Prototype int OsPedGetVer (unsigned char * PedVer); Function Return PED version. Parameters Return PedVer 【Output】 PED version, buffer size is 6 bytes. RET_OK Success ERR_DEV_NOT_O PEN PED device is not open. ERR_INVALID_PA RAM Invalid parameter. Instruction 6.4.3 OsPedSetInterval Prototype int OsPedSetInterval(unsigned long TpkIntervalMs); Function Set the minimum interval time between consecutive operations of getting PINBlock. Parameters Return Instruction =0 Use the default value(30s) <1000 Automatically set to 1000(1s) >600000 Automatically set to 600000(10 min) =0xffffffff No change in current settings. TpkIntervalMs RET_OK Success ERR_DEV_NOT_O PEN PED device is not open. Calculate the interval time of PINBLOCK: It can only be called 4 times within the default time which is 120-second, that is, the default value of TPKIntervalMs is 30-second, after reset by calling this function, it is limited to call 4 times during the 4*TPKIntervalMs time, for example, if the TPKIntervalMs is 20000(ms), then within 80 seconds, it can only be called 4 times. The timing function will restore the default values after switching machines. 6.4.4 OsPedVerifyPlainPin int OsPedVerifyPlainPin(int IccSlot, Prototype const char * ExpPinLen, int Mode, PAX Computer Technology (Shenzhen) Co., Ltd. 51 Prolin API Programming Guide unsigned long TimeoutMs, unsigned char * IccRsp); Function Verify the offline plaintext PIN Get plaintext PIN. According to card command and card slot number, then sending plaintext PIN BLOCK to card. IccSlot ICC slot number, and IccSlot=0. Enumeration of 0-12 Application enumerates all the possible lengths of PIN, and uses ‗,‘to separate each length. If it is allowed to input 4 or 6 digits password and confirm ExpPinLen 【Input】 without passwords, the string should be set to ‗0, 4, and 6‘. 0 means that user can press ‗Enter‘ to return without inputting any digits. Parameters 0x00: IC card command mode. Currently supports EMV2000 only. Mode The timeout of PIN input.【unit:ms】 Maximum is 300000. 0 means no timeout, and the PED doesn‘t do the timeout control. TimeoutMs IccRsp Return 【Output】 2 bytes Card response code (2 bytes: SWA++SWB) RET_OK Success ERR_DEV_NOT_OP EN PED device is not open. ERR_INVALID_PAR AM Invalid parameter. Others Refer to the PED Return code list . The internal processing is shown as follow: 1. Prompt cardholder to input PIN; 2. Prompt cardholder that it is in process; 3. Convert plaintext PIN to PIN BLOCK form. Use OsIccexchange () to do the verification interaction with the card, as follows: ST_APDU_REQ apdu_s; Instruction ST_APDU_RSP apdu_r; memcpy (apdu_s.cmd, icc_command, 4); apdu_s.lc = icc_command[4]; memcpy (apdu_s.data_in, PINBLOCK,apdu_s.lc ); PAX Computer Technology (Shenzhen) Co., Ltd. 52 Prolin API Programming Guide apdu_s.le = 0; if ( icc_exchange(icc_slot, 0, &apdu_s, &apdu_r) ) return CMDERR; icc_resp[0] = apdu_r.swa; icc_resp[1] = apdu_r.swb; 6.4.5 OsPedVerifyCipherPin int OsPedVerifyCipherPin(int IccSlot, const ST_RSA_PINKEY * RsaPinKey, const char * ExpPinLen, Prototype int Mode, unsigned long TimeoutMs, unsigned char * IccRsp); Function Verify offline enciphered PIN. Get plaintext PIN, and then use RsaPinKey provided by the application to encrypt plaintext PIN according to EMV standards. After that, according to card command and card slot number provided by application, send plaintext PIN BLOCK to card. IccSlot ICC slot number, Iccslot=0. RsaPinKey【Input】 Encrypt the data structure. ExpPinLen【Input】 Application enumerates all the possible lengths of PIN, and uses the ‗,‘to separate each length. If it is allowed to input 4 or 6 digits, confirm without passwords, thus, the string should be set to‗0, 4, 6‘. 0 means that user can press ‗Enter‘ to return without inputting any digits. Mode 0x00, currently supports EMV2000only. TimeoutMs The timeout of PIN input [ms] Maximum is 300000. 0 means no timeout, and the PED doesn‘t do the timeout control. IccRsp【Output】 2 bytes Card response code (2 bytes: SWA+SWB) RET_OK Success ERR_DEV_NOT_OPEN PED device is not open. Parameters Return PAX Computer Technology (Shenzhen) Co., Ltd. 53 Prolin API Programming Guide ERR_INVALID_PARAM Invalid parameter. Others Refer to the PED Return code list . Encryption algorithm: Use the public key, and apply RSA functions to the following data listed in the table to get enciphered PIN. Name Instruction Length Description Format Head of Data 1 Hex. The value is ‗7F‘ b PIN Block 8 PINBLOCK b unpredictable IC card random data 8 The random number got from card, and it is provided in RSA_PINKEY, b Random bytes NIC–17 the padding data got from the terminal application, it is provided in RSA_PINKEY, b padding 1. 2. 3. 4. 5. Prompt message for PIN input; Prompt cardholder that it is in process; Convert plaintext PIN to PIN BLOCK; Generate data, used for encryption(listed in above table) Use public key, and apply RSA functions to encryption data which is generated in step4, then getting Enciphered PIN. Use OsIccExchange () to send verification command to card, as follows: ST_APDU_REQ apdu_s; ST_APDU_RSP apdu_r; memcpy (apdu_s.cmd, icc_command, 4); Note apdu_s.LC = icc_command[4]; memcpy (apdu_s.data_in, EncipheredPIN, apdu_s.LC); apdu_s.LE = 0; if (OsIccExchange(icc_slot, 0, &apdu_s, &apdu_r) ) return ERR_PED_ICC_CMD_ERR; icc_resp[0] = apdu_r.SWA; icc_resp[1] = apdu_r.SWB; 6.4.6 OsPedEraseKeys Prototype int OsPedEraseKeys(void); Function Clear all key information in PED. Parameter None s Return RET_OK PAX Computer Technology (Shenzhen) Co., Ltd. Success. 54 Prolin API Programming Guide ERR_DEV_NOT_OPEN PED device is not open. Others Refer to the PED Return code list . Instructio n 6.4.7 OsPedSetFunctionKey Prototype int OsPedSetFunctionKey (int KeyFlag); Function Set some functions of function key. When PED is power on, the default function of CLEAR button is to clear input PIN. Other different functions of CLEAR button can also be set by calling this function. Parameters Return KeyFlag 0x00: The PIN has already been cleared or there is no input PIN. Press the CLEAR button, the PED will quit the input status and will return ERR_PED_INPUT_CLEAR. 0x01: While calling this function, during the input process of the key input interfaces (OsPedGetPinBlock, OsPedGetPinDukpt, OsPedVerifyPlainPin, and OsPedVerifyCipherPin etc), press CLEAR button to clear the latest input PIN digit by digit. When all the input PIN has been deleted, there will be no response if you keep pressing the CLEAR button, and it will not exit the PIN input function. 0x02: It is allowed to press ATM4 button to end the PIN input. This rule does not apply to the models without ATM button. 0x03: It is allowed to press Function button to end the PIN input. This rule does not apply to the models without FN button. 0xff: It means restore the default function of the function keys. (Press CLEAR button to clear all PIN; press ATM4/FN key does not exit the PIN input function.) RET_OK Success. ERR_DEV_NO T_OPEN PED device is not open. ERR_INVALID _PARAM Invalid parameter. Others Refer to the PED Return code list . Instruction During PIN entry, if needs to support keypress to exit or clear input PIN one by one; it should call this function once after startup. 6.4.8 OsPedClose Prototype void OsPedClose(void); PAX Computer Technology (Shenzhen) Co., Ltd. 55 Prolin API Programming Guide Function Close the PED device. Parameters None Return None Instruction This function should be called to close device before the program exits. 6.4.9 OsPedCancelPinEntry Property int OsPedCancelPinEntry(void); Function Terminate the PIN entry. Parameter Return Instruction None RET_OK Success. ERR_DEV_NOT_O PEN PED device is not open. Terminate the process of inputting PIN. 6.5 MK/SK 6.5.1 OsPedWriteKey Prototype int OsPedWriteKey (const unsigned char * KeyBlock); Function Write in a key, including write in and divergent of TLK, TMK and TWK, and use KCV to check the key correction. Parameters 1 byte Format: 0x03 1 byte SrcKeyType: PED_TLK PED_TMK PED_TPK/PED_TAK/PED_TDK 1 byte SrcKeyIdx: When SrcKeyType = PED_TLK, SrcKeyIdx = 1; When SrcKeyType = PED_TMK, SrcKeyIdx = [1~100]; When writing in plaintext, SrcKeyIdx = 0 1 byte DstKeyIdx: When DstKeyType = PED_TLK, DstKeyIdx = 1; When DstKeyType = PED_TMK, DstKeyIdx = [1~100]; When DstKeyType = PED_TPK or PED_TAK or PED_TDK, KeyBlock【Input】 PAX Computer Technology (Shenzhen) Co., Ltd. 56 Prolin API Programming Guide DstKeyIdx = [1~100]. 7 bytes Reserved domain. Random number. 1 byte DstKeyType: PED_TLK PED_TMK PED_TPK/PED_TAK/PED_TDK 1 byte DstKeyLen: 8/16/24 8/16/24 bytes DstKeyValue. The destination key plaintext / ciphertext 1 byte KcvMode: 0x00: No authentication 0x01: Performs DES/TDES encryption on 8-byte 0x00, and uses first 3 bytes in ciphertext as KCV. 0x02: Firstly, performs parity check, then does DES/TDES encryption on ―\x12\x34\x56\x78\x90\x12\x34\x56 ‖, and uses first 3 bytes in ciphertext as KCV. 0x03: Transfers in a string of KcvData, uses source key to perform specified MAC on [DstKeyValue + KcvData], and then gets the result as KCV. 128 bytes KcvData: When KcvMode is 0x00/0x01/0x02, padding with random numbers. When KcvMode is 0x03, the first byte of KcvData is the length of KCV data which participate in the calculation, the rest is KCV data. The first byte after the KCV data represents the MAC operation mode. 8 bytes 10 bytes Return When KcvMode = 0x00, padding with random numbers. When KcvMode =0x01/0x02/0x03, KcvValue points to the KCV value. Padding with random number. RET_OK Success. ERR_DEV_NOT_O PEN PED device is not open. ERR_INVALID_PA RAM Invalid parameter. Others Refer to the PED Return code list . PAX Computer Technology (Shenzhen) Co., Ltd. 57 Prolin API Programming Guide Instruction Writing the ciphertext and plaintext to the specific index position of the specific key type area. This function has following key points: 1. When SrcKeyIdx=0, system considers that the DstKeyValue is the plaintext of key and does not judge SrcKeyType and SrcKeyIdx. Write the DstKeyValue to DstKeyIdx in DstKeyType area directly. 2. Only when PED_TLK does not exist, to type-in plain text or download any key is allowed. 3. When PED_TLK exist, it is not allowed to type in plaintext or download key. PED_TLK can be 16 or 24 bytes.8-byte key is not allowed. 4. Format PED to clear all downloaded keys and then write in PED_TLK. 5. If SrcKeyIdx is valid, PED considers the DstKeyValue as the key ciphertext, thus decrypt it using SrcKeyIdx key and write the key to DstKeyIdx. DstKeyType >= SrcKeyType. 6. DstKeyLen only can be of 8, 16 or 24 bytes. If DstKeyLen = 8 bytes, the key could only be used for DES calculation. If DstKeyLen = 16 or 24 bytes, the key could be used for TDES calculation. DstKeyLen <= SrcKeyLen. 7. If DstKeyType=PED_TPK, the key only be used to encrypt PIN Block. If DstKeyType=PED_TAK, the key can only be used for MAC encryption. If DstKeyType=PED_TDK, the key can only be used for *DES/TDES. 8. KCV is the verification for plaintext. If plaintext is typed-in directly, the KcvMode of KeyIn is not 0 and the system will do the KCV verification for plaintext according to the specified KcvMode. 9. The valid KeyBlock must be 184 bytes, and the users must pass in valid parameters, otherwise an error will occur. 6.5.2 OsPedWriteTIK Prototype int OsPedWriteTIK (const unsigned char * KeyBlock); Function Write in a TIK, and check the key correction by KCV. Parameters 1 byte Format: 0x03 1 byte SrcKeyType: PED_TLK 1 byte SrcKeyIdx: When SrcKeyType = PED_TLK, SrcKeyIdx = 1; When plaintext writing, SrcKeyIdx = 0. 1 byte DstKeyIdx: DstKeyIdx = [1~100]; 7 bytes Reserved domain. Random number. 1 byte DstKeyType: PED_TIK 1 byte DstKeyLen: 8/16 KeyBlock【Input】 PAX Computer Technology (Shenzhen) Co., Ltd. 58 Prolin API Programming Guide 24 bytes DstKeyValue. The destination key plaintext / ciphertext 1 byte KcvMode: 0x00: No authentication. 0x01: Performs DES/TDES encryption on the 8-bytes 0x00, and uses first 3 bytes in ciphertext as KCV. 0x02: Performs parity check 1st, then performs DES/TDES encryption on 8 bytes ―\x12\x34\x56\x78\x90\x12\x34\x56 ‖, and uses first 3 bytes in ciphertext as KCV. 0x03: Sends in data KcvData, uses source key to perform specified mode of MAC on [aucDesKeyValue + KcvData], and use the result as KCV. 128 bytes KcvData: When the KcvMode is 0x00/0x01/0x02, padding with random numbers. When the KcvMode is 0x03the first byte of KcvData is the length of KCV data which participate in the calculation, the rest is KCV data. The first byte after the KCV data represents the MAC operation mode. 8 bytes 10 bytes Return Instruction When KcvMode = 0x00, padding with random numbers. When KcvMode = 0x01/0x02/0x03, KcvValue point to the KCV value. Initialize KSN. RET_OK Success ERR_DEV_NOT_O PEN PED device is not open. ERR_INVALID_PA RAM Invalid parameter Others Refer to the PED Return code list . Writes the cryptograph and plaintext of a key to the specific index position of the specific key type area. This function has following key points: 1. When SrcKeyIdx=0, system considers that the DstKeyValue is the plaintext of key and will not check the SrcKeyType and SrcKeyIdx. Write the DstKeyValue to DstKeyIdx in DstKeyType area directly. 2. Only when PED_TLK does not exist, it is allowed to type-in plaintext or download any key. 3. When PED_TLK exist, it is not allowed to type in plaintext or download key. 4. If SrcKeyIdx is valid, PED considers the DstKeyValue as key PAX Computer Technology (Shenzhen) Co., Ltd. 59 Prolin API Programming Guide 5. 6. cryptography thus decrypts it by SrcKeyIdx key and writes the key to DstKeyIdx. DstKeyType >= SrcKeyType. KCV is verification for plaintext. If plaintext is typed-in directly, and the KcvMode of KeyIn is not 0, the system will process KCV verification for plaintext according to the specified KcvMode. The valid KeyBlock must be 184 bytes, and the users must pass in valid parameters, otherwise an error will occur. 6.5.3 OsPedWriteKeyVar int OsPedWriteKeyVar(int KeyType, int SrcKeyIdx, int DstKeyIdx, const unsigned char * KeyVar); Prototype Function Parameters Uses the key plaintext that specified by source key index and key type, to do operation with a string of data and write the result to the location, specified by the destination key index with the same key type. KeyType SrcKeyIdx The source key index DstKeyIdx The destination key index KeyVar Return Instruction PED_TMK PED_TPK PED_TAK PED_TDK 24 bytes. 【Input】 The extensible input data to be used in exclusive-or, length of it should be same as the key. RET_OK Success ERR_DEV_NOT_O PEN PED device is not open. ERR_INVALID_PA RAM Invalid parameter Others Refer to the PED Return code list . Please refer to AS2805.6. 6.5.4 OsPedSetAsteriskLayout int OsPedSetAsteriskLayout(int x, int y, Prototype int fontSize, int fontColor, PAX Computer Technology (Shenzhen) Co., Ltd. 60 Prolin API Programming Guide uchar align); Function Sets how to display the layout attributes of asterisk while inputting PIN. x X-coordinate y Y-coordinate fontSize Font size of asterisk: fontSize = 16, represents the character has 16 dots; fontSize = 24, represents the character has 24 dots; fontSize = 32, represents the character has 32 dots; fontSize = 48,represents the character has 48 dots; Display the asterisk with PED internal font, and it is not relevant to system installed font. fontColor Font color of asterisk. Using the macro definition RGB (_r, _g, _b) and according to the input three-primary colors to generate color value with 16-bit. align Alignment: PED_ASTERISK_ALIGN_LEFT; PED_ASTERISK_ALIGN_CENTER PED_ASTERISK_ALIGN_RIGHT RET_OK Success ERR_DEV_N OT_OPEN PED device is not open. ERR_INVALI D_PARAM Invalid parameter. Others Refer to the PED Return code list . Parameters Return Instruction 1. The PIN input interface is displayed by the application, this function will only display asterisk. 2. It needs to call this function to set the displaying layout of asterisk before using PedVerifyPlainPin, PedVerifyCipherPin, PedGetPinBlock and PedGetPinDukpt. 6.5.5 OsPedGetPinBlock int OsPedGetPinBlock (int KeyIdx, const unsigned char * DataIn, const char * ExpPinLen, int Mode, unsigned long TimeoutMs, unsigned char * PinBlock); Prototype Function Scan the keyboard PIN entry and output the PIN BLOCK in a specific time. Input the PIN in the length specified by ExpPinLenIn, output the PIN BLOCK generated by algorithm encryption specified by Mode. PAX Computer Technology (Shenzhen) Co., Ltd. 61 Prolin API Programming Guide [1-100] Index of TPK. KeyIdx DataIn【Input】 Parameters ExpPinLen Instruction Enumeration of 0-12 Application enumerates all possible lengths of PIN. ‗,‘ will be used to separate each number of 【Input】 length. If no PIN, or 4 or 6 digits of PIN are allowed, the string will be set as ‗0, 4, and 6‘. 0 means that no PIN is required and pressing ‗Enter‘ will return. Mode PIN BLOCK format 0x00 0x00 ISO9564 format 0 0x01 0x01 ISO9564 format 1 0x02 0x02 ISO9564 format 3 0x03 0x03 HK EPS format TimeoutMs The timeout of PIN entry [ms] Maximum is 300000ms. 0: Without timeout or related control for PED. PinBlock Return If Mode=0x00, DataIn is 16 bytes primary account number after shifting. If Mode=0x01, Input parameters for participation in PinBlock formatting, 8 bytes data. (Refer to ISO9564 standard, this data can be Random number, transaction serial number or time stamp, etc.) If Mode=0x02, DataIn is 16 bytes primary account number after shifting. If Mode=0x03, DataIn is ISN [6 Bytes, ASCII code]. 【Output】 8bytes. Point to the generated PINBlock. RET_OK Success ERR_DEV_NOT_OPEN PED device is not open. ERR_INVALID_PARA M Invalid parameter. Others Refer to the PED Return code list . Press ‗CANCEL‘ to cancel input. 6.5.6 OsPedUpdatePinBlock int OsPedUpdatePinBlock (int UpdateFlag, const unsigned char * KeyInfo, Prototype const unsigned char * DataIn, unsigned char * PinBlock, PAX Computer Technology (Shenzhen) Co., Ltd. 62 Prolin API Programming Guide int Mode); Function Recalculates PINBlock and chooses to replace TPK. UpdateFlag 0: Do not replace TPK, Non zero: Replace TPK KeyInfo【Input】 Parameters DataIn 【Input】 PinBlock Return Instruction It has 184 bytes, please refer to the KeyBlock definition in OsPedWriteKey() for more detail. When UpdateFlag is 0, only ucDstKeyIdx is valid, adopt ucDstKeyIdx, specified by TPK and recalculate PINBLOCK. When UpdateFlag is 1, please refer to the OsWriteKey. When UpdateFlag is 0 and Mode=0x03, Transaction serial number ISN [6 Bytes, ASCII code]. When UpdateFlag is non-zero, it can be NULL. 【Output】 8 bytes. Input original PINBlock data, output new PINBLOCK. Mode 0x03 HK EPS dedication format[Appendix EPS_PINBLOCK Format] RET_OK Success ERR_DEV_NOT _OPEN PED device is not open. ERR_INVALID _PARAM Invalid parameter. Others Refer to the PED Return code list . For EPS. 6.5.7 OsPedGetMac int OsPedGetMac(int KeyIdx, const unsigned char *DataIn, int DataInLen, Prototype unsigned char *Mac, int Mode); Function Use MAC key specified by the KeyID to do the MAC operation for the following Mode algorithm, output the 8-byte result to Mac. KeyIdx Parameters DataIn【Input】 PAX Computer Technology (Shenzhen) Co., Ltd. TAK index. [1~100] <=1024 bytes The data package that needs to do the MAC operation. 63 Prolin API Programming Guide DataInLen The length of data package. If the length is not a multiple of 8, 0x00 will be padded automatically. Mac【Output】 8 bytes, output of MAC. 1. 2. Mode 3. Return Instruction 0x00: Performs the DES/TDES encryption for BLOCK1 by using MAC key, and then do it again by using TAK when and after bitwise XOR the previous encryption result with BLOCK 2. Processes in turn to get the 8 bytes encryption result. 0x01: Performs s bitwise XOR for BLOCK1 and BLOCK 2; and then do it again by using previous XOR result with BLOCK3, and finally gets the 8 bytes XOR result. Use TAK to process DES/TDES encryption for the result. 0x02: ANSIX9.19 standard. Performs DES encryption for BLOCK1 by using TAK (only take the first 8 bytes of the key). The encryption result will bitwise XOR with BLOCK 2, and then does it again by using TAK to get the 8 bytes encryption result. Until DES/TDES encryption for the last time. RET_OK Success ERR_DEV_NOT _OPEN PED device is not open. ERR_INVALID _PARAM Invalid parameter. Others Refer to the PED Return code list . For EPS. 6.5.8 OsPedDes int OsPedDes(int KeyIdx, unsigned char * InitVector, const unsigned char *DataIn, Prototype int DataInLen, unsigned char *DataOut, int Mode); Function Uses the TDK to do the DES/TDES decryption for the data and then outputs plaintext or ciphertext. A specified TDK can be used for encryption and decryption algorithms. KeyIdx Parameters TDK index. [1~100]. InitVecto 【Input】 Used for CBC/OFB encryption or decryption. If set to NULL, it will set the initialization vector as PAX Computer Technology (Shenzhen) Co., Ltd. 64 Prolin API Programming Guide ―\x00\x00\x00\x00\x00\x00\x00\x00‖ by default. It is not needed for ECB encryption or decryption, and can be set to NULL. DataIn 【Input】 Points to the data that needs to be calculated. DataInLen Data length. It should be <=1024 and multiple of 8. DataOut【Output】 Points to the data that has been calculated. Mode Return 0x00: ECB Decryption 0x01: ECB Encryption 0x02: CBC Decryption 0x03: CBC Encryption 0x04: OFB Decryption 0x05: OFB Encryption RET_OK Success ERR_DEV_NOT_ OPEN PED device is not open. ERR_INVALID_P ARAM Invalid parameter. Others Refer to the PED Return code list . Instruction Using DES or TDES depends on the key length. 6.5.9 OsPedGetKcv int OsPedGetKcv (int KeyType, int KeyIdx, int KcvMode, Prototype int KcvDataLen, unsigned char * KcvData, unsigned char * Kcv); Function Gets KCV value for key verification of two sides: 1. While it isn‘t TIK: uses specific key and algorithm to encrypt the data, and then return the first 3 bytes of the cryptograph. 2. While it is TIK: returns the 8-byte KCV which was injected while PAX Computer Technology (Shenzhen) Co., Ltd. 65 Prolin API Programming Guide TIK-injection. KeyType KeyIdx Index number of the key, for example: TLK can only be 1. TMK takes range value from 1 to 100. TWK takes range value from 1 to 100. TIK takes range value from 1 to 100. KcvMode 0x00: KCV check mode. KcvDataLen The data length used in the KCV calculation. It should be <=128 bytes and be the multiple of 8. It can be ―0‖ if the type is TIK. KcvData【Input】 Points to the data that needs to be calculated. It can be NULL if the type is TIK. Parameters Kcv Return 【Output】 PED_TLK PED_TMK PED_TAK PED_TPK PED_TDK PED_TIK 3 or 8bytes. Points to KCV. KCV of TIK has 8 bytes, other types have 3 bytes. RET_OK Success ERR_DEV_NOT _OPEN PED device is not open. ERR_INVALID _PARAM Invalid parameter. Others Refer to the PED Return code list . Instruction 6.5.10 OsPedDeriveKey int OsPedDeriveKey (int SrcKeyType, int SrcKeyIdx, int DstKeyType, Prototype int DstFromKeyIdx, int DstToKeyIdx, int Mode); Function Divergent key. Uses the key specified by SrcKeyIdx to do the encryption or decryption for the key specified by DstFromKeyIdx, then derives a new key PAX Computer Technology (Shenzhen) Co., Ltd. 66 Prolin API Programming Guide and save it as the specified key of DstToKeyIdx. SrcKeyType Types of the source key. PED_TLK PED_TMK PED_TAK PED_TPK PED_TDK SrcKeyIdx Index number of source key, for example: TLK can only be 1. TMK takes range value from 1 to 100. TWK takes range value from 1 to 100. DstKeyType Types of the destination key PED_TLK PED_TMK PED_TAK PED_TPK PED_TDK DstFromKeyIdx Source index of the destination key DstToKeyIdx Destination index of the destination key Mode 0x00: DES/TDES decryption 0x01: DES/TDES encryption RET_OK Success ERR_DEV_NOT _OPEN PED device is not open. ERR_INVALID _PARAM Invalid parameter. Others Refer to the PED Return code list . Parameters Return Instruction The source key level should not be lower than the destination key type. 6.6 DUKPT 6.6.1 OsPedGetPinDukpt int OsPedGetPinDukpt(int GroupIdx, const unsigned char * DataIn, Prototype const char * ExpPinLen, int Mode, PAX Computer Technology (Shenzhen) Co., Ltd. 67 Prolin API Programming Guide unsigned long TimeoutMs, unsigned char * Ksn, unsigned char * PinBlock); Function Scans the input PIN in a specified time, and outputs the PINBlock which generated by computing the PIN key of DUKPT. GroupIdx DUKPT group ID. [ 1~100] 1. 2. 【Input】 DataIn 3. 4. Parameters If Mode=0x20, DataIn is the 16 bytes primary account number after shifting. If Mode=0x21, inputs parameters for participation in PinBlock formatting, 8 bytes data (refer to ISO9564 standard, this data can be Random numbers, the transaction serial number or time stamp, etc.) If Mode=0x22, DataIn is the 16 bytes primary account number after shifting. If Mode=0x23, DataIn is ISN [6 Bytes, ASCII code] 0~12 enumerate set. Application enumerates all possible lengths of PIN. ‗,‘ will be used to separate each length. If no PIN, or 4 or 6 ExpPinLen【Input】 digits PIN are allowed, the string should be set to ‗0, 4, 6‘. 0 means that no PIN is required and pressing ‗Enter‘ will return. Mode TimeoutMs Ksn Choose the format of PIN BLOCK 0x20: ISO9564 format 0, KSN not plus 1 automatically. 0x21: ISO9564 format 1, KSN not plus 1 automatically. 0x22: ISO9564 format 2, KSN not plus 1 automatically. 0x23: HK EPS format, KSN not plus 1 automatically. The timeout of PIN entry [ms] Maximum is 300000ms. 0 means there is no timeout time, PED doesn‘t have to do the timeout control. 【Output】 Points to the current KSN.(10 bytes) PinBlock【Output】 Points to the generated PIN Block result.(8 bytes) Return Instruction RET_OK Success ERR_DEV_NOT_ OPEN PED device is not open. ERR_INVALID_P ARAM Invalid parameter. Others Refer to the PED Return code list . When KSN does not plus 1, a DUKPT PIN key can only calculate the PIN BLOCK for once. PAX Computer Technology (Shenzhen) Co., Ltd. 68 Prolin API Programming Guide 6.6.2 OsPedGetMacDukpt int OsPedGetMacDukpt(int GroupIdx, const unsigned char *DataIn, int DataInLen, Prototype unsigned char *Mac, unsigned char *Ksn, int Mode); Function Calculate MAC by using MAC key of DUKPT. GroupIdx DataIn DUKPT group ID. [1~100] 【Input】 Points to the data that needs to calculate the MAC. DataInLen The data length should be <=1024. If the length is not the multiple of 8, 0x00 will be padded automatically. Mac 【Output】 Points to the obtained MAC. Ksn 【Output】 Points to the current KSN. 1. 2. Parameters 3. Mode 4. 5. 6. 7. 8. 9. PAX Computer Technology (Shenzhen) Co., Ltd. 0x20: Perform TDES encryption for BLOCK1 by using MAC key. Does TDES encryption again by using TAK when and after bitwise XOR the previous encryption result with BLOCK 2. Processes in turn to get the 8 bytes encryption result. 0x21: Does bitwise XOR for BLOCK1 and BLOCK 2; Does bitwise XOR again by using previous XOR result with BLOCK3. Does it in turn and finally gets the 8 bytes XOR result. Uses TAK to process TDES encryption for the result. 0x22: ANSIX9.19 standard, Does DES encryption for BLOCK1 by using TAK (only take the first 8 bytes of key). The encryption result will bitwise XOR with BLOCK2 and then does DES encryption by using TAK again. Does it in turn and gets the 8 bytes encryption result. Uses TDES to encrypt in the last time. 0x20/0x21/0x22: KSN not plus 1 automatically. 0x40/0x41/0x42: The MAC calculation method is the same with 0x20/0x21/0x22. 0x40/0x41/0x42: Chooses to response the MAC key. 0x20/0x21/0x22: KSN chooses to request and response MAC key 0x40/0x41/0x42: KSN not plus 1 automatically. Other values are reserved for extended MAC algorithm. 69 Prolin API Programming Guide Return Instruction RET_OK Success ERR_DEV_NOT_ OPEN PED device is not open. ERR_INVALID_P ARAM Invalid parameter. Others Refer to the PED Return code list . If KSN does not increase, both the response MAC key and the response-request MAC key can calculate MAC for unlimited times. 6.6.3 OsPedDesDukpt int OsPedDesDukpt (int GroupIdx, int KeyVarType, unsigned char *InitVector, int DataInLen, Prototype unsigned char *DataIn, unsigned char *DataOut, unsigned char *Ksn, int Mode); Function Uses DES/MAC key of DUKPT to do encryption and decryption for the input data. GroupIdx DUKPT group ID. [1~100] 0x00: Uses the requests and responses of MAC key 0x01: Uses DES key of DUKPT KeyVarType 【Input】 0x02: Uses the PIN variant to encrypt the data and it is only available for ECB encryption that means the Mode can only be 1. Parameters InitVector Used for CBC/OFB encryption or decryption. If set to NULL, it will set the initialization vector as ―\x00\x00\x00\x00\x00\x00\x00\x00‖ by default.(8 【Input】 bytes) It is not needed for ECB encryption, and can be set to NULL. DataInLen The data needed to be calculated should be <= 8192 bytes. DataIn DataOut 【Input】 Input data. 【Output】 Points to the data that has been calculated. PAX Computer Technology (Shenzhen) Co., Ltd. 70 Prolin API Programming Guide 【Output】 Current KSN(10 bytes) Ksn Mode Return Instruction 0x00: ECB decryption 0x01: ECB encryption 0x02: CBC decryption 0x03: CBC encryption 0x04: OFB decryption 0x05: OFB encryption RET_OK Success ERR_DEV_NOT_OP EN PED device is not open. ERR_INVALID_PAR AM Invalid parameter. Others Refer to the PED Return code list . When KSN is unchanged, and KeyVarType is 0x00 or 0x01, a set of the DUKPT key can do DES operations for 256 times at most. When KeyVarType is 0x02, a set of the DUKPT key can only do the DES operation for once. 6.6.4 OsPedGetKsnDukpt int OsPedGetKsnDukpt (int GroupIdx, Prototype Function unsigned char * Ksn); Reads the current KSN value. GroupIdx Parameters Return Ksn DUKPT group ID. [1-100] 【Output】 Points to the current KSN. (10 bytes) RET_OK Success ERR_DEV_NOT _OPEN PED device is not open. ERR_INVALID _PARAM Invalid parameter. Others Refer to the PED Return code list . Instruction 6.6.5 OsPedIncreaseKsnDukpt Prototype int OsPedIncreaseKsnDukpt (int GroupIdx); Function Increases KSN value of the specific DUKPT group. Parameters Return GroupIdx 1-100: DUKPT group ID RET_OK Success ERR_DEV_NOT PED device is not open. PAX Computer Technology (Shenzhen) Co., Ltd. 71 Prolin API Programming Guide _OPEN ERR_INVALID _PARAM Invalid parameter. Others Refer to the PED Return code list . Instruction 6.7 RSA 6.7.1 OsPedReadRsaKey int OsPedReadRsaKey (int RsaKeyIdx, Prototype Function ST_RSA_KEY * RsaKey); Reads the RSA public key. RsaKeyIdx Parameters Return Instruction 1~10: Index of RSA Key. RsaKey 【Output】 RSA public key. RET_OK Success ERR_DEV_NOT_O PEN PED device is not open. ERR_INVALID_PA RAM Invalid parameter. Others Refer to the PED Return code list . It can only read the RSA public key, while reads private key, returns error. 6.7.2 OsPedWriteRsaKey int OsPedWriteRsaKey (int RsaKeyIdx, Prototype Function ST_RSA_KEY * RsaKey); Inject RSA key into the PED. RsaKeyIdx Parameters Return Instruction RsaKey 1~10: Index of RSA Key. 【Input】 Points to the RSA key that needs to be injected into PED. RET_OK Success ERR_DEV_NOT_O PEN PED device is not open. ERR_INVALID_PA RAM Invalid parameter. Others Refer to the PED Return code list . The type of RSA key is depending on the exponent‘s length, it is the private PAX Computer Technology (Shenzhen) Co., Ltd. 72 Prolin API Programming Guide key if the length equals to modulus. 1. Currently it does not support RSA key whose length is more than 256 bytes. 2. RSA key can be rewritten at any time. 6.7.3 OsPedRsaRecover int OsPedRsaRecover (int KeyIdx, int DataInLen, unsigned char * DataIn, Prototype unsigned char * DataOut, unsigned char * KeyInfo); Function Uses the RSA key stored in PED to process data operation. RsaKeyIdx 1~10: Index of RSA Key. DataInLen The length of operation data which is the same as the RSA modulus, the size in bytes. The length can be the value which is multiples of 8 and should also between 64 bytes and 256 bytes. Parameters DataIn 【Input】 Points to the data that needs to be calculated. DataOut 【Output】 Points to the data that has been calculated. KeyInfo 【Output】 Key information Return RET_OK Success ERR_DEV_NOT_O PEN PED device is not open. ERR_INVALID_PA RAM Invalid parameter. Others Refer to the PED Return code list . Instruction 6.7.4 OsPedReadCipherRsaKey int OsPedReadCipherRsaKey (int RsaKeyIdx, Prototype Function unsigned char * CipherRsaKey); Reads the ciphertext of RSA key. PAX Computer Technology (Shenzhen) Co., Ltd. 73 Prolin API Programming Guide RsaKeyIdx Parameters Return Index of RSA Key. [1~10] CipherRsaKey【Output】 Points to the ciphertext data of RSA key. >0 The byte length of the RSA ciphertext. ERR_DEV_NOT_OPE N PED device is not open. ERR_INVALID_PAR AM Invalid parameter. Others Refer to the PED Return code list . Instruction 6.7.5 OsPedWriteCipherRsaKey int OsPedWriteCipherRsaKey (int RsaKeyIdx, int CipherRsaKeyLen, Prototype unsigned char * CipherRsaKey); Function Parameters Writes the ciphertext of RSA key. RsaKeyIdx Index of RSA Key. [1~10] CipherRsaKeyLen The byte length of the ciphertext data of RSA key. CipherRsaKey【Input】 Points to the ciphertext data of RSA key. Return RET_OK Success ERR_DEV_NOT_OP EN PED device is not open. ERR_INVALID_PAR AM Invalid parameter. Others Refer to the PED Return code list . Instruction 6.8 AES 6.8.1 OsPedWriteAesKey Prototype intOsPedWriteAesKey (const unsigned char * KeyBlock); Function Write in an AES key and use KCV to check the key correction. Parameters 1 byte Format: 0x03 1 byte SrcKeyType: PED_TLK KeyBlock【Input】 PAX Computer Technology (Shenzhen) Co., Ltd. 74 Prolin API Programming Guide 1 byte SrcKeyIdx: When SrcKeyType = PED_TLK, SrcKeyIdx = 1; When SrcKeyType = PED_TMK, SrcKeyIdx = [1~100]; If ucSrcKeyIdx = 0, key will be written in PED as plain text. 1 byte DstKeyIdx: [1-100]. 7 bytes Reserved domain. Random number. 1 byte DstKeyType: PED_TAESK 1 byte DstKeyLen: 16/24/32 32 bytes DstKeyValue: The destination cipher-text. 1 byte KcvMode: 0x00: No KCV check. 0x01: Performs AES ECB encryption on 16-byte 0x00, and use first 3 bytes as KCV. 0x02: Perform parity check at first, then perform AESECB encryption on 16 bytes ―\x12\x34\x56\x78\x90\x12\x34\x56 \x12\x34\x56\x78\x90\x12\x34\x56‖ , and use first 3 bytes as KCV. 0x03: Transfers in a string of KcvData, use source key to perform specified mode MAC on [DstKeyValue (cipher) + KcvData], and use the result as KCV. 128 bytes KcvData: When KcvMode is 0x00/0x01/0x02, padding with random numbers. When KcvMode is0x03, the first byte of KcvData is the length of KCV data which participates in the calculation, the rest is KCV data. The first byte after the KCV data represents the MAC operation mode. 8 bytes 2 bytes Return PED_TMK plain-text or When KcvMode = 0x00, padding with random numbers. When KcvMode =0x01/0x02/0x03, KcvValue point to the KCV value. Padding with random number. RET_OK Success ERR_DEV_NOT_ Device is not open. PAX Computer Technology (Shenzhen) Co., Ltd. key 75 Prolin API Programming Guide OPEN Instruction ERR_INVALID_P ARAM Invalid parameter. Others Refer to the PED Return code list. Writing the cryptograph and plaintext of an AES key to the specific index position of the AES area. This function has following key points: 1. When SrcKeyIdx=0, system consider that the DstKeyValue is the plaintext of key and does not judge SrcKeyType and SrcKeyIdx. Write the DstKeyValue to DstKeyIdx in DstKeyType area directly. 2. Only when PED_TLK does not exist, to inject plaintext or download any key into PED is allowed. 3. When PED_TLK exist, it is not allowed to inject in plaintext or download key. 4. If SrcKeyIdx is valid, PED considers the DstKeyValue as the key cryptography, thus decrypt it using SrcKeyIdx key and write the key to DstKeyIdx. 5. The valid KeyBlock must be 184 bytes, and the users must pass a valid parameter to it, otherwise an error will occur. 6.8.2 OsPedAes intOsPedAes(intKeyIdx, unsigned char * InitVector, const unsigned char *DataIn, Prototype intDataInLen, unsigned char *DataOut, int Mode); Function Uses the specified AES key stored in PED to do the AES encryption or decryption for the data and then output ciphertext or plaintext. KeyIdx 【Input】 TAESK index: 1~100. InitVector Used for CBC/OFB encryption or decryption. If set to NULL, it will set the initialization vector as ―\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\ 【Input】 x00\x00\x00\x00\x00‖ by default. It is not needed for ECB encryption or decryption, and can be set to NULL. DataIn 【Input】 Points to the data that needs to be calculated. DataInLen 【Input】 Parameters DataOut Data length. It should be <=1024, and multiple of 16. 【Output】 Points to the data that has been calculated. PAX Computer Technology (Shenzhen) Co., Ltd. 76 Prolin API Programming Guide 0x00: ECB Decryption 0x01: ECB Encryption 0x02: CBC Decryption Mode 【Input】 0x03: CBC Encryption 0x04: OFB Decryption 0x05: OFB Encryption Return RET_OK Success ERR_DEV_NOT_OPEN Device is not open. ERR_INVALID_PARA M Invalid parameter. Others Refer to the PED Return code list . Instruction PAX Computer Technology (Shenzhen) Co., Ltd. 77 { This page intentionally left blank } Prolin API Programming Guide 7 LCD In Prolin, the operation of displaying contents on LCD is managed by the GUI; it supports the graphics systems such as Minigui, QT. In this chapter, it will provide OsScrBrightness(), OsScrContrast(), OsScrGetSize() and some related interfaces for application use. Application can adopt the XUI graphic interfaces that provided by PAX, for more details; refer to the ―XUI Programming Guide‖. It also can develop the GUI system by itself, or it can use FrameBuffer approach to test the validity of the LCD driver. OsScrContrast(), OsScrBrightness(), OsScrGetSize() and the rest of the LCD operations are managed by the GUI. Applications (such as driver testing) can also operate FrameBuffer directly. Details are as follows: 1. Open the FrameBuffer device, the device node is ―/dev/fb‖; 2. Get the fixed screen information through ioctl, 3. Get the variable screen information through ioctl, 4. Map device memory to the process space through mmap, 5. Write the FrameBuffer. int open_screen(void) { char vtname[128]; int fd, nr; PAX Computer Technology (Shenzhen) Co., Ltd. 79 Prolin API Programming Guide unsigned y, addr; struct fb_fix_screeninfo fix; sb = (screen_buffer*)malloc(sizeof (screen_buffer)); if ((sb->dev_fd = open(FB_DEV_PATH, O_RDWR)) == -1) { perror("open"); return -1; } int ret = ioctl(sb->dev_fd, FBIOGET_VSCREENINFO, &fb_vinfo); if (ret) { sb->width = FB_WIDTH; sb->height = FB_HEIGHT; sb->bytes_per_pixel = FB_BYTES_PER_PIXEL; fprintf(stderr,"in %s line %d",__FUNCTION__,__LINE__); } else { sb->width = fb_vinfo.xres; sb->height = fb_vinfo.yres; sb->bytes_per_pixel = fb_vinfo.bits_per_pixel / 8; } if(sb->bytes_per_pixel == 3) sb->bytes_per_pixel = 4; if (ioctl(sb->dev_fd, FBIOGET_FSCREENINFO, &fix) < 0) { close(sb->dev_fd); return -1; } fbmemlen = sb->width * sb->height * sb->bytes_per_pixel; if ((sb->buffer = (uint8_t *) mmap(NULL, fbmemlen, PROT_READ | PROT_ WRITE,MAP_FILE |MAP_SHARED, sb->dev_fd, 0)) == (uint8_t *) -1) { fprintf (stderr, "rw_sd_inand.c: Can't mmap frame buffer ++\n"); exit (1); } memset(sb->buffer, 0, fbmemlen); return 0; } 1. Close the FrameBuffer device PAX Computer Technology (Shenzhen) Co., Ltd. 80 Prolin API Programming Guide void close_screen(screen_buffer *sb) { if(!sb) return; // Unmap the framebuffer munmap(sb->buffer, fbmemlen); // Close framebuffer device close(sb->dev_fd); free(sb); } 7.1 OsScrContrast Prototype void OsScrContrast(int Contrast); Function Sets the contrast. Parameters Return Instruction Contrast Contrast level [0~7]. 0: darkest 7: lightest Default value: 4. Other values: no action. None This function is only applicable to monochrome LCD. 7.2 OsScrBrightness Prototype void OsScrBrightness(int Brightness); Function Sets the screen brightness. Parameters Brightness Brightness level [0~10]. 0: turn off the backlight 10: lightest value All brightness values are visible。 Default value: 8. Other values: no action. Return None Instruction PAX Computer Technology (Shenzhen) Co., Ltd. 81 Prolin API Programming Guide 7.3 OsScrGetSize void OsScrGetSize(int *Width, Prototype int *Height); Function Gets the LCD Physical screen size. Width【Output】 Width (unit: pixel). Parameters Return Instruction Height【Output】 Height (unit: pixel). None The screen size is just a read-only property. The interface only applys to the applications that does not support GUI. PAX Computer Technology (Shenzhen) Co., Ltd. 82 Prolin API Programming Guide 8 Keyboard The keyboard input of Prolin is managed by GUI. Key value definition Macro Value Description KEY1 2 KEY‖1‖ KEY2 3 KEY ―2‖ KEY3 4 KEY―3‖ KEY4 5 KEY―4‖ KEY5 6 KEY―5‖ KEY6 7 KEY―6‖ KEY7 8 KEY―7‖ KEY8 9 KEY―8‖ KEY9 10 KEY―9‖ KEY0 11 KEY―0‖ KEYCANCEL 223 KEY―CANCEL‖ KEYCLEAR 14 KEY―CLEAR‖ PAX Computer Technology (Shenzhen) Co., Ltd. 83 Prolin API Programming Guide KEYENTER 28 KEY―ENTER‖ KEYALPHA 69 KEY ―Alpha‖ KEYF1 59 At the bottom of S800 LCD, the first key from left to right. KEYF2 60 KEYF3 61 KEYF4 62 KEYFUNC 102 Key ―Function‖ KEYUP 103 At the bottom of S800 LCD, the second key from left to right. KEYDOWN 108 At the bottom of S800 LCD, the third key from left to right. KEYMENU 139 At the bottom of S800 LCD, the fourth key from left to right. The application developers can directly use the input subsystem when they need to test keyboard drivers or transplant other GUI systems. The device node of the keyboard is "/dev/ keypad". Details of calling the input subsystem are shown as follow: #include #include #include #include static int keypad_fd = -1; struct input_event ev0[64]; //for handling /key/event static int handle_event0() { int button = 0, realx = 0, realy = 0, i, rd; rd = read(keypad_fd, ev0, sizeof(struct input_event) * 64); if ( rd < sizeof(struct input_event) ) return 0; PAX Computer Technology (Shenzhen) Co., Ltd. 84 Prolin API Programming Guide for (i = 0; i < rd / sizeof(struct input_event); i++) { printf("", ev0[i].type, ev0[i].code, ev0[i].value); if (ev0[i].type == 3 && ev0[i].code == 0) realx = ev0[i].value; else if (ev0[i].type == 3 && ev0[i].code == 1) realy = ev0[i].value; else if (ev0[i].type == 1) { if (ev0[i].code == 158) { //if key esc then exit return 0; } } else if (ev0[i].type == 0 && ev0[i].code == 0 && ev0[i].value == 0) { realx = 0, realy = 0; } printf("event(%d): type: %d; code: %3d; value: %3d; realx: %3d; realy: %3d\n", i, ev0[i].type, ev0[i].code, ev0[i].value, realx, realy); } return 1; } int main(void) { int done = 1; printf("sizeof(struct input_event) = %d\n", sizeof(struct input_event)); keypad_fd = open("/dev/keypad", O_RDWR); if ( keypad_fd < 0 ) return -1; while ( done ) { printf("begin handel_event0...\n"); done = handle_event0(); printf("end handel_event0...\n"); } if ( keypad_fd > 0 ) { close(keypad_fd); keypad_fd = -1; } return 0; } PAX Computer Technology (Shenzhen) Co., Ltd. 85 Prolin API Programming Guide 8.1 OsKbBacklight Prototype void OsKbBacklight(int OnOff); Function Switches the keyboard backlight. Parameters OnOff Return None 0: Turn off the backlight. Non-zero: Turn on the backlight. Instruction PAX Computer Technology (Shenzhen) Co., Ltd. 86 Prolin API Programming Guide 9 Touch Screen The touch screen input of Prolin is managed by GUI. The application developers can directly use the input subsystem if they need to test touch screen drivers or transplant other GUI systems. About input subsystem calls, refer to the example of the keyboard, the node of touch screen is ―/dev/tp‖. PAX Computer Technology (Shenzhen) Co., Ltd. 87 Prolin API Programming Guide 10 Signature Pad For more details, refer to the ―XUI Programming Guide‖. PAX Computer Technology (Shenzhen) Co., Ltd. 88 Prolin API Programming Guide 11 Printer Prolin provides both virtual printing and physical printing function, and also provides the unified interface for API. For physical printer, the senior application developers can access the printer driver through a POSIX interface to achieve the specific print function. 11.1 Return code list Table 11 Printer return code list Macro Value Description ERR_PRN_BUSY -3701 Printer is busy ERR_PRN_PAPEROUT -3702 Out of paper ERR_PRN_WRONG_PACKAGE -3703 The format of print data packet error. ERR_PRN_OVERHEAT -3704 Printer overheats ERR_PRN_OUTOFMEMORY -3705 The print data is too large to exceed the buffer length. ERR_PRN_OVERVOLTAGE -3706 Voltage is too high. PAX Computer Technology (Shenzhen) Co., Ltd. 89 Prolin API Programming Guide 11.2 Open and Close This part includes three functions: opening, resetting and closing the printer. 11.2.1 OsPrnOpen int OsPrnOpen(unsigned int printertype, Prototype const char* targetname ); Function Opens the printer (including physical and virtual). printertype Types of printer: PRN_REAL: Physical printer. 【Input】 PRN_BMP: Bmp virtual printer and it generates bmp format files. targetname For the physical printer, this parameter should be NULL. 【Input】 The other output file name of virtual printer, this parameter should fill in the file name generated by virtual printing, for example, /home/app/test.bmp. Parameters Return RET_OK Success. ERR_DEV_NOT_EX IST Device does not exist. ERR_INVALID_PAR AM Invalid parameter ERR_DEV_BUSY ERR_BATTERY_AB SENT Instruction Device is occupied The battery is absent 1. This function needs to be called when the program starts to run, otherwise the associated functions won‘t work. 2. Noted that S920 and D200 mobile terminals need battery to work. 11.2.2 OsPrnReset Prototype void OsPrnReset(void); Function Implements the print restoration and initialization. Parameters None Return None Instruction Calling this function will restore the printer default settings and clear buffer data. This function is applicable to both physical printers and virtual printers. PAX Computer Technology (Shenzhen) Co., Ltd. 90 Prolin API Programming Guide After calling OsPrnReset (), the font choice of library file will be restored to default font status (only available in English). 11.2.3 OsPrnClose Prototype void OsPrnClose(void); Function Closes the printer. Parameters None Return None Instruction This function should be called to close the printer device when program exit. 11.3 Printer settings 11.3.1 OsPrnSetSize int OsPrnSetSize (unsigned int Width, Prototype unsigned int Height); Function Parameters Return Instruction Sets printer parameters. Width【Input】 Width Height【Input】 Height RET_OK Success. ERR_INVALID_PARAM Invalid parameter. Only applicable to the virtual printer. The default size is 384*5000, and the maximum size is 600*5000. This function is effective in the first calling, and it will not change the first settings in the following repeat calls. 11.3.2 OsPrnSetDirection Prototype int OsPrnSetDirection (unsigned char Mode); Function Sets the print direction. Mode 【Input】 0: print horizontally. Parameters Non-zero: print vertically. Return Instruction RET_OK Success ERR_INVALID_PA RAM Invalid parameter. This function is applicable to both physical printers and virtual printers. PAX Computer Technology (Shenzhen) Co., Ltd. 91 Prolin API Programming Guide 11.3.3 OsPrnSetGray Prototype void OsPrnSetGray(int Level); Function Sets printing gray level. Level Parameters Return Instruction Level =0, reserved, Level =1, default level, normal print slip, Level =2, reserved, Level =3, two-layer thermal printing, Level =4, two-layer thermal printing, higher gray level than 3, The default level is 1. The illegal value does not change current settings. None Before setting gray level, it prints with the default level, after calling this function it will print with the setting level. This function is only applicable to the physical printer. 11.4 TypeSetting 11.4.1 OsPrnSetSpace void OsPrnSetSpace(int CharSpace, Prototype int LineSpace); Function Sets the printing space. CharSpace Character space (unit: pixel) (It is invalid to the mandatory non-monospaced fonts, such as Arabic fonts, Thai fonts.) LineSpace Line space(unit: pixel) Parameters Return None 1. 2. 3. Instruction 4. 5. 6. Settings will be valid until they are set again or OsPrnReset() is called; Printing character space is 0 by default; Printing line spaces are 0 and 2 for thermal printer and stylus printer respectively by default ; The maximum line space can be 255; The maximum character space can be 255; Invalid parameter does not change the current settings. 11.4.2 OsPrnSetReversal Prototype int void OsPrnSetReversal(int Attr); Function Sets the reverse attribute of font, normal printing by default. Parameters Attr PAX Computer Technology (Shenzhen) Co., Ltd. 0: normal 92 Prolin API Programming Guide Non zero: reversal Return Instruction None This function is applicable to both physical printers and virtual printers 11.4.3 OsPrnSetIndent int OsPrnSetIndent (unsigned int Left, Prototype unsigned int Right); Function Sets the left and right margins. Left 【Input】 The left margin: the valid range is [0, 100] and the default value is 0. Right 【Input】 The right margin: the valid range is [0, 100] and the default value is 0. Parameters Return Instruction RET_OK Success ERR_INVALID_PA RAM Invalid parameter If the physical printer is set to print vertically, then the left margin should correspond to the top margin of the page, and right margin corresponds to the bottom margin. 11.4.4 OsPrnCheck Prototype int OsPrnCheck(void); Function Checks the current status of printer. Parameters Return Instruction None RET_OK Success. ERR_PRN_NOFONTLIB Has no font library. ERR_PRN_BUSY Printer is busy. ERR_PRN_PAPEROUT Out of paper. ERR_PRN_OVERHEAT Printer overheated. This function can be used to check whether there is a printing font library, whether there is paper, whether printing buffer is full, and whether the printer is overheated Only applicable to the physical printer. 11.4.5 OsPrnGetDotLine Prototype int OsPrnGetDotLine(void); Function Gets current printed dot line for slip alignment. Parameters None Return >=0 PAX Computer Technology (Shenzhen) Co., Ltd. Current dot line. 93 Prolin API Programming Guide Instruction Used for slip alignment. This function is applicable to both physical printers and virtual printers. 11.4.6 OsPrnSetFont Prototype int OsPrnSetFont(const char * fontname); Function Selects print fonts. Parameters fontname【Input】 Font(file) name RET_OK Success ERR_FONT_NOT_EXIST Font does not exist. ERR_INVALID_PARAM Invalid parameter. Return Instruction It can choose a different font style and font size for printing. The system built-in font (file) name can be obtained by calling OsEnumFont () function. 11.4.7 OsPrnSelectFontSize void OsPrnSelectFontSize(int SingleCodeWidth, int SingleCodeHeight, Prototype int MultiCodeWidth, int MultiCodeHeight); Function Parameters Return Instruction Sets the font size. SingleCodeWidth The width control of single code font. (For nonmonospaced font, width of each character may not meets the settings). The value ranges from 8 to 64. SingleCodeHeight The height control of single code font. The value ranges from 8 to 64. MultiCodeWidth The width control of multiple code fonts. The value ranges from 12 to 64. MultiCodeHeight The height control of multiple code font The value ranges from 12 to 64. None After the first calling of OsPrnOpen(), the font width and height are set to the default values (12x24) (24x24). This function is applicable to both physical printers and virtual printers. PAX Computer Technology (Shenzhen) Co., Ltd. 94 Prolin API Programming Guide Suggest the height and width of multiple code font should be the same, otherwise, the font may display abnormally. 11.4.8 OsPrnFeed Prototype void OsPrnFeed(int Pixel); Function Feeds printing paper ―pixel‖ pixels in print buffer. Parameters Pixel Return None 1. Instruction 2. number of pixels If the pixel value is positive, then the paper will feed forwards. If it is negative, then feed backwards. If it is 0, then no action. This function is applicable to both physical and virtual printers. This is a one-time action, that is, it will lose its effect after the implementation. 11.4.9 OsPrnPrintf Prototype void OsPrnPrintf(const char *Str, ...); Function Formats output string to print buffer. Parameters Return Instruction Str【Input】 None 1. 2. 3. 4. 5. 6. 11.4.10 Pointer of string that needs to be printed. Support variable parameters; Support ‗\n‘ (new line) and ‗\f‘ (new page) control characters in the string; If the printing data package is too long, then the program will overflow; If the string is longer than the printing boundary, it will automatically change line and continue printing; The maximum buffer size is 2048 bytes; Store str in printing buffer, and print data in printing buffer in sequence of writing into the buffer after calling OsPrnStart(). OsPrnPutImage Prototype void OsPrnPutImage(const unsigned char *Logo); Function Outputs images to the print buffer. Parameters Logo【Input】 PAX Computer Technology (Shenzhen) Co., Ltd. Pointer to the logo information; the length cannot be more than 20000 bytes. 95 Prolin API Programming Guide None Return 1. Instruction 2. 3. 4. Bitmap data is generated as follows: Draw a bitmap (usually a logo): use paintbrush program under Windows to draw a bitmap and save it as a ―monochromatic, bmp format‖ file. Use ―Bitmap Converter‖ provided by PAX to convert the .bmp file into a header file, for instance, Logo.h header file. (If more than one .bmp files are selected, after the conversion, the head file contain the same number of array\the definition of the name of the array will be associated with the BMP filename. Printing bitmap size limit: for thermal printer, up to 384 pixels in width is allowed, for stylus printer, 180 pixels are allowed, but the height is unlimited. Use the generated array as the input parameter of this function. If the bitmap width is larger than the limit of the printer, then it will be get rid of the redundant data on the right. . If the size of the data packet is too large, then this function will remove the LOGO message. Format description of the image array in the header file: First byte [1 byte]: number of rows of the bitmap; Size of the first bitmap line in byte [2 Bytes, MSB (most significant byte)ahead]; Bitmap data of the first bitmap line [one line of the bitmap have 8 pixels in height]; Size of the second bitmap line in byte [2 Bytes, MSB ahead]; Bitmap data of the second bitmap line; So on and so forth. This function only stores logo into printing buffer, and begins printing data in printing buffer in sequence after calling OsPrnStart (). 11.4.11 OsPrnStart Prototype int OsPrnStart(void); Function Starts printer and prints the data in the buffer. Parameters Return None RET_OK Success ERR_PRN_BUSY Printer is busy. PAX Computer Technology (Shenzhen) Co., Ltd. 96 Prolin API Programming Guide ERR_PRN_PAPEROUT Out of paper. ERR_PRN_WRONG_PACKAGE The format of printing data package error. ERR_PRN_OVERHEAT Printer overheats. ERR_PRN_OUTOFMEMORY The size of the printing data is too large. 1. Instruction 2. 3. After calling this API, the printer will perform the printing task and return after completing the whole printing task. After completing the whole printing task, this API will return the printer status in return value. Therefore the check printer status is not required. If the printing process is completed, recalling this function will reprint the slip. 11.5 POSIX Prolin physical printer driver module makes the POSIX programming interface open to the application developers. 11.5.1 open Opens the physical printer, the device name is ―/dev/printer‖ int handle = open(―/dev/printer‖, O_RDWR); 11.5.2 read Read the printer status. The data format of the first byte buf[0] in Read buffer is defined as follows:0x00 normal 0x01 printer is busy 0x02 out of paper 0x03 printer overheats 0x04~0xFF reserved unsigned char buf[10]; int ret = read(handle, buf, 2); if (ret > 0) { //buf[0] } 11.5.3 Write Send the contents of printer configuration and print the buffer. PAX Computer Technology (Shenzhen) Co., Ltd. 97 Prolin API Programming Guide The first two bytes of the buffer are gray settings and reserved bit, suppose that the buffer is char buf [50], bit0~bit2 in the buf [0] represent the printing gray control values, bit3~bit7 are reserved. char 0: bit0~bit2: The control value of print grayscale, 000(0) Reserved 001(1) Normal gray level 010(2) Reserved 011(3) Two-layer thermal printing A 100(4) Two-layer thermal printing B 101(5) Reserved 110(6) Reserved 111(7) Reserved The second byte buf [1] in the buffer: reserved. From buf [2], a single line is composed of every 48 characters (384 dots); if it is less than 48 then it will be padding with blank by the driver. unsigned char buf[50]; buf[0] = 0x01; memset(buf + 2, 0xff, 48); int ret = write(handle, buf, 50); if (ret < 0) { //Error handling…… } The limit of the maximum data length is: For the thermal printing of 384 dots, when prints horizontally, the driver can deal with 5000 lines each time at most, if out of the range, it will not print. When prints vertically, it can deal with 384 lines each time, and each line can print 5000 dots at most, if there are more than 384 PAX Computer Technology (Shenzhen) Co., Ltd. 98 Prolin API Programming Guide lines, it will not print. The longest length of a write buffer should be 384*5000/8 + 2 = 240002 Bytes. 11.5.4 Close Closes the printer file handles. close (handle); PAX Computer Technology (Shenzhen) Co., Ltd. 99 { This page intentionally left blank } Prolin API Programming Guide 12 Font Library Prolin supports Freetype as the system font library. Therefore, the system supports a series of vector font and bitmap font. 12.1 Data structure FT_FONT typedef struct { char FileName[64]; /* Font file name */ char FontName[64]; /* Font name */ }FT_FONT; FT_DOT typedef struct { unsigned char Left; /*Font offsets left from the baseline*/ unsigned char Top; /* Font offsets top from the baseline */ unsigned char Width; PAX Computer Technology (Shenzhen) Co., Ltd. /* Font width */ 101 Prolin API Programming Guide unsigned char Height; /* Font height */ unsigned char Dot[3072]; /*Valid font data */ }FT_DOT; 12.2 Font operation 12.2.1 OsEnumFont Prototype int OsEnumFont(FT_FONT *FontList); Function Gets the vector font list provided by system. Parameters Return FontList【Output】 Vector fonts list >=0 Read the number of vector fonts ERR_INVALID_P ARAM Invalid parameter. ERR_FONT_NOT _EXIST Font library does not exist. Example: int i, num; FT_FONT *FontList; num = OsEnumFont(&FontList); Instruction if(num <= 0) return -1; for(i=0; i =0 Font handle ERR_INVALID_P ARAM Invalid parameter. ERR_FONT_NOT _EXIST System does not install font library. PAX Computer Technology (Shenzhen) Co., Ltd. 102 Prolin API Programming Guide Instruction It needs to cache the dot-matrix data after open the fonts, and it is recommended to call OsGetFontDot() after 3 seconds. 12.2.3 OsCloseFont Prototype void OsCloseFont ( int Handle); Function Closes vector fonts. Parameters Return Instruction Handle 【Input】 Font handle None After using vector fonts, please promptly shut down to release the system resources. 12.2.4 OsGetFontDot int OsGetFontDot ( int Handle, const char *Utf8Code, const int Width, Prototype const int Height, const int Style, FT_DOT *FtDot); Function Gets the utf-8 encoding standard character font. Handle 【Input】 Utf8Code 【Input】 Font handle Characters of UTF-8 encoding standards Width 【Input】 Font width, value range is【8, 128】. Height 【Input】 Font height, value range is【8, 128】. Font style: Parameters Style 【Input】 FONT_STYLE_NON E 0 No style FONT_STYLE_BOL D 0x00000001 Bold type FONT_STYLE_ITAL IC 0x00000002 Italic type FONT_STYLE_BOL D|FONT_STYLE_IT ALIC FtDot Return 【Output】 RET_OK PAX Computer Technology (Shenzhen) Co., Ltd. bold italics The output of font data structure. Success 103 Prolin API Programming Guide ERR_INVALID_PAR AM Invalid parameter ERR_FILE_NOT_EX IST File does not exist. ERR_FONT_CODE Font code error. ERR_INVALID_HA NDLE Invalid handle Utf8Code input. UTF-8 code is a variable length, and it needs to end with '\ 0', when the code is composed of letters, Utf8Code requires two bytes where Utf8Code [0] represents letter, Utf8Code [1] represents ' \ 0'; but for Chinese, Utf8Code requires four bytes where Utf8Code [0-2] represents the Chinese and Utf8Code [3] represents ' \ 0'. The Italic style dot matrix. When using italics effects, the obtained dot matrix width is wider than the set value. It is not recommended that the dot size should be not less than 24; otherwise the dot may not show italics effects. For example, when the dot size of Song typeface is less than 19, and the bold font dot size is less than 21, the italic effects cannot be used for Chinese, but it is available for letters. The format of font data. 1. 2. All of the font dot matrix are in horizontal arrangement mode; The point which corresponds to each byte, the sequence from left to right is 0x80 to 0x01; 3. If the character width that is not enough to make a integer multiple of 8,the bytes of per line dot matrix are (width+7)/8 For example: For the character ― > ‖,with 10(width)x20(height) Instruction The font data is: 0x00, 0x00, 0x20, 0x00, 0x10, 0x00, 0x10, 0x00, 0x08, 0x00, PAX Computer Technology (Shenzhen) Co., Ltd. 104 Prolin API Programming Guide 0x04, 0x00, 0x04, 0x00, 0x02, 0x00, 0x01, 0x00, 0x00, 0x80, 0x00, 0x80, 0x01, 0x00, 0x02, 0x00, 0x04, 0x00, 0x04, 0x00, 0x08, 0x00, 0x10, 0x00, 0x10, 0x00, 0x20, 0x00, 0x00, 0x00 After calling this function, the character returns: Width = 10 Height = 20 Dot data: 0x00,0x00,0x20,0x00,0x10,0x00,0x10,0x00, 0x08,0x00,0x04,0x00,0x04,0x00,0x02,0x00, 0x01,0x00,0x00,0x80,0x00,0x80,0x01,0x00, 0x02,0x00,0x04,0x00,0x04,0x00,0x08,0x00, 0x10,0x00,0x10,0x00,0x20,0x00,0x00,0x00 PAX Computer Technology (Shenzhen) Co., Ltd. 105 { This page intentionally left blank } Prolin API Programming Guide 13 Code Prolin supports UTF8 as the system default code, and also provides the code-conversion interface. 13.1 Code Convert 13.1.1 OsCodeConvert int OsCodeConvert (const char *FromCharset, const char *ToCharset, const char *InBuf, Prototype char *OutBuf, unsigned int LenOut); Function Implement conversion of character encoding. FromCharset 【Input】 The original character encoding Parameters ToCharset 【Input】 The target character encoding InBuf 【Input】 OutBuf LenOut Return Character string of the original encoding, ending with ‘ \0‘.Unicode should end with‖\0\0‘‘ 【Output】 The converted encoding string 【Input】 >=0 PAX Computer Technology (Shenzhen) Co., Ltd. Size of array OutBuf, it should be at least 1.5 times of the array InBuf. Success, then returns the length of converted character string. 107 Prolin API Programming Guide ERR_INVALID_PARAM Invalid parameter Supports conversions among the following codes. Instruction ISO-8859-(1,2,3,4,5,6,7,8,9,10,11, 13,14,15,16) cp(850,874,932,1250,1251,1252,1253,1254,1255,1256,1257,1258) GBK/GB18030(2 bytes part) BIG5 SHIFT_JIS EUC-KR UNICODE UTF-8 1. The conversion is only recommended between the above codes and UTF-8 codes. Others might fail. 2. UNICODE adopts the Little-Endian mode. PAX Computer Technology (Shenzhen) Co., Ltd. 108 Prolin API Programming Guide 14 MSR Prolin provides the function of reading the magnetic stripe data and provides a unified API reading interface for use. In addition, senior application developers can access to the magnetic drive through the POSIX interface and directly get the magnetic stripe bit-stream to achieve different logics of magnetic stripe decoding. 14.1 Return code list Table 12 MSR return code list Macro Value ERR_MSR_FAILED -2701 Failed ERR_MSR_HEADERR -2702 Did not find the head mark. ERR_MSR_ENDERR -2703 Did not find the end mark ERR_MSR_LRCERR -2704 LRC check error ERR_MSR_PARERR -2705 One bit of MSR check error. ERR_MSR_NOT_SWIPED -2706 No swiping ERR_MSR_PED_DECRYPTERR -2709 PED decryption failed. PAX Computer Technology (Shenzhen) Co., Ltd. Description 109 Prolin API Programming Guide 14.2 Data structure MSR structure: Records information and status of each magnetic track. ST_MSR_DATA: typedef struct { unsigned char TrackData[256]; /*Track data buffer*/ int DataLen; /* Track data length*/ int Status; /*Track data status, status equal 0 indicates read track data succeed, other value indicates failed*/ }ST_MSR_DATA; When the status of track data is 0, it means reads track successfully, and it has two scenarios: 1. If the data format is correct or there is no data in track, then it needs to be combined with DataLen to be determined; 2. When Status <0, DataLen will be equal to 0, and the TackData will not include the information of magnetic track. 14.3 MSR control interface 14.3.1 OsMsrOpen Prototype int OsMsrOpen(void); Function Switches on magnetic stripe reader. Parameters Return Instruction None RET_OK Success ERR_DEV_NOT_EXIST Device does not exist. ERR_DEV_BUSY Device is busy. ERR_DEV_NOT_OPEN Fail to open the device. Other functions can be operated only after open device successfully. PAX Computer Technology (Shenzhen) Co., Ltd. 110 Prolin API Programming Guide Magnetic stripe reader works in interrupt mode. When the magnetic stripe reader is opened, it can read the magnetic track data, even if no card-reading function is called. So it is better to switch off magnetic stripe reader when it is not in use. 14.3.2 OsMsrClose Prototype void OsMsrClose(void); Function Switches off magnetic stripe reader. Parameters None Return None Instruction This function should be called to close device when program exit. 14.3.3 OsMsrReset Prototype void OsMsrReset(void); Function Resets magnetic stripe reader Parameters None Return None Instruction When the magnetic reader is powered on, this function resets the reader and clears the data in the buffer. 14.3.4 OsMsrSwiped Prototype int OsMsrSwiped(void); Function Checks whether a card is swiped or not. Parameters Return None TRUE Card swiped FALSE Not swiped ERR_DEV_NOT _OPEN Device is not open. 1. Instruction 2. 3. This function returns the corresponding value immediately, doesn‘t matter card is swiped or not. Call this function to check whether a card is swiped or not. After calling the OsMsrOpen(), OsMsrRead() or OsMsrReset(), the status of swiping card will be clear. PAX Computer Technology (Shenzhen) Co., Ltd. 111 Prolin API Programming Guide 14.3.5 OsMsrRead int OsMsrRead(ST_MSR_DATA *Track1, Prototype ST_MSR_DATA *Track2, ST_MSR_DATA *Track3); Function Parameters Return Instruction Reads data of magnetic stripe card. Track1 【Output】 Output the data of Track1 Track2 【Output】 Output the data of Track2 Track3 【Output】 Output the data of Track3 RET_OK Success ERR_MSR_NOT_S WIPED No swiping. ERR_INVALID_PA RAM Invalid parameter. ERR_DEV_NOT_O PEN Device is not open. If a certain track‘s data is not needed, set the corresponding pointer to NULL, then the data will not be outputted. After swiped card successfully, and users didn‘t call this interface to read the track data, the data will be automatically emptied. And all of the returned track data are 0x00. Calling OsMsrSwiped() first to detect the swipe actions, then callOsMsrRead() to obtain the data of magnetic track. Otherwise, when the function returns, the data included in the buffer is invalid. For magnetic card conforming to ISO7812: Track1 needs 79 bytes Track2 needs 37 bytes Track3 needs 107 bytes 14.4 POSIX Prolin Magnetic driver module makes the POSIX programming interface open to the senior application developers. PAX Computer Technology (Shenzhen) Co., Ltd. 112 Prolin API Programming Guide 14.4.1 Open Opens the magnetic stripe reader, and the device name is‖/dev/msr‖ int handle = open(―/dev/msr‖, O_RDONLY); 14.4.2 Read Read the bit stream data from magnetic stripe card. The data format in Read buffer is defined as follows: Variable length of data, but it is not more than 3 * 750 bytes. In the case of no card swiping, the returned data length of read is 0, and the read () may return -1. When the first byte of the buffer is 0, it presents that the following data will be plaintext magnetic track data. The data bit stream is represented by using the ASCII code 0/1 and an ASCII code represents a bit, tracks are separated by 0x0A. 010101010101010101000000000000000000000000000000000011111111111111111111111 111111\n 010101010101010101000000000000000000000000000000000011111111111111111111111 111111\n 010101010101010101000000000000000000000000000000000011111111111111111111111 111111\n The second byte of the buffer is 1 that means the following data will be locked by using fixed key encryption. Which needs PedMsrDecryptRaw() interface to do the decryption. unsigned char buf[2250]; int ret = read(handle, buf, 2250); if (ret > 0) { /*Bit stream decode*/ } 14.4.3 Close Closes file handles of the magnetic stripe reader. After closing the handle, the original magnetic data stored in the drive buffer will be cleared. close (handle); PAX Computer Technology (Shenzhen) Co., Ltd. 113 Prolin API Programming Guide 15 ICC Reader The basic protocol interface is customized according to the ISO7816/EMV. 15.1 Return Code List Table 13 ICC reader return code list Macro Value Description ERR_SCI_HW_NOCARD -2800 No card ERR_SCI_HW_STEP -2801 Exchange when no init, warm reset when no active ERR_SCI_HW_PARITY -2802 Parity error ERR_SCI_HW_TIMEOUT -2803 Time out ERR_SCI_TCK -2804 TCK error ERR_SCI_ATR_TS -2810 TS error in ATR ERR_SCI_ATR_TA1 -2811 TA1 error in ATR ERR_SCI_ATR_TD1 -2812 TD1 error in ATR ERR_SCI_ATR_TA2 -2813 TA2 error in ATR ERR_SCI_ATR_TB1 -2814 TB1 error in ATR PAX Computer Technology (Shenzhen) Co., Ltd. 114 Prolin API Programming Guide ERR_SCI_ATR_TB2 -2815 TB2 error in ATR ERR_SCI_ATR_TC2 -2816 TC2 error in ATR ERR_SCI_ATR_TD2 -2817 TD2 error in ATR ERR_SCI_ATR_TA3 -2818 TA3 error in ATR ERR_SCI_ATR_TB3 -2819 TB3 error in ATR ERR_SCI_ATR_TC3 -2820 TC3 error in ATR ERR_SCI_T_ORDER -2821 Protocol is not T0 or T1 ERR_SCI_PPS_PPSS -2830 PPSS error in PPS ERR_SCI_PPS_PPS0 -2831 PPS0 error in PPS ERR_SCI_PPS_PCK -2832 TC3 error in ATRPCK error in PPS ERR_SCI_T0_PARAM -2840 Data in transmitting is too long in T0 ERR_SCI_T0_REPEAT -2841 Too many character repetition in T0 ERR_SCI_T0_PROB -2842 Procedure byte error in T0 ERR_SCI_T1_PARAM -2850 Data in transmitting is too long in T1 ERR_SCI_T1_BWT -2851 BWT exceed in T1 ERR_SCI_T1_CWT -2852 CWT exceed in T1 ERR_SCI_T1_BREP -2853 Too many block repetition in T1 ERR_SCI_T1_LRC -2854 LRC error in T1 ERR_SCI_T1_NAD -2855 NAD error in T1 ERR_SCI_T1_LEN -2856 LEN error in T1 ERR_SCI_T1_PCB -2857 PCB error in T1 ERR_SCI_T1_SRC -2858 SRC error in T1 ERR_SCI_T1_SRL -2859 SRL error in T1 ERR_SCI_T1_SRA -2860 SRA error in T1 ERR_SCI_PARAM -2880 Parameter not allow PAX Computer Technology (Shenzhen) Co., Ltd. 115 Prolin API Programming Guide 15.2 Data Structure 15.2.1 IC card device control block sci_dcb_t: /* device control block */ struct sci_dcb_t { unsigned int voltage; /* operation condition: voltage */ /* frequency adjust integer, default value is 372 */ unsigned int fi; /* speed adjust integer, default value is 1 */ unsigned int di; unsigned int conv; unsigned int protocol; unsigned char option_clock; unsigned char option_voltage; unsigned char option_spu; /* logical converse direction */ /* T=0 or T=1 */ /* stop clock options */ /* voltage options */ /* these members are appended, you must notice */ unsigned int spec; unsigned int nego; /* support PPS protocol */ /* the guard time between characters, only for T=0 */ unsigned int cgt; /* block guard time, default value is 22, only for T=1 */ unsigned int bgt; /* RESET signal maintain LOW level clock cycles, default is 42500 */ unsigned int rstt; unsigned int wtt; /* TS wait time, default value is ??? */ /* allowed maximum of ATR duration, only used in EMV mode (spec=0) */ unsigned int twt; unsigned int wwt; /* T=0, work wait time, default is 0x0A */ /* character repetition (in T=0), maximum is 6 */ unsigned int tpar_retry; /* send repeat time on parity error */ unsigned int rpar_retry; /* recv repeat time on parity error */ unsigned int bwt; /* T=1, block wait time, default is 0x00 */ unsigned int cwt; /* T=1, character wait time, default is 0x05 */ unsigned char repeat; PAX Computer Technology (Shenzhen) Co., Ltd. 116 Prolin API Programming Guide /* the maxium frame size of ICC, default value is 32 */ unsigned int fsc; unsigned int fsd; unsigned char sci_last_ipcb; unsigned char icc_last_ipcb; unsigned char sci_last_pcb; unsigned char icc_last_pcb; /* reset status: cold reset, warm reset, or activation */ unsigned int status; }; 15.2.2 ATR structure sci_atr_t: /* ATR */ struct sci_atr_t { unsigned char ts; unsigned char t0; unsigned char ta_flag; unsigned char tb_flag; unsigned char tc_flag; unsigned char td_flag; unsigned char ta[8]; unsigned char tb[8]; unsigned char tc[8]; unsigned char td[8]; unsigned char hbytes[15]; unsigned char tck; }; 15.2.3 APDU Request Structure ST_ APDU_REQ typedef struct { Unsigned char Cmd[4]; /*CLA, INS, P1, P2*/ int LC; /* The valid length of DataIn sent to ICC */ unsigned char DataIn[512];/* The data sent to ICC */ int LE; /* The expected returned length */ }ST_ APDU_REQ; PAX Computer Technology (Shenzhen) Co., Ltd. 117 Prolin API Programming Guide ST_APDU_REQ structure: 1. LE is the expected return length. . The actual returned length is related to specific command. Here is an expected length but the actual returned length will be obtained by LenOut. 2. LE and LC are used in combination as follows: LC=0, LE=0. There are neither sending data nor return data. LC=0, LE>0. No sending data, but expecting return length. If the expected return length is unknown, set Le to 256; otherwise, set it to a specific value. LC>0, LE=0. The data are sent, but no expected return length. LC>0, LE>0. The data are sent and returned the expected length. . If expected return length is unknown, set Le to 256; otherwise, set it to a specific value. 15.2.4 APDU Response Structure ST_ APDU_RSP: typedef struct { Int LenOut; unsigned char DataOut[512]; unsigned char SWA; unsigned char SWB; }ST_ APDU_RSP; /* The actual returned data length */ /* Returned data pointer from ICC */ /*status word 1 of ICC */ /* status word 2 of ICC */ 15.3 API index sci_open () sci_get_dcb () sci_set_dcb () sci_read () sci_write () sci_close () sci_lock () PAX Computer Technology (Shenzhen) Co., Ltd. sci_detect () sci_cold_reset () sci_warm_reset () emv_atr_parse () iso7816_atr_parse () iso7816_pps () iso7816_ocs() 118 Prolin API Programming Guide sci_unlock() sci_powerup() sci_powerdown() iso7816_t1_ifsd_request() iso7816_t0_exchange() iso7816_t1_exchange() 15.3.1 sci_open Prototype int sci_open(int id); Function Opens the corresponding smartcard device. Parameters Return Instruction id 【Input】 device id 0 opened successfully others failed to open, return an error code Other functions can be operated only after open device successfully. 15.3.2 sci_get_fd Prototype int sci_get_dcb(int id); Function Gets the corresponding smartcard device's fd. Parameters Return Instruction id 【Input】 Device id, 0-user slot, 1,2,3,4, sam1-sam4. >=0 device‘s id others device not open or return a error code When open a smartcard device, fd is stored in sci_logical_devices [id].fp, get it by this function. 15.3.3 sci_get_dcb Prototype int sci_get_dcb(int id, struct sci_dcb_t *dcb) Function Gets the device control block from the device driver layer. Parameters Return id【Input】 device id dcb【Output】 device control block 0 success others error Instruction 15.3.4 sci_set_dcb Prototype int sci_set_dcb(int id, struct sci_dcb_t *dcb); Function Sets the device control block to the device driver layer. PAX Computer Technology (Shenzhen) Co., Ltd. 119 Prolin API Programming Guide Parameters Return id【Input】 device id dcb【Output】 device control block 0 success others error Instruction 15.3.5 sci_read Prototype int sci_read(int id, unsigned char *pbuf, int length); Function Reads bytes from the device driver layer. Parameters Return id【Input】 device id pbuf【Output】 data buffer length【Input】 data length 0 success others error Instruction 15.3.6 sci_write Prototype int sci_write(int id, unsigned char *pbuf, int length); Function Writes bytes into the device driver layer. Parameters Return id【Input】 device id pbuf【Output】 data buffer length【Input】 data length 0 success others error Instruction 15.3.7 sci_close Prototype int sci_close(int id); Function Closes the corresponding smartcard device. Parameters Return id【Input】 device id 0 success PAX Computer Technology (Shenzhen) Co., Ltd. 120 Prolin API Programming Guide others Instruction error This function should be called to close device while program exit. 15.3.8 sci_lock Prototype int sci_lock(int id); Function Locks the smartcard lock on the corresponding smartcard device. Parameters Return Instruction id【Input】 device id 0 success others error On smartcard devices, locking the smartcard lock before cold reset, warm reset, reading or writing has no effect on user card device (id = 0). 15.3.9 sci_unlock Prototype int sci_unlock(int id); Function Unlocks the smartcard lock on the corresponding smartcard device. Parameters Return Instruction 15.3.10 id【Input】 device id 0 success others error On smartcard devices, unlock the smartcard lock after getting all the data (or error info) from transmission by read operation. It has no effect on user card device (id = 0). sci_powerup Prototype int sci_powerup(int id); Function Card activation on the corresponding smartcard device. Parameters Return id【Input】 device id 0 success others error Instruction 15.3.11 sci_powerdown Prototype int sci_ powerdown (int id); Function Card deactivation on the corresponding smartcard device. Parameters Return id【Input】 device id 0 success others error PAX Computer Technology (Shenzhen) Co., Ltd. 121 Prolin API Programming Guide Instruction 15.3.12 sci_detect Prototype int sci_detect(int id); Function Detects whether the user card is in the socket or not. Parameters Return Instruction 15.3.13 id【Input】 device id 0 success others error Only id = 0 is accepted. sci_cold_reset Prototype int sci_cold_reset(int id, struct sci_atr_t *pstATR); Function Performs a cold reset sequence and receives the ATR data. Parameters Return id【Input】 device id pstATR【Output】 pointer to ATR data 0 success others error Instruction 15.3.14 sci_warm_reset Prototype int sci_warm_reset (int id, struct sci_atr_t *pstATR); Function Performs a warm reset sequence and receives the ATR data. Parameters Return id【Input】 device id pstATR【Output】 pointer to ATR data 0 success others error Instruction 15.4 Protocol processing function 15.4.1 emv_atr_parse Prototype int emv_atr_parse (const struct sci_atr_t *pstATR, PAX Computer Technology (Shenzhen) Co., Ltd. 122 Prolin API Programming Guide struct sci_dcb_t *dcb); Function Parameters Return Parses the ATR characters according to EMV v4.2 standard. pstATR【Input】 ATR point dcb【Output】 device control block 0 success others error Instruction 15.4.2 iso7816_atr_parse int iso7816_atr_parse (const struct sci_atr_t *pstATR, Prototype struct sci_dcb_t *dcb); Function Parameters Return Parses the ATR characters according to ISO7816 standard. pstATR【Input】 ATR point dcb【Output】 device control block 0 success others error Instruction 15.4.3 iso7816_pps int iso7816_pps(int id, Prototype Function Parameters Return struct sci_atr_t *pstATR, struct sci_dcb_t *dcb); PPS protocol process. id【Input】 device id pstATR【Input】 ATR point dcb【Output】 device control block 0 success others error Instruction 15.4.4 iso7816_ocs Prototype int iso7816_ocs(int id, struct sci_atr_t *pstATR); Function Select operating conditions. Parameters id【Input】 PAX Computer Technology (Shenzhen) Co., Ltd. device id 123 Prolin API Programming Guide Return Instruction pstATR【Output】 pointer to ATR data 0 success others card class selection abort Auto class selection, try 1.8V, then 3V, then 5V.It can be invoked as a cold reset with auto vcc selection. 15.4.5 iso7816_t1_ifsd_request Prototype int iso7816_t1_ifsd_request(int id); Function If sd request in T=1. Parameters Return id【Input】 device id 0 success others error Instruction 15.4.6 iso7816_t0_exchange Prototype int iso7816_t0_exchange(int id, ST_APDU_REQ *apdu_req, ST_APDU_RSP *apdu_resp); Function Transmission on T=0 protocol under ISO 7816-3 standard. Parameters Return id【Input】 device id apdu_req【Input】 pointer to APDU request, terminal request information apdu_resp【Output】 pointer to APDU response, card response information 0 success 1 success with a warning others Error Instruction 15.4.7 iso7816_t1_exchange int iso7816_t1_exchange(int id, Prototype ST_APDU_REQ *apdu_req, ST_APDU_RSP *apdu_resp); Function Parameters Transmission on T=1 protocol under ISO 7816-3 standard. id【Input】 Device id apdu_req【Input】 Pointer to APDU request, terminal request PAX Computer Technology (Shenzhen) Co., Ltd. 124 Prolin API Programming Guide information. Return apdu_resp【Output】 Pointer to APDU response, card response information. 0 success others Error Instruction 15.5 Encapsulated Interfaces 15.5.1 OslccOpen Prototype int OsIccOpen(int Slot); Function Open the ICC reader. Parameters Return Slot channel number: ICC_USER_SLOT ICC_SAM1_SLOT ICC_SAM2_SLOT ICC_SAM3_SLOT ICC_SAM4_SLOT RET_OK Success ERR_DEV_NOT_EXIST Device does not exist. ERR_DEV_BUSY Device is busy. User card SAM card slot 1 SAM card slot 2 SAM card slot 3 SAM card slot 4 Instruction 1. Other functions can be operated only after successfully opening the IC device. 2. For various machines, the number and types of slot might be different. For specific numbering of slots, please read the manual or consult professional staff. 15.5.2 OsIccDetect Prototype int OsIccDetect(int Slot); Function Check whether there is a card in the specified slot. Parameters Return Instruction Slot channel number: RET_OK Card-inserted Others Please refer to ICC Return code list 1. This function will return immediately no matter whether there is a card in PAX Computer Technology (Shenzhen) Co., Ltd. 125 Prolin API Programming Guide 2. slot or not. For USER_SLOT, if card-insert or card-extract happens, system will send MSG_ICCSIG message to the application which is used to open the device. This mechanism doesn‘t apply to SAM card. For SAM card, please make sure call this interface firstly before reset the SAM card. This interface will cause the SAM card to power off. 15.5.3 OsIccInit Prototype int OsIccInit(int Slot, unsigned long Option, unsigned char *Atr); Function Initialize the IC card device. Parameters Slot Channel number. Please refer to OslccOpen() Option (Bit 0~1)card voltage options: 00 - 5V, 01 - 1.8V, 10 - 3V, 11 - 7V (Bit 2)Support for PPS protocol: 0 – not support, 1 – support; (Bit 3~4)Rate used in ATR 00 – Standard rate 9600 01 – Twice rate 19200 10 – Four times rate 38400 The rate mentioned here is a reference value which the cards are operated under the typical frequency (3.57MHz) condition The communication rate between the IC card and the reader component is closely related to the working clock frequency which was provided to card by a specific machine. (Bit 5)Specification 0 – EMV 1 - ISO7816 If this bit specifically indicates EMV mode, the power rate will be marked as invalid. It uses the standard rate by default. (Bit 6 ~31)Reserved Option is set to 0 by default(that is 5V, not PPS, Standard rate, and follow EMVx) Atr 【Output】 PAX Computer Technology (Shenzhen) Co., Ltd. 1. Answer To Reset. Up to 34 bytes will be returned from card. 126 Prolin API Programming Guide 2. Return RET_OK Success. Others Please refer to ICC Return code list 1. 2. Instruction Content is composed of length of ATR (1 byte) and ATR[output] 3. ATR output buffer should be allocated at least 34 bytes. Whether PPS communication coordination protocol is supported or not depends on the specific cards is supported or not. For SAM card, some terminals can only work with one card at a time. If several cards need to be operated at the same time, initialize cards one by one.(OsIccInit ( ) ) - > operation ( OsIccExchange ) - > close ( ) Most of the SAM card only supports ISO7816, so the Option should be set to 0x20, but not 0x00. 15.5.4 OsIccExchange Prototype int OsIccExchange(int Slot, int CtrlFlag, const ST_APDU_REQ *ApduReq, ST_APDU_RSP *ApduRsp); Function Interacts with IC card using commands. Channel number. Please refer to OslccOpen() Slot 1. Parameters CtrlFlag 2. Return ApduReq 【Input】 ApduRsp 【Output】 Bit0 represents whether to send "Get Response" instruction automatically under T=0 protocol. 1 Yes 0 No Bit1~Bit31 Reserved The data structure sent to IC card. The data structure received from IC card. RET_OK Success. Others Please refer to ICC Return code list Instruction 15.5.5 OsIccClose Prototype int OsIccClose(int Slot); Function Close the IC card device. Parameters Slot PAX Computer Technology (Shenzhen) Co., Ltd. Channel number. Please refer to OslccOpen() 127 Prolin API Programming Guide Return RET_OK Success. Others Please refer to ICC Return code list Instruction PAX Computer Technology (Shenzhen) Co., Ltd. 128 Prolin API Programming Guide 16 RF Reader This part mainly describe the applicaton programming interface of contactless IC card reader conforming to the ISO14443 and ‗EMV Contactless Book D V2.1‘ regulation. 16.1 Return Code List Table 14 Return Code List Macro Value PCD_ERR_PAR_FLAG -2901 Parity error PCD_ERR_CRC_FLAG -2902 CRC error PCD_ERR_WTO_FLAG -2903 Timeout or no card PCD_ERR_COLL_FLAG -2904 PCD_ERR_ECD_FLAG -2905 Frame format error PCD_ERR_EMD_FLAG -2906 Interference PCD_ERR_COM_FLAG -2907 Chip error, it cannot communicate correctly. PCD_ERR_AUT_FLAG -2908 M1 authentication error PCD_ERR_TRANSMIT_FLAG -2909 Transmission PAX Computer Technology (Shenzhen) Co., Ltd. Description several cardscollision. error 129 Prolin API Programming Guide PCD_ERR_PROTOCOL_FLAG -2910 Protocol error PCD_ERR_PARAMFILE_FLAG -2911 Configuration file does not exist PCD_ERR_USER_CANCEL -2912 Usercancelled the transaction PCD_ERR_CARRIER_OBTAIN_FLAG -2913 Didn‘t obtain the carrier PCD_ERR_CONFIG_FLAG -2914 Configuration register failed PCD_ERR_NOT_ALLOWED_FLAG -2951 Parameter error or obtaining value isn‘t allowed PCD_CHIP_ABNORMAL -2952 Chip is abnormal or does not exist PCD_CHIP_NOT_OPENED -2953 Module is not open PCD_CHIP_CARDEXIST -2954 Card isn‘t removed PCD_ERR_NOT_IDLE_FLAG -2955 Card is not in idle state PCD_ERR_NOT_POLLING_FLAG -2956 Card did not do thePOLLING PCD_ERR_NOT_WAKEUP_FLAG -2957 Card does not wakeup PCD_ERR_NOT_ACTIVE_FLAG -2958 Card is not activated 16.2 Data Structure About request and response of data structure, please refer to the IC Card Reader section 15.2.3 and 15.2.4. 16.2.1 User Configuration Structure PCD_USER_ST typedef struct pcd_user_t{ unsigned char wait_retry_limit_w; of S(WTX) response*/ unsigned int wait_retry_limit_val; repeat most frequently.*/ /* Written enable for the number /* S(WTX) response to the times that unsigned char check_cancel_key_w; cancel key*/ /*Written enable for checking the unsigned char check_cancel_key_val; /* 0 represents no response to the PAX Computer Technology (Shenzhen) Co., Ltd. 130 Prolin API Programming Guide cancel key, 1 represents response the cancel key */ int (*check_cancel_key_function)(void);/* Check whether has pressed the cancel key, if set check_cancel_key_w=1 and check_cancel_key_val=1, the check_cancel_key_function will be called during the RF card transaction, when it returns 0, it represents it hasn’t pressed the cancel key, otherwise, it means it has, in this case it will be forced to exit the transaction */ unsigned char reserved[60]; /* Reserved byte, for future expansion */ } PCD_USER_ST; 16.2.2 Configuration Parameter Definition struct PCD_PARAM_ST /*Card protocol check enable switch,1- check;0 – do not check */ unsigned int uiProtocolCheckEn; /*the maximum block length that the card received .(unit: byte) */ unsigned int uiFSC; /*The longest time that waiting for card response, use the current ETU time as a time unit*/ unsigned int uiFWT; /*sending protection time, use the current ETU time as a unit */ unsigned int uiSFGT; /*Electrical conductivity of the A card */ unsigned int uiTypeAConduct; /*Reserved*/ unsigned int uiReserved; /* Receiving sensitivity of the A card */ unsigned int uiTypeARxThreshold; /* Antenna gain of A card */ unsigned int uiTypeAGain; /* Electrical conductivity of the B card */ unsigned int uiTypeBConduct; /* Modulation depth of B card*/ unsigned int uiTypeBModulDepth; PAX Computer Technology (Shenzhen) Co., Ltd. 131 Prolin API Programming Guide /* Receiving sensitivity of the B card */ unsigned int uiTypeBRxThreshold; /* Antenna gain of B card */ unsigned int uiTypeBGain; /* Electrical conductivity of the Felica card */ unsigned int uiFelicaConduct; /* Modulation depthof Felica card */ unsigned int uiFelicaModulDepth; /* Receiving sensitivity of the Felica card */ unsigned int uiFelicaRxThreshold; /* Antenna gain of Felica card */ unsigned int uiFelicaGain; /*Reserved for future use. */ unsigned int uiRFU[60]; }; 16.3 ISO14443 --- Type A 16.3.1 iso14443_3a_req Prototype int iso14443_3a_req( unsigned char *atqa ); Function Sends REQA command to PICC,and receives the ATQA from PICC. Parameters Return Instruction atqa【Output】 The buffer for ATQA,2 bytes 0 Success, the ATQA is valid, consists of two bytes. others Error 16.3.2 iso14443_3a_wup Prototype int iso14443_3a_wup( unsigned char *atqa ) ; Function Sends WUPA command to PICC and receives the ATQA from PICC. Parameters Return Instruction atqa【Output】 the buffer for ATQA, 2 bytes 0 Success, the ATQA is valid, consisting of two bytes. others Error PAX Computer Technology (Shenzhen) Co., Ltd. 132 Prolin API Programming Guide 16.3.3 iso14443_3a_antisel int iso14443_3a_antisel( unsigned char *uid, int uid_ln, Prototype unsigned char *sak ); Function Parameters Sends ANTICOLLISION command to PICC and receives the UID from PICC. uid the unique identifier of PICC uid_ln the length of the unique identifier of PICC sak the last selected command response 0 Success. others Error Return Instruction < EMV Contactless Book D - Contactless Comm Protocol 2.1, section 5.4.2> < ISO/IEC 14443-3:2001(E) Section 6.4.3.1 and 6.4.4 > 16.3.4 iso14443_3a_halt Prototype int iso14443_3a_halt( ); Function Sends HALT command to PICC. Parameters Return None 0 Success. Others Error. Instruction 16.3.5 iso14443_3a_rats Prototype int iso14443_3a_rats( unsigned char *ats ); Function Requests answer to selection.( defined by iso14443-4) Parameters Return ats【Output】 the response from PICC(must be greater than 256 bytes) 0 Success. others Error Instruction PAX Computer Technology (Shenzhen) Co., Ltd. 133 Prolin API Programming Guide 16.4 ISO14443 --- Type B 16.4.1 iso14443_3b_req Prototype int iso14443_3b_req( unsigned char *atqb ); Function Sends REQB command to PICC and receives the ATQB from PICC. Parameters Return Instruction atqb【Output】 The buffer for ATQB, 12 or 13 bytes 0 Success, the ATQB is valid; consisting of 12 or 13 bytes. others Error 16.4.2 iso14443_3b_wup Prototype int iso14443_3b_wup( unsigned char* atqb ); Function Sends WUPB command to PICC and receives the ATQB from PICC. Parameters Return Instruction atqb【Output】 the buffer for ATQB, 12 or 13 bytes 0 Success, the ATQB is valid; consisting of 12 or 13 bytes. others Error 16.4.3 iso14443_3b_attri int iso14443_3b_attri( const unsigned char *pupi, Prototype Function unsigned char* data, int *txr_ln ); PCD sends ATTRIB command to PICC and receives the SAK from PICC. pupi Parameters Return the picc's uid, 4 bytes dat【Input&Output】 higher layer INF.(command and response) txr_ln the number of higher layer INF. 0 Success others Error Instruction 16.4.4 iso14443_3b_halt Prototype int iso14443_3b_halt( ); Function Sends HALTB command to PICC. Parameters None PAX Computer Technology (Shenzhen) Co., Ltd. 134 Prolin API Programming Guide Return 0 Success others Error Instruction 16.5 Half-duplex transmission protocol 16.5.1 iso14443_4_transfer int iso14443_4_transfer( unsigned char *src, int tx_ln, Prototype unsigned char *des, int *rx_ln ); Function Parameters Return Implements the half duplex communication protocol with ISO14443-4. src The data will be transmitted by PCD. tx_ln The number of transmitted data by PCD. des The data will be transmitted by PICC rx_ln The number of transmitted data by PICC. 0 Success others Error Instruction 16.6 Encapsulate Interfaces 16.6.1 OsPiccOpen Prototype int OsPiccOpen(void); Function Power on the PCD module and work state. Parameters Return make the module enter into the preparatory None 0 Success Others Failed to open device. (Details refer to the return code list.) Instruction PAX Computer Technology (Shenzhen) Co., Ltd. 135 Prolin API Programming Guide 16.6.2 OsPiccClose Prototype int OsPiccClose (void); Function Power off the PCD module. Parameters Return None 0 Success Others Failed. (Details refer to the return code list.) Instruction 16.6.3 OsPiccResetCarrier Prototype int OsPiccResetCarrier (void); Function Reset the carrier wave. Parameters Return Instruction None 0 Success Others Failed. (Details refer to the return code list.) When doing the carrier reset operation for RF reader, the card state in the RF field will be changed, no matter what the state is, the card will enter the idle state after calling this interface. 16.6.4 OsPiccPoll Prototype int OsPiccPoll( char* pcPiccType, unsigned char* pucATQx ); Function Looks for cards, inlcuding the roll polling for type A card and type B card. pcPiccType【Output】 Card types: ‘A‘ - card A ‘B‘ - card B pucATQx 【Output】 In response to the WUPA commands, a Picc of card A will return an ATQA with a length of 2 bytes. In response to the WUPB commands, a Picc of card B will return an ATQB with a length of 12 bytes. 0 Success. Others Failed. (Details refer to the return code list.) Parameters Return Instruction Mifare card is a special A card, after calling this interface, M card returns as a type of A card. 16.6.5 OsPiccAntiSel Prototype int OsPiccAntiSel( const char pcPiccType, unsigned char *pucUID, PAX Computer Technology (Shenzhen) Co., Ltd. 136 Prolin API Programming Guide const unsigned char ucATQ0, unsigned char* pucSAK ); Function Do anti-collision and selection operations for cards. pcPiccType【Input】 Card types: ‘A‘ - card A ‘B‘ - card B pucUID【Output】 Unique identifier of the card: Card A-- 4, 7 or 10 bytes, the value of the UID shall be a fixed number or a random number which is dynamically generated by the Picc. Card B—4 bytes, the value of the pucUID of Type B card shall be fixed number or a random number which is dynamically generated by the Picc. ucATQ0【Input】 It is unused. pucSAK【Output】 The response data of card while selecting card, it has 1 byte. SAK represents the data that response to the last SELECT command of card A. This parameter is ignored by card B. 0 Success. Others Failed (Details refer to the return code list.) Parameters Return Instruction If users want to differentiate between the picc of card A and Mifare card, they can make the distinction by output parameters value of the pucSAK. 16.6.6 OsPiccActive Prototype int OsPiccActive( const char pcPiccType, unsigned char *pucRATS ); Function Activate the card. pcPiccType【Input】 Card types: ‘A‘ –Type A card ‘B‘ – Type B card The response data: Parameters pucRATS【Output】 PucRATS represents the data that responds to RATS command of card A. PucRATS represents the data that responds to ATTRIB command of card B. Return Instruction 0 Success. Others Failed(Details refer to the return code list.) The output data of PucRATS mainly includes the card frame waiting time, buffer size, maximum frame sizes, start-up frame guard time, etc. For details, PAX Computer Technology (Shenzhen) Co., Ltd. 137 Prolin API Programming Guide see the ‗EMV Contactless Book D V2.1‘ in section 5.7 and 6.4. 16.6.7 OsPiccTransfer int OsPiccTransfer( const unsigned char *pucTxBuff, int iTxLen, Prototype unsigned char* pucRxBuff, int *piRxLen ); Function Carry out the transparent transmission/reception in accordance with the half-duplex communication protocol in the ISO14443-4 pucTxBuff【Input】 iTxLen Parameters 【Input】 The length of data to be transmitted. pucRxBuff【Output】 piRxLen Return The data buffer to be transmitted. Response data buffer of receiving card. 【Output】 The length of receiving card‘s response data. 0 Success Others Failed(Details refer to the return code list.) Instruction 16.6.8 OsPiccRemove Prototype int OsPiccRemove ( void ); Function In accordance with the EMV mode to remove card. Parameters Return None 0 Success Others Failed. (Details refer to the return code list.) Instruction 16.6.9 OsMifareAuthority int OsMifareAuthority(unsigned char *uid, unsigned char blk_no, Prototype unsigned chargroup, unsigned char *psw); Function Parameters Verify the Mifare card. uid 【Input】 Card ID, 4 bytes. blk_no 【Input】 Block number group 【Input】 PAX Computer Technology (Shenzhen) Co., Ltd. Password types, can be evaluated as ‗A‘ or ‗B‘ 138 Prolin API Programming Guide psw Return 【Input】 Authentication password, 6 bytes. 0 Success. Others Failed. (Details refer to the return code list.) Instruction 16.6.10 OsMifareOperate int OsMifareOperate ( unsigned charucOpCode, unsigned charucSrcBlkNo, Prototype unsigned char*pucVal, unsigned char ucDesBlkNo ); Function Do operations of reading and writing block for the specified blocks of Mifare card, and increasing, decreasing or backup the specified data block of Mifare card, and then update it into other specified value block. ucOpCode 【Input】 ucSrcBlkNo【Input】 ‗r‘ or ‗R‘ represents read operations, ‗w‘ or ‗W‘ represents write operations, ‗+‘ represents Increase value, ‗-‘ represents Decrease value, ‗>‘ represents transfer /backup operation. Specify the visiting block number. Parameters pucVal【Input/Output】 Return If it is the read operation, pucVal outputs the block contents, and points to the buffer size of 16 bytes. If it is the write operation, pucVal inputs the block contents, and points to the buffer size of 16 bytes. If it is the ‗+‘or ‗-‘ operation, pucVal is the first address of buffer, and points to the buffer size of 4 bytes. If it is the transfer operation, pucVal has no practical meaning, but the incoming pointer must be NULL. ucUpdateBlkNo 【Input】 Specify the block number which used to written in the operation result.(while reading and writing block, it is NULL) 0 Success. Others Failed. (Details refer to the return code list.) Instruction PAX Computer Technology (Shenzhen) Co., Ltd. 139 Prolin API Programming Guide 16.6.11 OsPiccInitFelica int OsPiccInitFelica( unsigned char ucSpeed, Prototype Function unsigned char ucModInvert ); Initialize the configuration for the Felica card. ucSpeed【Input】 Set the transmission rate which is used to interact with card. 1: 424Kbp Others: 212Kbps ucModInvert【Input】 Set the FeliCa modulate mode. 1: forward modulate output; Others: reverse modulate output. 0 Success. Parameters Return Instruction 16.6.12 OsPiccIsoCommand int OsPiccIsoCommand(int cid, Prototype Function ST_APDU_REQ *ApduReq, ST_APDU_RSP *ApduRsp); Send the APDU format data and receive response in the specified channel. Used for specifying the logical channel number of the card, its value ranges from 0 to 14, currently the value is 0. cid 【Input】 ApduReq 【Input】 The structure sending Parameters ApduRsp to PICC card. 【Output】 The response structure returning from PICC card. 0 Success. Others Failed (Details refer to the return code list.) Return Instruction 16.6.13 OsPiccSetUserConfig Prototype int OsPiccSetUserConfig(PCD_USER_ST *pcd_user_config) ; Function Set the user configuration. Parameters pcd_user_config 【Input】 User configuration structure 0 Success. Others Failed (Details refer to the return code list.) Return Instruction PAX Computer Technology (Shenzhen) Co., Ltd. 140 Prolin API Programming Guide 16.6.14 OsPiccGetUserConfig Prototype int OsPiccGetUserConfig(PCD_USER_ST *pcd_user_config); Function Get the user configuration. Parameters pcd_user_config 【Output】 User configuration structure 0 Success. Others Failed (Details refer to the return code list.) Return Instruction 16.7 Note of touch screen and RF reader programming It has configured touch screen and RF reader on S300 and S800. When the RF card does the A/B transaction, application developers should note that touch screen cannot be used during the period. The remove card function should be called after finishing the transaction. When operating Mifare card, it must call OsPiccRemove () or OsPiccClose () at last. When operating Felica card, the RF module should be closed at last. PAX Computer Technology (Shenzhen) Co., Ltd. 141 { This page intentionally left blank } Prolin API Programming Guide 17 Communication Port 17.1 Data Definition Table 15 Macro definition list of communication ports Macro Value Description PORT_COM1 0 UART 1 PORT_COM2 1 UART 2 PORT_COM3 2 UART3 PORT_PINPAD 3 Built-out PORT_USBDEV 11 USB device mode port PORT_USBHOST 12 USB host mode port PinPad Table 16 Return code list of USB port functions Macro Value Description USB_ERR_NOT_OPEN -3403 Channel is not open. USB_ERR_BUF -3404 Send buffer error. USB_ERR_NOT_FREE -3405 No free port. PAX Computer Technology (Shenzhen) Co., Ltd. 143 Prolin API Programming Guide USB_ERR_NO_CONF -3411 The device has not completed enumeration and configuration process. USB_ERR_DISCONN -3412 The device has been disconnected with the host. USB_ERR_MEM_SYSTEM -3413 System memory is abnormal. USB_ERR_BUSY -3414 USB system is busy. USB_ERR_RC_SYSTEM -3415 The application for system resources is failed. USB_ERR_DEV_ABSENT -3416 The device on USB host is absent. USB_ERR_INVALID -3417 USB communication state is invalid. 17.2 Communication control 17.2.1 OsPortOpen int OsPortOpen(int Channel, Prototype const char *Attr); Function Opens communication port and sets communication parameters. Channel Please refer to the Macro definition list of communication ports, in S800, PORT_COM2 and PORT_PINPAD can be multiplex used but only one port at a time. While inS920, it only has ports of PORT USBDEV and PORT USBHOST.Please refer to Appendix 4. Attr【Input】 When the channel is PORT_USBDEV or PORT_USBHOST, attr does not work and it can be NULL. When the channel is UART port: 1. attr =―9600, 8, n, 1‖, it represents that the baud rate is 9600bps; 8 data bits; no parity; 1 stop bit. ‗,‘ will be used to separate characters. 2. Baud rate: One of 1200, 2400, 4800, 9600, 19200, 38400, 57600,115200 3. Data bit: 7 or 8; 4. Parity method: o-odd parity; e-even parity; n-no parity 5. Stop bit: 1 or 2 RET_OK Success. ERR_DEV_BUSY Device is busy. Parameters Return PAX Computer Technology (Shenzhen) Co., Ltd. 144 Prolin API Programming Guide Instruction ERR_DEV_NOT_E XIST The port does not exist. ERR_INVALID_PA RAM Invalid parameter. 1. 2. Other functions can be operated only after opening device successfully. Calling this function will close the functions of software flow control and hardware flow control. 1. The prolin2.4 system uses the USB to start the XCB service by default. When application needs to use the USB or serial port, it should call OsRegSetValue ("persist.sys.xcb.enable", "0") in mian() to close the XCB service in order to avoid the resource conflict. 2. We can start the XCB service in these ways. a) Call the OsRegSetValue("persist.sys.xcb.enable", "1") in the main application; b) Select a connection way among COM, USB and Network in TM. 17.2.2 OsPortClose Prototype void OsPortClose(int Channel); Function Closes the specified port. Parameters Return Instruction Channel Please refer to the Macro definition list of communication ports . None This function should be called to close the device while program exit. 17.2.3 OsPortSend int OsPortSend(int Channel, const void *SendBuf, Prototype int SendLen); Function Sends data to the specified communication port. Channel Parameters Please Refer to the Macro definition of communication port SendBuf【Input】 Sent data. SendLen PAX Computer Technology (Shenzhen) Co., Ltd. Length of sending data.(<=8*1024) 145 Prolin API Programming Guide Return RET_OK Success ERR_DEV_NOT _OPEN Port is not open. ERR_INVALID _PARAM Invalid parameter. 1. Instruction 2. The buffer size is 8K, when the sent data is less than the free space of the buffer, this function will not block and the sent data will only be stored in the send buffer. When calling OsPortClose(), the system will block until the send buffer data has been sent out. 17.2.4 OsPortRecv int OsPortRecv(int Channel, void *RecvBuf, Prototype int RecvLen, int TimeoutMs); Function Receives data from specified communication port. Channel Please Refer to the Macro definition of communication. RecvBuf【Output】 Received data buffering. RecvLen Parameters The data length that want to receive. When the length is 0, it means clear the receive buffer. Receive timeouts【unit:ms】 TimeoutMs Return Instruction (The minimum precision is 100ms) It should be <= 25500, otherwise, it will return ERR_INVALID_PARAM. >=0 The actual length of receive data. ERR_DEV_NOT_ OPEN Port does not open. ERR_INVALID_P ARAM Invalid parameter. 1. 2. The received data will return immediately when it is equal to the RecvLen. If did not reach the RecvLen, it will wait for timeouts. 17.2.5 OsPortReset Prototype int OsPortReset (int Channel); Function Reset the port. This function will clear all the data in send and receive buffers of COM port. Parameters Channel 【Input】 Please Refer to the Macro definition list of communication PAX Computer Technology (Shenzhen) Co., Ltd. 146 Prolin API Programming Guide ports. Return RET_OK Success ERR_DEV_NOT_OPEN Port is not open ERR_INVALID_PARAM Invalid parameter Instruction 17.2.6 OsPortCheckTx Prototype int OsPortReset(int Channel); Function Check the remaining bytes in sendbuffer of the specified COM port. Parameters Return Channel 【Input】 Please Refer to the Macro. >=0 The data size remained in the send buffer ERR_DEV_NOT_OPEN Port is not open ERR_INVALID_PARAM Invalid parameter Instruction 17.3 POSIX Prolin opens serial POSIX interfaces for applications developers to use. The corresponding relation between device node and serial port is shown as below: Device node Serial port The corresponding module applicable models /dev/ttyAMA0 modem modem S800 /dev/ttyAMA1 wireless wireless S800/S900 /dev/ttyAMA2 PORT_COM1 COM1 S800/S900/S300/D200 /dev/ttyAMA3 PORT_PINPAD pinpad S800 /dev/ttyhost PORT_USBHOST usb S800/S900/S300/D200 /dev/ttydev PORT_USBDEV usb S800/S900/S300/D200 Concrete operations as follow: 17.3.1 Open Opens the uart, and the device name are ttyAMA0, ttyAMA1, ttyAMA2, ttyAMA3. PAX Computer Technology (Shenzhen) Co., Ltd. 147 Prolin API Programming Guide int fd; /* Open the uart with read-write access mode*/ fd = open(“/dev/ttyAMA1”, O_RDWR); if(-1 == fd){ perror (“Open uart error!”); } 17.3.2 Read Read data from communication port. char buff [1024]; int Len = 1024; int readByte = read (fd, buff, Len); 17.3.3 Write Write data to the communication port. (send) char buffer [1024]; int Length = 1024; int nByte; nByte = write (fd, buffer, Length); 17.3.4 Close Close communication port. close(fd); 17.3.5 Query the buffer data of communication port int remain; int count; /* Inquiry the number of bytes remained in send buffer */ ioctl(fd, TIOCOUTQ, &remain); /* Inquiry the number of bytes which remained in receive buffer */ ioctl(fd, TIOCINQ, &count); 17.3.6 Clear the buffer data of communication port PAX Computer Technology (Shenzhen) Co., Ltd. 148 Prolin API Programming Guide /* clear the buffer data*/ tcflush(fd, TCIOFLUSH); 17.3.7 Set the configuration parameters of communication port /* Set the baud rate, data bits, parity bits and stop bits of uart*/ int SetTermios (int fd, int nSpeed, int nBits, char cEvent, int nStop) { struct termios newtio, oldtio; /* Get configurations of the original uart */ if (tcgetattr (fd, &oldtio) != 0) { printf("Get serial error\n"); return -1; } /* Initialize the variable of new configuration */ bzero (&newtio, sizeof (newtio)); newtio.c_cflag |= CLOCAL | CREAD; newtio.c_cflag &= ~CSIZE; /* close soft flow control*/ newtio.c_iflag &= ~(ICRNL | IXON | IXOFF); /* close hard flow control*/ newtio.c_cflag &= ~CRTSCTS; /* set the data bits */ switch (nBits) { case 7: newtio.c_cflag |= CS7; break; case 8: newtio.c_cflag |= CS8; break; } /* Configurate the parity bit*/ PAX Computer Technology (Shenzhen) Co., Ltd. 149 Prolin API Programming Guide switch (cEvent) { case 'o': newtio.c_cflag |= PARENB; newtio.c_cflag |= PARODD; newtio.c_iflag |= (INPCK | ISTRIP); break; case 'e': newtio.c_iflag |= (INPCK | ISTRIP); newtio.c_cflag |= PARENB; newtio.c_cflag &= ~PARODD; break; case 'n': newtio.c_cflag &= ~PARENB; break; } /* Set the baud rate*/ switch (nSpeed) { case 1200: cfsetispeed (&newtio, B1200); cfsetospeed (&newtio, B1200); case 2400: cfsetispeed (&newtio, B2400); cfsetospeed (&newtio, B2400); break; case 4800: cfsetispeed (&newtio, B4800); cfsetospeed (&newtio, B4800); break; case 9600: cfsetispeed (&newtio, B9600); cfsetospeed (&newtio, B9600); break; case 19200: cfsetispeed (&newtio, B19200); cfsetospeed (&newtio, B19200); break; case 38400: cfsetispeed (&newtio, B38400); PAX Computer Technology (Shenzhen) Co., Ltd. 150 Prolin API Programming Guide cfsetospeed (&newtio, B38400); break; case 57600: cfsetispeed (&newtio, B57600); cfsetospeed (&newtio, B57600); break; case 115200: cfsetispeed (&newtio, B115200); cfsetospeed (&newtio, B115200); break; default: printf ("Not support the speed %d\n", nSpeed); cfsetispeed (&newtio, B9600); cfsetospeed (&newtio, B9600); return -1; } /* set the stop bits */ if (nStop == 1) newtio.c_cflag &= ~CSTOPB; else if (nStop == 2) newtio.c_cflag |= CSTOPB; /* Set the waiting time and the minimum number of characters, there is no specific request for waiting time and receive characters ,and it can be set to 0 */ newtio.c_cc[VTIME] = 0; newtio.c_cc[VMIN] = 0; /* Clear the send buffer*/ tcflush (fd, TCIFLUSH); /* Set the new configuration message */ if ((tcsetattr (fd, TCSANOW, &newtio)) != 0) { printf("Set serial error\n"); return -1; } return 0; } PAX Computer Technology (Shenzhen) Co., Ltd. 151 { This page intentionally left blank } Prolin API Programming Guide 18 MODEM In Prolin, it can use the built-in UART to send AT commands to Modem and implement the Modem communication functions; at the same time, it can encapsulate some Modem communication interfaces for the developers to use. 18.1 Return code list Table 17 Modem return code list Macro Value Description MODEM_CONNECTING 10 Dialing MODEM_CONNECTED 0 Connected MODEM_HAVE_DIALED 6 Start sending numbers (only from automatically sending mode to manually answering mode) MODEM_RECV_POOL_HAVE_DATA 8 Receive buffer is not empty (received remote data) MODEM_RECVDATA_SEND_IS_FULL 9 Receive buffer is not empty, the send buffer is full. MODEM_SEND_POOL_FULL 1 Send buffer is full. (In OsModemCheck(), the full PAX Computer Technology (Shenzhen) Co., Ltd. 153 Prolin API Programming Guide status of send buffer represents that the modem is using the send buffer, at this time, the OsModemSend() cannot be used.) MODEM_IDLE ERR_MDM_TXOVER 11 -3100 Idle Sending buffer full. (presents return error. If synchronize, it means the system is using the send buffer; If asynchronize, it means the send buffer is full. ) The paralleled line is busy. ERR_MDM_BYPASS_BUSY -3101 The hardware of NGFP S800 has no side telephone port, and also no such return value. -3102 Telephone line is not properly connected, or parallel line is occupied. ERR_MDM_NO_CARRIER -3103 Carrier wave of telephone lost. (Built synchronization chain failure) ERR_MDM_NO_ANSWER -3104 No response for dialing. ERR_MDM_CALLEE_BUSY -3105 Line busy. ERR_MDM_NO_LINE -3106 Telephone line is not connected (Line voltage is 0). ERR_MDM_CMD_BUF_FULL -3108 The excommand() buffer is full. ERR_MDM_CMD_TOO_LONG -3109 Command of excommand() is too long, exceeded 100. ERR_MDM_CMD_NOT_SUPPORT -3110 Excommand() does support the command. ERR_MDM_LINE_BUSY OTHERS PAX Computer Technology (Shenzhen) Co., Ltd. -3XXX ( -3111 ~ -3199 not Abnormal error code doesn‘t appear frequently in practice. Setting abnormal error code is for the purpose of maintainability. Details about 154 Prolin API Programming Guide ) PAX Computer Technology (Shenzhen) Co., Ltd. what error code means are not important. -3115 Calling synchronization handshake receiving process 1 error -3116 Calling synchronization handshake receiving data package error. -3117 Calling synchronization handshake receiving package type error. -3118 Calling synchronization handshake receiving process 2 error -3119 Calling communication process 1 error -3120 Calling synchronous communication chip hang up -3121 Calling synchronous communication receiving packet series number error -3122 Calling communication process 2 error -3123 Calling synchronous communication sent overload -3124 Calling communication load. -3130 Calling synchronous communication line rate is illegal. -3131 Calling communication packet 1 errors synchronous receiving synchronous receiving synchronous sent under synchronous send state 155 Prolin API Programming Guide PAX Computer Technology (Shenzhen) Co., Ltd. -3132 Calling synchronous communication sent data packets retry more than the specified time. -3133 Calling communication packets timeout -3134 Calling synchronous communication receiving the acknowledgement packet retry more than the specified time -3135 Calling synchronous communication sent stateful packet 2 error -3136 Calling synchronous communication sent stateful packet 3 error -3137 Calling synchronous communication sent stateful packet 4 error -3138 Calling synchronous communication receiving data packets retry more than the specified time -3139 Calling synchronous communication sent stateful packet 5 error -3140 Calling synchronous communication sent stateful packet 6 error -3144 Sent number automatically and not to pick up the phone timely. -3145 Called synchronization handshake sent handshake packets failed synchronous sent data 156 Prolin API Programming Guide PAX Computer Technology (Shenzhen) Co., Ltd. -3146 Called synchronization handshake receiving handshake packets failed -3147 Called synchronization handshake more than the specified time. -3148 Called synchronous communication sent stateful packet 1 error -3149 Called communication process 1 error -3150 Called synchronous communication chip hang up -3151 Called communication process 2 error -3152 Called synchronous communication receiving retry more than the specified time -3153 Called synchronous communication sent stateful packet 2 error -3154 Called communication packet error synchronous sent data -3155 Called communication process 3 error synchronous receiving -3156 Called synchronous communication receiving the packet retry more than the specified time -3157 Called synchronous communication sent stateful packet 3 error synchronous receiving synchronous receiving 157 Prolin API Programming Guide PAX Computer Technology (Shenzhen) Co., Ltd. -3160 Called connection receiving ring information error -3161 Called connection detecting the line voltage failed -3162 Called connection detecting the line voltage data format error -3163 Called connection voltage is less than the threshold -3164 Called connection timeout -3165 Called asynchronous line rate format is incorrect -3166 Called asynchronous line rate is illegal. -3167 Called connection information format is incorrectly. -3170 Called connection set instruction string 1 failed the -3171 Called connection set instruction string 2 failed the -3172 Called connection set the extended instruction string failed -3175 Calling connection instruction string 1 failed. set -3176 Calling connection instruction string 2 failed. set -3177 Calling connection instruction string 3 failed. set -3178 Calling connection instruction string 4 failed. set -3180 Calling connection instruction string 5 failed. set 158 Prolin API Programming Guide -3181 Calling asynchronous illegal -3182 Calling connection instruction string 6 failed. -3183 Calling extended failed -3185 Calling connection has no dial tone. -3186 Calling connection indicate an error. -3187 Calling connection detect the digital lines. -3188 Calling connection has no dial tone and the voltage is too low. -3189 Calling connection has other exception errors. -3192 connection line rate is set connection set instruction string Non-pre-dial-up timeout dial chip up (300s) PAX Computer Technology (Shenzhen) Co., Ltd. -3193 When FSK sends data, the DCD signal timeout -3194 When FSK sends data, the CTS signal timeout -3195 FSK sends data timeout. -3196 Called synchronous communication sent data packet format error -3197 Asynchronous communication does not support the Connect Format parameters -3198 Daemon to create thread failed 159 Prolin API Programming Guide PAX Computer Technology (Shenzhen) Co., Ltd. -3199 The process with Daemon communication failure or error -3200 Modem is using the bound uart. -3201 Socket creation failed -3202 Socket link failed -3203 Socket send failed -3204 Create semaphore failed -3205 Set the semaphore value failed -3206 Semaphore pre-empted. -3207 Semaphore cannot be released. -3208 Semaphore initialization failed -3209 Failed to get time of the day. -3210 More than 2 links are using the modem daemon -3211 Received the cancel button in the dial-up process. -3212 The request of receiving data is rejected. (Receive buffer is empty.) -3213 The command string 7 of calling connection Setting is failed. -3214 The command string 8 of calling connection Setting is failed. -3215 FSK sending is overtime, but still has data in send buffer. -3216 Invalid data length (len=0 or len>2048), will not send data. has been 160 Prolin API Programming Guide ERR_MDM_INIT -3217 Modem initialization failed. -3218 If does not implement OsModemConnect(), or implemented OsModemConnect() wrongly, then implement OsPppomLogin() or OsPppomCheck(). -3219 The Modem or ModemPPP is being used, Modem cannot be powered off. -3220 Modem does not power on. 18.2 Data structure ST_MODEM_SETUP: typedef struct { int CallMode; int CommMode; int CodeType; int CodeDuration; int CodeSpacing; int DetectLineVoltage; int DetectDialTone; int DialToneTimeout; int CommaPauseTime; char ConnectRate[20]; char ConnectFormat[20]; int ConnectTimeout; int DialTimes; int IdleTimeout; PAX Computer Technology (Shenzhen) Co., Ltd. 161 Prolin API Programming Guide int Pppom; int Reserved[9]; }ST_MODEM_SETUP; Table 18 Variable definition of ST_MODEM_SETUP CallMode MODEM_PRE_DIAL Caller pre-dial MODEM_DIAL Caller dial MODEM_WAIT_CALL Called/Answered the call MODEM_COMM_SYN C synchronous MODEM_COMM_ASY NC asynchronous MODEM_CODE_DTMF DTMF(Dual Tone Multi Frequency) dialing MODEM_CODE_PULS E1 Pulse dialing 1(Pulse rate 10/s; Intermittent proportion 1.6:1;Signal interval>=500ms) MODEM_CODE_PULS E2 Pulse dialing 2(Pulse rate 10/s; Intermittent proportion 2:1; Signal interval >=600ms) Other values Reserved CommMode CodeType CodeDuration The duration of two-tone dialing a single number (Unit:10ms,valid range 5~25) CodeSpacing The interval time between two numbers of two-tone dial-up. It cannot be set to any value in 93011 chip, and it is not applicable to S800. (Unit:10ms, valid range 5~25) TRUE DetectLineVoltage DetectDialTone Detect the parallel telephone occupation (Caller dialing, No assigned number switch to manual answer mode) FALSE Doesn‘t not detect the parallel telephone occupation (Caller dialing, if there is no assigned number, switch to manual answer mode) TRUE Dial tone detection. Refer to the instruction of DailTone Timeout. PAX Computer Technology (Shenzhen) Co., Ltd. 162 Prolin API Programming Guide Does not detect dial tone. FALSE DialToneTimeout If the 8th bit of DetectDialTone is 1(0x80), while set is called, it will not postback in 8s and the drive will send 15 to client, or the drive will postback 15 to client. Dial tone detection: The longest time to wait for the dial tone. Exit waiting when the dial tone has been detected during this time. Dial tone not detected: The waiting time for dial tone when hang up machine. Unit: 100ms, both the minimum value and default value are 20, valid range is 20~50. In both cases, waits 450 to 500ms to start starts the timer after hanging up the machine. CommaPauseTime ―,‖wait time when dial outside line (Unit: 100ms). This value will be set according to the actual application environment. It is better to keep interface of manually setting in the application. (Range is 0~255. The range is not applicable to S800) The valid range of S800 is 1~26s (Because of the modem patch, it is inconsistent with the Datasheet) ConnectRate[20] The rate of connection and communication(Expressed as a string ): ―1200‖//1200 bps fast connect ―1200,V22‖//1200 bps normal connect ―1200,V23C‖//1200 bps for V.23C(FSK) ―1200,B202‖//1200 bps for Bell 202(FSK) ―2400,FC‖//2400 bps fast connect ―2400‖//2400 bps normal connect ―4800‖//4800 bps ―7200‖//7200 bps PAX Computer Technology (Shenzhen) Co., Ltd. 163 Prolin API Programming Guide ―9600‖//9600 bps ―12000‖//12000 bps ―14400‖//14400 bps ―19200‖//19200 bps ―24000‖//24000 bps ―26400‖//26400 bps ―28800‖//28800 bps ―31200‖//31200 bps ―33600‖//33600 bps ―48000‖//48000 bps ―56000‖//56000 bps For null string "\ 0"and synchronous communication, the system will select ―1200‖ by default. For asynchronous communication, the system will by default select the maximum rate that the chip can support. S800 supports the baud rate. Asynchronous: ―1200‖//1200 bps ―1200,V23C‖//1200 bps for V.23C(FSK) ―1200,B202‖//1200 bps for Bell 202(FSK) ―2400‖//2400 bps ―4800‖//4800 bps ―7200‖//7200 bps ―9600‖//9600 bps ―12000‖//12000 bps PAX Computer Technology (Shenzhen) Co., Ltd. 164 Prolin API Programming Guide ―14400‖//14400 bps ―19200‖//19200 bps ―24000‖//24000 bps ―26400‖//26400 bps ―28800‖//28800 bps ―31200‖//31200 bps ―33600‖/33600 bps ―48000‖//48000 bps ―56000‖//56000 bps Synchronous: ―1200‖//1200 bps ―1200,V22‖//1200 bps normal connect ―2400,FC‖//2400 bps fast connect ―2400‖//2400 bps ―9600‖//9600 bps ConnectFormat[20 Format of connection and communication(Expressed as a string): ―8, n, 1‖ ―8, e, 1‖ ―8, o, 1‖ ―7, e, 1‖ ―7, o, 1‖ For null string "\ 0", the system will select―8, n, 1‖ by default. For Synchronous communication, the system will select―8, n, 1‖ automatically. ConnectTimeout Timeouts of waiting for connection,【unit: s】,(valid range 0~300) PAX Computer Technology (Shenzhen) Co., Ltd. 165 Prolin API Programming Guide DialTimes The total number of dial-up cycle (convert 0 to 1 if it is 0). Dialing all the numbers in a dial number string is one cycle (valid range is 1~255). IdleTimeout There is no application-layer data exchange in the specified time. MODEM then will hang up. Use 10s as a unit., no timeout if it is 0. The maximum timeout is 900s.This value is invalid to Modem PPP. Pppom TRUE Modem PPP communication FALSE Common communication Reserved. Reserved[9] 18.3 OsModemOpen Prototype int OsModemOpen(void); Function Switches on the Modem device. Parameters Return Instruction None RET_OK Success ERR_DEV_NOT_EXIST Device does not exist. ERR_DEV_BUSY Device is busy. ERR_NO_PORT No communication port. Other functions can be operated only after opening the device successfully. It should call the OsModemSwitchPower() to power on the device before using the Modem. 18.4 OsModemClose Prototype void OsModemClose(void); Function Switches off the Modem device. Parameters None Return None Instruction This function can only close the modem that is opened by the local application. When the modem device is not open, this function can‘t do any operation. 18.5 OsModemSwitchPower Prototype int OsModemSwitchPower(int OnOff); Function Manages the Modem Power. Parameters int OnOff PAX Computer Technology (Shenzhen) Co., Ltd. OnOff=1, power on, 166 Prolin API Programming Guide OnOff=0, power off. Return Instruction RET_OK Success -3219 The Modem or ModemPPP is being used, Modem cannot be power off. -3220 Modem does not power on. 1. 2. 3. It should power on the Modem before using Modem or ModemPPP. This function is independent of the interface functions in Modem module. It will not automatically perform OsModemClose() when Modem module is powered off. 18.6 OsModemConnect int OsModemConnect(const ST_MODEM_SETUP *Setup, Prototype const unsigned char *TelNo); Function Sets the communication link function, for both calling and being called. Setup【Input】 Modem parameter. While mdm_setup==NULL, default dialing parameter will be used. Default dialing mode includes: Synchronous, 1200, DTMF, connection timeout for 10 seconds, idle hang up for 60 seconds. TelNo【Input】 Telephone number. RET_OK Success ERR_MDM_BYPASS_BUSY The paralleled line is busy. ERR_MDM_LINE_BUSY Telephone line is not properly connected, or parallel line is occupied. ERR_MDM_NO_ANSWER No response for dialing. ERR_MDM_CALLEE_BUSY Line is busy. ERR_MDM_NO_LINE Telephone line is not connected (Line voltage is 0). ERR_MDM_NO_CARRIER Carrier wave of telephone lost. ERR_INVALID_PARAM Invalid parameter. ERR_MDM_CANCEL_KEY _DOWN Press CANCEL key while dialing. ERR_DEV_NOT_OPEN Device is not open. Parameters Return 1. Instruction The function can also be used to set Modem mode to being called. 2. Telephone icon will be controlled by a program. It shows hang-up icon while connecting; it shows pickup icon when communication is established, or during switching time of pre-dial after hang-up. PAX Computer Technology (Shenzhen) Co., Ltd. 167 Prolin API Programming Guide 3. 4. It needs to call the OsModemCheck() to query the result of pre-dial. It must call OsModemConnect() before using the ModemPPP, sets ST_MODEM_SETUP.Pppom=1, and it doesn‘t need to call OsModemOpen (), then calls OsPppomLogin(). Meanings of telephone symbols: 0-9,*, #,A~D — Telephone numbers , — Dialing delay ; — Transmitting next telephone number . — End of numbers, which is used to keep connected with application after sending numbers .. — End of extension numbers, which is used to switch to manual receiving after sending numbers. 18.7 OsModemCheck Prototype int OsModemCheck(void); Function Checks the status of Modem and telephone line. Parameters None MODEM_CONNECTING Dialing MODEM_CONNECTED Connected MODEM_IDLE Idle ERR_MDM_BYPASS_BUSY The parallel line is busy. ERR_MDM_LINE_BUSY Telephone line is not properly connected, or parallel line is occupied. ERR_MDM_NO_ANSWER No response for dialing. ERR_MDM_CALLEE_BUSY Line busy. ERR_MDM_NO_LINE Telephone line is not connected (Line voltage is 0). ERR_MDM_NO_CARRIER Carrier wave of telephone lost. ERR_MDM_RECVPOOL_N OT_EMPTY Receive buffer is not empty(received remote data) ERR_MDM_RECVPOOL_SE NDPOOL_BOTH_NOT_EMP TY Receive buffer is not empty (received remote data), and the send buffer is sending data. ERR_DEV_NOT_OPEN Device is not open. Return 1. Instruction 2. This function can be used to check whether communication has been established or not by the pre-dial. After calling OsModemOpen(), OsModemHangup() or OsModemClose(), the status of the last Modem dial will become: MODEM_IDLE. PAX Computer Technology (Shenzhen) Co., Ltd. 168 Prolin API Programming Guide 18.8 OsModemExCmd int OsModemExCmd(const char *Cmd, char *Rsp, Prototype int *RespLen, int TimeoutMs); Function Sets additional AT control command for OsModemConnect() to control the connection behavior of Modem dialing. 【Input】 Input AT control command. Cmd Parameters Return Rsp 【Output】 Contents of response data. RespLen 【Output】 Length of response data. TimeoutMs Waiting time for response.(unit:ms) RET_OK Success ERR_INVALID_PARAM Invalid parameter. ERR_MDM_CMD_BUF_ FULL Command buffer overflow. ERR_MDM_CMD_TOO_ LONG Command is too long. ERR_MDM_CMD_NOT_ SUPPORT Does not support the command. (command that begin with AT,S3,S7,WT=) ERR_DEV_NOT_OPEN Device is not open. 1. Instruction 2. 3. The function is needed to be called before OsModemConnect(), and it is only valid for the entire process of OsModemConnect(). While the function is executing, it will automatically hang up current dialing or communication process. The function can be called 100 times continuously. If it is more than 100, the exceeding callings will be discarded and report error. 1. Maximum 100 bytes of string can be inputted for each calling. If it is more than 100 bytes, the entire control command will be discarded and report error. 2. Every input of control command has to be AT control command supported by this Modem chip. Otherwise, it will lead to OsModemConnect( ) failure. PAX Computer Technology (Shenzhen) Co., Ltd. 169 Prolin API Programming Guide 18.9 OsModemHangup Prototype void OsModemHangup(void); Function Hangs up Modem or terminates Modem dialing. Parameters None Return None Instruction If dialing the number again right after hanging up, the Modem will wait and start redialing after 3 seconds in order to allow PABX finish hanging up and transmitting dialing tone. 18.10OsModemSend int OsModemSend(const void *SendBuf, Prototype int SendLen); Function Parameters Return Instruction Sends packets out through Modem. SendBuf【Input】 Pointer of packets, which will be sent SendLen Length of packets, which will be sent (bytes) RET_OK Success ERR_NOT_CONNE CT Not connected. ERR_MDM_TXOVE R Send buffer is full. ERR_MDM_NO_CA RRIER No carrier waves.(Disconnected) ERR_INVALID_PAR AM Invalid parameter ERR_DEV_NOT_OP EN Device is not open. It can send 2048 bytes each time at most. Receiving and sending data of synchronous called are up to 2053 bytes, because there are more than 5 control characters. 18.11OsModemRecv int OsModemRecv(void *RecvBuf, Prototype int BufSize, int Timeout); PAX Computer Technology (Shenzhen) Co., Ltd. 170 Prolin API Programming Guide Function Receives packets by MODEM. RecvBuf Parameters Return BufSize Size of RecvBuf (<=2048bytes) Timeout Timeouts【ms】 >= 0 The actual number of receiving data. ERR_NOT_CONNECT Not connected. ERR_MDM_NO_CARRIE R No carrier waves.(Disconnected) ERR_INVALID_PARAM Invalid parameter ERR_DEV_NOT_OPEN Device is not open. 1. 2. 3. Instruction Pointer of the packets that have been received. 【Output】 [Buffer size can be defined according to the requirements of different cases.] 4. 5. 6. 7. It can receive 2048 bytes each time at most. Receiving and sending data of synchronous called are up to 2053 bytes, because it has 5 more control characters. If the size of actual data is not larger than the specified size of receive buffer, it will return immediately. While receiving data, if there‘s a line error, it will immediately return the corresponding error code. For SDLC synchronous communication, it will immediately return after receiving a packet.(even if the received packet length is less than the BufSize) For asynchronous communication, it will immediately return after receiving byte data of BufSize, or wait until the timeout. For synchronous receiving, it will receive a complete frame each time, and it is not limited by BufSize. For FSK, the timeout does not work. 18.12OsPppomLogin int OsPppomLogin(const char *Name const char *Password, Prototype long Auth, int TimeOutMs); Function Establishes the Modem PPP network link. Parameters Name User name; Length<=50 bytes; 【Input】 It cannot be NULL. For the 96169 background of ChinaTelecom, it can enter any user name, and it must enter a character at PAX Computer Technology (Shenzhen) Co., Ltd. 171 Prolin API Programming Guide least. Password Password; Length<=50 bytes;; 【Input】 It cannot be NULL. For the 96169 background of ChinaTelecom, it can enter any password, and it must enter a character at least. Authentication Algorithms; Currently the following Authentication algorithms are supported PPP_ALG_PAP 0x1 PAP Authentication Algorithm PPP_ALG_CHAP 0x2 CHAP Authentication Algorithm PPP_ALG_MSCH APV1 0x4 MSCHAPV1 Authentication Algorithm PPP_ALG_MSCH APV2 0x8 MSCHAPV2 Authentication Algorithm PPP_ALG_ALL 0xff All Authentication Algorithms Auth At least one type of authentication algorithm has to be selected, more than one authentication algorithm will also be allowed by using (+) or (|), for example, PPP_ALG_PAP| PPP_ALG_CHAP. If the algorithm is unknown, fill with parameter PPP_ALG_ALL. Timeouts【unit:ms】; TimeOutMs Return PPP_LOGINING In process RET_OK The link established successfully. ERR_INVALID_PAR AM Invalid parameter ERR_NET_PASSWD wrong password ERR_NET_SERVER _BUSY Server is busy, communication failed. 1. Instruction The valid range is 0~3600000. If timeout is <0, it will automatically be set to 0. If more than 360000. It will automatically be set to 3600000. 2. 3. 4. Before using this function, call OsModemConnect() first and set the ST_MODEM_SETUP.Pppom to 1, also it doesn‘t need to call OsModemOpen(); TimeOutMs=0 means return immediately, Call OsPppomCheck() to check the link status The login time may vary from settings to settings of ST_MODEM_SETUP parameters. The modem chip of S800 supports up to 33600 asynchronous PAX Computer Technology (Shenzhen) Co., Ltd. 172 Prolin API Programming Guide 5. 6. 7. baud rate, dial-up while the setting is less than or equal to 33600, there will be a low re-training rate and high success rate. For the 96169 background (Guidway A8010), if a re-training is occurred and the time period after sending number is more than 20 seconds, then the background communication will no longer confirm to ppp protocol, which will end up in failure. After the link has been set up successfully, it can communicate through the IP network communication function. In the process of dialing, when users want to hang up by pressing the cancel button, the methods of operation are as follows: Application porting a thread and take the key, if it is the cancel key, perform OsPppomLogin ("a", "a", 1, -1), the first 3 parameters should be filled in accordance with the requirements, and the fourth parameter must be set to -1, then ModemPPP will hang-up and automatically logout. 18.13OsPppomCheck Prototype int OsPppomCheck(void); Function Checks the link status of Modem network. Parameters None PPP_LOGOUTING Return In disconnection state PPP_LOGINING In process RET_OK Established the link successfully. ERR_NET_PASSWD wrong password ERR_NET_LOGOUT Already called OsPppomLogout() to disconnect the link. ERR_NET_IF Link has been disconnected. Instruction 18.14OsPppomLogout Prototype int OsPppomLogout(void); Function Exits network, disconnect the Modem PPP link. Parameters None Return RET_OK Success Instruction PAX Computer Technology (Shenzhen) Co., Ltd. 173 { This page intentionally left blank } Prolin API Programming Guide 19 Network Communication Prolin uses the unified TCP/IP stack to manage different physical connections. For the network communications programming, it provides a standard socket programming (socket). 19.1 TCP programming /* Server code in C */ #include #include #include #include #include #include #include #include int main(void) { struct sockaddr_in stSockAddr; int SocketFD = socket(PF_INET, SOCK_STREAM, IPPROTO_TCP); PAX Computer Technology (Shenzhen) Co., Ltd. 175 Prolin API Programming Guide if(-1 == SocketFD) { perror("cannot create socket"); exit(EXIT_FAILURE); } memset(&stSockAddr, 0, sizeof(stSockAddr)); stSockAddr.sin_family = AF_INET; stSockAddr.sin_port = htons(1100); stSockAddr.sin_addr.s_addr = INADDR_ANY; if(-1 == bind(SocketFD,(struct sockaddr *)&stSockAddr, sizeof(stSockAddr))) { perror("error bind failed"); close(SocketFD); exit(EXIT_FAILURE); } if(-1 == listen(SocketFD, 10)) { perror("error listen failed"); close(SocketFD); exit(EXIT_FAILURE); } for(;;) { int ConnectFD = accept(SocketFD, NULL, NULL); if(0 > ConnectFD) { perror("error accept failed"); close(SocketFD); exit(EXIT_FAILURE); } /* perform read write operations ... read(ConnectFD,buff,size)*/ PAX Computer Technology (Shenzhen) Co., Ltd. 176 Prolin API Programming Guide if (-1 == shutdown(ConnectFD, SHUT_RDWR)) { perror("cannot shutdown socket"); close(ConnectFD); exit(EXIT_FAILURE); } close(ConnectFD); } return EXIT_SUCCESS; } /* Client code in C */ #include #include #include #include #include #include #include #include int main(void) { struct sockaddr_in stSockAddr; int Res; int SocketFD = socket(PF_INET, SOCK_STREAM, IPPROTO_TCP); if (-1 == SocketFD) { perror("cannot create socket"); exit(EXIT_FAILURE); } memset(&stSockAddr, 0, sizeof(stSockAddr)); stSockAddr.sin_family = AF_INET; stSockAddr.sin_port = htons(1100); Res = inet_pton(AF_INET, "192.168.1.3", &stSockAddr.sin_addr); PAX Computer Technology (Shenzhen) Co., Ltd. 177 Prolin API Programming Guide if (0 > Res) { perror("error: first parameter is not a valid address family"); close(SocketFD); exit(EXIT_FAILURE); } else if (0 == Res) { perror("char string (second parameter does not contain valid ipaddress)"); close(SocketFD); exit(EXIT_FAILURE); } if (-1 == connect(SocketFD, (struct sockaddr *)&stSockAddr, sizeof(stSockAddr))) { perror("connect failed"); close(SocketFD); exit(EXIT_FAILURE); } /* perform read write operations ... */ shutdown(SocketFD, SHUT_RDWR); close(SocketFD); return EXIT_SUCCESS; } 19.2 UDPprogramming #include #include #include #include #include #include PAX Computer Technology (Shenzhen) Co., Ltd. 178 Prolin API Programming Guide #include /* for close() for socket */ #include int main(void) { int sock = socket(PF_INET, SOCK_DGRAM, IPPROTO_UDP); struct sockaddr_in sa; char buffer[1024]; ssize_t recsize; socklen_t fromlen; memset(&sa, 0, sizeof sa); sa.sin_family = AF_INET; sa.sin_addr.s_addr = INADDR_ANY; sa.sin_port = htons(7654); fromlen = sizeof(sa); if (-1 == bind(sock,(struct sockaddr *)&sa, sizeof(sa))) { perror("error bind failed"); close(sock); exit(EXIT_FAILURE); } for (;;) { printf ("recv test....\n"); recsize = recvfrom(sock, (void *)buffer, sizeof(buffer), 0, (struct sockaddr *)&sa, &fromlen); if (recsize < 0) { fprintf(stderr, "%s\n", strerror(errno)); exit(EXIT_FAILURE); } printf("recsize: %z\n ", recsize); sleep(1); printf("datagram: %.*s\n", (int)recsize, buffer); } } #include #include PAX Computer Technology (Shenzhen) Co., Ltd. 179 Prolin API Programming Guide #include #include #include #include #include #include #include int main(int argc, char *argv[]) { int sock; struct sockaddr_in sa; int bytes_sent; char buffer[200]; strcpy(buffer, "hello world!"); sock = socket(PF_INET, SOCK_DGRAM, IPPROTO_UDP); if (-1 == sock) /* if socket failed to initialize, exit */ { printf("Error Creating Socket"); exit(EXIT_FAILURE); } memset(&sa, 0, sizeof sa); sa.sin_family = AF_INET; sa.sin_addr.s_addr = inet_addr("127.0.0.1"); sa.sin_port = htons(7654); bytes_sent = sendto(sock, buffer, strlen(buffer), 0,(struct sockaddr*)&sa, sizeof sa); if (bytes_sent < 0) { printf("Error sending packet: %s\n", strerror(errno)); exit(EXIT_FAILURE); } close(sock); /* close the socket */ return 0; } PAX Computer Technology (Shenzhen) Co., Ltd. 180 Prolin API Programming Guide 20 Network Configuration Prolin provides the interface for network configuration, including ARP settings, Ping services, DNS configuration, network card configuration, DHCP service, routing settings and PPPoE service etc. 20.1 Return code list Table 19 Network Configuration return code list Macro Value Description -3301 IP server error. ERR_NET_SERVER_BUSY -3302 IP server is busy; it can only provide service for at most 5 applications at a time. ERR_NET_NO_ROUTE -3305 Haven‘t configured the router ERR_NET_FULL -3306 Connection is full; the application can set up to 20 connections at a time. ERR_NET_IF -3307 Network interface link is unavailable (The link has not set up or there is no corresponding device.) ERR_NET_SESS_BROKEN -3308 TCP / UDP session connection is ERR_NET_SERVER_BAD PAX Computer Technology (Shenzhen) Co., Ltd. 181 Prolin API Programming Guide broken and unavailable. ERR_NET_PASSWD -3309 Password is incorrect. ERR_NET_LOGOUT -3310 Application logout initiatively. ERR_NET_INIT -3311 Initialization failed. ERR_NET_DHCP_DISCOVER -3312 Has not found DHCP Server. ERR_NET_DHCP_OFFER -3313 DHCP cannot be assigned the IP address. ERR_NET_DHCP_START -3314 DHCP has not started. ERR_NET_DNS -3315 DNS cannot analyze the corresponding domain. ERR_NET_SERV_USING -3316 The port specified by the server is in use. ERR_NET_NODNServer -3317 Has not configured the domain name server ERR_NET_LINKDOWN -3318 Link is disconnected by the server. ERR_NET_CONN -3319 Cannot connect to the specified server. ERR_NET_TIMEOUT -3320 Connection timeout ERR_NET_PPP -3321 PPP connection error ERR_NET_SERV -3322 Has not found the PPPoE server ERR_NET_AGAIN -3323 The request resource wasn‘t found, please try again. ERR_NET_AUTH -3324 Has no authority to access to the RADIUS server. 1 NET_DOING Some related operations are being done.(such as PPP login, DHCP) 20.2 Data Definition 20.2.1 Physical channel list Table 20 Physical Channel List PAX Computer Technology (Shenzhen) Co., Ltd. 182 Prolin API Programming Guide Macro Description NET_LINK_ETH Ethernet NET_LINK_WL Wireless, including GPRS, CDMA, TDSCDM A NET_LINK_WIFI WIFI NET_LINK_PPPOE ADSL link NET_LINK_MODEM Modem PPP link All of the macro values listed in the above table are positive integers, and they are greater than 0. For more Details, refer to osal.h. 20.3 Network Configuration interface 20.3.1 OsNetAddArp int OsNetAddArp(int NetLink, Prototype const char *Addr, const char MAC[6]); Function Adds the IP address to MAC address mapping table, which is static. NetLink Parameters Return Physical channel can only be set to Ethernet and WIFI; NET_LINK_ETH Ethernet; NET_LINK_WIFI WIFI Addr【Input】 IP address. The format is ―XXX.XXX.XXX.XXX‖, and XXX ranges from 0 to 255. For example: ―192.168.0.1‖; Cannot be NULL. MAC【Input】 the MAC address corresponding to the IP address; Cannot be NULL, the space has 6 bytes. RET_OK Success <0 Failed, the value is error code. Instruction PAX Computer Technology (Shenzhen) Co., Ltd. 183 Prolin API Programming Guide 1. Static ARP table is used to resist the attack from ARP Cheat, 2. If there is no static ARP table, the system will dynamically obtain, and it doesn’t need to be configured by the application. 20.3.2 OsNetPing int OsNetPing(const char *Addr, Prototype int TimeOutMs); Function Pings a specific machine to check the status of network connection. Addr【Input】 The IP address of target device; Format is ―XXX.XXX.XXX.XXX‖, XXX represents 0~255, for example:‖192.168.0.3‖; TimeOutMs Timeout【unit:ms】, the valid range is 3000~3600000. RET_OK Success ERR_NET_IF Link is unavailable, means the link has not been set correctly (or has been disconnected). ERR_INVALID_P ARAM Invalid parameter ERR_TIME_OUT Timeout Parameters Return Instruction Use the default route to do the communication, and searching the route can be done by calling OsNetGetRoute(). 20.3.3 OsNetPingEx int OsNetPingEx(const char *Addr, Prototype Function int TimeOutMs, int Size); Pings a specific IP address to check the status of the network connection. Addr Parameters Return IP address of the target device. 【Input】 The format is ―XXX.XXX.XXX.XXX‖, the range of XXX is 0~255, for example ―192.168.0.3‖. TimeOutMs 【Input】 Timeout 【 unit:ms 】 the 3000~3600000. Size 【Input】 The size of the data, it can‘t exceed 1024 bytes. >0 Success, the time takes to ping ERR_NET_IF Link is unavailable, means the link has not been PAX Computer Technology (Shenzhen) Co., Ltd. valid range is 184 Prolin API Programming Guide set correctly (or has been disconnected). Usage ERR_INVALID_ PARAM Invalid parameter ERR_TIME_OU T Timeout Use the default route to do the communication, and searching the route can be done by calling OsNetGetRoute(). 20.3.4 OsNetDns int OsNetDns(const char *Name, char *Addr, Prototype int TimeOutMs); Function Analyzes the IP address corresponding to the domain name and stores the results in Addr parameter. Name【Input】 Information of domain name, for example: [www.sina.com.cn]. The maximum length cannot be NULL and cannot exceed255 characters. Addr【Output】 It is an output parameter; Use to store the IP address, mapped by the domain name, the format is ―XXX.XXX.XXX.XXX‖, XXX represents 0~255,e.g:‖192.168.0.3‖; It cannot be NULL; there are at least 16 bytes in the space. TimeOutMs Timeout【unit:ms】, the valid range is 1000~3600000 RET_OK Success ERR_NET_IF The Link is unavailable, means the link has not been set correctly (or has been disconnected). ERR_INVALID_P ARAM Invalid parameter ERR_TIME_OUT Timeout. ERR_NET_DNS The domain server cannot analyze the corresponding domain, or it does not exist. Parameters Return Instruction Use the default route to do the communication, and searching the route can be done by calling OsNetGetRoute(). PAX Computer Technology (Shenzhen) Co., Ltd. 185 Prolin API Programming Guide 20.3.5 OsNetSetConfig int OsNetSetConfig(int NetLink, const char *Addr, const char *Mask, Prototype const char *Gateway, const char *DNSServer); Function Configures the network information. NetLink Physical channel can only be set to Ethernet and WIFI; NET_LINK_ETH Ethernet; NET_LINK_WIFI WIFI Addr【Input】 The address used by POS Format is ―XXX.XXX.XXX.XXX‖, XXX represents 0~255; e.g: ―192.168.0.3‖; If it is ― ‖ or NULL, means do not change the previous configuration; Mask【Input】 Mask code used by POS; Format is ―XXX.XXX.XXX.XXX‖; e.g.: ―255.255.255.0‖; If it is ― ‖ or NULL, means do not change the original configuration; Gateway【Input】 Address of the default gateway Format is ―XXX.XXX.XXX.XXX‖, XXX represents 0~255; e.g.: ―192.168.0.1‖; if it is ― ‖ or NULL, means do not change the previous configuration; DNSServer【Input】 DNS server address Format is ―XXX.XXX.XXX.XXX‖, XXX represents 0~255; e.g.: ―192.168.0.1‖; if it is ― ‖ or NULL, means do not change the previous configuration; RET_OK Success ERR_NET_IF The link is unavailable, means the link has not been set correctly (or has been disconnected). ERR_INVALID_PARAM Invalid parameter. Parameters Return Instruction 1. After calling successfully, the system will stop the DHCP function. PAX Computer Technology (Shenzhen) Co., Ltd. 186 Prolin API Programming Guide 2. The function does not check the matching relationship between Addr, Mask and Gateway; it only checks the validity of their formats. 3. Wireless link, PPPoE, and ModemPPP can only be dynamically allocated and cannot be configured by this interface. 4. After setting the configuration successfully, this link will be set to be the default route. 20.3.6 OsNetGetConfig int OsNetGetConfig(int NetLink, char *Addr, char *Mask, Prototype char *Gateway, char *DNSServer); Function Gets the network configuration information, such as IP, subnet mask, gateway and DNS. NetLink Physical channel can only be set to Ethernet and WIFI; NET_LINK_ETH Ethernet; NET_LINK_WIFI WIFI(Wireless Local Area Network) Addr【Output】 The address used by POS is an Output parameter. There are at least 16 bytes in the space. The format is ―XXX.XXX.XXX.XXX‖, XXX represents 0~255; e.g.: ―192.168.0.3‖; It can be NULL. Mask【Output】 Mask code used by POS is an Output parameter. There are at least 16 bytes in the space. Format is ―XXX.XXX.XXX.XXX‖; e.g.: ―255.255.255.0‖; It can be NULL. Gateway 【Output】 Address of the default gateway is an Output parameter. There are at least 16 bytes in the space. Format is ―XXX.XXX.XXX.XXX‖, XXX represents 0~255; e.g.: ―192.168.0.1‖; It can be NULL. DNSServer 【Input】 DNS server address is an Output parameter. There are at least 16 bytes in the space. Format is ―XXX.XXX.XXX.XXX‖, XXX represents 0~255; e.g.: ―192.168.0.1‖; It can be NULL. Parameters PAX Computer Technology (Shenzhen) Co., Ltd. 187 Prolin API Programming Guide Return RET_OK Success ERR_NET_IF The link is unavailable, means the link has not been set correctly. Instruction When Addr, Mask, Gateway and DNS Server return the string as “ ”, that means there is no configuration. 20.3.7 OsNetStartDhcp Prototype int OsNetStartDhcp(int NetLink); Function Starts the DHCP function to obtain a dynamically assigned address. Parameters Return Instruction NetLink Physical channel can only be set to Ethernet and WIFI; NET_LINK_ETH Ethernet; NET_LINK_WIFI WIFI(Wireless Local Area Network) RET_OK Success ERR_NET_IF Has not configured Ethernet or WIFI. 1. This interface is only used to start the DHCP function, does not wait for assigning addresses. 2. It can check whether assigning address is completed by calling the OsNetCheckDhcp () or not. 3. After acquiring the address successfully, this link is set to be the default route. Before starting the DHCP, it should close all the connections because these connections may not be able to communicate properly in the subsequent activity. 20.3.8 OsNetCheckDhcp Prototype int OsNetCheckDhcp(int NetLink); Function Check DHCP status. Parameters Return NetLink Physical channel can only be set to Ethernet and WIFI; NET_LINK_ETH Ethernet; NET_LINK_WIFI WIFI(Wireless Local Area Network) NET_DOING DHCP is doing the dynamic allocation. RET_OK Dynamic allocation has been done. PAX Computer Technology (Shenzhen) Co., Ltd. 188 Prolin API Programming Guide ERR_NET_DHCP _DISCOVER DHCP Server has not been found. ERR_NET_DHCP _OFFER DHCP cannot be assigned the IP address. ERR_NET_DHCP _START DHCP does not start. Instruction 20.3.9 OsNetStopDhcp Prototype void OsNetStopDhcp(int NetLink); Function Stops DHCP function. Parameters Return NetLink None 1. Instruction 20.3.10 Physical channel can only be set to Ethernet and WIFI; NET_LINK_ETH Ethernet; NET_LINK_WIFI WIFI(Wireless Local Area Network) 2. After the DHCP function stops, the application needs to re-configure the network using OsNetSetConfig (); After DHCP, the system will regularly update the configuration information, when the update fails, it will cause the network become unusable. OsNetSetRoute Prototype int OsNetSetRoute(int NetLink); Function Set system default route. Parameters Return NetLink Physical channel, please refer to Physical channel list RET_OK Success, the new route came into effect. ERR_INVALID _PARAM ERR_NET_IF Invalid parameter. This link has not been set up. 1. If only one link needs to set up, then it is not necessary to use this interface to do the setup. 2. When there are several links have been set up, it is allowed to use this function to switch the default router. Instruction 3. It is allowed to switch only when the default route has been set up, otherwise return ERR_NET_IF. 4. If switch the router in the process of communication, it will cause a communication failure. PAX Computer Technology (Shenzhen) Co., Ltd. 189 Prolin API Programming Guide 20.3.11 OsNetGetRoute Prototype int OsNetGetRoute(void); Function Reads the system default route. Parameters None >0 Physical channel, please refer to Physical channel list . ERR_NET_NO_ROUTE There is no default route. Return This function will return ERR_NET_NO_ROUTE in following situations: 1. There is no link has been set up. 2. Any link that has been set up successfully will be configured as the Instruction default route. When the last used link is being logged off, it will delete this route. At this time, call OsNetSetRoute to reconfigure . 20.3.12 OsPppoeLogin int OsPppoeLogin(const char *Name, const char *Password, Prototype int TimeOutMs); Function PPPoE link Login. Name【Input】 Parameters User name; Cannot exceed 50 bytes Cannot be NULL, if there is no password, use an null string ― ‖; Password; Password【Input】 Cannot exceed 50 bytes Cannot be NULL, if there is no password, use ― ‖; Timeout,【unit:ms】 TimeOutMs The valid range is 0~3600000; Return Instruction 20.3.13 Prototype NET_DOING Logging RET_OK Success <0 Failed After the link has been set up successfully, this link will be set to be the default route. OsPppoeCheck int OsPppoeCheck(void); PAX Computer Technology (Shenzhen) Co., Ltd. 190 Prolin API Programming Guide Function Parameters Return Checks the PPPoE link. None NET_DOING Logging RET_OK The link has been successfully established. <0 The link has been disconnected. Instruction 20.3.14 OsPppoeLogout Prototype void OsPppoeLogout(void); Function Disconnects the PPPoE link. Parameters None Return None Instruction PAX Computer Technology (Shenzhen) Co., Ltd. 191 { This page intentionally left blank } Prolin API Programming Guide 21 GPRS/CDMA Prolin provides supports for GPRS and CDMA, for the utility and configuration of these wireless modules. It also provides a series of APIs for application developers to use. 21.1 Return code list Table 21 GPRS/CDMA return code list Macro Value Description PPP_LOGINING 1 PPP is logging in. PPP_LOGOUTING 2 PPP is logging out. ERR_WL_POWER_ONING -3501 Module is powered on, please wait. ERR_WL_POWER_OFF -3502 Module is powered off. ERR_WL_NOT_INIT -3503 Has not called OsWlInit() to initialize and cannot work normally. ERR_WL_NEEDPIN -3504 SIM card needs PIN. ERR_WL_RSPERR -3505 Module response error. ERR_WL_NORSP -3506 Module has no response. PAX Computer Technology (Shenzhen) Co., Ltd. 193 Prolin API Programming Guide ERR_WL_NEEDPUK -3507 SIM card needs PUK. ERR_WL_WRONG_PIN -3508 PIN of SIM card error. ERR_WL_NOSIM -3509 SIM card not inserted ERR_WL_NOREG -3510 Cannot register on the GPRS network. ERR_WL_AUTO_RST -3511 Module reset automatically. ERR_WL_BUF -3512 Module memory error. ERR_WL_GET_SIGNAL -3513 Getting the signal, please wait for 3s. ERR_WL_NOTYPE -3514 Module cannot be recognized. ERR_WL_PPP_ONLINE -3515 PPP is on line, and it cannot be sleeping. ERR_WL_ERR_BUSY -3516 Module is busy. ERR_WL_SLEEP_ONING -3517 Module is in sleeping. ERR_WL_SLEEP_FAIL -3518 Sleeping failed. ERR_WL_SIM_FAILURE -3519 SIM card Operation failed. ERR_WL_NO_SIMSOCKET -3520 The machine does not have a SIM card slot. ERR_WL_ONLY_ONE_SIMSOCKET -3521 The machine only has one SIM card slot. ERR_WL_SIMSOCKET_CONFIGFILE -3522 The ro.fac.simsocket in config file is incorrectly set. 21.2 Wireless module interface 21.2.1 OsWlLock Prototype int OsWlLock(void); Function Opens the wireless module. Parameters Return None RET_OK PAX Computer Technology (Shenzhen) Co., Ltd. Open successfully. 194 Prolin API Programming Guide Instruction ERR_DEV_BUSY Device is already in use. ERR_DEV_NOT_ EXIST ERR_BATTERY_ ABSENT Device does not exist. Battery is absent 1. Before calling OsWlInit(), OsWlPowerSwitch(), OsWlLogin() or OsWlLogout(), this function must be called to open the wireless module first. 2. OsWlUnLock() must be called to close wireless module when there is no operation any more. 3. Noted that S920 and D200 mobile terminals need battery to work. 21.2.2 OsWlUnLock Prototype void OsWlUnLock(void); Function Close the wireless module. Parameters None Return None Instruction 21.2.3 OsWlInit() Prototype int OsWlInit(const char *SimPin); Function Initializes wireless module. Parameters Return Instruction SimPin SIM card PIN, 【Input】 The PIN length can't exceed 50 characters. NULL means it does not need the PIN. RET_OK Success ERR_DEV_NOT_OPE N Fail to call WlOpen(). ERR_DEV_NOT_EXI ST Wireless module does not exist. ERR_NO_PORT Not enough physical ports. ERR_WL_NEEDPIN SIM card needs PIN. ERR_WL_RSPERR Response error. ERR_WL_NORSP Module does not respond ERR_WL_NEEDPUK SIM card needs PUK. ERR_WL_WRONG_PI N PIN error. ERR_WL_NOSIM No SIM card. ERR_WL_NOTYPE ERR_WL_NOREG Module cannot be recognized. Registering GPRS network failed. 1. Before using this function, make sure to call OsWlLock() successfully. PAX Computer Technology (Shenzhen) Co., Ltd. 195 Prolin API Programming Guide 2. 3. 4. 5. 6. This function needs to be called successfully at system startup time before calling OsWlLogin() to establish the link. SIM card will automatically check the password when the password is required. If the module does not power on, the system will automatically supply power for it. When ERR_WL_NOSIM is returned (No SIM card), the application can use some functions that do not require SIM card. After calling OsWlSwitchPower(), application should wait for at least 15 seconds until the module is stable, otherwise, calling OsWlInit() might fail. 21.2.4 OsWlSwitchPower Prototype int OsWlSwitchPower(int OnOff); Function Powers on /off the wireless module. Parameters Return Instruction OnOff 0: Power off 1: Power on RET_OK Success ERR_DEV_NOT_EXIST Wireless module does not exist. ERR_DEV_NOT_OPEN Fail to call OsWlLock(). Reserved interface and it is not yet supported. 1. The time it took to power on the different modules is different. 2. Module powers off means directly shutting off the module power supply. . 3. While the power is on, if the wireless module has been detected by the Prolin OS, the system will power on automatically. 4. Please wait for 8 seconds between power off and power on, if the application did not wait enough time to immediately power on, then it will be blocked until it wait long enough to power on . 5. Before power off, it will disconnect ppp automatically. 6. In the state of power off, it should wait for 15 seconds before initializing module and getting signal. The login connection will be performed after 15 seconds, and it results a long time landing. 21.2.5 OsWlSwitchSleep Prototype int OsWlSwitchSleep(int OnOff); Function Makes the wireless module sleep or wake up. Parameters OnOff PAX Computer Technology (Shenzhen) Co., Ltd. 0: 1: Wake up Sleep 196 Prolin API Programming Guide Others: Errors. Return Instruction RET_OK Success ERR_DEV_NOT_EXIST Module does not exist. ERR_DEV_NOT_OPEN Fail to call Os WlLock(). ERR_WL_PPP_ONLINE PPP is on line. Reserved interface and it is not yet supported. If it detects the PPP is on line, it will not be in sleep. For MG323, when there is no inserted SIM card, or has not activated the PIN, or has not registered to the network, it will not be in sleep. 21.2.6 OsWlGetSignal Prototype int OsWlGetSignal(void); Function Gets the wireless signal strength. Parameters Return None 0~5 Represents the signal strength, the higher the number, the stronger the signal, 0 means no signal and 5 represents the strongest signal. ERR_DEV_NOT_EXIST Module does not exist. ERR_NO_PORT Not enough physical uart. ERR_WL_POWER_ONING Module is power on. 1. 2. Instruction 3. It doesn‘t need to call OsWLock() when use this function; When the wireless link is not established, this API will get the signal values from the module through AT commands; OsWlGetSignal() can‘t obtain the current signal strength and returns ‗ERR_WL_RSPERR‘ after a wireless link established by calling OsWlLogin(). In this time, module is in the data exchange mode, can‘t get the real-time signal. 21.2.7 OsWlCheck Prototype int OsWlCheck(void); Function Checks the status of wireless link. Parameters Return None PPP_LOGOUTING Link disconnecting. PPP_LOGINING Link establishing. RET_OK Link established successful. ERR_DEV_NOT_EXIST Module does not exist. PAX Computer Technology (Shenzhen) Co., Ltd. 197 Prolin API Programming Guide ERR_WL_POWER_ONING Module is powered on. ERR_WL_POWER_OFF Module is powered off. ERR_WL_NOT_INIT Initialization failed. ERR_NET_PASSWD Password is incorrect. ERR_NET_LOGOUT OsWlLogout() disconnect the link. ERR_NET_IF Link has been disconnected. Instruction 21.2.8 OsWlLogin int OsWlLogin(const char *APN, const char *Name, const char *Password, long Auth, Prototype int TimeOutMs, int KeepAlive, int ReserParam); Function Log in on the wireless network and set up a wireless link. APN Name Parameters 【Input】 APN – Access Point Name for GPRS communication, dialing number for CDMA. Length <= 50 characters; When pointer points to NULL, the application should dial-up first and the protocol stacks directly log in on PPP. User name; Length <= 50 bytes; 【Input】 It cannot be NULL, if there is no user name, replace it with an empty string ― ‖; Password 【Input】 Password; Length <= 50 characters; It cannot be NULL, if there is no password, replace it with an empty string ― ‖; The supported authentication algorithms PPP_ALG_PAP 0x00000001 PAP authentication algorithm PPP_ALG_CHAP 0x0000000 CHAP Auth PAX Computer Technology (Shenzhen) Co., Ltd. 198 Prolin API Programming Guide authentication algorithm PPP_ALG_MSCH APV1 0x00000004 MSCHAPV1 authentication algorithm PPP_ALG_MSCH APV2 0x00000008 MSCHAPV2 authentication algorithm PPP_ALG_ALL 0xff All algorithms are supported At least one type of authentication algorithm has to be chosen; or choose more than one authentication algorithm by using (+) or (|), for example, PPP_ALG_PAP| PPP_ALG_CHAP. If the algorithm is unknown, fill it with PPP_ALG_ALL. Timeout,【unit:ms】; TimeOutMs Return The valid range is 0~3600000; if it is <0, automatically set it to 0, if more than 360000, automatically set it to 3600000. KeepAlive Interval for link check, unit is ms; The valid range is 10000~3600000; If the link is longer than KeepAlive time but without any messages; the system automatically starts the link check interval; ReserParam Reserved parameter, used for extension. PPP_LOGINING In process PPP_LOGOUTING The wireless module is logging out. RET_OK Set up link successfully. ERR_DEV_NOT_E XIST Wireless module does not exist. ERR_DEV_NOT_O PEN Performing OsWlLock() failed ERR_INVALID_PA RAM Invalid parameter. ERR_WL_POWER _ONING Module is powered on. ERR_WL_POWER _OFF Module is powered off. ERR_WL_NOT_IN IT Initialization failed. ERR_NET_PASSW D Password is incorrect. ERR_NET_SERVE R_BUSY Server is busy, communication failure. PAX Computer Technology (Shenzhen) Co., Ltd. 199 Prolin API Programming Guide ERR_NET_AUTH 1. 2. 3. 4. 5. Instruction 6. 7. Has no authority to access to the RADIUS server. Before using this function, make sure to call OsWlLock() successfully. When Timeouts=0,it means return immediately; Calling OsWlCheck() to check the link status; For different modules and different network environments, the login time will be different; if within 60 seconds the login did not complete, it means login failure or the module has an exception error. Unsuccessful login for three consecutive times, it indicates the module has no response, the application must call OsWlSwitchPower() to reset the module. After setting up the link successfully, the link will be set to be the default route and communication can be done through the IP network communication function. When the return vaule is PPP_LOGOUTING, need to call OsWlCheck() function to check whether it has finished logout, and OsWlCheck() returns ERR_NET_LOGOUT means completing logout. 21.2.9 OsWlLoginEx int OsWlLoginEx(const char *DialNum, const char *APN, const char *Name, const char *Password, Prototype long Auth, int TimeOutMs, int KeepAlive, int ReserParam); Function Log in on the wireless network and set up a wireless link.(it supports modifying the dialing instructions) DialNum The PPP dialing instruction. Length <= 50 characters; 【Input】 When it is NULL, it adopts the default instruction of system. ANP APN – Access Point Name for GPRS communication, dialing number for CDMA. 【Input】 Length <= 50 characters; It cannot be NULL. Name User name; Length <= 50 bytes; 【Input】 It cannot be NULL, if there is no user name, replace it with an empty string ― ‖; Parameters Password; Password 【Input】 Length <= 50 characters; It cannot be NULL, if there is no password, replace it PAX Computer Technology (Shenzhen) Co., Ltd. 200 Prolin API Programming Guide with an empty string ― ‖; The supported authentication algorithms: Auth PPP_ALG_PAP 0x00000001 PAP authentication algorithm PPP_ALG_CHAP 0x0000002 CHAP authentication algorithm PPP_ALG_MSCH APV1 0x00000004 MSCHAPV1 authentication algorithm PPP_ALG_MSCH APV2 0x00000008 MSCHAPV2 authentication algorithm PPP_ALG_ALL 0xff All algorithms are supported At least one type of authentication algorithm has to be chosen; or choose more than one authentication algorithms by using (+) or (|), for example, PPP_ALG_PAP| PPP_ALG_CHAP. If the algorithm is unknown, fill it with PPP_ALG_ALL. Timeout,【unit:ms】; TimeOutMs KeepAlive Interval for link check, unit is ms; The valid range is 10000~3600000; If the link is longer than KeepAlive time but without receiving any messages; the system automatically starts the link check interval; (This functionality does not work now, originally it was designed for CDMA to prevent it forming going to sleep.) ReserParam Reserved parameter, used for extension. PPP_LOGINING Return The valid range is 0~3600000; if it is <0, automatically set it to 0, if more than 360000, automatically set it to 3600000. In process RET_OK Set up link successfully. ERR_DEV_NOT_E XIST Wireless module does not exist. ERR_DEV_NOT_O PEN Performing OsWlLock() failed. ERR_INVALID_PA RAM Invalid parameter. ERR_WL_POWER _ONING Module is powered on. ERR_WL_POWER Module is powered off. PAX Computer Technology (Shenzhen) Co., Ltd. 201 Prolin API Programming Guide _OFF Instruction 21.2.10 ERR_WL_NOT_IN IT Initialization failed. ERR_NET_PASSW D Password is incorrect. ERR_NET_SERVE R_BUSY Server is busy, communication failure. 1. This function is similar to OsWlLogin(), when DialNum is NULL, the two functions have the same functionality. 2. Before using this function, make sure to call OsWlLock() successfully. 3. When TimeOutMs=0,it means return immediately; 4. Calling OsWlCheck() to check the link status; 5. For different modules and different network environments, the login time will be different; if the login did not complete in 60 seconds, it means login failure or the module has an exception error. 6. Unsuccessful login for three consecutive times, it indicates the module has no response, the application must call OsWlSwitchPower() to reset the module. 7. After the link has been set up successfully, the link will be set to be the default route and communication can be done through the IP network communication function. OsWlLogout Prototype int OsWlLogout(void); Function Exits the wireless network and disconnects the wireless link. Parameters Instruction None PPP_LOGOUTING The link is being disconnected ERR_DEV_NOT_OPEN Fail to call OsWlLock(). 1. Before using this function, make sure to call OsWlLock() successfully. 2. After calling this function, OsWlCheck() should be called to check the status of the logout. Only when ERR_NET_LOGOUT is returned does that mean disconnecting the link successfully. 21.3 Wireless module information settings 21.3.1 OsWlSelSim Prototype int OsWlSelSim(int simno); Function Selects SIM card. Parameters simno 【Input】 Return RET_OK PAX Computer Technology (Shenzhen) Co., Ltd. 0: Selecting card slot 1 1: Selecting card slot 2 Others: Parameter error Success 202 Prolin API Programming Guide ERR_DEV_NOT_EXIST Module does not exist. ERR_DEV_NOT_OPEN Fail to call OsWlLock(). ERR_WL_ERR_BUSY Module is busy. Other non-zero value Refer to the Return code list. 1. 2. Instruction 3. Before using this function, make sure to call OsWlLock() successfully. After selecting SIM card, the module will be powered on/off, and this function blocks about 15 seconds. Application needs to re-call OsWilInit() to initialize the module. If users select a card slot with bad cards or without any cards, the function will also return successfully. And it can detect the problems while logging in. PAX Computer Technology (Shenzhen) Co., Ltd. 203 Prolin API Programming Guide 22 WIFI Prolin WIFI supports two modes: STATION and IBSS(ad-hoc). 1) STATION mode refers to the communication between the wireless modems. IBSS mode is referred to the direct communication between several devices. It can be used in the following situations. Assume that there is an ad-hoc device named ‗A‘ in the network, device ‗B‘ tries to connect to device ‗A‘. If the connection is successful, ‗A‘ and ‗B‘ can ping successfully with each other; if not, device ‗B‘ will create an ad-hoc network by itself; 2) In the network without an ad-hoc device, device ‗B‘ will create an ad-hoc network by itself. 3) At present, Prolin WIFI only supports module with keyword ro.fac.wifi is ―RS9110-N-11-02‖ or ―01‖. 22.1 Return Code List Table 22 Return Code List Macro Value Description ERR_WIFI_POWER_OFF -3351 Module is powered off. ERR_NOT_FOUND_AP -3352 Has not found AP. ERR_AUTH_SEC_MODE -3353 Authentication mode or encryption mode error. PAX Computer Technology (Shenzhen) Co., Ltd. 204 Prolin API Programming Guide -3354 ERR_WIFI_BAD_SIGNAL 1 RET_CONNECTING WIFI signal is bad. Connecting 22.2 Encryption type List Table 23 Encryption type List Macro Value Description PARE_CIPHERS_NONE 0x00000000 No encryption PARE_CIPHERS_WEP64 0x00000001 Means 40 bit key with concatenated 24 bit initialization vector PARE_CIPHERS_WEP128 0x00000002 Means 104 bit key with 24 bit initialization vector PARE_CIPHERS_WEPX 0x00000004 Unknown WEP key bits PARE_CIPHERS_CCMP 0x00000010 AES in Counter CBC-MAC PARE_CIPHERS_TKIP 0x00000020 Temporal Key Integrity Protocol mode with 22.3 Data Structure Authentication Modes: enum WIFI_AUTH_MODE{ AUTH_NONE_OPEN=1, AUTH_NONE_WEP, AUTH_NONE_WEP_SHARED, /* The mode will be scanned as AUTH_NONE_WEP */ AUTH_IEEE8021X, AUTH_WPA_PSK, AUTH_WPA_EAP, AUTH_WPA_WPA2_PSK, AUTH_WPA_WPA2_EAP, AUTH_WPA2_PSK, AUTH_WPA2_EAP }; PAX Computer Technology (Shenzhen) Co., Ltd. 205 Prolin API Programming Guide Extension for WEP64 and WEP128: typedef struct _WepSecKey{ char Key[4][40]; /* WEP key data */ int KeyLen; /* WEP key data length */ int Idx; /* WEP key index [0..3] of actually used key */ } WEP_SEC_KEY; Extension for WPA/WPA2-PSK: typedef struct _WpaPskKey{ char Key[64]; /* PSK-Key data */ int KeyLen; /* PSK-Key data length */ } WPA_PSK_KEY; Extension for EAP: typedef struct _WpaEapKey{ int EapType; /* EAP type */ char Pwd[132]; /* Password */ char Id[132]; /* Identity */ char CaCert[132]; /* Path and filename of CA certificate */ char CliCert[132]; /* Path and filename of client certificate */ char PriKey[132]; /* File path to client private key file */ char PriKeyPwd[132]; /* Password for private key file */ } WPA_EAP_KEY; Scan the AP information: typedef struct _WifiApInfo { char Essid[33]; /* AP name */ PAX Computer Technology (Shenzhen) Co., Ltd. 206 Prolin API Programming Guide char Bssid[20]; /* MAC address */ int Channel; /* Channel */ int Mode; /* Connection mode, 0:Station; 1:IBSS */ int Rssi; /* Signal value, The value range is [-99,0] */ int AuthMode; /* Authentication mode*/ int SecMode; /* Encryption mode, NONE,WEP,TKIP,CCMP */ }ST_WifiApInfo; Connect to AP settings: typedef struct _WifiApSet { char Essid[33]; /* AP name, it can support 32 bytes at most, ending with ’\0’*/ char Bssid[20]; /* MAC address, ending with ’\0’, if there is no any APs with the same ESSID, Bssid can be ”\0”*/ int Channel; /* Channel, only valid in IBSS mode, 0:Auto set */ int Mode; /* Connection mode, 0:Station; 1:IBSS */ int AuthMode; /* Authentication mode */ int SecMode; /*Encryption mode, NONE,WEP,TKIP,CCMP*/ union KEY_UNION{ /* Key */ WEP_SEC_KEY WepKey; /* For wep */ WPA_PSK_KEY PskKey; /* For wpa,wpa2-psk authentication */ WPA_EAP_KEY EapKey; /* For wpa,wpa2-eap*/ } KeyUnion; }ST_WifiApSet; 22.4 OsWifiOpen Prototype int OsWifiOpen(void); Function Get access to the WIFI module. Parameters None Return RET_OK Success ERR_DEV_NOT_ EXIST Driver loading exception or module error. PAX Computer Technology (Shenzhen) Co., Ltd. 207 Prolin API Programming Guide ERR_DEV_BUSY ERR_BATTERY_ ABSENT Instruction WIFI is already in use. Battery does not exist. For D200 and S920 POS models, the battery must be installed in order to operate the Wifi, otherwise ERR_BATTERY_ABSENT will be returned. 22.5 OsWifiClose Prototype void OsWifiClose (void); Function Release the WIFI module. Parameters None Return None Instruction 22.6 OsWifiSwitchPower Prototype int OsWifiSwitchPower (int Type); Function Sets WIFI module into the state of power-on and power-off. Parameters Type Return Instruction 1: Set module hardware into the state of power-on 0: Set module hardware into the state of power-off RET_OK Success ERR_INVALID_P ARAM Invalid parameter ERR_DEV_NOT_ EXIST Driver loading exception or module error. ERR_DEV_NOT_ OPEN Fail to access to the WIFI device. The module will automatically power on after the boot, it doesn‘t need to call this function. Reserved interface and it is not yet supported. 22.7 OsWifiScan Prototype int OsWifiScan (ST_WifiApInfo **Aps); Function Search for APs. PAX Computer Technology (Shenzhen) Co., Ltd. 208 Prolin API Programming Guide Parameters Aps 【Output】 The searched AP information >=0 The number of searched APs ERR_MEM_FAU LT Memory error ERR_INVALID_P ARAM Invalid parameter ERR_WIFI_POW ER_OFF WIFI module is powered off. ERR_DEV_NOT_ OPEN Fail to access to the WIFI device. Return Instruction /*For example:*/ int i, num; ST_WifiApInfo * Aps; num = OsWifiScan (&Aps); if(num <= 0) return -1; for(i=0; i . It is allowed to use the standard POSIX interface to get the access. PAX Computer Technology (Shenzhen) Co., Ltd. 213 Prolin API Programming Guide 24 System Information In Prolin, the system messages generated by the hardware device are implemented by asynchronous notification. The system provides two kinds of hardware system messages, magnetic cards and IC cards. SIGMAG SIGICC The SIGMAG is only valid when the magnetic stripe reader device is open. The code of registered asynchronous notification function is shown as follows: EXAMPLE #include #include #include #include #include #include #define printf(...) LOGI(__VA_ARGS__) static sigset_t mask; void * handler_sigwait(void * arg) { PAX Computer Technology (Shenzhen) Co., Ltd. 214 Prolin API Programming Guide int ret, signo; while(1){ ret = sigwait(&mask, &signo); if(ret != 0){ printf("sigwait err, ret=%d\n", ret); break; } switch(signo){ case SIGMAG: printf("Capture msr signal\n"); break; case SIGICC: printf("Capture icc signal\n"); break; default: printf("Capture other signal %d\n", signo); break; } } } int main() { int ret; sigset_t oldmask; pthread_t tid; ret = OsMsrOpen(); if (ret < 0) exit(-1); ret = OsIccOpen(ICC_USER_SLOT); if (ret < 0){ OsMsrClose(); return -1; } PAX Computer Technology (Shenzhen) Co., Ltd. 215 Prolin API Programming Guide sigemptyset(&mask); sigaddset(&mask, SIGMAG); sigaddset(&mask, SIGICC); ret = pthread_sigmask(SIG_SETMASK, &mask, &oldmask); if(ret != 0){ printf("pthread_sigmask error, ret=%d\n", ret); exit(-1); } ret = pthread_create(&tid, NULL, handler_sigwait, 0); if(ret != 0){ printf("pthread_create error, ret=%d\n", ret); exit(-1); } pthread_join(tid, NULL); OsMsrClose(); OsIccClose(ICC_USER_SLOT); } PAX Computer Technology (Shenzhen) Co., Ltd. 216 Prolin API Programming Guide 25 Audio The speaker volume of Prolin is divided into five levels, ranging from 0 to 4, 0 means mute. In general, the volume setting is unified, and it can set in the TM interface. 25.1 OsPlayWave Prototype int OsPlayWave(const char *Buf, int Len, int Volume, int DurationMs); Function Play WAV audio files. Parameters Buf 【Input】 The audio data buffer. Len 【Input】 Length of the data buffer. Volume 【Input】 Volume, the values range from 0 to 4. 0 represents playing in mute. DurationMs【Input】 Play duration【Unit:ms】 Return Instruction RET_OK Success ERR_FILE_FORMAT File format error ERR_ACCESS_DENY Access denied ERR_INVALID_PARAM Invalid parameter 1. The Volume value ranges from 0 to 4, when Volume<0, set it as the system volume, that is the value of persist.sys.sound.volume, it can be set PAX Computer Technology (Shenzhen) Co., Ltd. 217 Prolin API Programming Guide 2. 3. in tm; when Volume>4, set is as 4. If the DurationMs is more than the Len play time, it will play on a continuous loop of the file. On the contrary, DurationMs shall prevail. When DurationMs=0, the actual length of the audio data shall prevail. Support WAVE audio file with single track or double track; Support 8-bit sampling , 16 bit sampling. The supported sample frequencies are 8000 Hz,11025 Hz,6000 Hz,22050 Hz,24000 Hz,32000 Hz,44100 Hz and 48000 Hz. For example, FILENAME is the name of the audio file. EXAMPLE int fd, ret = 0; char *buff; int len; struct stat state; stat(FILENAME, &state); len = state.st_size; buff = (char *) malloc(len * sizeof(char)); fd = open(FILENAME, O_RDONLY); if(fd<0) printf("Open File Fail\n"); ret = read(fd, buff, len); ret = OsPlayWave(buff, len, 3, 0); if(ret != RET_OK) printf("PlayWave Fail\n"); close(fd); free(buff); PAX Computer Technology (Shenzhen) Co., Ltd. 218 Prolin API Programming Guide 26 Barcode 26.1 General Definiton Prolin barcode supports one-dimensional and two-dimensional barcode. One-dimensional code is composed of vertical black and white bars with letters or digits at the bottom of the bars, and the thickness of black and white is different. It used to identify the basic information of products, such as name, price, etc. Two-dimensional code is a dot matrix form with a rectangular structure. It has some polygon images inside the code, and texture is black and white with different thickness. Two-dimensional code could represent more detailed content in addition to the identification function. The usage of barcode is as follow: Firstly, OsScanOpen() is called to open the barcode module; Then, OsScanRead() is called and the light beam will be emitted from barcode scanning head, and the barcode scanning head align the code image to get the code information; Lastly, OsScanClose() is called to close the barcode module. 26.2 OsScanOpen Property int OsScanOpen (void); Function Open the barcode scanning module. Parameter Return None RET_OK PAX Computer Technology (Shenzhen) Co., Ltd. Success 219 Prolin API Programming Guide ERR_DEV_BUSY Device has been occupied. ERR_DEV_NOT_OPEN Device is not open. ERR_DEV_NOT_EXIST Device does not exist. Instruction 26.3 OsScanRead int OsScanRead(char *Buf, Property Function int Len, int TimeoutMs); Read the barcode. Buf Len The buffer is used to store the barcode data. 【Output】 One-dimensional code recommends being more than 512 bytes, and two-dimensional code suggests being 3072 bytes. 【Input】 Buffer length Parameter Timeout of reading barcode,【unit:ms】 The valid range is 1500~36000, if it is less than 1500, TimeoutMs 【Input】 set is to 1500, and if it is greater than 36000, set it to 36000. The margin of error between the actual timeout value and the setting value may be less than 1s, it is recommended to set the timeout value to 3000ms. Return >=0 The actual length of the read barcode data. ERR_DEV_NOT_O PEN Device is not open. ERR_TIME_OUT Timeout. ERR_INVALID_PA RAM Invalid parameter Instruction 26.4 OsScanClose Property void OsScanClose (void); Function Close the scanning device. Parameter None Return None Instruction PAX Computer Technology (Shenzhen) Co., Ltd. 220 Prolin API Programming Guide 27 Power Management 27.1 OsCheckBattery Prototype int OsCheckBattery(void); Function Checks the battery. Parameters None BATTERY_LEVEL_0 Return It needs immediately charge the battery. At this point, it should not do the transaction, wireless communications and printing. When the battery capacity is low, the system will automatically turn off. 0~5%battery BATTERY_LEVEL_1 5%~15% battery BATTERY_LEVEL_2 15%~40%battery BATTERY_LEVEL_3 40%~70%battery BATTERY_LEVEL_4 70%~100%battery BATTERY_LEVEL_CHA RGE Battery is being charged. BATTERY_LEVEL_COM PLETE Battery is fully charged, external power supplies the electricity. PAX Computer Technology (Shenzhen) Co., Ltd. 221 Prolin API Programming Guide Instruction BATTERY_LEVEL_ABS ENT Battery does not exist. It needs external power supplies electricity. ERR_SYS_NOT_SUPPOR T System does not support checking the battery. S800/S300 returns this value. 1. When using an electric power supply, it can detect whether the battery is full charged or not, but the battery level only can be detected when the batter is in use. 2. It is not recommended to call this function during printing, because the printer requires high current in the printing procedure, otherwise, it will make the interface obtain an inaccurate charge. 3. When RF searching the card, or wireless module attaching to the network, it needs a higher power, then please note that the battery may fluctuate during the above processes. 4. When the battery level is BATTERY_LEVEL_0, wireless module, printer, RF module are probably can not continue to function normally, the battery needs to be charged. 27.2 OsCheckPowerSupply Prototype int OsCheckPowerSupply (void); Function Check the power supply type. Parameters None Return POWER_BATTERY Powered by the battery. POWER_ADAPTER Powered by the adapter. POWER_USB Powered by the USB, such as PC. Instruction 27.3 OsSysSleep Prototype int OsSysSleep(void); Function Make the system enter the sleep mode to save power. Parameters None Return Instruction RET_OK Success ERR_SYS_NOT_SUPPORT System does not support this function. The system will enter sleep mode by calling this function, otherwise, it never sleep. In sleep mode, CPU stops running and the screen is black; Terminal could be PAX Computer Technology (Shenzhen) Co., Ltd. 222 Prolin API Programming Guide awakened up by pressing key, the contents displayed in the screen are the same as before calling this function. System continues running at the breakpoint which was made before sleep. It is not recommended to hibernate during using RF card, if so, after wake up, it must call OsPiccClose() firstly, and then call OsPiccOpen() and other cards operations. 27.4 OsSysSleepEx Prototype int OsSysSleepEx(int Level); Function Make the POS terminal enter different levels of sleep mode, and reduce the power consumption. 【Input】 Sleep level, value range is [0, 2]. 0: System runs normally; 1: Screen save mode. CPU works well, specific performance in turning the LCD, key backlight, touch key, touch screen off. You also can wake up them by plastic button. 2: System hibernation. CPU stops working, modules can only be awakened by plastic button. RET_OK Success ERR_INVALID _PARAM Invalid parameter ERR_SYS_NO T_SUPPORT System hibernation is not Supported. Level Parameters Return 1. 2. 3. Instruction 4. When Level=2, it is equivalent to calling the OsSysSleep(); The opened handle will not be closed in any sleep level. The current working state of cards and communication modules will not be changed in level 0 and level 1. In level 2, the modules other than plastic button will be closed. Under normal operation, it will enter the screen save mode if there is no input event within the default interval of one minute. The interval can be set by persist.sys.backlighttime(unit: minute), when persist.sys.backlighttime = 0, it means turn off the screensaver. 27.5 OsReboot Prototype int OsReboot(void); Function Reboot the machine. PAX Computer Technology (Shenzhen) Co., Ltd. 223 Prolin API Programming Guide Parameters None Return ERR_SYS_BAD System error RET_OK Success Instruction 27.6 OsPowerOff Prototype int OsPowerOff (void); Function Turn off the power. Parameters None Return ERR_SYS_BAD System error RET_OK Success Instruction PAX Computer Technology (Shenzhen) Co., Ltd. 224 Prolin API Programming Guide Appendix 1 PIN Block Format Format 0 PIN block This PIN block is constructed by modulo-2 addition of two 64-bit fields: the plain text PIN field and the account number field. The formats of these fields are described in 1.1.1 and 1.1.2 respectively. The format 0 PIN block shall be reversibly enciphered when transmitted. Plain text PIN field The plain text PIN field shall be formatted as follows. Bit 1 5 9 13 17 21 25 29 33 37 41 45 49 53 57 61 64 C N P P P P P P/F P/F P/F P/F P/F P/F P/F F F where C = Control field: shall be binary 0000; N = PIN length: 4-bit binary number with permissible values of 0100(4) to 1100(12); P = Pin digit: 4-bit field with permissible values of 0000(zero) to 1001(9); P/F = PIN/Fill digit: designation of these fields is determined by the PIN length field; F = Fill digit: 4-bit field value 1111(15). Account number field The account number field shall be formatted as follows. Bit 1 5 9 13 17 21 25 29 33 37 41 45 49 53 57 61 64 PAX Computer Technology (Shenzhen) Co., Ltd. 225 Prolin API Programming Guide 0 0 0 0 A1 A2 A3 A4 A5 A6 A7 A8 A9 A10 A11 A12 where 0 = Pad digit: a 4-big field with the only permissible value of 0000(zero); A1…A12 = Account number: content is the 12 rightmost digits of the primary account number (PAN) excluding the check digit. A12 is the digit immediately preceding the PAN‘s check digit. If the PAN excluding the check digit is less than 12 digits, the digits are right justified and padded to the left with zeros. Permissible values are 0000 (zero) to 1001 (9). Format 1 PIN block This PIN block is constructed by concatenation of two fields: the plain text PIN field and the transaction field. The format 1 PIN block should be used in situations where the PAN is not available. The format 1 PIN block shall be reversibly enciphered when transmitted. The format 1 PIN block shall be formatted as follows. Bit 1 5 9 13 17 21 25 29 33 37 41 45 49 53 57 61 64 C N P P P P P/T P/T P/T P/T P/T P/T P/T P/T T T where C = Control field: shall be binary 0001; N = PIN length: 4-bit binary number with permissible values 0100(4) to 1100 (12); P = PIN digit: 4-bitfield with permissible values 0000 (zero) to 1001 (9); P/T = PIN/Transaction digit: designation of these fields is determined by the PIN length field; T = Transaction digit: 4-bit binary number with permissible values of 0000 (zero) to 1111 (15). PAX Computer Technology (Shenzhen) Co., Ltd. 226 Prolin API Programming Guide The transaction field is a binary number formed by [56-(N*4)] bits. This binary shall be unique (except by chance) for every occurrence of the PIN block and can, for example, be derived from a transaction sequence number, time stamp, random number or similar. The transaction field should not be transmitted and is not required in order to translate the PIN block to another format since the PIN length is known. Format 2 PIN block The format 2 PIN block has been specified for local use with IC cards. The format 2 PIN block shall only be used in an offline environment and shall not be used for online PIN verification. Format 3 PIN block Format 3 PIN block construction The format 3 PIN block is the same as format 0 PIN block except for the fill digits. This PIN block is constructed by modulo-2 addition of two 64-bit fields: the plain text PIN field and the account number field. The formats of these fields are described in 1.4.2 and 1.4.3 respectively. Plain text PIN field The plain text PIN field shall be formatted as follows. Bit 1 5 9 13 17 21 25 29 33 37 41 45 49 53 57 61 64 C N P P P P P/F P/F P/F P/F P/F P/F P/F P/F F F where C = Control field: shall be binary 0011; N = PIN number: 4-bit binary number with permissible values of 0100 (4) to 1100 (12); P = PIN digit: 4-bit field with permissible values of 0000 (zero) to 1001 (9); P/F = PIN/Fill digit: designation of these fields is determined by the PIN length field; PAX Computer Technology (Shenzhen) Co., Ltd. 227 Prolin API Programming Guide F = Fill digit: 4-bit field, with values from 1010(10) to 1111(15), where the Fill-digit values are randomly or sequentially selected from this set of six possible values, such that it is highly unlikely that the identical configuration of fill digits will be used more than once with the same account number field by the same PIN encipherment device. Account number field The account number field shall be formatted as follows. Bit 1 5 9 13 17 21 25 29 33 37 41 45 49 53 57 61 64 0 0 0 0 A1 A2 A3 A4 A5 A6 A7 A8 A9 A10 A11 A12 For more details related to PIN Block format please refer to ISO 9564-1:2002(E). PAX Computer Technology (Shenzhen) Co., Ltd. 228 Prolin API Programming Guide Appendix 2 EPS PINBLOCK Format String format: ―1234‖+ISN [6 byte] +PIN [Byte bit]; If the PIN is less than 6 bytes, add ‗0‘ before PIN; The data string will be converted to BCD code, Using TPK to process DES/TDES encryption for BCD code. PAX Computer Technology (Shenzhen) Co., Ltd. 229 Prolin API Programming Guide Appendix 3 Registry Table The names begin with "ro.fac." can be read-only, for "persist.sys.", it can be both write and read. System configuration name Note ro.fac.ubootver Uboot version information ro.fac.hwver Hardware version number. Main board- Interface board. ro.fac.mach Product type name. ro.fac.boardid The information about the product ‘boardid’includes the product model type and hardware version number ect. ro.fac.conf.ver Version information of configuration files. ro.fac.pn PN number ro.fac.sn SN number The current system Prolin debug_level information. Values of ro.fac.prolin_debug_level release version system and debug version system are 0 and 1 respectively. ro.fac.eth Whether there is network cable.(0- does not exist, 1- exist) ro.fac.usb.host Whether there is the main device interface.(0- does not exist, 1exist) ro.fac.usb.device Whether there is an USB device interface.(0- does not exist, 1exist) ro.fac.usb.otg Whether there is an USB OTG interface.(0- does not exist, 1exist) ro.fac.leddt Whether there is LED digital tube.(0- does not exist, 1- exist) ro.fac.keybroad Key types.(0- have no keys, 1- indicates the presence of physical buttons, 2- indicates the presence of a touch-screen buttons) ro.fac.buzzer Whether there is a Buzzer module.(0- does not exist, 1- exist) ro.fac.simsocket The number of SIM card slot. ro.fac.battery Whether there is a battery.(0- does not exist, 1- exist) ro.fac.wifi Name of WIFI module.(If none, it means does not exist by default) ro.fac.bt Name of Bluetooth module. (If none, it means does not exist by default) ro.fac.radio Wireless module information, and the parameter information is optional. It needs to isolate when there are multiple wireless modules. (If none, it means does not exist by default) ro.fac.modem Name of Modem module. (If none, it means does not exist by default) ro.fac.printer Name of Printer module. (If none, it means does not exist by default) PAX Computer Technology (Shenzhen) Co., Ltd. 230 Prolin API Programming Guide ro.fac.pcd Name of PCD module. (If none, it means does not exist by default) ro.fac.sci Name of ICC Reader. (If none, it means does not exist by default) ro.fac.msr Name of MSR Reader. (If none, it means does not exist by default) ro.fac.videocard Name of video card module. (If none, it means does not exist by default) ro.fac.audiocard Name of audio card module. (If none, it means does not exist by default) ro.fac.touchscreen Name of Touch-screen module. (If none, it means does not exist by default) ro.fac.sdhc The specification, capacity range and speed level supported by SD card. (If none, it means does not exist by default) ro.fac.scanner Name of Scanner module. (If none, it means does not exist by default) ro.fac.pcd.param1 PCD antenna parameter 1. (If none, it needn't to fill in.) ro.fac.pcd.param2 PCD antenna parameter 2. (If none, it needn't to fill in.) ro.fac.pcd.param3 PCD antenna parameter 3. (If none, it needn't to fill in.) ro.fac.lcd.rotate The LCD clockwise rotation degrees. ("0","90","180","270") persist.sys.eth0.enable Supported Ethernet or not. ("true" or " "- support, "false"- does not support) persist.sys.eth0.dhcp DHCP is open or not. ("true" - opened, "false" or " "- closed) persist.sys.eth0.ip Ethernet ip address persist.sys.eth0.mask Ethernet subnet mask persist.sys.eth0.gateway Ethernet gateway persist.sys.dns1 System Preferred DNS persist.sys.dns2 System alternative DNS persist.sys.eth0.speed network port speed.("eth_auto" represents automatic configuration, "eth_10mhd" represents 10M half-duplex, "eth_10mfd" represents 10M full-duplex, "eth_100mhd" represents 100M half-duplex, "eth_100mfd" represents 100M full-duplex) persist.sys.prolin Prolin system version information persist.sys.language System language LCD backlight waits ‘backlighttime’ minutes, then it will persist.sys.backlighttime automatically turn off (value ranges from 0 to 32767, 0 means LCD backlight is turned on) persist.sys.key.backlight Whether the button backlight is open or not (0 means close, 1 means open) persist.sys.lcd.brightness LCD brightness (value ranges from 1 to 10, the higher, the brighter) PAX Computer Technology (Shenzhen) Co., Ltd. 231 Prolin API Programming Guide persist.sys.sound.enable Whether the beep is open or not(false means close, true means open) persist.sys.sound.volume Beep sound volume (value ranges from 1 to 99) PAX Computer Technology (Shenzhen) Co., Ltd. 232 Prolin API Programming Guide Appendix 4 Validity of models and contents According to the differences of the hardware design, some OSAL interfaces cannot take into effect on a certain model. For more, refer to the table below. Whether there is Wireless module, Modem module or Ethernet module depends on the model configuration.( Refer to the POS PN number) Chapters S300 S800 S920 D200 Thread √ √ √ √ System Function √ √ √ √ Encryption and √ Decryption √ √ √ PED √ √ √ √ LCD 240*320, Keyboard √ √ √ √ Touch Screen √ NA √ NA Signature Pad √ NA √ NA Printer NA √ √ NA Font Library √ √ √ √ Code √ √ √ √ MSR √ √ √ √ ICC Reader √ √ √ √ RF Reader √ √ √ √ rotate 320*240, rotate 240*320, rotate 240*320, 90°in clockwise 90 ° in clockwise 90 ° in clockwise rotation direction direction direction PAX Computer Technology (Shenzhen) Co., Ltd. no 233 Prolin API Programming Guide Communication Port PORT_COM1 PORT_COM1 PORT_USBDEV PORT_USBDE V PORT_COM2 PORT_USBHOS T PORT_PINPAD PORT_USBHOS PORT_USBDEV T PORT_USBHOS T PORT_COM 1 PORT_ USBDEV MODEM N/A √ N/A N/A Network Communication √ √ N/A N/A Network Configuration √ √ N/A N/A GPRS/CDMA N/A √ √ N/A WIFI N/A N/A √ √ File System √ √ √ √ System Information √ √ √ √ Audio √ √ √ N/A Power Management N/A N/A √ √ Barcode N/A N/A N/A N/A Bluetooth N/A N/A √ √ Above table is based on the fully configured models. PAX Computer Technology (Shenzhen) Co., Ltd. 234 Prolin API Programming Guide
Source Exif Data:
File Type : PDF File Type Extension : pdf MIME Type : application/pdf PDF Version : 1.6 Linearized : No Author : pax Create Date : 2015:05:05 15:59:19Z Modify Date : 2015:05:05 16:08:12+08:00 Subject : V 1.0.0 Language : zh-CN Tagged PDF : Yes XMP Toolkit : Adobe XMP Core 4.2.1-c041 52.342996, 2008/05/07-20:48:00 Format : application/pdf Creator : pax Description : V 1.0.0 Title : PAX XXX Programming Guide Creator Tool : Microsoft® Office Word 2007 Metadata Date : 2015:05:05 16:08:12+08:00 Producer : Microsoft® Office Word 2007 Document ID : uuid:71846617-89fd-4c34-a01c-4b94103b9c82 Instance ID : uuid:72759840-bbb1-4551-97b5-8e9843f097c6 Page Count : 243EXIF Metadata provided by EXIF.tools