Prolin API Programming Guide(v2.0.2)
User Manual:
Open the PDF directly: View PDF 
.
Page Count: 243
| Download | |
| Open PDF In Browser | View PDF |
Prolin API Programming
Guide
V 2.0.2
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.
Add the return code list in the System
function;
Add
a
new
function Prolin
OsVerifySignExternal ();
Team
Add the WIFI module;
Add the Register table in Appendix 3.
1.
Add descriptions in OsOpenFont ().
1.
Modify
the
description
of
OsModemOpen();
Add two return values -3219 and
-3220 in Modem;
Add
the
instruction
of
DetectDailTone;
Prolin
Add
a
new
function Team
OsModemSwitchPower ();
Modify the parameter description of
OsPrnOpen (), it does not support the
png format;
Modify the sci_get_fd ().
2.
2.
3.
2013-03-06
V1.0.4
4.
5.
6.
1.
2.
2013-04-17
V1.0.5
3.
4.
2013-05-17
V1.0.6
Prolin
Team
1.
2.
3.
4.
5.
6.
Prolin
Team
Modify the knots of the 14.4.1 open();
Modify the “pow-hwclock -w” to
“pow-hwclock -w -u” in the code of
Timeset;
Prolin
Update the instruction of the Team
OsWlInit();
Update the instruction of the
OsCheckBattery ().
Modify the description of ‘Timer’.
Add description of ‘Delay’.
Add description for registry table.
Modify the parameter description of Prolin
Value in OsRegGetValue ().
Team
Modify the parameter description of
ShaOut in OsSHA ().
Update the description of GUI.
II
2013-08-09
2013-10-22
V1.0.7
V1.0.8
7.
Add ‘1200, V22’ and ‘2400, FC’ to
the parts of synchronous variable for
MODEM.
1.
2.
3.
4.
Modify the Register table.
Modify the data structure of Font.
Prolin
Update the OsCheckBattery () .
Team
Update the chapter 15 ICC Reader
and chapter 16 RF Reader.
1.
Add 4.11 Save the crash report for
system function.
Modify the brightness level to [0~10] Prolin
in the chapter of LCD.
Team
Update the key value definitions in
the chapter of Keyboard.
2.
3.
2013-10-31
V1.0.9
1.
2.
3.
4.
1.
2.
3.
4.
2013-11-20
V2.0.0
5.
6.
7.
8.
9.
1.
2.
3.
2014-2-25
V2.0.1
4.
5.
6.
7.
8.
9.
Update the System Function.
Modify the OsCodeConvert().
Add new interfaces OsPortReset() and Prolin
OsPortCheckTx().
Team
Update the Audio chapter, add a new
interface OsPlayWave().
Add the description about 0x02 in
parameter KeyVarType.
Modify the value ranges in PED.
Modify the description of parameter
ucATQ0 in OsPiccAntiSel ().
Delete OsPiccGetParam () and
OsPiccSetParam ().
Prolin
Update
the
instruction
of Team
OsRegGetValue ().
Add notes of OsPortOpen ().
Update instructions of OsSysSleep ().
Update the Return code list in chapter
Network Configuration.
Add instruction of OsNetDns ().
Modify
the
instruction
of
OsWlSelSim().
Add a return value for OsMsrOpen ().
Add new interfaces OsWlLoginEx (),
OsMount (), OsUmount ().
Add chapter 26 Barcode.
Prolin
Add AES functions.
Team
Update the Appendix 4.
Modify the parameter Name in the
OsInstallFile().
Add
an
error
code
“ERR_APP_MODE”
for
the
OsInstallFile().
Add
a
new
interface
III
OsCheckPowerSupply().
10. Since Prolin2.4 upgrade, delete the
unsuccessful code in chapter 7 LCD.
2014-3-4
V2.0.2
1.
2.
Update the OsSysSleep().
Update the WIFI module.
IV
Prolin
Team
Contents
1
2
Introduction ......................................................................................................................... 1
1.1
Purpose ..................................................................................................................... 1
1.2
Readers ..................................................................................................................... 1
1.3
Conditions ................................................................................................................ 2
1.4
Related Documents .................................................................................................. 2
1.5
Abbreviation ............................................................................................................ 2
1.6
Document Conventions ............................................................................................ 3
Return Code and Parameter ................................................................................................. 5
2.1
Return code classification ........................................................................................ 5
2.2
General return code .................................................................................................. 6
2.3
Parameter ................................................................................................................. 7
3
Thread .................................................................................................................................. 9
4
System Function ................................................................................................................ 11
4.1
Return code list ...................................................................................................... 11
4.2
Data Definition....................................................................................................... 12
4.3
Timeset ................................................................................................................... 13
4.3.1 OsSetTime ...................................................................................................... 13
4.3.2 OsGetTime...................................................................................................... 13
4.4
Timer ...................................................................................................................... 14
4.4.1 OsTimerSet ..................................................................................................... 14
4.4.2 OsTimerCheck ................................................................................................ 14
4.5
Delay ...................................................................................................................... 14
4.5.1 OsSleep ........................................................................................................... 14
4.6
Thread dormancy ................................................................................................... 14
4.7
Log ......................................................................................................................... 15
4.7.1 OsLogSetTag .................................................................................................. 15
4.7.2 OsLog ............................................................................................................. 16
4.8
Get the count value ................................................................................................ 16
4.8.1 OsGetTickCount ............................................................................................. 16
V
4.9
Get Appliaction information .................................................................................. 16
4.9.1 OsGetAppInfo ................................................................................................ 16
4.10 Buzzer .................................................................................................................... 17
4.10.1 OsBeep ........................................................................................................ 17
4.11 Run Application ..................................................................................................... 17
4.11.1 OsRunApp................................................................................................... 17
4.12 Set and Read the registry table............................................................................... 18
4.12.1 OsRegSetValue ........................................................................................... 18
4.12.2 OsRegGetValue .......................................................................................... 18
4.13 Install and uninstall files ........................................................................................ 19
4.13.1 OsInstallFile ................................................................................................ 19
4.13.2 OsUninstallFile ........................................................................................... 20
4.14 Verify signature ..................................................................................................... 20
4.14.1 OsVerifySign .............................................................................................. 20
4.14.2 OsVerifySignExternal ................................................................................. 21
4.15 Get system version ................................................................................................. 22
4.15.1 OsGetSysVer............................................................................................... 22
4.16 Determine whether on the base .............................................................................. 23
4.16.1 OsOnBase ................................................................................................... 23
4.17 Save the crash report .............................................................................................. 23
4.17.1 OsSaveCrashReport .................................................................................... 23
4.18 Mount and Unmount the external file system ........................................................ 24
4.18.1 OsMount ..................................................................................................... 24
4.18.2 OsUmount ................................................................................................... 25
5
Encryption and Decryption ................................................................................................ 27
5.1
Return code list ...................................................................................................... 27
5.2
Random number ..................................................................................................... 27
5.2.1 OsGetRandom ................................................................................................ 27
5.3
SHA algorithm ....................................................................................................... 28
5.3.1 OsSHA ............................................................................................................ 28
VI
5.4
DES algorithm ....................................................................................................... 28
5.4.1 OsDES ............................................................................................................ 29
5.5
AES algorithm ....................................................................................................... 29
5.5.1 OsAES ............................................................................................................ 29
5.6
RSA algorithm ....................................................................................................... 30
5.6.1 OsRSA ............................................................................................................ 30
5.6.2 OsRSAKeyGen ............................................................................................... 31
6
PED.................................................................................................................................... 33
6.1
Return code list ...................................................................................................... 33
6.2
Data Definition....................................................................................................... 34
6.2.1 Key type .......................................................................................................... 34
6.2.2 Display attribute of Asterisk ........................................................................... 35
6.3
Data Structure ........................................................................................................ 35
6.3.1 Structure of RSA key...................................................................................... 35
6.3.2 RSA key structure for verifying the cipher text IC card PIN ......................... 36
6.4
Basic PED .............................................................................................................. 36
6.4.1 OsPedOpen ..................................................................................................... 36
6.4.2 OsPedGetVer .................................................................................................. 36
6.4.3 OsPedSetInterval ............................................................................................ 37
6.4.4 OsPedVerifyPlainPin ...................................................................................... 38
6.4.5 OsPedVerifyCipherPin ................................................................................... 39
6.4.6 OsPedEraseKeys ............................................................................................. 41
6.4.7 OsPedSetFunctionKey .................................................................................... 41
6.4.8 OsPedClose ..................................................................................................... 42
6.5
MK/SK ................................................................................................................... 42
6.5.1 OsPedWriteKey .............................................................................................. 42
6.5.2 OsPedWriteTIK .............................................................................................. 45
6.5.3 OsPedWriteKeyVar ........................................................................................ 47
6.5.4 OsPedSetAsteriskLayout ................................................................................ 48
6.5.5 OsPedGetPinBlock ......................................................................................... 49
VII
6.5.6 OsPedUpdatePinBlock ................................................................................... 50
6.5.7 OsPedGetMac ................................................................................................. 51
6.5.8 OsPedDes........................................................................................................ 52
6.5.9 OsPedGetKcv ................................................................................................. 53
6.5.10 OsPedDeriveKey......................................................................................... 55
6.6
DUKPT .................................................................................................................. 56
6.6.1 OsPedGetPinDukpt ......................................................................................... 56
6.6.2 OsPedGetMacDukpt ....................................................................................... 58
6.6.3 OsPedDesDukpt.............................................................................................. 59
6.6.4 OsPedGetKsnDukpt........................................................................................ 60
6.6.5 OsPedIncreaseKsnDukpt ................................................................................ 61
6.7
RSA ........................................................................................................................ 61
6.7.1 OsPedReadRsaKey ......................................................................................... 61
6.7.2 OsPedWriteRsaKey ........................................................................................ 62
6.7.3 OsPedRsaRecover .......................................................................................... 63
6.7.4 OsPedReadCipherRsaKey .............................................................................. 63
6.7.5 OsPedWriteCipherRsaKey ............................................................................. 64
6.8
AES ........................................................................................................................ 65
6.8.1 OsPedWriteAesKey ........................................................................................ 65
6.8.2 OsPedAes........................................................................................................ 67
7
8
LCD ................................................................................................................................... 69
7.1
OsScrContrast ........................................................................................................ 71
7.2
OsScrBrightness ..................................................................................................... 71
7.3
OsScrGetSize ......................................................................................................... 72
Keyboard ........................................................................................................................... 73
8.1
9
OsKbBacklight ....................................................................................................... 76
Touch Screen ..................................................................................................................... 77
10
Signature Board ............................................................................................................. 78
11
Printer ............................................................................................................................ 79
11.1 Return code list ...................................................................................................... 79
VIII
11.2 Open and Close ...................................................................................................... 79
11.2.1 OsPrnOpen .................................................................................................. 79
11.2.2 OsPrnReset .................................................................................................. 80
11.2.3 OsPrnClose ................................................................................................. 80
11.3 Printer settings ....................................................................................................... 81
11.3.1 OsPrnSetSize............................................................................................... 81
11.3.2 OsPrnSetDirection ...................................................................................... 81
11.3.3 OsPrnSetGray ............................................................................................. 81
11.4 Type Setting ........................................................................................................... 82
11.4.1 OsPrnSetSpace ............................................................................................ 82
11.4.2 OsPrnSetReversal ....................................................................................... 82
11.4.3 OsPrnSetIndent ........................................................................................... 82
11.4.4 OsPrnCheck ................................................................................................ 83
11.4.5 OsPrnGetDotLine ....................................................................................... 83
11.4.6 OsPrnSetFont .............................................................................................. 84
11.4.7 OsPrnSelectFontSize................................................................................... 84
11.4.8 OsPrnFeed ................................................................................................... 85
11.4.9 OsPrnPrintf ................................................................................................. 85
11.4.10 OsPrnPutImage ........................................................................................... 85
11.4.11 OsPrnStart ................................................................................................... 86
11.5 POSIX .................................................................................................................... 87
11.5.1 open ............................................................................................................. 87
11.5.2 read .............................................................................................................. 87
11.5.3 write ............................................................................................................ 88
11.5.4 Close ........................................................................................................... 89
12
Font Library................................................................................................................... 91
12.1 Data structure ......................................................................................................... 91
12.2 Font operation ........................................................................................................ 92
12.2.1 OsEnumFont ............................................................................................... 92
12.2.2 OsOpenFont ................................................................................................ 92
IX
12.2.3 OsCloseFont ................................................................................................ 93
12.2.4 OsGetFontDot ............................................................................................. 93
13
Code .............................................................................................................................. 97
13.1 Code Convert ......................................................................................................... 97
13.1.1 OsCodeConvert ........................................................................................... 97
14
MSR .............................................................................................................................. 99
14.1 Return code list ...................................................................................................... 99
14.2 Data structure ....................................................................................................... 100
14.3 MSR control interface .......................................................................................... 100
14.3.1 OsMsrOpen ............................................................................................... 100
14.3.2 OsMsrClose............................................................................................... 101
14.3.3 OsMsrReset ............................................................................................... 101
14.3.4 OsMsrSwiped ............................................................................................ 101
14.3.5 OsMsrRead ............................................................................................... 102
14.4 POSIX .................................................................................................................. 103
14.4.1 Open .......................................................................................................... 103
14.4.2 Read .......................................................................................................... 103
14.4.3 Close ......................................................................................................... 103
15
ICC Reader .................................................................................................................. 104
15.1 Return Code List .................................................................................................. 104
15.2 Data Structure ...................................................................................................... 106
15.2.1 IC card device control block ..................................................................... 106
15.2.2 ATR structure............................................................................................ 107
15.2.3 APDU Request Structure .......................................................................... 107
15.2.4 APDU Response Structure ........................................................................ 108
15.3 API index ............................................................................................................. 108
15.3.1 sci_open .................................................................................................... 109
15.3.2 sci_get_fd .................................................................................................. 109
15.3.3 sci_get_dcb ............................................................................................... 109
15.3.4 sci_set_dcb ................................................................................................ 110
X
15.3.5 sci_read ..................................................................................................... 110
15.3.6 sci_write .................................................................................................... 111
15.3.7 sci_close .................................................................................................... 111
15.3.8 sci_lock ..................................................................................................... 111
15.3.9 sci_unlock ................................................................................................. 112
15.3.10 sci_powerup .............................................................................................. 112
15.3.11 sci_powerdown ......................................................................................... 112
15.3.12 sci_detect .................................................................................................. 112
15.3.13 sci_cold_reset ........................................................................................... 113
15.3.14 sci_warm_reset ......................................................................................... 113
15.4 Protocol processing function................................................................................ 114
15.4.1 emv_atr_parse ........................................................................................... 114
15.4.2 iso7816_atr_parse ..................................................................................... 114
15.4.3 iso7816_pps .............................................................................................. 114
15.4.4 iso7816_ocs............................................................................................... 115
15.4.5 iso7816_t1_ifsd_request ........................................................................... 115
15.4.6 iso7816_t0_exchange ................................................................................ 116
15.4.7 iso7816_t1_exchange ................................................................................ 116
15.5 Encapsulated Interfaces ....................................................................................... 117
15.5.1 OslccOpen ................................................................................................. 117
15.5.2 OsIccDetect ............................................................................................... 117
15.5.3 OsIccInit .................................................................................................... 118
15.5.4 OsIccExchange ......................................................................................... 119
15.5.5 OsIccClose ................................................................................................ 119
16
RF Reader .................................................................................................................... 121
16.1 Return Code List .................................................................................................. 121
16.2 Data Structure ...................................................................................................... 122
16.2.1 User Configuration Structure .................................................................... 122
16.2.2 Configuration Parameter Definition ......................................................... 123
16.3 ISO14443 --- Type A ........................................................................................... 124
XI
16.3.1 iso14443_3a_req ....................................................................................... 124
16.3.2 iso14443_3a_wup ..................................................................................... 124
16.3.3 iso14443_3a_antisel .................................................................................. 125
16.3.4 iso14443_3a_halt ...................................................................................... 125
16.3.5 iso14443_3a_rats ...................................................................................... 125
16.4 ISO14443 --- Type B ........................................................................................... 126
16.4.1 iso14443_3b_req ....................................................................................... 126
16.4.2 iso14443_3b_wup ..................................................................................... 126
16.4.3 iso14443_3b_attri ..................................................................................... 126
16.4.4 iso14443_3b_halt ...................................................................................... 127
16.5 Half-duplex transmission protocol ....................................................................... 127
16.5.1 iso14443_4_transfer .................................................................................. 127
16.6 Encapsulated Interfaces ....................................................................................... 128
16.6.1 OsPiccOpen............................................................................................... 128
16.6.2 OsPiccClose .............................................................................................. 128
16.6.3 OsPiccResetCarrier ................................................................................... 128
16.6.4 OsPiccPoll ................................................................................................. 128
16.6.5 OsPiccAntiSel ........................................................................................... 129
16.6.6 OsPiccActive............................................................................................. 129
16.6.7 OsPiccTransfer .......................................................................................... 130
16.6.8 OsPiccRemove .......................................................................................... 130
16.6.9 OsMifareAuthority .................................................................................... 131
16.6.10 OsMifareOperate ...................................................................................... 131
16.6.11 OsPiccInitFelica ........................................................................................ 132
16.6.12 OsPiccIsoCommand ................................................................................. 132
16.6.13 OsPiccSetUserConfig ............................................................................... 132
16.6.14 OsPiccGetUserConfig............................................................................... 133
16.7 Note of touch screen and RF reader programming .............................................. 133
17
Communication Port ................................................................................................... 135
17.1 Data Definition..................................................................................................... 135
XII
17.2 Communication control ....................................................................................... 136
17.2.1 OsPortOpen ............................................................................................... 136
17.2.2 OsPortClose .............................................................................................. 137
17.2.3 OsPortSend ............................................................................................... 137
17.2.4 OsPortRecv ............................................................................................... 138
17.2.5 OsPortReset............................................................................................... 139
17.2.6 OsPortCheckTx ......................................................................................... 139
17.3 POSIX .................................................................................................................. 139
17.3.1 Open .......................................................................................................... 140
17.3.2 Read .......................................................................................................... 140
17.3.3 Write ......................................................................................................... 140
17.3.4 Close ......................................................................................................... 140
17.3.5 Query the buffer data of communication port........................................... 140
17.3.6 Clear the buffer data of communication port ............................................ 141
17.3.7 Set the configuration parameters of communication port ......................... 141
18
MODEM...................................................................................................................... 145
18.1 Return code list .................................................................................................... 145
18.2 Data structure ....................................................................................................... 153
18.3 OsModemOpen .................................................................................................... 158
18.4 OsModemClose.................................................................................................... 158
18.5 OsModemSwitchPower ....................................................................................... 158
18.6 OsModemConnect ............................................................................................... 159
18.7 OsModemCheck .................................................................................................. 160
18.8 OsModemExCmd ................................................................................................ 161
18.9 OsModemHangup ................................................................................................ 162
18.10
OsModemSend ................................................................................................. 163
18.11
OsModemRecv ................................................................................................. 163
18.12
OsPppomLogin................................................................................................. 164
18.13
OsPppomCheck ................................................................................................ 166
18.14
OsPppomLogout............................................................................................... 167
XIII
19
Network Communication ............................................................................................ 169
19.1 TCP programming ............................................................................................... 169
19.2 UDP programming ............................................................................................... 172
20
Network Configuration ............................................................................................... 175
20.1 Return code list .................................................................................................... 175
20.2 Data Definition..................................................................................................... 176
20.2.1 Physical channel list .................................................................................. 176
20.3 Network Configuration interface ......................................................................... 177
20.3.1 OsNetAddArp ........................................................................................... 177
20.3.2 OsNetPing ................................................................................................. 178
20.3.3 OsNetDns .................................................................................................. 178
20.3.4 OsNetSetConfig ........................................................................................ 179
20.3.5 OsNetGetConfig ....................................................................................... 181
20.3.6 OsNetStartDhcp ........................................................................................ 182
20.3.7 OsNetCheckDhcp ..................................................................................... 183
20.3.8 OsNetStopDhcp ........................................................................................ 183
20.3.9 OsNetSetRoute .......................................................................................... 183
20.3.10 OsNetGetRoute ......................................................................................... 184
20.3.11 OsPppoeLogin .......................................................................................... 184
20.3.12 OsPppoeCheck .......................................................................................... 185
20.3.13 OsPppoeLogout ........................................................................................ 185
21
GPRS/CDMA .............................................................................................................. 187
21.1 Return code list .................................................................................................... 187
21.2 Wirless module interface ..................................................................................... 188
21.2.1 OsWlLock ................................................................................................. 188
21.2.2 OsWlUnlock ............................................................................................. 189
21.2.3 OsWlInit .................................................................................................... 189
21.2.4 OsWlSwitchPower .................................................................................... 190
21.2.5 OsWlSwitchSleep ..................................................................................... 191
21.2.6 OsWlGetSignal ......................................................................................... 191
XIV
21.2.7 OsWlCheck ............................................................................................... 192
21.2.8 OsWlLogin ................................................................................................ 192
21.2.9 OsWlLoginEx ........................................................................................... 194
21.2.10 OsWlLogout ............................................................................................. 197
21.3 Wireless module information settings ................................................................. 197
21.3.1 OsWlSelSim .............................................................................................. 197
22
WIFI ............................................................................................................................ 198
22.1 Return code list .................................................................................................... 198
22.2 Encryption type List ............................................................................................. 198
22.3 Data Structure ...................................................................................................... 199
22.4 OsWifiOpen ......................................................................................................... 201
22.5 OsWifiClose ......................................................................................................... 201
22.6 OsWifiSwitchPower ............................................................................................ 202
22.7 OsWifiScan .......................................................................................................... 202
22.8 OsWifiConnect .................................................................................................... 203
22.9 OsWifiDisconnect ................................................................................................ 203
22.10
OsWifiCheck .................................................................................................... 204
22.11
OsWifiCmd ...................................................................................................... 205
23
File System .................................................................................................................. 206
24
System Information ..................................................................................................... 207
25
Audio ........................................................................................................................... 209
25.1 OsPlayWave ......................................................................................................... 209
26
Barcode........................................................................................................................ 212
26.1 General Definiton................................................................................................. 212
26.2 APIs...................................................................................................................... 212
26.2.1 OsScanOpen .............................................................................................. 212
26.2.2 OsScanRead .............................................................................................. 212
26.2.3 OsScanClose ............................................................................................. 213
27
Power Management ..................................................................................................... 214
27.1 OsCheckBattery ................................................................................................... 214
XV
27.2 OsCheckPowerSupply ......................................................................................... 215
27.3 OsSysSleep .......................................................................................................... 215
Appendix 1 PIN Block Format............................................................................................... 216
Appendix 2 EPS PINBLOCK Format .................................................................................... 220
Appendix 3 Register Table ..................................................................................................... 221
Appendix 4 Validity of models and contents ......................................................................... 223
XVI
Table List
Table 1 Abbreviation .......................................................................................................... 2
Table 2 General return code list ......................................................................................... 6
Table 3 System function return code list .......................................................................... 11
Table 4 Macro definitions of file types ............................................................................ 11
Table 5 Encryption and decryption return code list ......................................................... 27
Table 6 PED Return code list ........................................................................................... 33
Table 7 Key Types ........................................................................................................... 34
Table 8 Layout attributes of asterisk ................................................................................ 35
Table 9 The color values of asterisk................................................................................. 35
Table 10 Printer return code list ....................................................................................... 79
Table 11 MSR return code list ......................................................................................... 99
Table 12 ICC reader return code list .............................................................................. 104
Table 13 Macro definition list of communication ports ................................................. 135
Table 14 Return code list of USB port functions ........................................................... 135
Table 15 Modem return code list ................................................................................... 145
Table 16 Variable definition of ST_MODEM_SETUP ................................................. 154
Table 17 Network Configuration return code list .......................................................... 175
Table 18 GPRS/CDMA return code list ......................................................................... 187
XVII
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, different
from the system daemons. The Prolin applications, which are based on Prolin OS devices,
work in Prolin internal and run as an independent executive program.
Whereas, Prolin application can access all system features of Prolin OS, can save 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.
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 which provide by Prolin is based on calling Linux system 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
PAX Computer Technology (Shenzhen) Co., Ltd.
1
Prolin API Programming Guide
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.
In this document, the interface that begins with the prefix “Os” has been defined in osal.h of
SDK, unless otherwise specified.
1.3
Conditions
The prerequisites for this document are:
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
PAX Computer Technology (Shenzhen) Co., Ltd.
2
Prolin API Programming Guide
1.6
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
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.】
PAX Computer Technology (Shenzhen) Co., Ltd.
3
Prolin API Programming Guide
【Used for reminding the audience some place may have to pay
attention to, which may lead to exceptions or errors.】
【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.
4
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 1 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.
5
Prolin API Programming Guide
2.2 General return code
Table 2 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 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 not exists.
ERR_FILE_FORMAT
-1009
File format error.
ERR_USER_CANCEL
-1010
Users cancel.
ERR_NO_PORT
-1011
No communication port.
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.
6
Prolin API Programming Guide
2.3 Parameter
API parameters are divided into input parameters and output parameters.
String input and output parameters are ending with "\x00". String parameters must indicate
the length limit.
PAX Computer Technology (Shenzhen) Co., Ltd.
7
{ This page intentionally left blank }
Prolin API Programming Guide
3 Thread
PROLIN supports multithreaded development. The platform provides standard POSIX
threading library (pthread) for developers to use.
The pthread header file is located under the installation directory of Prolin SDK.
toolchains\arm-linux\arm-softfloat-linux-gnu\include\pthread.h
PAX Computer Technology (Shenzhen) Co., Ltd.
9
{ This page intentionally left blank }
Prolin API Programming Guide
4 System Function
4.1 Return code list
Table 3 System function return code list
Macro
Value
Description
ERR_FILE_NOT_FOUND
-2201
File has not 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 4 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.
11
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.
12
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.
Time structure
Parameters Time【Input】
Return
Instruction
RET_OK
Success
ERR_NEED_ADMIN
Need higher permissions.
ERR_INVALID_PARA
M
Invalid parameter
Only the main application has permission to set the time, otherwise, it returns
ERR_NEED_ADMIN.
4.3.2 OsGetTime
Prototype
void OsGetTime(ST_TIME *Time);
Function
Get the system time.
Parameters Time【Output】
Return
Time structure
None
Instruction
PAX Computer Technology (Shenzhen) Co., Ltd.
13
Prolin API Programming Guide
4.4 Timer
4.4.1 OsTimerSet
Prototype
int OsTimerSet(ST_TIMER *Timer,
unsigned long Ms);
Function
Set the timer.
Parameters
Return
Timer【Output】
Timer
Ms【Input】
Time【unit:ms】
RET_OK
Success
ERR_INVALID_PARA
M
Invalid parameter
Instruction
4.4.2 OsTimerCheck
Prototype
unsigned long OsTimerCheck(ST_TIMER *Timer);
Function
Check the remaining time.
Timer
Parameters Timer【Input】
Return
>=0
The remaining time【unit:ms】
ERR_INVALID_PARA
M
Invalid parameter
Instruction
4.5 Delay
4.5.1 OsSleep
Prototype
void OsSleep(unsigned int Ms);
Function
System delay, the process will not be interrupted by signal.
Parameters Ms 【Input】
Return
The delay time【unit:ms】
None
Instruction
4.6 Thread dormancy
The dormancy is realized by thread management. Kindly refer to the following code.
PAX Computer Technology (Shenzhen) Co., Ltd.
14
Prolin API Programming Guide
Example:
#include
static 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
Tag【Input】
LOG information tag
None
Set the LOG tag, and the default tag is null.
Instruction
Suggest to set it as an application name. It supports up to 32 bytes, when more
than it, just using the first 32 bytes.
When the Tag is an empty string or NULL, the OsLog() will not work..
PAX Computer Technology (Shenzhen) Co., Ltd.
15
Prolin API Programming Guide
4.7.2 OsLog
Prototype
int OsLog(LOG_T Prio,
const char *fmt,
…);
Function
Record the LOG information.
Parameters
Return
Prio【Input】
LOG type
fmt 【Input】
Format of log information
RET_OK
Success
ERR_INVALID_PAR
AM
Invalid parameter
Instruction
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. 【unit:ms】
4.9 Get Appliaction information
4.9.1 OsGetAppInfo
Prototype
int OsGetAppInfo(ST_APP_INFO AppInfo[],
int InfoCnt);
Function
Get the application information.
Parameters
Return
Instruction
AppInfo【Output】
Array of AppInfo structure
InfoCnt【Input】
The number of Apps that can be stored in the array
>=0
Returns the number of obtained App information
ERR_NEED_ADMIN
Need higher permissions.
ERR_INVALID_PAR
AM
Invalid parameter
Only the main application has permission to get the information.
PAX Computer Technology (Shenzhen) Co., Ltd.
16
Prolin API Programming Guide
When the number of existing applications are more than InfoCnt, the InfoCnt
shall prevail.
4.10 Buzzer
4.10.1 OsBeep
Prototype
void OsBeep(int ToneType, int DurationMs)；
Function
The buzzer.
ToneType 【Input】 Tone type. The value ranges from 1 to 7.
Parameters
Return
Instruction
Duration【unit:ms】
The value ranges from 10 to 10000.
DurationMs
【Input】
None
If ToneType<1, set it as 1, if ToneType>7, set it as 7.
If DurationMs<10, set it as 10, if DurationMs>10000, set it as 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
Parameters
Return
Switch to a specified sub-application.
AppId【Input】
sub-application ID
Argv【Input】
Argument list, it can be NULL
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【Input】
Callback function of the standard error information
RET_OK
Success
ERR_ACCESS_DENY
Access denied
ERR_APP_MODE
Mode Error
PAX Computer Technology (Shenzhen) Co., Ltd.
17
Prolin API Programming Guide
ERR_INVALID_PARAM
Invalid parameter
ERR_NEED_ADMIN
Need higher permissions.
Only the main application has permission to switch application, Otherwise, it
returns ERR_NEED_ADMIN.
Switch to a specified sub-application.
This will output the standard output information and standard error information
Instruction
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 obsolete, and
the related functions can be realized by calling OsRegGetValue ().
4.12.1 OsRegSetValue
Prototype
Function
Parameters
Return
Instruction
int OsRegSetValue(const char *Key,
const char *Value);
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 begin with “persist.sys.” For
example, “persist.sys.app0.pic”.
4.12.2 OsRegGetValue
Prototype
int OsRegGetValue(const char *Key,
PAX Computer Technology (Shenzhen) Co., Ltd.
18
Prolin API Programming Guide
Function
Parameters
Return
Instruction
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.
>=0
Read the string length
ERR_INVALID_PARAM
Invalid Parameters
The system configuration name can only be set begin with “ro.fac.” or
“persist.sys.” About the “ro.fac.”, users can refer to register table.
If the query parameter does not exist, or the parameter value is empty, and then
returns 0, the output parameter Value is “ ”.
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.
When FileType is FILE_TYPE_PUB_KEY, Name gets
the value from "uspuk0" to "uspuk8", and it represents
the user public key ranged from 0 to 8.
Name
【Input】 When FileType is FILE_TYPE_APP_PARAM and
Name is the Application ID of parameter file.
When FileType is the other type, Name is invalid, and it
can be NULL.
Parameters
FileName 【Input】 The filename which needs to be installed.
FileType
Return
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_FOUND
FileName does not exist.
PAX Computer Technology (Shenzhen) Co., Ltd.
19
Prolin API Programming Guide
Instruction
ERR_FILE_FORMAT
FileName format error.
ERR_INVALID_PARAM
Invalid Parameters
ERR_VERIFY_SIGN_FAIL
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.
4.13.2 OsUninstallFile
Prototype
int OsUninstallFile(const char *AppName,
int FileType);
Function
Uninstall applications and system files.
AppName
【Input】
Parameters
1. When the FileType is FILE_TYPE_APP, it means
AppName is the Application ID which needs to be
deleted.
2. When the FileType is FILE_TYPE_ SYS_LIB,
AppName is the name of system library.
FileType
Return
Instruction
FILE_TYPE_APP (Application package, the
application has been 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.
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 should prompt the user to restart the
terminal to complete the uninstallation.
4.14 Verify signature
The PROLIN provides a function to verify the file signature. It should use this interface to
verify the signature before using the files.
4.14.1 OsVerifySign
Prototype
int OsVerifySign(const char *FileName,
int PUKType);
PAX Computer Technology (Shenzhen) Co., Ltd.
20
Prolin API Programming Guide
Function
Parameters
Return
Instruction
Verify the file signature specified by FileName is legal or not, the signature
data is included in the file.
FileName
【Input】
The file name which contains the path.
PUKType
【Input】
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
verification for user application.
RET_OK
Success
ERR_VERIFY_SIGN_FAIL
Illegal signature.
ERR_FILE_NOT_EXIST
The file does not exist.
ERR_INVALID_PARAM
Invalid parameter
1. 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.
2. 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.14.2 OsVerifySignExternal
int OsVerifySignExternal(const char *FileName,
Prototype
const void *SignData,
int PUKType);
Function
Verify the file signature specified by FileName is legal or not. The file does not
include the signature data.
FileName
【Input】
SignData
【Input】
Parameters
PUKType
【Input】
PAX Computer Technology (Shenzhen) Co., Ltd.
The file name which contains the path.
Signature data, it has 284 bytes.
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.
21
Prolin API Programming Guide
PUK_TYPE_USER0 or PUK_TYPE_USER
The public key of users, it is used to do the signature
verification for user application.
Return
Instruction
RET_OK
Success
ERR_VERIFY_SIGN_FAIL
Illegal signature.
ERR_FILE_NOT_EXIST
The file does not exist.
ERR_INVALID_PARAM
Invalid parameter
1. 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.
2. In order to avoid repeating validation, it should use this function to
verify the legitimacy of the file before installing the file. (System will
verify automatically in OsInstallFile ()).
4.15 Get system version
This interface is reserved for future used.
4.15.1 OsGetSysVer
Prototype
void OsGetSysVer(int VerType,
char *Version);
Function
Read information of the system version.
Version types:
VerType
Parameters
Version
【Output】
PAX Computer Technology (Shenzhen) Co., Ltd.
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 <=31 bytes)
22
Prolin API Programming Guide
Return
None
1. If Version[0] is equal to 0x00, it means the module does not exist,
2. The buffer space of version must be >= 31 bytes.
Instruction
4.16 Determine whether on the base
PROLIN supports a function to determine whether the handset is on the base or not.
4.16.1 OsOnBase
Prototype
int OsOnBase(void) x ;
Function
Determines whether the handset is on the base.
Parameters
Return
Instruction
None
1
yes
0
no
This function is effective only to handsets which on the base.
4.17 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.17.1 OsSaveCrashReport
Prototype
void OsSaveCrashReport(ing sig);
Function
Save the crash report.
Parameters
Return
Instruction
Sig
Signal value
None
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,
calling
OsSaveCrashReport(sig) to save the error message. For example:
int mysighandler(int sig)
{
do_something();
OsSaveCrashReport(sig);
}
PAX Computer Technology (Shenzhen) Co., Ltd.
23
Prolin API Programming Guide
The recommended signals are SIGILL, SIGABRT, SIGBUS, SIGFPE,
SIGSEGV and SIGSTKFLT.
After calling this function, it will ignore the signal which is corresponding 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.
4.18 Mount and Unmount the external file system
4.18.1 OsMount
int OsMount(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 located in /dev/block/, and the path length
cannot exceed 128 bytes.
Target【Input】
The target file directory that will mount to, it must be in the
/mnt/ directory, and the path length cannot exceed 128
bytes.
FileSystemType
【Input】
File system type that needs to be mounted, it can be as
‘vfat’.
MountFlags
【Input】
Mount flag, it can be the combinations of the following
flags:
~MS_DIRSYNC: Synchronize the directory updates
MS_MANDLOCK: Allow the mandatory locks on files
Parameters
MS_MOVE: Move the subdirectory tree
MS_NOATIME: Need not to update the access time
MS_NODEV: Don't allow access to device file.
MS_NODIRATIME: Don't allow update 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: Specify the file system as read-only.
MS_RELATIME: When a file is accessed, if the last access
time (atime) is less than or equal to the last modification
PAX Computer Technology (Shenzhen) Co., Ltd.
24
Prolin API Programming Guide
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
MS_STRICTATIME: Always updating the last access time
(atime)
MS_SYNCHRONOUS: Synchronize the file updates
Return
Instruction
Data【Input】
The user-defined additional data
RET_OK
Success
ERR_INVALID
_PARAM
Invalid parameter
ERR_STR_LEN
The stringR_LENameis overlength.
ERR_NEED_AD
MIN
Need higher permissions.
Only the main application can mount, otherwise it fails to mount and returns
ERR_NEED_ADMIN.
4.18.2 OsUmount
Prototype
Function
int OsUmount(const char *Target,
int Flags);
Unmount the file system file system.
Target【Input】
The file system that needs to unmount, it must be
in the /mnt/ directory, and the path length cannot
exceed 128 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.
Parameters
MNT_EXPIRE:The mount point is marked as
expired
UMOUNT_NOFOLLOW: If the target is a
symbolic link, do not reduce the reference count.
RET_OK
Return
Success
ERR_INVALID_PAR Invalid parameter
AM
PAX Computer Technology (Shenzhen) Co., Ltd.
25
Prolin API Programming Guide
Instruction
ERR_STR_LEN
The string length is overlength.
ERR_NEED_ADMIN
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.
26
Prolin API Programming Guide
5 Encryption and
Decryption
5.1 Return code list
Table 5 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
PAX Computer Technology (Shenzhen) Co., Ltd.
Storing the pointer of random number.
27
Prolin API Programming Guide
【Output】
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_384 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.
28
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 of the 8 bytes.
Input 【Input】
8 bytes input data
Output【Output】 8 bytes output data
Parameters
Return
Instruction
DesKey【Input】 DES/TDES key
KeyLen
8, 16 or 24 (bytes)
Mode
0-decryption;
1-encryption.
None
The encryption or decryption should be according to the mode selection.
If the parameters are invalid, there will be no any operations.
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
Parameters
Perform AES encryption and decryption operation.
Input 【Input】
PAX Computer Technology (Shenzhen) Co., Ltd.
16 bytes input data
29
Prolin API Programming Guide
Output【Output】 16 bytes output data
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 RSA algorithm
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 * Modulus,
int ModulusLen,
const unsigned char *Exp,
Prototype
int ExpLen,
const unsigned char *DataIn,
unsigned char *DataOut);
Function
Parameters
Perform RSA encryption and decryption operation.
Modulus【Input】
Pointer that used to store the RSA algorithm
modulus buffer (n=p*q). High byte first.
ModulusLen
Modulus length(byte)
Exp【Input】
Pointer to the exponent buffer in RSA operation.
High byte first.
ExpLen
Exponent length.(byte)
DataIn【Input】
Pointer to input data buffer, length is the same as
module.
PAX Computer Technology (Shenzhen) Co., Ltd.
30
Prolin API Programming Guide
Return
DataOut【Output】
Pointer to output data buffer, length is the same
as module.
RET_OK
Success
ERR_INVALID_PARAM
Invalid parameter.
ERR_DATA_TOO_BIG
ExpLen is bigger than ModulusLen.
1.
Instruction
2.
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; for
public key, does decryption.
This function can perform RSA operation with the length of no more than
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【Output】
Private key exponent. (High byte first)
ModulusLen
Modulus length. (It can be 64, 128, 256 (bytes)).
Parameters
PubExp【Input】
Public key exponent.
It only can be:”\x00\x00\x00\x03” or “\x00\x01\x00\x01”
Return
RET_OK
Success
ERR_INVALID_PARAM
Invalid Parameters
ERR_GEN_RANDOM
Fail to generate random data.
ERR_GEN_FAIL
Fail to generate.
PAX Computer Technology (Shenzhen) Co., Ltd.
31
Prolin API Programming Guide
Instruction By calling this interface, it will randomly generate a RSA Key pair with a specifying
exponent and modulus.
PAX Computer Technology (Shenzhen) Co., Ltd.
32
Prolin API Programming Guide
6 PED
PROLIN provides a series of PED interface, including built-in pinpad, MK / SK, DUKPT,
RSA and other related interfaces.
6.1 Return code list
Table 6 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
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 to enter PIN.
ERR_PED_WAIT_INTERVAL
-3807
Calling function interval is less
than minimum interval
time.(CalculatePINBLOCK/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.
ERR_PED_PIN_LEN_ERR
-3811
The input PIN length is not equal
to the expected PIN length.
PAX Computer Technology (Shenzhen) Co., Ltd.
33
Prolin API Programming Guide
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
IC card is not initialized.
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 error.
ERR_PED_SRCKEY_TYPE_ERR
-3825
Source key type error.
ERR_PED_UNSPT_CMD
-3826
Command 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.
6.2 Data Definition
6.2.1 Key type
Table 7 Key Types
PAX Computer Technology (Shenzhen) Co., Ltd.
34
Prolin API Programming Guide
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 8 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 9 The color values of asterisk
Macro
RGB(_r, _g, _b)
Value
...
Description
According to the inputted
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{
int ModulusLen;
/*Modulus length(bits) */
unsigned char Modulus[512];
/*Modulus, if the length of modulus <512
bytes, store from right, add 0x00 in left. */
int ExponentLen;
/* Exponent Length (bits) */
PAX Computer Technology (Shenzhen) Co., Ltd.
35
Prolin API Programming Guide
unsigned char Exponent
[512];
unsigned char KeyInfo[128];
/* When exponent <512 bytes, add 0x00
in left.*/
/* RSA key information */
}ST_RSA_KEY;
6.3.2 RSA key structure for verifying the cipher text 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 operated only after open device
successfully.
6.4.2 OsPedGetVer
Prototype
int OsPedGetVer (unsigned char * PedVer);
PAX Computer Technology (Shenzhen) Co., Ltd.
36
Prolin API Programming Guide
Function
Parameters
Return
Return to PED version.
PedVer【Output】
PED version, buffer size is 6 bytes.
RET_OK
Success
ERR_DEV_NOT_OPEN
PED device is not open.
ERR_INVALID_PARAM
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
1000 (1s)
set
to
>600000
Automatically set
600000 (10 min)
to
=0xffffffff
No change in current
settings.
TpkIntervalMs
RET_OK
Success
ERR_DEV_NOT_OPEN
PED device is not open.
ERR_INVALID_PARAM
Invalid parameter.
Calculate the interval time of PINBLOCK:
It can only be called 4 times, if the default time is 120-second, it means default
value of TPKIntervalTimeMs is 30-second, after reset by calling this function,
it is limited to call 4 times during the 4*TPKIntervalTimeMs time, for example,
if the TPKIntervalTimeMs is 20000 (ms), then within 80 seconds it can only be
called 4 times.
This function is valid when open/close the machine. For example, set it only
can be called 4 times within 80 seconds, if reboot the machine after the third
time, then immediately to call 2 times in succession, these five times were all
within 80 seconds, but the fifth time could not be successful, and it will prompt
to wait.
PAX Computer Technology (Shenzhen) Co., Ltd.
37
Prolin API Programming Guide
6.4.4 OsPedVerifyPlainPin
int OsPedVerifyPlainPin(int IccSlot,
const char * ExpPinLen,
Prototype
int Mode,
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
ExpPinLen【Input】
Application enumerates all the possible lengths
of PIN, used the ‘,’ to separate each number of
length. If it is allowed to input 4 or 6 digits, or
enter without pressing any passwords, the string
should be ‘0, 4, 6’.
0 means that user can press ‘Enter’ to return but
without inputting any digits.
Parameters
Mode
0x00, IC card command mode. Currently
supports EMV2000 only.
The timeout of PIN input [ms]
TimeoutMs
Return
Instruction
Maximum is 300000.
0 means no timeout, and the PED without
timeout control.
IccRsp【Output】
2 bytes, card
SWA++SWB)
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 .
1.
response
code
(2
bytes:
Prompt cardholder to input PIN;
PAX Computer Technology (Shenzhen) Co., Ltd.
38
Prolin API Programming Guide
2.
3.
Prompt cardholder that it is processing;
Convert plaintext PIN to PIN BLOCK.
Use OsIccexchange () to do the verification interaction with the card, as
follows:
ST_APDU_REQ apdu_s;
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 );
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 * IccRspOut);
Function
Verify offline enciphered PIN.
Get plaintext PIN, use RsaPinKey provided by the application to encrypt
plaintext PIN according to EMV standards.
According to card command and card slot number provided by application, and
then sending 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, used the ‘,’ to separate each number of
length. If it is allowed to input 4 or 6 digits, or
Parameters
PAX Computer Technology (Shenzhen) Co., Ltd.
39
Prolin API Programming Guide
enter without pressing any passwords, the string
should be set as ‘0, 4, 6’.
0 means that user can press ‘Enter’ to return but
without inputting any digits.
Mode
0x00, currently supports EMV2000 only.
The timeout of PIN input [ms]
Maximum is 300000.
TimeoutMs
0 means no timeout, and the PED without
timeout control.
2 bytes
IccRsp【Output】
Return
Card response code (2 bytes: SWA+SWB)
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 .
Encryption algorithm:
Use the public key, and apply RSA functions to the following data listed in the
table to get enciphered PIN.
Name
Instruction
Note
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. Prompt message for PIN input;
2. Prompt cardholder that it is processing;
3. Convert plaintext PIN to PIN BLOCK;
4. Generate data, used for encryption (listed in above table)
5. 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;
PAX Computer Technology (Shenzhen) Co., Ltd.
40
Prolin API Programming Guide
memcpy (apdu_s.cmd, icc_command, 4);
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
Success.
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
KeyFlag
PAX Computer Technology (Shenzhen) Co., Ltd.
0x00:
The PIN has already been cleared or no input PIN. By
keep pressing the CLEAR button will make 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,
OsPedVerifyCipherPin etc), press CLEAR button is to
clear the latest input PIN digit by digit. The CLEAR
button is ineffective after clearing the entire PIN, and it
will not exit the PIN input function.
0x02:
It is allowed to press ATM4 button to end the PIN input.
41
Prolin API Programming Guide
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.)
Return
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
During PIN input, 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);
Function
Close the PED device.
Parameters
None
Return
None
Instruction
This function should be called to close device before the program exits.
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
KeyBlock【Intput】
PAX Computer Technology (Shenzhen) Co., Ltd.
1 byte
Format: 0x03
42
Prolin API Programming Guide
SrcKeyType:
1 byte
PED_TLK
PED_TMK
PED_TPK/PED_TAK/PED_TDK
SrcKeyIdx:
When SrcKeyType = PED_TLK,
then SrcKeyIdx = 1;
1 byte
When SrcKeyType = PED_TMK,
then SrcKeyIdx = [1~100]
When writing in plaintext,
SrcKeyIdx = 0
DstKeyIdx:
When DstKeyType = PED_TLK,
then DstKeyIdx = 1;
1 byte
When DstKeyType = PED_TMK,
then DstKeyIdx = [1~100];
When DstKeyType = PED_TPK or
PED_TAK or PED_TDK,
Then DstKeyIdx = [1~100].
7 bytes
Reserved domain. Random number.
DstKeyType:
1 byte
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
KcvMode:
1 byte
PAX Computer Technology (Shenzhen) Co., Ltd.
0x00: No authentication
0x01:Performs
DES/TDES
43
Prolin API Programming Guide
encryption on 8-byte 0x00, and use
first 3 bytes in ciphertext as KCV.
0x02:Firstly, performs parity check,
then doing DES/TDES encryption
on
“\x12\x34\x56\x78\x90\x12\x34\x5
6”, and use first 3 bytes in
ciphertext as KCV.
0x03:Transfers in a string of
KcvData, use source key to
perform specified mode MAC on
[DstKeyValue + KcvData], and use
the result as KCV.
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.
128
bytes
When KcvMode = 0x00, padding
with random numbers.
8 bytes
10 bytes
Return
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.
44
Prolin API Programming Guide
Instruction
Writing the ciphertext and plaintext to the specific index position of the specific
key type area. Using this function have following key points:
1. When SrcKeyIdx=0, system considers that the DstKeyValue is the
plaintext of key and does not judge SrcKeyType and SrcKeyIdx.
Directly write the DstKeyValue to DstKeyIdx in DstKeyType area.
2. Only when PED_TLK does not exist, to type-in plaintext 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 of 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 or 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.
a) If DstKeyType=PED_TPK, the key only be used to encrypt PIN
Block.
b) If DstKeyType=PED_TAK, the key can only be used for MAC
encryption.
c) 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.
1 byte
Format: 0x03
SrcKeyType:
1 byte
Parameters
PED_TLK
SrcKeyIdx:
KeyBlock【Intput】
When SrcKeyType = PED_TLK,
1 byte
then SrcKeyIdx = 1;
When plaintext writing,
PAX Computer Technology (Shenzhen) Co., Ltd.
45
Prolin API Programming Guide
SrcKeyIdx = 0.
1 byte
DstKeyIdx:
DstKeyIdx = [1~100];
7 bytes
Reserved domain. Random number.
DstKeyType:
1 byte
1 byte
24 bytes
PED_TIK
DstKeyLen: 8/16
DstKeyValue
The destination key plaintext / ciphertext
KcvMode:
1 byte
0x00: No authentication
0x01:Performs
DES/TDES
encryption on the 8-bytes 0x00, and
use 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\x5
6”, and use first 3 bytes in
ciphertext as KCV.
0x03: Sends in data KcvData, use
source key to perform specified
mode
of
MAC
on
[aucDesKeyValue + KcvData], and
use the result as KCV.
KcvData:
128
bytes
When
the
KcvMode
is
0x00/0x01/0x02, padding with
random numbers.
When the 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.
When KcvMode = 0x00, padding
with random numbers.
8 bytes
When
KcvMode
=
0x01/0x02/0x03, KcvValue point
PAX Computer Technology (Shenzhen) Co., Ltd.
46
Prolin API Programming Guide
to the KCV value.
10 bytes
Return
Instruction
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. Using this function has following key points:
1. When SrcKeyIdx=0, system considers that the DstKeyValue is the
plaintext of key and will not judge 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 cryptograph
thus decrypts it bySrcKeyIdx key and writes the key to DstKeyIdx.
DstKeyType >= SrcKeyType.
5. 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.
6. 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
Uses the key plaintext that specified by source key index and key type, to do
operation with a string of data and writes the result to the location, specified by
the destination key index with the same key type.
PED_TMK
Parameters
KeyType
PAX Computer Technology (Shenzhen) Co., Ltd.
PED_TPK
47
Prolin API Programming Guide
PED_TAK
PED_TDK
Return
Instruction
SrcKeyIdx
The source key index
DstKeyIdx
The destination key index
KeyVar【Input】
24 bytes.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_OPEN
PED device is not open.
ERR_INVALID_PARAM
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,
int fontSize,
Prototype
int fontColor,
uchar align);
Function
Sets how to display the layout attributes of asterisk while inputting PIN.
x
X-coordinate
y
Y-coordinate
Font size of asterisk:
fontSize = 16, represents the character has 16
dots;
Parameters
fontSize = 24, represents the character has 24
fontSize
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
PAX Computer Technology (Shenzhen) Co., Ltd.
48
Prolin API Programming Guide
it is not relevant to system installed font.
Font color of asterisk.
fontColor
Using the macro definition RGB(_r, _g, _b)
and according to the inputted three-primary
colors to generate color value with 16-bit.
Alignment:
PED_ASTERISK_ALIGN_LEFT;
align
PED_ASTERISK_ALIGN_CENTER
PED_ASTERISK_ALIGN_RIGHT
Return
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 .
1. The PIN inputting interface is displayed by the application, this
function will only display asterisk.
Instruction
2. It needs to call this function to set the displaying layout of asterisk
before
using
PedVerifyPlainPin,
PedVerifyCipherPin,
PedGetPinBlock andPedGetPinDukpt.
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 BLOCKin a specific time.
Input the PIN in the length specified by ExpPinLenIn, output the PIN BLOCK
generated by algorithm encryption specified by Mode.
KeyIdx
[1-100]
Index of TPK.
1.
Parameters
DataIn【Input】
PAX Computer Technology (Shenzhen) Co., Ltd.
2.
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
49
Prolin API Programming Guide
3.
4.
Return
Instruction
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]
ExpPinLen【Input】
Enumeration of 0-12
Application enumerates all possible lengths of
PIN. ‘,’ will be used to separate each number of
length. If no PIN, or 4 or 6 digits of PIN are
allowed, the string will be set as ‘0, 4, 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【Output】
8 bytes. Point to the generated PINBlock.
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 .
Press ‘CANCEL’ to cancel input.
6.5.6 OsPedUpdatePinBlock
int OsPedUpdatePinBlock (int UpdateFlag,
const unsigned char * KeyInfo,
const unsigned char * DataIn,
Prototype
unsigned char * PinBlock,
int Mode);
Function
Parameters
Getting PINBlock again and choose to replace TPK.
UpdateFlag
PAX Computer Technology (Shenzhen) Co., Ltd.
0:
Do not replace TPK,
Non zero: Replace TPK
50
Prolin API Programming Guide
KeyInfo【Input】
DataIn【Input】
PinBlock
【Output】
Return
Instruction
It has 184 bytes, details refer to the KeyBlock
definition in OsPedWriteKey().
When UpdateFlag is 0, only ucDstKeyIdx is valid,
using ucDstKeyIdx, specify TPKand recalculate
PINBLOCK.
When UpdateFlag is 1,please refer to the OsWriteKey
When Mode=0x03,
Transaction serial number ISN [6 Bytes, ASCII code]
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
Parameters
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
1~100 TAK index
DataIn【Input】
<=1024 bytes
The data package that needs to do the MAC operation.
DataInLen
The length of data package. If the length is not multiple of
8, 0x00 will be padded automatically.
PAX Computer Technology (Shenzhen) Co., Ltd.
51
Prolin API Programming Guide
Mac【Output】
8 bytes, output of MAC.
1.
2.
Mode
3.
Return
Instruction
0x00: Does the DES/TDES encryption for BLOCK1
by using MAC key. Does the DES/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.
0x01: 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
DES/TDES encryption for the result.
0x02: ANSIX9.19 standard. Does 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 the DES encryption by using
TAK again. Does it in turn and get the 8 bytes
encryption result. Uses DES/TDES to encrypt in 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.
PAX Computer Technology (Shenzhen) Co., Ltd.
52
Prolin API Programming Guide
KeyIdx
TDK index.1~100.
Used for CBC/OFB encryption or decryption. If set to
NULL, it will set the initialization vector as
InitVecto【Input】 “\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.
Parameters
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.
0x00: ECB Decryption
0x01: ECB Encryption
0x02: CBC Decryption
0x03: CBC Encryption
0x04: OFB Decryption
0x05: OFB Encryption
Mode
Return
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
Using DES or TDES depends on the key length.
6.5.9 OsPedGetKcv
int OsPedGetKcv (int KeyType,
Prototype
int KeyIdx,
int KcvMode,
PAX Computer Technology (Shenzhen) Co., Ltd.
53
Prolin API Programming Guide
int KcvDataLen,
unsigned char * KcvData,
unsigned char * Kcv);
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
TIK-injection.
Function
PED_TLK
PED_TMK
PED_TAK
KeyType
PED_TPK
PED_TDK
PED_TIK
Parameters
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.
Kcv【Output】
Return
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
Invalid parameter.
PAX Computer Technology (Shenzhen) Co., Ltd.
54
Prolin API Programming Guide
_PARAM
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
and save it as the specified key of DstToKeyIdx.
Types of the source key.
PED_TLK
PED_TMK
SrcKeyType
PED_TAK
PED_TPK
PED_TDK
Parameters
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.
Types of the destination key
PED_TLK
DstKeyType
PED_TMK
PED_TAK
PAX Computer Technology (Shenzhen) Co., Ltd.
55
Prolin API Programming Guide
PED_TPK
PED_TDK
DstFromKeyIdx
Source index of the destination key
DstToKeyIdx
Destination index of the destination key
Mode
Return
Instruction
0x00: DES/TDES decryption
0x01: DES/TDES 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 .
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,
const char * ExpPinLen,
int Mode,
Prototype
unsigned long TimeoutMs,
unsigned char * Ksn,
unsigned char * PinBlock);
Function
Parameters
Scans the input PIN in a specified time, and outputs the PINBlock which
generated by computing the PIN key of DUKPT.
GroupIdx
PAX Computer Technology (Shenzhen) Co., Ltd.
1~100:DUKPT group ID
56
Prolin API Programming Guide
DataIn【Input】
1. If Mode=0x20, DataIn is the 16 bytes primary
account number after shifting.
2. 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.)
3. If Mode=0x22, DataIn is the 16 bytes primary
account number after shifting.
4. 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 number of lengths. If no
ExpPinLen【Input】 PIN, or 4 or 6 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.
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.
Mode
TimeoutMs
The timeout of PIN entry [ms]
Maximum is 300000ms.
0 means there is no timeout time, not doing timeout
control for PED.
Ksn【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
PAX Computer Technology (Shenzhen) Co., Ltd.
57
Prolin API Programming Guide
BLOCK for once.
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
1~100:DUKPT group ID
DataIn【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.
0x20: Does 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.
2.
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.
3.
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 BLOCK 2 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.
Parameters
Mode
PAX Computer Technology (Shenzhen) Co., Ltd.
58
Prolin API Programming Guide
Return
Instruction
4.
0x20/0x21/0x22: KSN not plus 1 automatically.
5.
0x40/0x41/0x42: The MAC calculation method is
the same with 0x20/0x21/0x22.
6.
0x40/0x41/0x42: Chooses to response the MAC key.
7.
0x20/0x21/0x22: KSN chooses to request and
response MAC key
8.
0x40/0x41/0x42: KSN not plus 1 automatically.
9.
Other values are reserved for extended MAC
algorithm.
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
Parameters
Uses DES/MAC key of DUKPT to do encryption and decryption for the input
data.
GroupIdx
PAX Computer Technology (Shenzhen) Co., Ltd.
1~100:DUKPT group ID
59
Prolin API Programming Guide
0x00 Uses the requests and responses of MAC key
0x01 Uses DES key of DUKPT
KeyVarType【Input】 0x02 Uses the PIN variant to to encrypt the data, and it
is only available for EBC encryption, that means
the Mode can only be 1.
InitVector【Input】
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
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 【Input】
Input data.
DataOut【Output】
Points to the data that has been calculated.
Ksn【Output】
Current KSN.(10 bytes)
0x00: ECB decryption
0x01: ECB encryption
0x02: CBC decryption
0x03: CBC encryption
0x04: OFB decryption
0x05: OFB encryption
Mode
Return
Instruction
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 .
When KSN is unchanged, a group of the DUKPT Data key can do DES
operations for 256 times at most.
6.6.4 OsPedGetKsnDukpt
int OsPedGetKsnDukpt (int GroupIdx,
Prototype
Function
unsigned char * Ksn);
Reads the current KSN value.
PAX Computer Technology (Shenzhen) Co., Ltd.
60
Prolin API Programming Guide
Parameters
Return
GroupIdx
1-100: DUKPT group ID
Ksn【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
_OPEN
PED device is not 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
Parameters
ST_RSA_KEY * RsaKey);
Reads the RSA public key.
RsaKeyIdx
PAX Computer Technology (Shenzhen) Co., Ltd.
1~10: Index of RSA Key.
61
Prolin API Programming Guide
Return
Instruction
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
Parameters
Return
Instruction
ST_RSA_KEY * RsaKey);
Inject RSA key into the PED.
RsaKeyIdx
1~10: Index of RSA Key.
RsaKey【Input】
RSA public key. 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
key if the length equals to modulus.
1. Currently it does not support that RSA key whose length is
more than 256 bytes.
2.
RSA key can be rewritten at any time.
PAX Computer Technology (Shenzhen) Co., Ltd.
62
Prolin API Programming Guide
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, and it is the same with the
RSA modulus.
64 bytes or 128 bytes or 256 bytes.
Parameters
Return
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
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
Parameters
unsigned char * CipherRsaKey);
Reads the ciphertext of RSA key.
RsaKeyIdx
PAX Computer Technology (Shenzhen) Co., Ltd.
1~10: Index of RSA Key.
63
Prolin API Programming Guide
CipherRsaKey
【Output】
Return
Points to the ciphertext data of RSA key.
>0
The byte length of the RSA ciphertext.
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.5 OsPedWriteCipherRsaKey
int OsPedWriteCipherRsaKey (int RsaKeyIdx,
int CipherRsaKeyLen,
Prototype
unsigned char * CipherRsaKey);
Function
Writes the ciphertext of RSA key.
RsaKeyIdx
1~10: Index of RSA Key.
CipherRsaKeyLen
The byte length of the ciphertext data of RSA key.
Parameters
CipherRsaKey
【Input】
Return
Points to the ciphertext data of RSA 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 .
Instruction
PAX Computer Technology (Shenzhen) Co., Ltd.
64
Prolin API Programming Guide
6.8 AES
6.8.1 OsPedWriteAesKey
Prototype
int OsPedWriteAesKey (const unsigned char * KeyBlock);
Function
Write inan AES key and use KCV to check the key correction.
1 byte
Format: 0x03
SrcKeyType:
1 byte
Parameters
KeyBlock【Input】
PED_TLK
PED_TMK
1 byte
SrcKeyIdx:
When SrcKeyType = PED_TLK,
then SrcKeyIdx = 1;
When SrcKeyType = PED_TMK,
then 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
DstKeyValue:
32 bytes
The destination
cipher-text.
key
plain-text
or
KcvMode:
1 byte
PAX Computer Technology (Shenzhen) Co., Ltd.
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\x5
6\x12\x34\x56\x78\x90\x12\x34\x5
6”, 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],
65
Prolin API Programming Guide
and use the result as KCV.
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 participates in the
calculation, the rest is KCV data.
The first byte after the KCV data
represents the MAC operation
mode.
128 bytes
When KcvMode = 0x00, padding
with random numbers.
8 bytes
2 bytes
When
KcvMode
=0x01/0x02/0x03,KcvValue point
to the KCV value.
Padding with random number.
RET_OK
Success
ERR_DEV_NOT_
OPEN
Device is not open.
ERR_INVALID_P
ARAM
Invalid parameter.
Others
Refer to the PED Return code list.
Return
Instruction
Writing the cryptograph and plaintext of an AES key to the specific index
position of the AES area. Using this function have 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 in
valid parameters, otherwise an error will occur.
PAX Computer Technology (Shenzhen) Co., Ltd.
66
Prolin API Programming Guide
6.8.2 OsPedAes
int OsPedAes(intKeyIdx,
unsigned char * InitVector,
const unsigned char *DataIn,
Prototype
intDataInLen,
unsigned char *DataOut,
int Mode);
Function
Parameters
Uses the specified AES key stored in PED to do the AES encryption or
decryption for the data and then output cipher-text or plain-text.
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\x0
【Input】 0\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】 Data length. It should be <=1024, and multiple of
DataOut
Mode
16.
【Output】 Points to the data that has been calculated.
0x00: ECB Decryption
0x01: ECB Encryption
0x02: CBC Decryption
0x03: CBC Encryption
0x04: OFB Decryption
0x05: OFB Encryption
【Input】
RET_OK
Success
ERR_DEV_NOT_OPEN
Device is not open.
ERR_INVALID_PARAM
Invalid parameter.
Others
Refer to the PED Return code list .
Return
Instruction
PAX Computer Technology (Shenzhen) Co., Ltd.
67
{ 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, 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 effectiveness 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,
2.
Get the fixed screen information by ioctl,
3.
Get the variable screen information by ioctl,
4.
Map device memory to the process space by mmap,
5.
Write the FrameBuffer
int open_screen(void)
{
char vtname[128];
PAX Computer Technology (Shenzhen) Co., Ltd.
69
Prolin API Programming Guide
int fd, nr;
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;
}
PAX Computer Technology (Shenzhen) Co., Ltd.
70
Prolin API Programming Guide
1.
Close the FrameBuffer device
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, darkest: 0, lightest: 7].
Default value: 4.
Other values: no action.
None
Only available on monochrome LCD models.
7.2 OsScrBrightness
Prototype
void OsScrBrightness(int Brightness);
Function
Sets the screen brightness.
Parameters
Return
Brightness
Brightness level[0~10, 0 represents turn off the backlight.
10 represents the lightest value. All brightness values are
visible]
Default value: 8.
Other values: no action.
None
Instruction
PAX Computer Technology (Shenzhen) Co., Ltd.
71
Prolin API Programming Guide
7.3 OsScrGetSize
Prototype
Function
void OsScrGetSize(int *Width,
int *Height);
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 does not apply to the GUI application.
PAX Computer Technology (Shenzhen) Co., Ltd.
72
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.
73
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.
Details refer to the following examples of calling the input subsystem:
#include
#include
#include
#include
static int event0_fd = -1;
struct input_event ev0[64];
//for handling event0, mouse/key/ts
static int handle_event0() {
int button = 0, realx = 0, realy = 0, i, rd;
rd = read(event0_fd, ev0, sizeof(struct input_event) * 64);
if ( rd < sizeof(struct input_event) ) return 0;
for (i = 0; i < rd / sizeof(struct input_event); i++) {
printf("", ev0[i].type, ev0[i].code, ev0[i].value);
PAX Computer Technology (Shenzhen) Co., Ltd.
74
Prolin API Programming Guide
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));
event0_fd = open("/dev/input/event0", O_RDWR);
if ( event0_fd < 0 )
return -1;
while ( done ) {
printf("begin handel_event0...\n");
done = handle_event0();
printf("end handel_event0...\n");
}
if ( event0_fd > 0 ) {
close(event0_fd);
event0_fd = -1;
}
return 0;
}
PAX Computer Technology (Shenzhen) Co., Ltd.
75
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.
76
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, it can refer to the example of the keyboard.
Prolin input subsystem has two device nodes, /dev/event0 and /dev/event1, they are
respectively used for Keys and PED keys.
PAX Computer Technology (Shenzhen) Co., Ltd.
77
Prolin API Programming Guide
10Signature Board
Details refer to the “XUI Programming Guide”.
PAX Computer Technology (Shenzhen) Co., Ltd.
78
Prolin API Programming Guide
11Printer
PROLIN provides the printer function of physical printer and virtual printer 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 10 Printer return code list
Macro
Value
Description
ERR_PRN_BUSY
-3701
Printer 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 over heating
ERR_PRN_OUTOFMEMORY
-3705
The print data is too large,
and exceeds the buffer
length.
ERR_PRN_OVERVOLTAGE
-3706
Voltage is too high.
11.2 Open and Close
11.2.1 OsPrnOpen
Prototype
int OsPrnOpen(unsigned int printertype,
PAX Computer Technology (Shenzhen) Co., Ltd.
const char* targetname );
79
Prolin API Programming Guide
Function
Opens the printer (including physical and virtual).
Printer type
PRN_REAL: Physical printer.
PRN_BMP: Bmp virtual printer and it
generates bmp format files.
printertype【Input】
Parameters
Return
Instruction
targetname【Input】
For the physical printer, this parameter should
be NULL.
The output file name of virtual printer, this
parameter should fill in the file name generated
by
virtual
printing,
for
example,
/home/app/test.bmp.
RET_OK
Success.
ERR_DEV_NOT_EXIST
Device does not exist.
ERR_INVALID_PARAM
Invalid parameter
ERR_DEV_BUSY
Device is busy.
Other functions can be operated only after open device successfully.
11.2.2 OsPrnReset
Prototype
void OsPrnReset(void);
Function
Resets and re-initializes the printer.
Parameters
None
Return
None
Instruction
Calling this function will restore the printer default settings and clear the print
buffer data.
This function is applicable to both physical printers and virtual printers.
After calling OsPrnReset (), the font choice of library file will be
set to default font status (only available in English).
11.2.3 OsPrnClose
Prototype
void OsPrnClose(void);
Function
Closes the printer.
Parameters
None
Return
None
PAX Computer Technology (Shenzhen) Co., Ltd.
80
Prolin API Programming Guide
Instruction
This function should be called to close the printer device while program exit.
11.3 Printer settings
11.3.1 OsPrnSetSize
Prototype
Function
int OsPrnSetSize (unsigned int Width,
unsigned int Height);
Sets printer parameters.
Width 【Input】 Width
Parameters
Return
Instruction
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.
0; print horizontally.
Non-zero; print vertically.
Mode 【Input】
Parameters
Return
Instruction
RET_OK
Success
ERR_INVALID_PARAM
Invalid parameter.
This function is applicable to both physical printers and virtual printers.
11.3.3 OsPrnSetGray
Prototype
void OsPrnSetGray(int Level);
Function
Sets printing gray level.
Level
Parameters
PAX Computer Technology (Shenzhen) Co., Ltd.
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.
81
Prolin API Programming Guide
The illegal value does not change current settings.
Return
Instruction
None
Before setting gray level, it prints with the default level, after calling this
function it will print with the setting level.
Only applicable to the physical printer.
11.4 Type Setting
11.4.1 OsPrnSetSpace
Prototype
Function
void OsPrnSetSpace(int CharSpace,
int LineSpace);
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
Instruction
None
1.
2.
3.
4.
5.
6.
Settings will be valid until they are set again or OsPrnReset () is called;
Printing character space defaults to 0;
Printing line space defaults to 0 for thermal and 2 for spocket;
The maximum line space can be 255;
The maximum character space can be 255.
Illegal value 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 with the default settings.
Parameters
Return
Instruction
Attr
0:
normal
Non zero: reversal
None
This function is applicable to both physical printers and virtual printers.
11.4.3 OsPrnSetIndent
Prototype
int OsPrnSetIndent (unsigned int Left,
PAX Computer Technology (Shenzhen) Co., Ltd.
unsigned int Right);
82
Prolin API Programming Guide
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.
RET_OK
Success
ERR_INVALID_PARAM
Invalid parameter
Parameters
Return
Instruction
If the physical printer is set to print vertically, then the left margin should
correspond to the bottom margin of the page, and right margin corresponds to
the top 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 overheating.
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
over heating or not.
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
Instruction
Current dot line.
Used for slip alignment.
This function is applicable to both physical printers and virtual printers.
PAX Computer Technology (Shenzhen) Co., Ltd.
83
Prolin API Programming Guide
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
Sets the font size.
SingleCodeWidth
The width control of single code font. (For nonmonospaced font, width of each character may not meet
the settings).
The value ranges from 8 to 64.
SingleCodeHeight
Parameters
The height control of single code font.
The value ranges from 8 to 64.
MultiCodeWidth
The width control of multiple code font.
The value ranges from 12 to 64.
MultiCodeHeight
The height control of multiple code font
The value ranges from 12 to 64.
Return
Instruction
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.
84
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
Instruction
number of pixels
1. 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.
2. This function is applicable to both physical and virtual printers.
This is a one-time action.
11.4.9 OsPrnPrintf
Prototype
void OsPrnPrintf(const char *Str, ...);
Function
Formats output string to print buffer.
Parameters
Return
Instruction
11.4.10
Str【Input】
Pointer of string that needs to be printed.
None
1. Support variable parameters;
2. Support ‘\n’ (new line) and ‘\f’ (new page) control characters;;
3. If the printing data package is too long, then the printing program will
overflow;
4. If the string is longer than the current printing line, automatically
changes line and continues printing;
5. The maximum buffer size is 2048 bytes;
6. Store str in printing buffer, and print data in printing buffer in sequence
after calling OsPrnStart ().
OsPrnPutImage
Prototype
void OsPrnPutImage(const unsigned char *Logo);
Function
Outputs images to the print buffer.
PAX Computer Technology (Shenzhen) Co., Ltd.
85
Prolin API Programming Guide
Parameters
Logo【Input】
Pointer to the logo information; the length cannot be more
than 20000 bytes.
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, then multiple character arrays (with the corresponding bmp
file name) will be defined in the generated header file.)
Printing bitmap size limit: up to 384 pixels in width, spocket with 180
pixels and 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
sliced on the right side.
If the data packet is too long, then this function will remove the LOGO
message.
Description of the array in the header file:
First byte [1 byte]: lines number 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.
86
Prolin API Programming Guide
Instruction
ERR_PRN_PAPEROUT
Out of paper.
ERR_PRN_WRONG_PACKAGE
The format of print data packet error.
ERR_PRN_OVERHEAT
Printer overheating.
ERR_PRN_OUTOFMEMORY
The print data is too large.
1. After calling this API, the printer will perform the printing task and return after
completing the whole printing task.
2. After completing the whole printing task, this API will return the printer status in
return value. Therefore the check printer status is not required.
3. 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
senior 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 over heating
0x04~0xFF reserved
unsigned char buf[10];
int ret = read(handle, buf, 2);
if (ret > 0) {
//buf[0]
}
PAX Computer Technology (Shenzhen) Co., Ltd.
87
Prolin API Programming Guide
11.5.3 write
Send the printer configurationbuffer.
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 pringting gray control values, bit3~bit7
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], multiple batches of 48 characters composed a single line (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 write data length is:
To the thermal printing of 384 dots, the driver can deal with 5000 lines each time at most; the
longest length of a write buffer should be 384*5000/8 + 2 = 240002 Bytes. The out of bound
content will be trimmed off.
PAX Computer Technology (Shenzhen) Co., Ltd.
88
Prolin API Programming Guide
To 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
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.
89
{ This page intentionally left blank }
Prolin API Programming Guide
12Font 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 offset left from the baseline*/
unsigned char Top;
/* Font top offset from the baseline */
unsigned char
/* Font width */
Width;
PAX Computer Technology (Shenzhen) Co., Ltd.
91
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
PAX Computer Technology (Shenzhen) Co., Ltd.
92
Prolin API Programming Guide
Instruction
ERR_INVALID
_PARAM
Invalid parameter.
ERR_FONT_NO
T_EXIST
System does not install font library.
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】
Font handle
Utf8Code 【Input】
Characters of UTF-8 encoding standards
Width 【Input】
Font width, value range is【8, 128】.
Height 【Input】
Font height, value range is【8, 128】.
Parameters
Font style:
Style 【Input】
PAX Computer Technology (Shenzhen) Co., Ltd.
FONT_STYLE_NONE 0
No style
93
Prolin API Programming Guide
FONT_STYLE_BOLD 0x00000001
Bold type
FONT_STYLE_ITALIC 0x00000002
Italic type
FONT_STYLE_BOLD|FONT_STYLE_ITALIC
represents bold italics.
Return
FtDot 【Output】
The output of font data structure.
RET_OK
Success
ERR_INVALID_PARA
M
Invalid parameter
ERR_FILE_NOT_EXIST
File does not exist.
ERR_FONT_CODE
Font code error.
ERR_INVALID_HAND
LE
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, which Utf8Code [0]
represents letter, Utf8Code [1] represents ' \ 0'; but for Chinese, Utf8Code
requires four bytes, which Utf8Code [0-2] represents the Chinese, and
Utf8Code [3] represents ' \ 0'.
The Italic style dot matrix.
Instruction
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, or the
dot may cannot 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.
All of the font dot matrix are in horizontal arrangement mode;
2.
The point which corresponds to each byte, the sequence from left to right
is 0x80 to 0x01;
3.
If the character width is not integer multiple of 8, the bytes of per line dot
matrix are (width+7)/8
For example: For the character”>“, with 10(width)×20(height)
PAX Computer Technology (Shenzhen) Co., Ltd.
94
Prolin API Programming Guide
The font data is:
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,
PAX Computer Technology (Shenzhen) Co., Ltd.
95
Prolin API Programming Guide
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.
96
Prolin API Programming Guide
13Code
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
Parameters
Implement conversion of character encoding.
FromCharset
【Input】
The original character encoding
ToCharset
【Input】
The target character encoding
InBuf 【Input】
Character string of the original encoding, ending with’ \0’.
Unicode should end in”\0\0’’
OutBuf
The converted encoding string
PAX Computer Technology (Shenzhen) Co., Ltd.
97
Prolin API Programming Guide
【Output】
LenOut 【Input】
Size of array OutBuf, it should be 1.5 times of the array
InBuf.
>=0
Return
ERR_INVALID_PARAM
Success, then returns
the length of
converted character string
Invalid parameter
Supports conversions among the following codes.
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)
Instruction
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.
98
Prolin API Programming Guide
14MSR
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 11 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
99
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
indicate read track data succeed,
other value indicate 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
None
RET_OK
Success
ERR_DEV_NOT_EXIST
Device does not exist.
ERR_DEV_BUSY
Device is busy.
PAX Computer Technology (Shenzhen) Co., Ltd.
100
Prolin API Programming Guide
ERR_DEV_NOT_OPEN
Instruction
Device is not open.
Other functions can be operated only after open device successfully.
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 while 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 magnetic buffer.
14.3.4 OsMsrSwiped
Prototype
int OsMsrSwiped(void);
Function
Checks whether a card is swiped or not
Parameters
None
TRUE
Card swiped
FALSE
Not swiped
ERR_DEV_NOT
_OPEN
Device is not open.
Return
Instruction
1.
This function returns the corresponding value immediately, doesn’t matter
PAX Computer Technology (Shenzhen) Co., Ltd.
101
Prolin API Programming Guide
2.
3.
card 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.
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_SWIPED
No swiping.
ERR_INVALID_PARAM
Invalid parameter.
ERR_DEV_NOT_OPEN
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 call
OsMsrRead() 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
PAX Computer Technology (Shenzhen) Co., Ltd.
102
Prolin API Programming Guide
14.4 POSIX
PROLIN Magnetic driver module makes the POSIX programming interface open to the senior
application developers.
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 data of the magnetic bit stream.
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.
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
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.
103
Prolin API Programming Guide
15ICC Reader
The basic protocol interface is customized according to the ISO7816/EMV.
15.1 Return Code List
Table 12 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
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
PAX Computer Technology (Shenzhen) Co., Ltd.
104
Prolin API Programming Guide
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.
105
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.
106
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];
int LC;
ICC */
unsigned char DataIn[512];
int LE;
}ST_ APDU_REQ;
PAX Computer Technology (Shenzhen) Co., Ltd.
/*CLA, INS, P1, P2*/
/* The valid length of DataIn that sending to
/* The data that sending to ICC */
/* The expected returned length */
107
Prolin API Programming Guide
ST_APDU_REQ structure:
1. LE is the length of expected returned data. The actual
returned data length is related to specific command. Here is an
expected length but the actual returned data 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 data.
If the length of expected return data is unknown, set Le
to 256; otherwise, set it to certain value.
LC>0, LE=0. The data are sent, but no expected data are
returned;
LC>0, LE>0. The data are sent and the expected data
are returned. If the length of expected return data is
unknown, set Le to 256; otherwise, set it to certain 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 ()
PAX Computer Technology (Shenzhen) Co., Ltd.
sci_detect ()
sci_cold_reset ()
sci_warm_reset ()
emv_atr_parse ()
108
Prolin API Programming Guide
sci_write ()
sci_close ()
sci_lock ()
sci_unlock()
sci_powerup()
sci_powerdown()
iso7816_atr_parse ()
iso7816_pps ()
iso7816_ocs()
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
Get 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
id【Input】
PAX Computer Technology (Shenzhen) Co., Ltd.
device id
109
Prolin API Programming Guide
Return
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.
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
PAX Computer Technology (Shenzhen) Co., Ltd.
110
Prolin API Programming Guide
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【Iutput】
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
Instruction
id【Input】
device id
0
success
others
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, lock the smartcard lock before cold reset, warm reset,
reading, writing. It has no effect on usercard device (id = 0).
PAX Computer Technology (Shenzhen) Co., Ltd.
111
Prolin API Programming Guide
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 while getting all the data (or
error info) from transmission by read operation. It has no effect on usercard
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
Instruction
15.3.12
Prototype
sci_detect
int sci_detect(int id);
PAX Computer Technology (Shenzhen) Co., Ltd.
112
Prolin API Programming Guide
Function
Parameters
Return
Instruction
15.3.13
Detects whether the user card is in the socket or not.
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
PAX Computer Technology (Shenzhen) Co., Ltd.
113
Prolin API Programming Guide
15.4 Protocol processing function
15.4.1 emv_atr_parse
Prototype
Function
Parameters
Return
int emv_atr_parse (const struct sci_atr_t *pstATR,
struct sci_dcb_t *dcb);
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
Prototype
Function
Parameters
Return
int iso7816_atr_parse (const struct sci_atr_t *pstATR,
struct sci_dcb_t *dcb);
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
struct sci_atr_t *pstATR, struct sci_dcb_t *dcb);
PPS protocol process.
PAX Computer Technology (Shenzhen) Co., Ltd.
114
Prolin API Programming Guide
Parameters
Return
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
Return
Instruction
id【Input】
device id
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
ifsd request in T=1.
Parameters
Return
id【Input】
device id
0
success
others
error
Instruction
PAX Computer Technology (Shenzhen) Co., Ltd.
115
Prolin API Programming Guide
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
Return
Transmission on T=1 protocol under ISO 7816-3 standard.
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
others
Error
Instruction
PAX Computer Technology (Shenzhen) Co., Ltd.
116
Prolin API Programming Guide
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
Succeed
ERR_DEV_NOT_EXIST
Device does not exist.
ERR_DEV_BUSY
Device is busy.
User card
SAM slot 1
SAM slot 2
SAM slot 3
SAM slot 4
Instruction
1. Other functions can be operated only after open IC device
successfully.
2.
For various machines, the numbers and types of slots are
different. For specify numbering of slots, please read 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
Slot
channel number:
RET_OK
Card-inserted
Others
Please refer to ICC Return code list
1.
Instruction
2.
3.
This function will return immediately no matter whether there is a card in
slot or not.
For USER_SLOT, if card-insert or card-extract happens, system will send
MSG_ICCSIG message to the application which used to open the device.
It is not applicable to SAM card.
PAX Computer Technology (Shenzhen) Co., Ltd.
117
Prolin API Programming Guide
For SAM card, please make sure call this interface firstly before
reset the SAM card. This interface will lead to the SAM card
power off.
15.5.3 OsIccInit
Prototype
int OsIccInit(int Slot,
unsigned long Option,
unsigned char *Atr);
Function
Initialize the IC card device.
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).
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 the specific is marked as EMV mode, the
power rate will be marked as invalid. It uses the
standard rate by default.
(Bit 6 ~31)Reserved
Option is set as 0 by default(that is 5V, do not
support PPS, Standard rate, and follow EMVx)
Parameters
1.
*Atr
Return
Instruction
【Output】
2.
Answer To Reset. Up to 34 bytes will be
returned from card.
Content is composed of length of ATR (1
byte) and ATR[output]
RET_OK
Succeed
Others
Please refer to ICC Return code list
1.
ATR output buffer should be allocated at least 34 bytes.
PAX Computer Technology (Shenzhen) Co., Ltd.
118
Prolin API Programming Guide
2.
3.
Whether PPS protocol is available or not, it depends on the specific cards
is support or not.
For SAM card, some terminals can only make one card effective at a time.
If multi cards need to be operated, it should initialize cards one by
one.(OsIccInit ( ) ) - > operation ( OsIccExchange ) - > close ( )
Most of the SAM card only supports ISO7816, so the Option
should be set as 0x20, but not 0x00.
15.5.4 OsIccExchange
Prototype
int OsIccExchange(int Slot,
int CtrlFlag,
cosnt ST_APDU_REQ *ApduReq,
ST_APDU_RSP *ApduRsp);
Function
Interacts command with IC card.
Channel number.
Please refer to OslccOpen()
Slot
1.
CtrlFlag
Parameters
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 which was sent to IC card.
The data structure which was received from IC
card.
RET_OK
Succeed
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
Return
Slot
Channel number.
Please refer to OslccOpen()
RET_OK
Succeed
Others
Please refer to ICC Return code list
Instruction
PAX Computer Technology (Shenzhen) Co., Ltd.
119
{ This page intentionally left blank }
Prolin API Programming Guide
16RF Reader
This part conforms to the ISO14443 and the specification of ‘EMV Contactless Book D V2.1’
and mainly describes the application programming interfaces of RF reader.
16.1 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
Multi-card conflict
PCD_ERR_ECD_FLAG
-2905
Frame format is wrong
PCD_ERR_EMD_FLAG
-2906
Interference
PCD_ERR_COM_FLAG
-2907
Chip error, it cannot
communicate properly
PCD_ERR_AUT_FLAG
-2908
M1 authentication error
PCD_ERR_TRANSMIT_FLAG
-2909
Transmit error
PCD_ERR_PROTOCOL_FLAG
-2910
Protocol error
PAX Computer Technology (Shenzhen) Co., Ltd.
Description
121
Prolin API Programming Guide
PCD_ERR_PARAMFILE_FLAG
-2911
Configuration file does not
exist
PCD_ERR_USER_CANCEL
-2912
Users cancel the transaction
PCD_ERR_CARRIER_OBTAIN_FLAG
-2913
Didn’t obtain the carrier
PCD_ERR_CONFIG_FLAG
-2914
Configuration register occurs
error
PCD_ERR_NOT_ALLOWED_FLAG
-2951
Parameter error or the value is
invalid
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 does not remove
PCD_ERR_NOT_IDLE_FLAG
-2955
Card is out of the idle state
PCD_ERR_NOT_POLLING_FLAG
-2956
Card without POLLING
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 structure and response structure please refer to the 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;
response */
/* Written enable for the number
/* The most repeat times of S(WTX)
unsigned char check_cancel_key_w;
cancel key*/
/*Written enable for checking the
unsigned char check_cancel_key_val; /* 0 represents has no response to
the cancel key, 1 represents response to
PAX Computer Technology (Shenzhen) Co., Ltd.
122
Prolin API Programming Guide
the cancel key */
int (*check_cancel_key_function)(void);/* Detect whether has pressed the cancel
key or not, if set the
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 that does not
pressed the cancel key, otherwise, it
means it does, and then 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, the unit is according to
the current ETU time */
unsigned int uiFWT;
/*the protection time of sending, the unit is according to the current ETU
time */
unsigned int uiSFGT;
/* Electrical conductivity of the A card */
unsigned int uiTypeAConduct;
/*Reserved*/
unsigned int uiReserved;
/* Receiver 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*/
PAX Computer Technology (Shenzhen) Co., Ltd.
123
Prolin API Programming Guide
unsigned int uiTypeBModulDepth;
/* Receiver 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 depth of Felica card */
unsigned int uiFelicaModulDepth;
/* Receiver 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
atqa【Output】
the buffer for ATQA, 2 bytes
0
Success, the ATQA is valid, consists of two bytes.
PAX Computer Technology (Shenzhen) Co., Ltd.
124
Prolin API Programming Guide
others
Instruction
Error
16.3.3 iso14443_3a_antisel
int iso14443_3a_antisel( unsigned char *uid,
int uid_ln,
Prototype
unsigned char *sak );
Function
Parameters
Return
Sends ANTICOLLISION command to PICC, and receives the UID from PICC.
uid
the unique number of PICC
uid_ln
the length of the unique number of PICC
sak
the last selected command response
0
Success.
others
Error
< 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 >
Instruction
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】
0
PAX Computer Technology (Shenzhen) Co., Ltd.
the response from PICC (must be greater than 256 bytes)
Success.
125
Prolin API Programming Guide
others
Error
Instruction
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; consists 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; consists 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
dat
Parameters
【Input&Output】
txr_ln
PAX Computer Technology (Shenzhen) Co., Ltd.
the picc's uid, 4 bytes
higher layer INF.(command and response)
the number of higher layer INF.
126
Prolin API Programming Guide
Return
0
Success
others
Error
Instruction
16.4.4 iso14443_3b_halt
Prototype
int iso14443_3b_halt( );
Function
Sends HALTB command to PICC.
Parameters
Return
None
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
PAX Computer Technology (Shenzhen) Co., Ltd.
127
Prolin API Programming Guide
16.6 Encapsulated Interfaces
16.6.1 OsPiccOpen
Prototype
int OsPiccOpen(void);
Function
Power on the PCD module, make the module into the preparatory work state.
Parameters
Return
None
0
Succeed.
Others
Failed to open device. (Details refer to the return
code list.)
Instruction
16.6.2 OsPiccClose
Prototype
int OsPiccClose (void);
Function
Power off the PCD module.
Parameters
Return
None
0
Succeed.
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
Succeed.
Others
Failed. (Details refer to the return code list.)
When do the carrier reset operation for RF reader, it will change the card state
in the RF field, 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
Detect cards, it only can do the roll polling for card A and card B.
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
Parameters
PAX Computer Technology (Shenzhen) Co., Ltd.
128
Prolin API Programming Guide
bytes.
In response to the WUPB commands, a Picc of
card B, will return an ATQB with a length of 12
bytes.
Return
Instruction
0
Succeed.
Others
Failed. (Details refer to the return code list.)
Mifare card is a special A card, after calling this interface, M card returns as an
A card.
16.6.5 OsPiccAntiSel
Prototype
int OsPiccAntiSel( const char cPiccType,
unsigned char *pucUID,
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
Unique identifier of the card:
pucUID
【Output】
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.
Parameters
ucATQ0
【Input】
It is unused.
The response data of card while selecting card, it
has 1 byte.
pucSAK
【Output】
SAK represents the data that response to the last
SELECT command of card A.
This parameter is ignored by card B.
Return
Instruction
0
Succeed.
Others
Failed. (Details refer to the return code list.)
If users want to differentiate between the picc of card A and Mifare card, they
can carry out the decision according to the output parameters value of the
pucSAK.
16.6.6 OsPiccActive
Prototype
int OsPiccActive( const char cPiccType,
PAX Computer Technology (Shenzhen) Co., Ltd.
129
Prolin API Programming Guide
unsigned char *pucATS );
Function
Activate the card.
pcPiccType
【Input】
Card types:
’A’ - card A
’B’ - card B
The response data:
Parameters
pucRATS 【Output】
PucRATS represents the data that responsed to
ATS command of card A.
PucRATS represents the data that response to
ATTRIB command of card B.
Return
Instruction
0
Succeed.
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,
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, unsigned char*
Prototype
pucRxBuff,
int *piRxLen );
Function
Parameters
Return
Realize the transparent transmission/reception in accordance with the
half-duplex communication protocol in the ISO14443-4
pucTxBuff
【Input】
The data buffer to be transmitted.
iTxLen
【Input】
The byte count of data to be transmitted.
pucRxBuff 【Output】
Response data buffer of received card.
piRxLen
The length of received card’s response data.
【Output】
0
Succeed.
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
Succeed.
Others
Failed. (Details refer to the return code list.)
PAX Computer Technology (Shenzhen) Co., Ltd.
130
Prolin API Programming Guide
Instruction
16.6.9 OsMifareAuthority
int OsMifareAuthority(unsigned char *uid,
unsigned char blk_no,
Prototype
unsigned char group,
unsigned char *psw);
Function
Parameters
Return
Verify the Mifare card.
uid
【Input】
Card ID, 4 bytes.
blk_no
【Input】
Block number
group
【Input】
Password types, can be value as ‘A’ or ‘B’
psw
【Input】
Authentication password, 6 bytes.
0
Succeed.
Others
Failed. (Details refer to the return code list.)
Instruction
16.6.10
OsMifareOperate
int OsMifareOperate ( unsigned char ucOpCode,
unsigned char ucSrcBlkNo,
Prototype
unsigned char* pucVal,
unsigned char ucDesBlkNo );
Function
Parameters
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】
Operation types include reading block, writing
block, increment, decrement and backup.
ucSrcBlkNo
【Input】
Specify the visiting block number
pucVal 【Input/Output】
For read block, it is output. Output the block
value.
For write block, it is input. The contents which
points by pucVal should be written in the
specified block.
For increase/decrease value, it represents the
first address of amount buffer is waiting for
increasing or decreasing value.
ucUpdateBlkNo 【Input】
Specify the block number which used to written
in the operation result.(while reading and
writing block, it is NULL)
PAX Computer Technology (Shenzhen) Co., Ltd.
131
Prolin API Programming Guide
Return
0
Succeed.
Others
Failed. (Details refer to the return code list.)
Instruction
16.6.11
OsPiccInitFelica
int OsPiccInitFelica( unsigned char ucSpeed,
Prototype
Function
unsigned char ucModInvert );
Initialize the configuration for the Felica card.
ucSpeed
Set the transmission rate which used to interact
with card.
1-424Kbp
Others-212Kbps
【Input】
Parameters
Return
ucModInvert 【Input】
Set the FeliCa modulate mode.
1 : forward modulate output;
Others: reverse modulate output.
0
Succeed.
Instruction
16.6.12
OsPiccIsoCommand
int OsPiccIsoCommand(int cid,
Prototype
Function
Parameters
ST_APDU_REQ *ApduReq,
ST_APDU_RSP *ApduRsp);
Send the APDU data and receive response in the specified channel.
【Input】
ApduReq
【Input】 The structure sends to PICC card.
ApduRsp
Return
Used for specifying the logical channel number of the
card, it values from 0 to 14, currently the value is 0.
cid
【Output】 The response structure returns from PICC card.
0
Succeed
Others
Failed (Details refer to the return code list.)
Instruction
16.6.13
OsPiccSetUserConfig
Prototype
int OsPiccSetUserConfig(PCD_USER_ST *pcd_user_config) ;
Function
Set the user configuration.
Parameters
Return
pcd_user_config 【Input】 User configuration structure
0
PAX Computer Technology (Shenzhen) Co., Ltd.
Succeed
132
Prolin API Programming Guide
Others
Failed (Details refer to the return code list.)
Instruction
16.6.14
OsPiccGetUserConfig
Prototype
int OsPiccGetUserConfig(PCD_USER_ST *pcd_user_config);
Function
Get the user configuration.
Parameters
Return
pcd_user_config
【Output】
User configuration structure
0
Succeed
Others
Failed (Details refer to the return code list.)
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 doing 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.
133
{ This page intentionally left blank }
Prolin API Programming Guide
17Communication Port
17.1 Data Definition
Table 13 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 PinPad
PORT_BT
9
Bluetooth
PORT_USBDEV
11
USB device mode port
PORT_USBHOST
12
USB host mode port
Table 14 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.
PAX Computer Technology (Shenzhen) Co., Ltd.
135
Prolin API Programming Guide
USB_ERR_NOT_FREE
-3405
Has no free port.
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
Prototype
Function
int OsPortOpen(int Channel,
const char *Attr);
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 reused but only one port at a
time. Please refer to Appendix 4.
Attr
【Input】
Parameters
PAX Computer Technology (Shenzhen) Co., Ltd.
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
136
Prolin API Programming Guide
Return
Instruction
RET_OK
Success.
ERR_DEV_BUSY
Device is busy.
ERR_DEV_NOT_E
XIST
The port does not exist.
ERR_INVALID_PA
RAM
Invalid parameter.
Other functions can be operated only after open device successfully.
1. In Prolin2.4, it defaults to use the USB to start the XCB
service. In order to avoid the resource conflict, 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 firstly.
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.
PAX Computer Technology (Shenzhen) Co., Ltd.
137
Prolin API Programming Guide
Channel
Parameters
Return
to the
Macro definition list of
communication ports .
SendBuf【Input】 Buffer of sending data.
SendLen
Length of sending data.(<=8*1024)
RET_OK
Success
ERR_DEV_NOT
_OPEN
Port is not open.
ERR_INVALID
_PARAM
Invalid parameter.
1.
Instruction
Please Refer
2.
The buffer size is 8K, when the send data is less than the free space of the
buffer, this function will not block and the data will 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
list
of
communication ports .
RecvBuf【Output】 Buffer of receiving data.
Parameters
RecvLen
The data length that want to receive. When the length is
0, it means clear the receive buffer.
TimeoutMs
Receive timeouts 【unit:ms】 (The minimum precision is
100ms)
>=0
The actual length of receive data.
ERR_DEV_NOT_
Port does not open.
Return
PAX Computer Technology (Shenzhen) Co., Ltd.
138
Prolin API Programming Guide
OPEN
ERR_INVALID_P
ARAM
Instruction
Invalid parameter.
1.
The received data will return immediately when it is equal to the RecvLen.
2.
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 any buffered data in send and receive
buffers of COM port.
Parameters
Return
Channel 【Input】
Please Refer to the Macro definition list of communication
ports .
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 sending buffer of the specified COM port.
Parameters
Return
Channel 【Input】
Please Refer to the Macro definition list of communication
ports .
>=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 advanced applications developers to use.
PAX Computer Technology (Shenzhen) Co., Ltd.
139
Prolin API Programming Guide
17.3.1 Open
Opens the uart, and the device name are ttyAMA0, ttyAMA1, ttyAMA2, ttyAMA3.
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 into 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);
PAX Computer Technology (Shenzhen) Co., Ltd.
140
Prolin API Programming Guide
17.3.6 Clear the buffer data of communication port
/* 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;
/* set the data bits */
switch (nBits)
{
case 7:
newtio.c_cflag |= CS7;
break;
case 8:
newtio.c_cflag |= CS8;
break;
}
/* Configurate the parity bit*/
switch (cEvent)
{
case 'o':
PAX Computer Technology (Shenzhen) Co., Ltd.
141
Prolin API Programming Guide
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);
cfsetospeed (&newtio, B38400);
break;
case 57600:
PAX Computer Technology (Shenzhen) Co., Ltd.
142
Prolin API Programming Guide
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.
143
{ This page intentionally left blank }
Prolin API Programming Guide
18MODEM
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 15 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.
145
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.
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 not support
the command.
-3XXX
(
-3111
~
-3199
)
Abnormal error code will not
appear
frequently.
Setting
abnormal error code is for the
purpose of maturity and
maintainability. Details about
what error code means are not
important.
ERR_MDM_LINE_BUSY
OTHERS
-3115
PAX Computer Technology (Shenzhen) Co., Ltd.
Calling
synchronization
146
Prolin API Programming Guide
handshake receiving process 1
error
PAX Computer Technology (Shenzhen) Co., Ltd.
-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 the
packet series number error
-3122
Calling
communication
process 2 error
-3123
Calling
synchronous
communication sent overload
-3124
Calling
synchronous
communication sent under run
-3130
Calling
communication
illegal.
-3131
Calling
synchronous
communication send stateful
packet 1 errors
-3132
Calling
synchronous
communication
sent
data
packets retry more than the
specified time.
synchronous
receiving
synchronous
receiving
synchronous
line rate is
147
Prolin API Programming Guide
PAX Computer Technology (Shenzhen) Co., Ltd.
-3133
Calling
communication
packets timeout
synchronous
sent
data
-3134
Calling
synchronous
communication receiving the
acknowledgement packet retry
more than the specified time
-3135
Calling
communication
packet 2 error
synchronous
sent stateful
-3136
Calling
communication
packet 3 error
synchronous
sent stateful
-3137
Calling
communication
packet 4 error
synchronous
sent stateful
-3138
Calling
synchronous
communication receiving data
packets retry more than the
specified time
-3139
Calling
communication
packet 5 error
synchronous
sent stateful
-3140
Calling
communication
packet 6 error
synchronous
sent stateful
-3144
Sent number automatically and
not to pick up the phone timely.
-3145
Called
synchronization
handshake sent handshake
packets failed
-3146
Called
synchronization
handshake receiving handshake
packets failed
-3147
Called
handshake
synchronization
more than the
148
Prolin API Programming Guide
specified time.
PAX Computer Technology (Shenzhen) Co., Ltd.
-3148
Called
communication
packet 1 error
synchronous
sent stateful
-3149
Called
communication
process 1 error
synchronous
receiving
-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
communication
packet 2 error
-3154
Called
synchronous
communication sent data packet
error
-3155
Called
communication
process 3 error
-3156
Called
synchronous
communication receiving the
packet retry more than the
specified time
-3157
Called
communication
packet 3 error
-3160
Called connection receiving
ring information error
-3161
Called connection detecting the
line voltage failed
synchronous
receiving
synchronous
sent stateful
synchronous
receiving
synchronous
sent stateful
149
Prolin API Programming Guide
PAX Computer Technology (Shenzhen) Co., Ltd.
-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
-3181
Calling
connection
asynchronous line rate is illegal
-3182
Calling
connection
instruction string 6 failed.
set
150
Prolin API Programming Guide
-3183
Calling connection set extended
instruction string failed
-3185
Calling connection has no dial
tone.
-3186
Calling connection chip 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
PAX Computer Technology (Shenzhen) Co., Ltd.
Non-pre-dial-up dial up timeout
(300s)
-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
ConnectFormat parameters
-3198
Daemon to create thread failed
-3199
The process with Daemon
communication failure or error
-3200
Modem is using the bound uart.
-3201
Socket creation failed
-3202
Socket link failed
151
Prolin API Programming Guide
ERR_MDM_INIT
PAX Computer Technology (Shenzhen) Co., Ltd.
-3203
Socket send failed
-3204
Create semaphore failed
-3205
Set the semaphore value failed
-3206
Semaphore
pre-empted.
-3207
Semaphore cannot be released.
-3208
Semaphor initialization failed
-3209
Gettimeofday failed
-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.
-3217
Modem initialization failed.
-3218
If
does
not
implement
OsModemConnect
(),
or
implemented
OsModemConnect () wrongly,
then implement OsPppomLogin
() or OsPppomCheck ().
has
been
152
Prolin API Programming Guide
-3219
The Modem or ModemPPP is
being used, Modem cannot be
power 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;
int Pppom;
int Reserved[9];
}ST_MODEM_SETUP;
PAX Computer Technology (Shenzhen) Co., Ltd.
153
Prolin API Programming Guide
Table 16 Variable definition of ST_MODEM_SETUP
CallMode
MODEM_PRE_DIAL
Caller pre-dial
MODEM_DIAL
Caller dial
MODEM_WAIT_CAL
L
Called/Answered the call
MODEM_COMM_SY
NC
synchronous
MODEM_COMM_AS
YNC
asynchronous
MODEM_CODE_DT
MF
DTMF (Dual Tone Multi Frequency) dialing
MODEM_CODE_PUL
SE1
Pulse dialing 1 (Pulse rate 10/s; Intermittent
proportion 1.6:1;Signal interval >=500ms)
MODEM_CODE_PUL
SE2
Pulse dialing 2 (Pulse rate 10/s; Intermittent
proportion 2:1; Signal interval >=600ms)
Other values
Reserved
CommMode
CodeType
CodeDuratio
n
CodeSpacing
The duration of two-tone dialing a single number (Unit:10ms,valid range 5~25)
The interval time between two numbers of two-tone dial-up. It cannot be set to
93011 chips, and it is not applicable to S800. (Unit:10ms, valid range 5~25)
TRUE
DetectLineV
oltage
DetectDialTo
ne
DialToneTim
eout
Detect the parallel telephone occupation (Caller
dialing, No assigned number switch to manual answer
mode)
FALSE
Not detected the parallel telephone occupation (Caller
dialing, No assigned number switch to manual answer
mode)
TRUE
Dial tone detection. Refer to the instruction of
DailTone Timeout.
Does not detect dial tone.
FALSE
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:
PAX Computer Technology (Shenzhen) Co., Ltd.
154
Prolin API Programming Guide
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 off /hook.
Unit: 100ms, Minimum and default value is 20, valid range is 20~50.
In both cases, it starts the timer since offhook about 450 to 500 ms.
CommaPaus
eTime
“,”wait time when dial outside line (Unit: 100ms). This value will be set up
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
“9600”//9600 bps
“12000”//12000 bps
“14400”//14400 bps
“19200”//19200 bps
“24000”//24000 bps
PAX Computer Technology (Shenzhen) Co., Ltd.
155
Prolin API Programming Guide
“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
“14400”//14400 bps
“19200”//19200 bps
“24000”//24000 bps
“26400”//26400 bps
“28800”//28800 bps
PAX Computer Technology (Shenzhen) Co., Ltd.
156
Prolin API Programming Guide
“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
ConnectFor
mat[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.
ConnectTime
out
DialTimes
IdleTimeout
Pppom
Timeouts of waiting for connection,【unit: s】, (valid range 0~300)
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).
There is no application-layer data exchange in the specified time. MODEM then
will hang up. Unit 10s, no timeout if it is 0. The maximum timeout is 900s.This
value is invalid to ModemPPP.
TRUE
Modem PPP communication
FALSE
Common communication
PAX Computer Technology (Shenzhen) Co., Ltd.
157
Prolin API Programming Guide
Reserved[9]
Reserved.
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 open device successfully. It should
call the OsModemSwitchPower () firstly, before using the Modem.
18.4 OsModemClose
Prototype
void OsModemClose(void);
Function
Switches off the Modem device.
Parameters
None
Return
None
Instruction
This function should be called to close device while program exit.
18.5 OsModemSwitchPower
Prototype
int OsModemSwitchPower(int OnOff);
Function
Manages the Modem Power.
Parameters int OnOff
Return
OnOff=1, power on,
OnOff=0, power off.
RET_OK
Success
-3219
The Modem or ModemPPP is being used,
Modem cannot be power off.
-3220
Modem does not power on.
PAX Computer Technology (Shenzhen) Co., Ltd.
158
Prolin API Programming Guide
1. It should power on the Modem before using Modem or ModemPPP.
2. This function is independent of the interface functions in Modem
Instruction
module.
3. It will not automatically perform OsModemClose () when Modem
module is power off.
18.6 OsModemConnect
Prototype
Function
int OsModemConnect(const ST_MODEM_SETUP *Setup,
const unsigned char *TelNo);
Sets the communication link function, for both calling and being called.
Setup【Input】
Parameters
Return
Modem
parameter,
mdm_setup==NULL,
default
parameter will be used.
while
dialing
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.
PAX Computer Technology (Shenzhen) Co., Ltd.
159
Prolin API Programming Guide
Instruction
1.
The function can also be used to set Modem mode as 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 hangup.
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 ().
3.
4.
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 result of the last Modem dialing.
Parameters
Return
None
MODEM_CON
NECTING
Dialing
MODEM_CON
NECTED
Connected
MODEM_IDLE
Idle
ERR_MDM_BY
PASS_BUSY
The parallel line is busy.
ERR_MDM_LI
NE_BUSY
Telephone line is not properly connected, or parallel line is
occupied.
ERR_MDM_NO
_ANSWER
No response for dialing.
ERR_MDM_CA
LLEE_BUSY
Line busy.
PAX Computer Technology (Shenzhen) Co., Ltd.
160
Prolin API Programming Guide
Instruction
ERR_MDM_NO
_LINE
Telephone line is not connected (Line voltage is 0).
ERR_MDM_NO
_CARRIER
Carrier wave of telephone lost.
ERR_MDM_RE
CVPOOL_NOT_
EMPTY
Receive buffer is not empty (received remote data)
ERR_MDM_RE
CVPOOL_SEN
DPOOL_BOTH_
NOT_EMPTY
Receive buffer is not empty (received remote data), and the
send buffer is sending data.
ERR_DEV_NOT
_OPEN
Device is not open.
1. This function can be used to check whether communication has been
established or not by the redial.
2. After calling OsModemOpen (), OsModemHangup () or
OsModemClose (), the status of the last Modem dial will become:
MODEM_IDLE.
18.8 OsModemExCmd
int OsModemExCmd(const char *Cmd,
char *Rsp,
Prototype
int *RespLen,
int TimeoutMs);
Function
Parameters
Sets additional AT control command for OsModemConnect (), to control
Modem dialing.
Cmd【Input】
Input AT control command.
Rsp【Output】
Contents of response data.
RespLen
【Output】
TimeoutMs
PAX Computer Technology (Shenzhen) Co., Ltd.
Length of response data.
Waiting time for response.(unit:ms)
161
Prolin API Programming Guide
Return
RET_OK
Success
ERR_INVALID
_PARAM
Invalid parameter.
ERR_MDM_CM
D_BUF_FULL
Command buffer overflow.
ERR_MDM_CM
D_TOO_LONG
Command is too long.
ERR_MDM_CM
D_NOT_SUPPO
RT
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 will return, failed.
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 will return, failed.
2. Every input of control command has to be AT control
command, which should be supported by this Modem
chip. Otherwise, it will lead to OsModemConnect ( )
failure.
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.
PAX Computer Technology (Shenzhen) Co., Ltd.
162
Prolin API Programming Guide
18.10OsModemSend
Prototype
Function
int OsModemSend(const void *SendBuf,
int SendLen);
Sends packets out by Modem.
SendBuf【Input】 Pointer of packets, which will be sent
Parameters
Return
Instruction
SendLen
Length of packets, which will be sent (bytes)
RET_OK
Success
ERR_NOT_CO
NNECT
Not connected.
ERR_MDM_TX
OVER
Send buffer is full.
ERR_MDM_NO
_CARRIER
No carrier waves.( Disconnected)
ERR_INVALID
_PARAM
Invalid parameter
ERR_DEV_NOT
_OPEN
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,
int BufSize,
Prototype
int Timeout);
Function
Parameters
Receives packets by MODEM.
RecvBuf【Output】
PAX Computer Technology (Shenzhen) Co., Ltd.
Pointer of the packets that have been
received. [Buffer size can be defined
according to the requirements of different
cases.]
163
Prolin API Programming Guide
Return
BufSize
Size of RecvBuf (<=2048bytes)
Timeout
Timeouts【ms】
>= 0
The actual number of receiving data.
ERR_NOT_CONNECT
Not connected.
ERR_MDM_NO_CARRIER
No carrier waves. (Disconnected)
ERR_INVALID_PARAM
Invalid parameter
ERR_DEV_NOT_OPEN
Device is not open.
1.
2.
3.
Instruction
4.
5.
6.
7.
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.
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 does not affected by restriction of 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.
User name;
Parameters Name【Input】
Length<=50 bytes;
It cannot be NULL.
PAX Computer Technology (Shenzhen) Co., Ltd.
164
Prolin API Programming Guide
For the 96169 background of China
Telecom, it can enter any user name, and
it must enter a character at least.
Password;
Length<=50 bytes;;
Password【Input】
It cannot be NULL.
For the 96169 background of China
Telecom, 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
Authentication Algorithm
PAP
PPP_ALG_CHAP
0x2
Authentication Algorithm
CHAP
PPP_ALG_MSCHAPV1
0x4
MSCHAPV1 Authentication Algorithm
Auth
PPP_ALG_MSCHAPV2
0x8
MSCHAPV2 Authentication Algorithm
PPP_ALG_ALL 0xff (all Authentication
Algorithms are supported)
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
PPP_ALG_ALL.
Timeouts【ms】;
TimeOutMs
PAX Computer Technology (Shenzhen) Co., Ltd.
The valid range is 0~3600000; if it is <0,
it will automatically set it to 0, if more
than 360000. It will automatically set it
to 3600000.
165
Prolin API Programming Guide
Return
Instruction
PPP_LOGINING
Being processed.
RET_OK
The link established successfully.
ERR_INVALID_PARAM
Invalid parameter
ERR_NET_PASSWD
wrong password
ERR_NET_SERVER_BUSY
Server is busy, communication failed.
1. Before using this function, it should call OsModemConnect () first and
set the ST_MODEM_SETUP.Pppom as 1. also it doesn’t need to call
OsModemOpen();
2. While TimeOutMs=0 means return immediately,
3. Call OsPppomCheck ( ) to check the link status
4. The login time may vary from settings to settings of
ST_MODEM_SETUP parameters. The modem chip of S800 supports up
to 33600 asynchronous 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.
5. 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 be according to ppp
protocol, which will end up in failure.
6. After the link sets up successfully, it can communicate through the IP
network communication function.
7. 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
Return
PPP_LOGOUTING
The link is in the status of disconnection.
PPP_LOGINING
Being processed.
RET_OK
The link established successfully
ERR_NET_PASSWD
wrong password
ERR_NET_LOGOUT
Has been calling the OsPppomLogout ( )
to disconnect the link.
PAX Computer Technology (Shenzhen) Co., Ltd.
166
Prolin API Programming Guide
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.
167
{ This page intentionally left blank }
Prolin API Programming Guide
19Network
Communication
PROLIN uses the unified TCP/IP 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.
169
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.
170
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.
171
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 UDP programming
#include
#include
#include
#include
#include
#include
PAX Computer Technology (Shenzhen) Co., Ltd.
172
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.
173
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.
174
Prolin API Programming Guide
20Network 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.
20.1 Return code list
Table 17 Network Configuration return code list
Macro
Value
Description
ERR_NET_SERVER_BAD
-3301
IP server error.
ERR_NET_SERVER_BUSY
-3302
IP server is busy; it can only provide
service for 5 applications at a time.
ERR_NET_NO_ROUTE
-3305
Set no route.
-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 has
been broken and is unavailable
ERR_NET_FULL
PAX Computer Technology (Shenzhen) Co., Ltd.
175
Prolin API Programming Guide
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 assign the IP address.
ERR_NET_DHCP_START
-3314
DHCP not started.
ERR_NET_DNS
-3315
DNS cannot analyse 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.
Some related operations are being
done.(such as PPP login, DHCP)
1
NET_DOING
20.2 Data Definition
20.2.1 Physical channel list
Macro
NET_LINK_ETH
PAX Computer Technology (Shenzhen) Co., Ltd.
Description
Ethernet
176
Prolin API Programming Guide
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, list in the above table are positive
integers, and are greater than 0.
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
Physical channel can only configuration with Ethernet and
WiFi;
NET_LINK_ETH
NET_LINK_WIFI
Parameters
Addr【Input】
Ethernet;
WiFi
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】
Return
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.
177
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 be dynamically
obtained, and it doesn’t need to be configured by the
application.
20.3.2 OsNetPing
Prototype
Function
int OsNetPing(const char *Addr,
int TimeOutMs);
Pings a specific machine to check whether the network is running smoothly or
not.
The IP address of destination machine;
Addr【Input】
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
Before calling OsNetPing( ), it should call OsNetSetRoute( ) to set the physical
channel first.
20.3.3 OsNetDns
int OsNetDns(const char *Name,
char *Addr,
Prototype
int TimeOutMs);
Function
Parameters
Analyzes the IP address corresponding to the domain name and stores the
results in Addr parameter.
Name【Input】
PAX Computer Technology (Shenzhen) Co., Ltd.
Information of domain name, e.g.: [www.sina.com.cn].
178
Prolin API Programming Guide
The maximum length cannot be NULL and cannot
exceed 255 characters.
Addr【Output】
Return
Instruction
1. It is an output parameter;
2. 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”;
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.
Before calling OsNetDns(), it should call OsNetSetRoute() to set the physical
channel first.
20.3.4 OsNetSetConfig
int OsNetSetConfig(int NetLink,
const char *Addr,
const char *Mask,
Prototype
const char *Gateway,
const char *DNSServer);
Function
Configures the network information.
Physical channel can only configure with
Ethernet and WiFi;
Parameters
NetLink
PAX Computer Technology (Shenzhen) Co., Ltd.
NET_LINK_ETH Ethernet;
NET_LINK_WIFI WiFi
179
Prolin API Programming Guide
the address used by POS
Format is “XXX.XXX.XXX.XXX”, XXX
represents 0~255;
Addr【Input】
e.g: “192.168.0.3”;;
if it is “ “ or NULL, means do not change the
original configuration;
Mask code used by POS;
Format is “XXX.XXX.XXX.XXX”;;
Mask【Input】
e.g.: “255.255.255.0”;;
if it is “ “ or NULL, means do not change the
original configuration;
Address of the default gateway
Gateway【Input】
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
original configuration;
DNS server address
Format is “XXX.XXX.XXX.XXX”, XXX
represents 0~255;
DNSServer【Input】
e.g.: “192.168.0.1”;;
if it is “ “ or NULL, means do not change the
original configuration;
Return
Instruction
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.
1. After calling successfully, the system will stop the DHCP function.
2. The function does not check the matching relationship between Addr,
Mask and Gateway; it only checks the legality of their formats.
3. Wireless link, PPPoE, and ModemPPP can only be dynamically
PAX Computer Technology (Shenzhen) Co., Ltd.
180
Prolin API Programming Guide
allocated and cannot be configured by this interface.
20.3.5 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.
Physical channel can only configure with Ethernet and
WiFi;
NetLink
NET_LINK_ETH Ethernet;
NET_LINK_WIFI WiFi(Wireless Local Area
Network)
The address use 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;
Addr【Output】
e.g.: “192.168.0.3”;;
It can be NULL.
Mask code used by POS is an Output parameter. There are
at least 16 bytes in the space.
Parameters
Mask【Output】
Format is “XXX.XXX.XXX.XXX”;;
e.g.: “255.255.255.0”;;
It can be NULL.
Address of the default gateway is an Output parameter.
There are at least 16 bytes in the space.
Gateway
【Output】
Format is “XXX.XXX.XXX.XXX”, XXX represents
0~255;
e.g.: “192.168.0.1”;;
PAX Computer Technology (Shenzhen) Co., Ltd.
181
Prolin API Programming Guide
It can be NULL.
DNS server address is an Output parameter. There are at
least 16 bytes in the space.
DNSServer
【Input】
Format is “XXX.XXX.XXX.XXX”, XXX represents
0~255;
e.g.: “192.168.0.1”;;
It can be NULL.
Return
RET_OK
Success
ERR_NET_IF
The link is unavailable, means the link has not been set
correctly.
Instruction
Addr, Mask, Gateway and DNSServer return the string as ‘’ that
means it has not been set.
20.3.6 OsNetStartDhcp
Prototype
Function
Parameters
Return
Instruction
int OsNetStartDhcp(int NetLink);
Starts the DHCP function to obtain a dynamically assigned address.
Physical channel can only configure with Ethernet and
WiFi;
NetLink
NET_LINK_ETH Ethernet;
NET_LINK_WIFI WiFi(Wireless Local Area
Network)
RET_OK
Success
ERR_NET_IF
Has not configured Ethernet or WiFi.
This interface is only used to start the DHCP function, does not wait to assign
addresses, but it can check whether the address distribution is completed by
calling the OsNetCheckDhcp () or not.
Before starting the DHCP, it should close all the connections
because these connections may not be able to communicate
properly in the subsequent activity.
PAX Computer Technology (Shenzhen) Co., Ltd.
182
Prolin API Programming Guide
20.3.7 OsNetCheckDhcp
Prototype
Function
int OsNetCheckDhcp(int NetLink);
Check DHCP status.
Physical channel can only configure with Ethernet and
WiFi;
Parameters
Return
NetLink
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.
ERR_NET_DHCP
_DISCOVER
DHCPServer has not been found.
ERR_NET_DHCP
_OFFER
DHCP cannot assign the IP address.
ERR_NET_DHCP
_START
DHCP does not start.
Instruction
20.3.8 OsNetStopDhcp
Prototype
Function
Parameters
Return
void OsNetStopDhcp(int NetLink);
Stops DHCP function.
Physical channel can only configure with Ethernet and
WiFi;
NetLink
None
1.
Instruction
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 the success of DHCP, the system will regularly update the
configuration information, when the update fails, it will cause the network
become unavailable.
20.3.9 OsNetSetRoute
Prototype
int OsNetSetRoute(int NetLink);
PAX Computer Technology (Shenzhen) Co., Ltd.
183
Prolin API Programming Guide
Function
Parameters
Return
Sets the physical channel which used for connection.
NetLink
Physical channel, please refer to Physical channel list.
RET_OK
Success, the new link came into effect.
ERR_INVALID
_PARAM
Invalid parameter.
1.
2.
Instruction
3.
20.3.10
When the application starts, it must call this function to establish the TCP /
UDP connection;
While setting the physical channel, the system does not check the
availability of link. It will check only when the TCP connection is
established.
After setting the physical channel, it is only effective to the new
connection. The old ones continue to use the old channel.
OsNetGetRoute
Prototype
int OsNetGetRoute(void);
Function
Reads the physical channel which is currently used by the system.
Parameters
Return
None
>0
Physical channel, please refer to Physical channel list .
<0
Has not initialized the settings.
1.
Instruction
20.3.11
2.
After system initialization, the user needs to call OsNetSetRoute (),
otherwise OsNetGetRoute() will return <0;
After calling OsNetSetRoute () successfully, the system return values
must be NetLink that set by OsNetSetRoute ().
OsPppoeLogin
int OsPppoeLogin(const char *Name,
const char *Password,
Prototype
int TimeOutMs);
Function
Parameters
PPPoE link Login.
Name【Input】
PAX Computer Technology (Shenzhen) Co., Ltd.
User name;
184
Prolin API Programming Guide
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 ““;
TimeOutMs
Timeout,【unit:ms】
The valid range is 0~3600000;
Return
NET_DOING
Logging
RET_OK
Success
<0
Failed
Instruction
20.3.12
OsPppoeCheck
Prototype
int OsPppoeCheck(void);
Function
Checks the PPPoE link.
Parameters
Return
None
NET_DOING
Logging
RET_OK
The link has been successfully established.
<0
The link has been disconnected.
Instruction
20.3.13
OsPppoeLogout
Prototype
voidO sPppoeLogout(void);
Function
Disconnects the PPPoE link.
Parameters
None
Return
None
Instruction
PAX Computer Technology (Shenzhen) Co., Ltd.
185
{ This page intentionally left blank }
Prolin API Programming Guide
21GPRS/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 18 GPRS/CDMA return code list
Macro
Value
Description
PPP_LOGINING
1
PPP is logining.
PPP_LOGOUTING
2
PPP is logouting.
ERR_WL_POWER_ONING
-3501
Module is power on, please
wait.
ERR_WL_POWER_OFF
-3502
Module is power off.
ERR_WL_NOT_INIT
-3503
Has not called OsWlInit () to
initialize successfully and
cannot work normally.
ERR_WL_NEEDPIN
-3504
Sim card needs PIN.
ERR_WL_RSPERR
-3505
Module response error.
ERR_WL_NORSP
-3506
Module no response.
PAX Computer Technology (Shenzhen) Co., Ltd.
187
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 Wirless 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.
188
Prolin API Programming Guide
ERR_DEV_BUSY
Device is being used by another application.
ERR_DEV_NOT_
EXIST
Device does not exist.
1.
Instruction
2.
Before calling OsWlInit (), OsWlPowerSwitch (), OsWlLogin () or
OsWlLogout (), it must call this function to open the wireless module first.
It must call OsWlUnlock () to close wireless module if does not carry out
any operation.
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.
SIM card PIN,
Parameters
SimPin【Input】
The PIN length can't exceed 50 characters.
NULL means it does not need the PIN.
Return
RET_OK
Success
ERR_DEV_NOT_OPEN
Fail to call WlOpen ().
ERR_DEV_NOT_EXIST
Wireless module does not exist.
ERR_NO_PORT
Not enough physical uart.
ERR_WL_NEEDPIN
SIM card needs PIN.
ERR_WL_RSPERR
Response error.
ERR_WL_NORSP
Module has no response.
ERR_WL_NEEDPUK
SIM card needs PUK.
PAX Computer Technology (Shenzhen) Co., Ltd.
189
Prolin API Programming Guide
Instruction
ERR_WL_WRONG_PIN
PIN error.
ERR_WL_NOSIM
No SIM card.
ERR_WL_NOTYPE
Module cannot be recognized
1. Before using this function, be sure to call OsWlLock () successfully.
2. It needs to call this function successfully at system startup time and then
call OsWlLogin () to establish the link.
3. SIM card will automatically check the password if it requires.
4. If the module does not power on, the system will automatically supply
power for it.
5. When it returns ERR_WL_NOSIM (No SIM card), the application can use
some functions without SIM card.
6. After calling OsWlSwitchPower (), it should wait for 15 seconds until the
the module is stable, otherwise, it will be failed to perform OsWlInit ().
21.2.4 OsWlSwitchPower
Prototype
int OsWlSwitchPower(int OnOff);
Function
Powers on /off the wireless module.
Parameters
Return
OnOff
0
Power off
1
Power on
RET_OK
Success
ERR_DEV_NOT_EXIST
Module does not exist.
ERR_DEV_NOT_OPEN
Fail to call OsWlLock ().
Instruction
1. The time cost to power on the modules is different.
2. If the power is off, the O/S will shut off power to module.
3. While the power is on, if the wireless module has been
detected by the monitor, the system will power on
automatically.
4. Please wait for 8 seconds between call off and on.
5. Before power off, it will quit 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.
PAX Computer Technology (Shenzhen) Co., Ltd.
190
Prolin API Programming Guide
21.2.5 OsWlSwitchSleep
Prototype
int OsWlSwitchSleep(int OnOff);
Function
Makes the wireless module sleep or wake up.
Parameters
OnOff
0:
Wake up
1:
Sleep
Others : Errors.
Return
RET_OK
Success
ERR_DEV_NOT_EXIST
Module does not exist.
ERR_DEV_NOT_OPEN
Fail to call OsWlLock( ).
ERR_WL_PPP_ONLINE
PPP is on line.
Instruction
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
Instruction
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. It doesn’t need to call OsWLock() when use this function;
2. When the wireless link is not established, this API will get the signal
values from the module through AT commands;
3. After calling OsWlLogin () and establishing wireless link, if obtained
PAX Computer Technology (Shenzhen) Co., Ltd.
191
Prolin API Programming Guide
signal value is not the latest, then enter the data mode and if cannot
obtain real-time signal, it will return to ERR_WL_RSPERR.
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.
ERR_WL_POWER_ONING
Module is power on.
ERR_WL_POWER_OFF
Module is power 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,
Prototype
long Auth,
int TimeOutMs,
int KeepAlive,
PAX Computer Technology (Shenzhen) Co., Ltd.
192
Prolin API Programming Guide
int ReserParam);
Function
Logins on the wireless network and set up a wireless link.
APN – AccessPointName for GPRS
communication, dialing number for CDMA.
APN【Input】
Length <= 50 characters;
When pointer points to NULL, the application
should dial-up first and the protocol stacks
direct login on PPP.
User name;
Name【Input】
Length <= 50 bytes;
It cannot be NULL, if there is no user name,
replace it with an empty string “ “;
Password;
Password【Input】
Length <= 50 characters;
It cannot be NULL, if there is no password,
replace it with an empty string “ “;
Parameters
Auth
The supported authentication algorithms that
can support:
PPP_ALG_PAP
0x00000001
PAP
authentication algorithm
PPP_ALG_CHAP
0x0000000
CHAP
authentication algorithm
PPP_ALG_MSCHAPV1
0x00000004
MSCHAPV1 authentication algorithm
PPP_ALG_MSCHAPV2
0x00000008
MSCHAPV2 authentication algorithm
PPP_ALG_ALL
0xff
All algorithms are supported.
At least one type of authentication algorithm
has to be chosen; more than one
authentication algorithm will also be allowed
to choose 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
PAX Computer Technology (Shenzhen) Co., Ltd.
The valid range is 0~3600000; if it is <0,
automatically set it to 0, if more than 360000,
automatically set it to 3600000.
193
Prolin API Programming Guide
Interval for link check, unit is ms;
The valid range is 10000~3600000;
KeepAlive
Return
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
Processing
RET_OK
Link set up successfully.
ERR_DEV_NOT_EXIST
Wireless module does not exist.
ERR_DEV_NOT_OPEN
Perform OsWlLock() failed
ERR_INVALID_PARAM
Invalid parameter.
ERR_WL_POWER_ONING
Module is power on.
ERR_WL_POWER_OFF
Module is power off.
ERR_WL_NOT_INIT
Initialized failed.
ERR_NET_PASSWD
Password is incorrect.
ERR_NET_SERVER_BUSY
Server is busy, communication failure.
ERR_NET_AUTH
Has no authority to access to the RADIUS
server.
1.
2.
3.
4.
Instruction
Before using this function, be sure to call OsWlLock () successfully.
When TimeOutMs=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 with-in 60 seconds the login did not complete,
it means login failure or the module has an exception error.
5. Unsuccessful login for three consecutive times, it indicates the module
has no response, the application must call OsWlSwitchPower () to
reset the module.
6. After the link set up successfully, it can communicate through the IP
network communication function.
21.2.9 OsWlLoginEx
Prototype
int OsWlLoginEx(const char *DialNum,
PAX Computer Technology (Shenzhen) Co., Ltd.
const char *APN,
194
Prolin API Programming Guide
const char *Name,
const char *Password,
long Auth,
int TimeOutMs,
int KeepAlive,
int ReserParam);
Function
Logins on the wireless network and set up a wireless link.(it supports
modifying the dialing instructions)
The PPP dialing instruction.
DialNum【Input】
Length <= 50 characters;
When it is NULL, it adopts the default
instruction of system.
APN – AccessPointName for GPRS
communication, dialing number for CDMA.
ANP【Input】
Length <= 50 characters;
It cannot be NULL.
User name;
Name【Input】
Length <= 50 bytes;
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 with an empty string “ “;
Auth
PAX Computer Technology (Shenzhen) Co., Ltd.
The supported authentication algorithms:
PPP_ALG_PAP
0x00000001
PAP
authentication algorithm
PPP_ALG_CHAP
0x0000002
CHAP
authentication algorithm
PPP_ALG_MSCHAPV1
0x00000004
MSCHAPV1 authentication algorithm
PPP_ALG_MSCHAPV2
0x00000008
MSCHAPV2 authentication algorithm
PPP_ALG_ALL
0xff
All algorithms are supported.
At least one type of authentication algorithm
195
Prolin API Programming Guide
has to be chosen; more than one
authentication algorithms can be allowed to
choose 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
The valid range is 0~3600000; if it is <0,
automatically set it to 0, if more than 360000,
automatically set it to 3600000.
Interval for link check, unit is ms;
The valid range is 10000~3600000;
KeepAlive
If the link is longer than KeepAlive time but
without any messages; the system
automatically starts the link check interval;
(This functionality does not work now.)
Return
Instruction
ReserParam
Reserved parameter, used for extension.
PPP_LOGINING
Processing
RET_OK
Link set up successfully.
ERR_DEV_NOT_EXIST
Wireless module does not exist.
ERR_DEV_NOT_OPEN
Perform OsWlLock() failed。
ERR_INVALID_PARAM
Invalid parameter.
ERR_WL_POWER_ONING
Module is power on.
ERR_WL_POWER_OFF
Module is power off.
ERR_WL_NOT_INIT
Initialized failed.
ERR_NET_PASSWD
Password is incorrect.
ERR_NET_SERVER_BUSY
Server is busy, communication failure.
1. This function is similar to OsWlLogin (), when DialNum is NULL, the two
functions are the same.
2. Before using this function, be 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.
PAX Computer Technology (Shenzhen) Co., Ltd.
196
Prolin API Programming Guide
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 set up successfully, it can communicate through the IP
network communication function.
21.2.10
OsWlLogout
Prototype
int OsWlLogout(void);
Function
Logouts the wireless network and disconnects the wireless link.
Parameters
Instruction
None
RET_OK
Disconnect the wireless link successfully.
ERR_DEV_NOT_OPEN
Fail to call OsWlLock ().
Before using this function, be sure to call OsWlLock () successfully.
21.3 Wireless module information settings
21.3.1 OsWlSelSim
Prototype
int OsWlSelSim(int simno);
Function
Selects Sim card.
Parameters
Return
simno 【Input】
RET_OK
Success
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
0:
Selecting card slot 1
1:
Selecting card slot 2
Others:Parameter error
3.
Before using this function, be sure to call OsWlLock () successfully.
After select sim card, the module will be power on/off, and this function
blocks about 15 seconds. Application needs to re-calll 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
logining.
PAX Computer Technology (Shenzhen) Co., Ltd.
197
Prolin API Programming Guide
22WIFI
22.1 Return code list
Macro
Value
Description
#define ERR_WIFI_POWER_OFF
-3351
Module is power off.
#define ERR_NOT_FOUND_AP
-3352
Has not found AP.
#define ERR_AUTH_SEC_MODE
-3353
Authentication mode or encryption
mode error.
#define ERR_WIFI_BAD_SIGNAL
-3354
Wifi signal is bad.
1
#define RET_CONNECTING
Connecting
22.2 Encryption type List
Macro
Value
Description
#define PARE_CIPHERS_NONE
0X00000000
/* No security */
#define PARE_CIPHERS_WEP64
0x00000001
/* Means 40 bit key with
concatenated 24 bit initialization
vector */
#define PARE_CIPHERS_WEP128
0x00000002
/* Means 104 bit key with 24 bit
initialization vector */
#define PARE_CIPHERS_WEPX
0x00000004
/* Not sure of WEP key bits */
#define PARE_CIPHERS_CCMP
0X00000010
/* AES in Counter mode with
CBC-MAC */
PAX Computer Technology (Shenzhen) Co., Ltd.
198
Prolin API Programming Guide
#define PARE_CIPHERS_TKIP
0X00000020
/* Temporal Key Integrity Protocol
*/
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
};
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;
PAX Computer Technology (Shenzhen) Co., Ltd.
199
Prolin API Programming Guide
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 */
char Bssid[20]; /* MAC address */
int Channel;
/* Channel */
int Mode;
/* Connection mode, 0:Station; 1:IBSS */
int Rssi;
/* Signal value */
int AuthMode;
/* Authentication modes */
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, and 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,0:Auto set */
PAX Computer Technology (Shenzhen) Co., Ltd.
200
Prolin API Programming Guide
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.
ERR_DEV_BUSY
WIFI is already in use.
Instruction
22.5 OsWifiClose
Prototype
int OsWifiClose (void);
Function
Release the WIFI module
Parameters None
Return
None
Instruction
PAX Computer Technology (Shenzhen) Co., Ltd.
201
Prolin API Programming Guide
22.6 OsWifiSwitchPower
Prototype
int OsWifiSwitchPower (int Type);
Function
Sets WIFI module into the state of power-on and power-off.
1：Set module hardware into the state of power-on
Parameters Type
Return
Instruction
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 up after the boot, it doesn’t need to call this
function.
22.7 OsWifiScan
Prototype
int OsWifiScan (ST_WifiApInfo **Aps);
Function
Search for APs.
Parameters Aps【Output】
Return
Instruction
The searched AP information
>=0
The number of searched APs
ERR_MEM_FAULT
Memory error
ERR_INVALID_PARAM
Invalid parameter
ERR_WIFI_POWER_OFF
WIFI module is power off.
ERR_DEV_NOT_OPEN
Fail to access to the WIFI device.
/*For example:*/
int i, num;
ST_WifiApInfo * Aps;
num = OsWifiScan (&Aps);
if(num <= 0)
return -1;
for(i=0; i. For real-time operation, it can use the standard POSIX interface to get the access.
PAX Computer Technology (Shenzhen) Co., Ltd.
206
Prolin API Programming Guide
24System Information
In Prolin, the system messages generated by the hardware device will be realized 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)
{
int ret, signo;
while(1){
ret = sigwait(&mask, &signo);
if(ret != 0){
printf("sigwait err, ret=%d\n", ret);
PAX Computer Technology (Shenzhen) Co., Ltd.
207
Prolin API Programming Guide
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;
}
sigemptyset(&mask);
sigaddset(&mask, SIGMAG);
sigaddset(&mask, SIGICC);
ret = pthread_sigmask(SIG_SETMASK, &mask, &oldmask);
if(ret != 0){
PAX Computer Technology (Shenzhen) Co., Ltd.
208
Prolin API Programming Guide
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);
}
25Audio
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,
PAX Computer Technology (Shenzhen) Co., Ltd.
209
Prolin API Programming Guide
int Len,
int Volume,
int DurationMs);
Function
Parameters
Play WAV audio files.
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 using
the default volume.
DurationMs
【Output】
Play duration【Unit:ms】
RET_OK
Success
ERR_FILE_FORMAT
File format error
ERR_ACCESS_DENY
Access denied
ERR_INVALID_PARAM
Invalid parameter
Return
When Volume <0, set it as 0; when Volume >4, set is as 4.
Instruction
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.
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);
PAX Computer Technology (Shenzhen) Co., Ltd.
210
Prolin API Programming Guide
ret = OsPlayWave(buff, len, 3, 0);
if(ret != RET_OK)
printf("PlayWave Fail\n");
close(fd);
free(buff);
PAX Computer Technology (Shenzhen) Co., Ltd.
211
Prolin API Programming Guide
26Barcode
26.1 General Definiton
26.2 APIs
26.2.1 OsScanOpen
Property
int OsScanOpen (void);
Function
Open the barcode scanning module.
Parameter
Return
None
RET_OK
Success
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.2.2 OsScanRead
int OsScanRead(char *Buf,
Property
Function
int Len,
int TimeoutMs);
Read the barcode.
Buf
【Output】
The buffer used to store the barcode data.
One-dimensional code recommends being more
than 512 bytes, and two-dimensional code
suggests being 3072 bytes.
Len
【Input】
Buffer length
Parameter
PAX Computer Technology (Shenzhen) Co., Ltd.
212
Prolin API Programming Guide
Return
TimeoutMs 【Input】
Timeout of reading barcode,【unit:ms】
The valid range is 1500~36000, if it is less than
1500, set is as 1500, and if it is greater than
36000, set it as 36000. The error between the
actual timeout value and set value may be no
more than 1s, it is recommended to set the
timeout value as 3000ms.
>=0
The actual length of the read barcode data.
ERR_DEV_NOT_OPEN
Device is not open.
ERR_TIME_OUT
Timeout.
ERR_INVALID_PARAM
Invalid parameter
Instruction
26.2.3 OsScanClose
Property
void OsScanClose (void);
Function
Close the scanning device.
Parameter
None
Return
None
Instruction
PAX Computer Technology (Shenzhen) Co., Ltd.
213
Prolin API Programming Guide
27Power Management
27.1 OsCheckBattery
Prototype
int OsCheckBattery(void);
Function
Checks the battery.
Parameters None
BATTERY_LEVEL_0
0~20%
It needs immediately charge to the battery. At
this time it should not do the transaction,
wireless communications and printing.
When the battery capacity is low, the system
will automatically turn off.
Return
Instruction
BATTERY_LEVEL_1
20%~40%
BATTERY_LEVEL_2
40%~60%
BATTERY_LEVEL_3
60%~80%
BATTERY_LEVEL_4
80%~100%
BATTERY_LEVEL_CHARGE
Battery is being charged.
BATTERY_LEVEL_ABSENT
Battery does not exist. It needs an electric
power supply.
BATTERY_LEVEL_COMPLE
TE
Battery is fully charged, use the electric
power supply.
ERR_SYS_NOT_SUPPORT
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
PAX Computer Technology (Shenzhen) Co., Ltd.
214
Prolin API Programming Guide
charged or not, but the battery level only can be detected in the state of
battery powered.
2.
It is not recommended to call this function during printing, because th
e printer requires high current in the printing procedure, otherwise, it
will make the interface obtain an inaccurate charge.
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 into 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
wake up by pressing key, the screen is displayed and same as before sleep,
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.
PAX Computer Technology (Shenzhen) Co., Ltd.
215
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 0011;
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.
216
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.
217
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.
218
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.
219
Prolin API Programming Guide
Appendix 2 EPS PINBLOCK Format
String format: “1234”+ISN [6 byte] +PIN [Byte bit];
If the PIN 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.
220
Prolin API Programming Guide
Appendix 3 Register 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.hwver
Hardware version number. Main board- Interface board.
ro.fac.mach
Product type name.
ro.fac.conf.ver
Version information of configuration files.
ro.fac.pn
PN number
ro.fac.sn
SN number
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)
ro.fac.bt
Name of Bluetooth module. (If none, it means does not exist)
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)
ro.fac.modem
Name of Modem module. (If none, it means does not exist)
ro.fac.printer
Name of Printer module. (If none, it means does not exist)
ro.fac.pcd
Name of PCD module. (If none, it means does not exist)
ro.fac.sci
Name of ICC Reader. (If none, it means does not exist)
ro.fac.msr
Name of MSR Reader. (If none, it means does not exist)
ro.fac.videocard
Name of videocard module. (If none, it means does not exist)
ro.fac.audiocard
Name of audiocard module. (If none, it means does not exist)
ro.fac.sensor.gravity
Name of Gravity sensor module. (If none, it means does not
exist)
ro.fac.touchscreen
Name of Touch-screen module. (If none, it means does not exist)
ro.fac.sdhc
The specification, capacity range and speed level that support by
PAX Computer Technology (Shenzhen) Co., Ltd.
221
Prolin API Programming Guide
SD card. (If none, it means does not exist)
ro.fac.scanner
Name of Scanner module. (If none, it means does not exist)
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
System Preferred DNS
persist.sys.dns1
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)
PAX Computer Technology (Shenzhen) Co., Ltd.
222
Prolin API Programming Guide
Appendix 4 Validity of models and contents
According to the differences of the hardware design, some OSAL interfaces cannot take an
effect on a certain model. Details refer to the table below.
whether there is Wireless module, Modem module or Ethernet
module, it depends on the model configuration.( refer to the POS
PN number)
Chapters
S300
S800
S900
D200
Thread
√
√
√
√
System
Function
√
√
√
√
Encryption and √
Decryption
√
√
√
PED
√
√
√
√
LCD
√
√
√
√
Keyboard
√
√
√
√
Touch Screen
√
NA
√
NA
Signature
Board
√
NA
√
NA
Printer
NA
√
√
NA
Font Library
√
√
√
√
Code
√
√
√
√
MSR
√
√
√
√
ICC Reader
√
√
√
√
RF Reader
√
√
√
√
Communicatio
PORT_COM1
PORT_COM1
PORT_COM1
PORT_COM
PAX Computer Technology (Shenzhen) Co., Ltd.
223
Prolin API Programming Guide
n Port
PORT_USBDEV
PORT_COM2
PORT_USBDEV
1
PORT_USBHOS
T
PORT_PINPAD
PORT_USBHOS
T
PORT_
USBDEV
PORT_USBDEV
PORT_USBHOS
T
MODEM
NA
√
NA
NA
Network
Communicatio
n
√
√
√
NA
Network
Configuration
√
√
√
NA
GPRS/CDMA
NA
√
√
NA
WIFI
NA
NA
√
√
File System
√
√
√
√
System
Information
√
√
√
√
Audio
√
√
√
NA
Power
Management
√
√
√
√
Barcode
NA
NA
√
NA
Above table is based on the fully configured models.
PAX Computer Technology (Shenzhen) Co., Ltd.
224
Prolin API Programming Guide
Source Exif Data:
File Type : PDF File Type Extension : pdf MIME Type : application/pdf Linearized : No XMP Toolkit : XMP Core 5.4.0 Title : PAX XXX Programming Guide Creator : pax Format : application/pdf Description : V 1.0.0 Metadata Date : 2014:03:11 14:56:25+08:00 Create Date : 2014:03:11 14:54:49+08:00 Modify Date : 2014:03:11 14:56:25+08:00 Creator Tool : Microsoft® Word 2010 Instance ID : uuid:086d5556-755e-4311-a7d5-65fbb18adef9 Document ID : uuid:fdf09a27-c850-468d-a588-5e818a5c6661 Producer : Microsoft® Word 2010 Page Count : 243 PDF Version : 1.4 Author : pax Subject : V 1.0.0EXIF Metadata provided by EXIF.tools