Prolin API Programming

Guide
V 2.4.0

PAX Computer Technology(Shenzhen)Co.,Ltd.

PAX Computer Technology (Shenzhen) Co., Ltd. 1

Copyright Statement

Copyright © 2000-2020 PAX Computer Technology (Shenzhen) Co., Ltd. All rights
reserved. Any part of this documentation is strictly prohibited to be reproduced or
distributed in any form or for any purpose without the prior written permission of PAX
Computer Technology (Shenzhen) Co., Ltd. Despite the effort to enhance the
accuracy of this documentation, there are possible errors or omissions left herein. The
content of this documentation is subject to change without further notice. The
examples and sample programs demonstrated in this manual are for illustrations only
and may fail to meet practical needs. Please test and verify their applicability before
putting into commercial use.

I
 History of Revisions
Date Version Note Author
1. Exported the original version of
2012-08-15 V1.0.0 Prolin Team
Prolin from WIKI.
2012-11-06 V1.0.1 1. Internal review and modification. Prolin Team
1. Added Return Code List in
system function;
2. Added a new interface:
2012-12-26 V1.0.2 OsVerifySignExternal(); Prolin Team
3. Added WiFi module;
4. Added Appendix registry table.
2013-02-20 V1.0.3 Added instruction of OsOpenFont (). Prolin Team
1. Modified the instruction of
OsModemOpen();
2. Added two return values in
Modem: -3219 and -3220;
3. Added notes of DetectDialTone;
2013-03-06 V1.0.4 Added a new interface: Prolin Team
OsModemSwitchPower();
4. Modified parameter description
of OsPrnOpen() to “support bmp
format only”;
5. Modified sci_get_fd ().
1. Modified the description of
Chapter 4.10 “S series do not
support this function as S model
has no landline”;
2. Modified open() node in Chapter
14.4.1;
3. Updated time setting code
“pow-hwclock –w” to
2013-04-17 V1.0.5 Prolin Team
“pow-hwclock –w –u”;
4. Updated instruction of
OsWlInit(): When return value is
ERR_WL_NOSIM, some
functions can be used without an
SIM card;
5. Updated the instruction of
OsCheckBattery ().

2013-05-17 V1.0.6 1. Modified the description of Prolin Team

Timer;

II
 2. Supplemented the description of
Time Delay;
3. Added description of Registry
Table;
4. Modified the parameter
description of
ValueinOsRegGetValue ();
5. Modified the parameter
description of ShaOut in OsSHA
();
6. Updated description of GUI;
7. Added “1200, V22” and“2400,
FC” to the parts of synchronous
variable of ConnectRate[20]
inMODEM.
1. Modified the Registry;

2. Modified the data structure in

Font Library;
2013-08-09 V1.0.7 3. Updated interface Prolin Team
OsCheckBattery();
4. Updated chapter 15 IC Card
Reader and chapter 16 RF
Reader.
1. Added chapter 4.11 Save the
Crash Report for System
Function;
2. Modified the brightness level to
2013-10-22 V1.0.8 [0~10] in OsScrBrightness() in Prolin Team
the chapter of LCD and 0 means
closing the backlight;
3. Updated key value definition list
in the chapter of Keyboard.
1. Updated the chapter of
SystemFunction;
2. Modified character conversion
interface;
3. Added new interfaces
2013-10-31 V1.0.9 OsPortReset() and Prolin Team
OsPortCheckTx() in the chapter
of Communication;
4. Updated chapter Audio and
added a new interface:
OsPlayWave().

2013-11-20 V2.0.0 1. Added parameter description of Prolin Team

KeyVarType about 0x02 in

III
 OsPedDesDukpt();
2. Modified the value ranges of
several parameters in chapter
PED;
3. Modified the parameter
description of ucATQ0 in
OsPiccAntiSel();
4. Deleted OsPiccGetParam() and
OsPiccSetParam();
5. Updated the instruction of
OsRegGetValue();
6. Added description of
OsPortOpen();
7. Added description of
OsSysSleep();
8. Updated Return Code List in
Network Configuration chapter;
9. Added instruction of OsNetDns().
1. Modified Appendix 4;
2. Modified the instruction of
OsWlSelSim();
3. Added a new return value
forOsMsrOpen();
4. Added new interfaces
OsWlLoginEx(), OsMount() and
OsUmount();
5. Added chapter 26 Barcode;
6. Added description of AES
2014-02-25 V2.0.1 functional interface; Prolin Team
7. Modified the parameter
description of Name in
OsInstallFile();
8. Added an error code
“ERR_APP_MODE” for
OsInstallFile();
9. Added a new interface
OsCheckPowerSupply();
10. Deleted invalid codes in chapter
7 LCD for upgraded Prolin-2.4.
1. Updated OsSysSleep();
2014-03-04 V2.0.2 Prolin Team
2. Updated the WiFi module.
Modified the description of WiFi
2014-03-24 V2.0.3 Prolin Team
module.
1. Updated WiFi module;
3. Added a new interface
2014-04-16 V2.0.4 OsSysSleepEx(); Prolin Team
4. Removed MountFlag’s support
to MS-MOVE in OsMount();

IV
 5. Added new interfaces
OsReboot() and OsPowerOff().
1. Modified the instruction of
OsPrnSetIndent();
2. Modified functionality description
of OsModemCheck();
3. Modified parameter description
of TimeoutMS in OsPortRecv();
4. Modified value range of Volume
in OsPlayWave();
2014-06-03 V2.0.5 Prolin Team
5. Modified parameter description
of OsMifareOperate();
6. Added the corresponding
relationship between device
node and serial port.
7. Updated the instruction of
OsWlSwitchSleep() and
OsWifiSwitchPower().
1. Updated the instruction of
OsLog();
2. Updated the return value of
OsPedSetInterval();
3. Added a new interface
OsPedCancelPinEntry();
2014-07-10 V2.0.6 4. Added new return values of Prolin Team
OsVerifySign() and
OsVerifySignExternal();
5. Updated the instruction of
OsCheckBattery();
6. Updated Appendix 3 and
Appendix 4.
1. Updated the return value
PPP_LOGOUTING in
OsWlLogin() and add
corresponding instruction;
2014-10-09 V2.0.7 Prolin Team
2. Modified int OsWifiClose(void) to
void OsWifiClose(void);
3. Modified device nodes of LCD,
keypad and touch screen.
1. Modified the instruction of
OsRunApp();
2. Added U disk file format limitation
2014-11-26 V2.0.8 in OsMount(); Prolin Team
3. Added the instruction of
parameter Channel about S920
model in OsPortOpen();
4. Modified the instruction of

V
 OsNetPing();
5. Modified the instruction of
OsNetDns();
6. Added the instruction of
OsNetSetConfig();
7. Added the instruction of
OsNetStartDhcp();
8. Modified the functionality of
OsNetSetRoute()and added a
new return value;
9. Modified functionality, return
value and instruction of
OsNetGetRoute();
10. Modified the instruction of
OsPppoeLogin();
11. Modified the instruction of
OsWILogin();
12. Modified the instruction of
OsWILoginEx();
13. Added sampling frequency
limitation of WAVE file in
OsPlayWave();

14. Added new instruction for S920

models in Appendix 4.

1. Added a new interface

OsNetPingEx() to check the
status of network connection;
2. Added some return codes in
chapter 2.2 General Return
Code;
3. Added a return value and
instruction in OsPrnOpen();
4. Added some return values and
instruction in OsWlLock();
2014-12-18 V2.0.9 Prolin Team
5. Added a new return value and
instruction in OsWlLogout();
6. Modified the description of return
value in OsCheckBattery();
7. Added new instruction in
OsNetSetRoute();
8. Added two functions
OsFirmwareGetVersion() and
OsFirmwareUpgrade() in the
chapter of System Function.
1. Added a new return value
2015-02-06 V2.1.0 ERR_APP_NOT_EXIST in Prolin Team
OsRunApp();

VI
 2. Modified the instruction of
OsPedSetInterval();
3. Updated the parameter
description of DataIn in
OsPedUpdatePinBlock();
4. Modified the instruction of
OsPedDesDukpt();
5. Modified parameter description of
DataInLen in
OsPedRsaRecover();
6. Modified Appendix 1;

7. Added a new return value

ERR_WL_NOREG in OsWlInit()
denoting “fail to register GPRS
network ”;

8. Added a new restriction in

chapter Wifi: Prolin WiFi only
supports modules whose keyword
ro.fac.wifi is
“RS9110-N-11-02”,“01”, “03” or
“04”;
9. Added a new use instruction in
OsPortOpen(): Software
flow control and hardware flow
control will be closed after calling
this function;
10. Added two lines of code in “Set
Configuration Parameters of
Communication Port”.
1. Added specifications of LCD size
and rotation method of different
POS models in Appendix 4;
2. Added a new macro
ERR_BATTERY_ABSENT in
return value of OsWifiOpen() and
added its instruction;
2015-04-13 V2.1.1 Prolin Team
3. Added two new battery
management functions:
OsPmGetEvent() and
OsPmRequest();
4. Added key words
persist.sys.sleeptime and
persist.sys.sleepwaittime.
1. Revised the V2.1.1 version of
2015-07-09 V2.1.2 this documentation; Prolin Team
2. Added a return value and
function instruction in condition

VII
 that the battery power of D200 or
S920 gets too low (<3.65V);
3. Added the instruction of
OsPedWriteRsaKey();
4. Supplemented the instruction of
OsSysSleep();
5. Added and modified some codes
of user configuration structure:
PCD_USER_ST;
6. Modified parameter description
of PUKType in OsVerifySign();
7. Added some codes in TCP
programming;
8. Modified the instruction of
OsInstallFile();
9. Added the instructionof PX7
andPX5 in OsPortOpen();
10. Supplemented the instruction of
Prolin-2.4 and Prolin-phoenix-2.5
in OsPedWriteKey();
11. Added some descriptions of PX5
and PX7 in chapter POSIX
Interface;
12. Added PXX model in Appendix 4.
1. Added a return value
ERR_PUK_NOT_EXIST in the
chapter of System Function;
2. Added the instruction of
OsMount();
3. Added the instruction of
OsUmount();
4. Addedthe macro of SM (Secure
Module) key in the chapter of
PED;
5. Added the SM part in
OsPedWriteKey() function;
2015-11-24 V2.1.3 6. Added nine functions in the Prolin Team
chapter of PED, including
OsPedGenSM2Pair(),
OsPedWriteSM2Key(),
OsPedSM2Sign(),
OsPedSM2Verify(),
OsPedSM2Recover(),
OsPedSM(), OsPedSM(),
OsPedGetMacSM(), and
OsPedGetPinBlockSM4();
7. Added two new return values
ERR_MSR_END_ZEROERR
and

VIII
 ERR_MSR_PED_DECRYPTER
R in the chapter of MSR;
8. Added new return values in
Return Code List and added
PPP_DIRECT link in Physical
Channel List in the chapter of
Network Configuration;
9. Added a return value
ERR_MODE_NOT_SUPPORT
in the chapter of WiFi;
10. Added return value and
instruction in OsSysSleep ();
11. Added return value and
instruction in OsSysSleepEx().
1. Updated the instruction of
OsMount();
2. Updated the instruction of
OsUmount();
3. Added a return value and
instruction in
OsFirmwareUpgrade();
4. Added introduction of three-level
key system and PED key
mechanism in PED chapter;
5. Added OsGetOptInfo() and its
corresponding data structure in
chapter System Function;
6. Added instruction of low battery
2016-06-13 V2.1.4 in RF, Wifi, Printer and GPRS Prolin Team
chapters;
7. Added a member unsigned char
anti_interference_flag in user
configuration structure struct
pcd_user_t in RF chapter;
8. Modified some errors of Ipv6
related interfaces;
9. Added some related return
values and data structure of Ipv6
in chapter Network
Configuration;
10. Added some system
configuration parameters in
Appendix 3 Registry.
1. Updated the instruction of
OsSysSleep();
2016-07-04 V2.1.5 2. Modified the value range of Prolin Team
ConnectTimeout from 0~300 to
0~60 in the table of Variable

IX
 definitions of
ST_MODEM_SETUP in chapter
MODEM;
3. Updated the parameter
KeepAlive in OsWlLogin() and
OsWlLoginEx();
4. Updated the instruction of
OsModemConnect();
5. Updated the instruction of
OsSysSleepTime();
6. Added a new system
configuration parameter
persist.sys.lcdsaverbrightness
and deleted
persist.sys.eth0.enable in the
Appendix 3 Registry;
7. Added three encrypted file
system interfaces
OsCryptFormat() ,
OsCryptMount() and
OsCryptUmount() and related
return code list in chapter
System Function;
8. Added chapter 23 GPS;
9. Added a new return value
POWER_WPC and an related
note in OsCheckPowerSupply();
10. Modified the second point in the
note area under the
OsPmGetEvent().
1. Added an interface
OsPedSetPinIconLayout() in
PED chapter;
2. Added an interface
OsPrnClrBuf() in Printer chapter;
3. Added a note about Bssid
member of ST_WifiApSet structure
in the instruction of OsWifiConnect();
4. Added two new system
2016-07-21 V2.1.6 Prolin Team
configuration parameters
persist.sys.wifi.roam.dhcp
and persist.sys.tm.imei in
Appendix 3 Registry;
5. Updated the instruction of
OsGpsClose();
6. Updated the instruction of
OsWlSwitchPower();
7. In 6.5.6

X
 OsPedGetPinBlock(),6.6.1
OsPedGetPinDukpt(),6.4.4
OsPedVerifyPlainPin(),6.4.5
OsPedVerifyCipher() and 6.9.9
OsPedGetPinBlockSM4()
interfaces, added a note about
how calling they migh cause an
exception to the applications that
are running XUI and how to solve
this problem.
1. In Appendix 4 Validity of models
and contents, added Q80 and
D220 models to the validity table;
2. In MODEM chapter, added two
new return values, the error
codes are -3180 and -3184;
3. Added new system configuration
parameters
persist.sys.timezone.tz,
persist.sys.delayshutdown and
persist.sys.continue.print in
Appendix 3 Registry;
4. Added DnsAddrInfo structure
2016-10-17 V2.1.7 and OsNetDnsEx() function in Prolin Team
chapter 20 Network
Configuration;
5. Added a new interface
OsWifiWpsConnect() in WiFi
chapter;
6. In Power Management chapter,
added poweroff event, forbidding
poweroff and allowing poweroff
functions;
7. In Printer chapter, updated the
instruction of interface
OsPrnStart() and added a new
interface OsPrnSetParam().
1. Added new system configuration
parameters
persist.sys.autouload.enable,
persist.sys.autostartup.enable,
persist.sys.hostname,
2017-03-10 V2.1.8 persist.sys.wnet.version and Prolin Team
persist.sys.confirmshutdown in
Appendix 3 Registry;
2. In Network Configuration
chapter, added two new return
values ERR_ROUTE_EXIST

XI
 and
ERR_ROUTE_NONEXIST, a
structure Ipv4RouteTable and
three Ipv4 interfaces
OsNetSetRouteTable(),
OsNetDelRouteTable() and
OsNetGetRouteTable();
3. In Keyboard chapter, added a
new key value KEYCAMERA in
the key definition table;
4. In Barcode chapter, added data
definition and
OsScanSetParam() interface of
camera’s scan barcode function;
5. In Power Management chapter,
added return code list and
POWER_TYPE structure;
6. Added description of ports used
by USB scanner;
7. Added instructions for
OsPortOpen() and
OsPortSend();
8. Added chapter 24 Base;
9. Added instruction and return
value for OsScanSetParam();
10. Modified instruction of
OsBaseOpen() and
OsBaseClose();
11. Delete the repeated return value
-3606 in barcode module;
12. Added
persist.sys.keypad.duty_cycle
and items related to barcode
module in registry table;
13. Deleted ro.fac.scanner in registry
table.
1. Added a return value of
OsGpsOpen();
2. Added instruction of
OsNetSetDns();
3. Added note of OsSysSleep();
4. Added ro.fac.coulomb_counter
2017-07-13 V2.1.9 key in registry table; Prolin Team
5. Modified the function of
OsGetSysVer();
6. Added a note of OsSysSleep();
7. Modified the instruction of
OsPortRecv();
8. Added persist.sys.enable.debug

XII
 and rt.sys.mainapp.restart in
registry table, and updated the
relevant function instructions;
9. Modified the description of lights
in OsScanSetParam();
10. Updated the parameter
description of KeyVarType in
OsPedDesDukpt();
11. Added note of OsGetAppInfo();
12. Added the length limit of key in
OsRegSetValue() function;
13. Added return code list,
OsRecordOpen(),
OsRecordStart(),
OsRecordStop(),
OsRecordCheck(),
OsRecordClose() and
OsStopPlayWave() functions in
chapter 27 Audio.
14. Add new functions
OsPiccApplePoll() and
OsPiccOffCarrier().
1. Add a Enumeration structure
WAKEUP_SOURCE;
2. Add a new function
OsWakeupSource();
2017-09-07 V2.2.0 Prolin Team
3. Add a new function
OsPedSetPinBg().
4. Add a new function
OsPedCustomKeypad().
1. Modified the description of
OsRecordStart();
2. Updated the instruction of
OsPedCustomKeypad();
3. Added
persist.sys.ped.keypad.mask in
registry table;
4. Added persist.sys.sound.enable
in registry table;
2017-11-15 V2.2.1 5. Modified the description of Prolin Team
persist.sys.delayshutdown in
registry table;
6. Modified the instructions of
OsSysSleep() and
OsSysSleepEx();
7. Updated the instruction of
OsPmGetEvent();
8. Added ro.fac.security_level and
ro.fac.security_mode in registry

XIII
 table;
9. Added camera photography
function.
1. Added
persist.sys.mainapp.restart in
registry table;
2. Added
persist.sys.ped.keypad.type in
registry table;
3. Added a new function
OsGetAppExitCode();
4. Added
persist.sys.batterylow.offcnt,
2018-01-08 V2.2.2 Prolin Team
persist.sys.reboot.cnt and
persist.sys.powerkey.offcnt in
registry table;
5. Added a new function
OsPedSetOfflinePin();
6. Modified instruction and
parameter Dns of
OsNetSetDns();
7. Modified the value of parameter
InputLen in PED SM2 Algorithm.
1. Added macro
PORT_USBHOST1, and
modified the instruction of
OsPortOpen();
2. Modified the instruction of
OsNetSetDns() in section 20.4.1;
3. Added persist.sys.dns.static in
registry table;
4. Added
2018-04-02 V2.2.3 Prolin Team
persist.sys.xcb.installapp.lock in
registry table;
5. Modified the description of
DataIn in section 6.5.6
OsPedGetPinBlock;
6. Updated section 24.3 API
7. Updated the instructions of
OsInstallFile() and
OsFirmwareUpgrade().
1. Updated the instructions of
OsPedSetPinIconLayout(), the
description of parameters DataIn
and Mode in
2018-05-23 V2.2.4 Prolin Team
OsPedUpdatePinBlock() and the
description of parameters
InitVector, DataInLen and Mode
in OsPedAes();

XIV
 2. Modified the description of
persist.sys.ped.keypad.type and
added
persist.sys.ped.pin.icon.alignin in
registry table;
3. Added interface
OsScanDecodeBuf().
4. Added the permission instruction
of OsInstallFile() and
OsUninstallFile();
5. Deleted section 14.4 POSIX;
6. Added return code -3606.
1. Updated the content of chapter
“IC Card Reader” and “RF
Reader”;
2. Updated the description of
“POSIX Interface”.
3. Updated the description of
parameters DataInLen and Mode
in OsPedDes();
4. Added section “6.10 DES FIRE”;
2018-08-16 V2.2.5 Prolin Team
5. Added interface
OsPiccInitIso15693();
6. Added a new return code -2959
to RF module;
7. Added interfaces
OsPedEndPinEntry() and
OsPedPinKeyNotify(), and
updated section “6.5.10
OsPedGetKcv”.
1. Added NET_LINK_BT for
Bluetooth link;
2. Modified the instruction of the
registry key
“persist.sys.ped.keypad.type”;
3. Added two interfaces
OsPlayAudio() and
OsStopPlayAudio();
4. Added macros
2018-11-15 V2.2.6 RESOLUTION_WIDTH_1024_H Prolin Team
EIGHT_480 and
CAMERA_PIXEL_FORMAT_SB
GGR8 in chapter “Barcode and
Camera”;
5. Updated the instruction in
section OsCameraCapture();
6. Updated the parameter and
instruction in
OsPedGetPinBlock();

XV
 7. Updated the parameter and
instruction in
OsPedWriteAesKey();
8. Updated the function description
of OsPedAes();
9. Added a new return value
ERR_MSR_NO_TRACK_ERR in
“MSR” module;
10. Added a new interface
OsMsrReadJIS();
11. Added NET_LINK_USB link in
“Network Configuration” module;
12. Added event type
PM_MSG_POWER_ABNORMA
L and interface
OsCheckPowerStatus() in
“Power Management” module.
1. Updated the description of
parameter Level in
“OsSysSleepEx”;
2. Added key word
ro.security_version in “Appendix
3 Registry”;
3. Modified the description of
2018-11-29 V2.2.7 DUKPT mechanism; Prolin Team
4. Updated the structure
WAKEUP_SOURCE;
5. Updated the function instruction
and description of parameter
level in OsSysSleepEx();
6. Updated the applicable platform
of OsWakeupSource().
1. Updated the limited models for
OsSysSleep() and
OsSysSleepEx();
2019-02-01 V2.2.8 2. Added interface OsWlInitEx(); Prolin Team
3. Modified the description of return
code -3510 in chapter
“GPRS/CDMA”.
1. Added keyword
persist.sys.usbd.mode in the
registry;
2. Added new interface OsLed(),
and list the interface parameter
2019-03-13 V2.2.9 Prolin Team
settings related to the model in
the instruction;
3. Updated parameter KeyFlag in
OsPedSetFunctionKey(), and the
instruction of

XVI
 OsPedGetPinBlock(), and the
keyword
persist.sys.ped.keypad.type in
the registry.
Added
PM_MSG_BATTERY_DAMAGE and
2019-04-22 V2.3.0 Prolin Team
upgraded section
“OsCheckPowerStatus()”.
1. Added a new interface
OsTerminalConsumeInfo()；
2. Added description of
usbd.mode=4 in keyword
persist.sys.usbd.mode
3. Added
PCD_ERR_RXLEN_EXCEED_F
2019-05-15 V2.3.1 LAG in the return code list of RF Prolin Team
reader;
4. Updated section “User
Configuration Structure”;
5. Added macro ERR_EAP_ID in
the WiFi return code list.
6. Added a new interface
OsPedRkiInjectKey().
1. Added a new interface
OsSetKeyTone();
2. Modified the instruction of
OsRegSetValue().
2019-06-20 V2.3.2 Prolin Team
3. Modified the parameter
description in OsPedGetKcv();
4. Added a new interface
OsNetNat().
1. Modified the instruction of
OsCheckPowerStatus();
2. Added ERR_USB_MODE;
3. Added instruction in Zhang Mengying
2019-07-23 V2.3.3 OsOnBase();
4. Updated the return code and Zheng Zhihai
instruction of OsBaseOpen();
5. Added interface
OsCheckPortStatus().
1. Added instruction for
OsPedCancelPinEntry() and
OsPedEndPinEntry();
2. Updated the parameter Chen Xiaoyong
2019-09-12 V2.3.4 description of
OsPedGetPinBlock(); Zheng Zhihai
3. Added keywords
“persist.sys.ped.reboot.cycle”
and

XVII
 “persist.sys.ped.pinwait.retain” in
the Registry table;
4. Updated the instruction and
parameter description of
OsCheckPortStatus().
1. Added a new interface
OsGetBaseInfo();
2. Updated the description of
parameter DutyCycle;
3. Updated interface
OsCameraCapture(); Zheng Zhihai
4. Added a new interface Huang Ruzhen
2019-11-20 V2.3.5
OsCameraDetectMotion(); Li Xin
5. Modified the definition of wakeup Zhang Mengying
source;
6. Added description for interface
OsCheckBMSMode(), keyword
rt.app.key.tone and
rt.app.key.backlight.
1. Added section “Digital IO”;
2. Updated section “Macro
Definition of Camera” and
“OsScanSetParam”;
3. Updated chapter “Power
Management” and the Zheng Zhihai
description of Fang Wei
2019-12-03 V2.3.6 “persist.sys.confirmshutdown” in
registry; Zhang Mengying
4. Added section Zheng Zhihai
“OsPortCheckRx”;
5. Updated the return value in
section “OsCheckPortStatus”
and “OsGetBaseInfo”;
6. Added section “OsBaseCmd”.
1. Updated the instruction of
section “OsPortRecv”; Xu Bin
2019-12-31 V2.3.7
2. Added the instruction of Zhang Mengying
“OsPortCheckRx”.
1. Added the return code
description for installing fwp in
the OsInstallFile();
2020-04-01 V2.3.8 Zhang Mengying
2. Updated the description of the
registry key
“persist.sys.usbd.mode”.
1. Update the user configuration
structure in the chapter “RF Zhang Mengying
2020-05-13 V2.3.9 Reader”.
2. Modified the description of the Huang Ruzhen
keyword ro.fac.videocard;

XVIII
 3. Added descriptions of keywords
persist.sys.tm.cpu,
persist.sys.tm.flash and
persist.sys.tm.ram.
Updated “OsTerminalConsumeInfo”
and “OsPiccApplePoll” and Zhang Mengying
2020-06-30 V2.4.0
“persist.sys.usbd.mode” in the Huang Ruzhen
Registry.

XIX
Table of Contents

1 Introduction ........................................................................................................... 1

1.1 Purpose ...................................................................................................... 1

1.2 Target Readers .......................................................................................... 1

1.3 Prerequisites .............................................................................................. 2

1.4 Document Conventions .............................................................................. 2

2 Return Code and Parameter................................................................................. 4

2.1 Return Code Classification ......................................................................... 4

2.2 General Return Code ................................................................................. 5

2.3 Parameter .................................................................................................. 6

3 Thread .................................................................................................................. 7

4 System Function ................................................................................................... 8

4.1 Return Code List ........................................................................................ 8

4.2 Data Definition ............................................................................................ 9

4.3 Time set ................................................................................................... 10

OsSetTime ..................................................................................... 10

OsGetTime ..................................................................................... 11

4.4 Timer ........................................................................................................ 11

OsTimerSet .................................................................................... 11

OsTimerCheck ............................................................................... 11

4.5 Delay ........................................................................................................ 12

XX
 OsSleep.......................................................................................... 12

4.6 Thread ...................................................................................................... 12

4.7 Log ........................................................................................................... 13

OsLogSetTag ................................................................................. 13

OsLog ............................................................................................. 13

4.8 Get the Count Value ................................................................................. 13

OsGetTickCount ............................................................................. 13

4.9 Get Application Information ...................................................................... 14

OsGetAppInfo................................................................................. 14

OsGetOptInfo ................................................................................. 14

4.10 Buzzer ...................................................................................................... 15

OsBeep .......................................................................................... 15

4.11 Key tone ................................................................................................... 16

OsSetKeyTone ............................................................................... 16

4.12 Run Application ........................................................................................ 16

OsRunApp ...................................................................................... 16

OsGetAppExitCode ........................................................................ 17

4.13 Set and Read the Registry ....................................................................... 17

OsRegSetValue.............................................................................. 17

OsRegGetValue ............................................................................. 18

4.14 Install and Uninstall Files.......................................................................... 19

OsInstallFile.................................................................................... 19

XXI
 OsUninstallFile ............................................................................... 20

4.15 System Firmware Upgrade....................................................................... 21

OsFirmwareGetVersion .................................................................. 21

OsFirmwareUpgrade ...................................................................... 21

4.16 Verify Signature ........................................................................................ 22

OsVerifySign .................................................................................. 22

OsVerifySignExternal ..................................................................... 23

4.17 Get System Version ................................................................................. 24

OsGetSysVer ................................................................................. 24

4.18 Test Whether on the Base........................................................................ 24

OsOnBase ...................................................................................... 24

4.19 Save the Crash Report ............................................................................. 25

OsSaveCrashReport ...................................................................... 25

4.20 Mount and Unmount the External File System ......................................... 26

OsMount ......................................................................................... 26

OsUmount ...................................................................................... 28

4.21 Encrypted File System Interface .............................................................. 29

OsCryptFormat ............................................................................... 29

OsCryptMount ................................................................................ 30

OsCryptUmount.............................................................................. 31

4.22 LED .......................................................................................................... 31

OsLed ............................................................................................. 31

XXII
 4.23 Get Terminal Accumulated Usage Information......................................... 33

OsTerminalConsumeInfo................................................................ 33

4.24 Digital IO .................................................................................................. 34

OsDigitalIOGetStat ......................................................................... 34

OsDigitalIOSetStat ......................................................................... 34

5 Encryption and Decryption.................................................................................. 36

5.1 Return Code List ...................................................................................... 36

5.2 Random Number ...................................................................................... 36

OsGetRandom ............................................................................... 36

5.3 SHA Algorithm.......................................................................................... 37

OsSHA ........................................................................................... 37

5.4 DES Algorithm.......................................................................................... 38

OsDES ........................................................................................... 38

5.5 AES Algorithm .......................................................................................... 38

OsAES ........................................................................................... 39

5.6 RSA Algorithm.......................................................................................... 39

OsRSA ........................................................................................... 39

OsRSAKeyGen .............................................................................. 40

6 PED .................................................................................................................... 42

6.1 Return Code List ...................................................................................... 43

6.2 Data Definition .......................................................................................... 45

Key Type ........................................................................................ 45

XXIII
 DisplayAttribute of Asterisk............................................................. 46

6.3 Data Structure .......................................................................................... 46

Structure of RSA Key ..................................................................... 46

RSA Key Structure for Verifying the Ciphertext IC Card PIN .......... 46

6.4 Basic PED ................................................................................................ 47

OsPedOpen.................................................................................... 47

OsPedGetVer ................................................................................. 47

OsPedSetInterval ........................................................................... 47

OsPedVerifyPlainPin ...................................................................... 48

OsPedVerifyCipherPin ................................................................... 49

OsPedEraseKeys ........................................................................... 52

OsPedSetFunctionKey ................................................................... 52

OsPedClose ................................................................................... 53

OsPedCancelPinEntry .................................................................... 53

OsPedSetOfflinePin ....................................................................... 53

OsPedEndPinEntry ........................................................................ 54

OsPedPinKeyNotify ........................................................................ 55

6.5 MK/SK ...................................................................................................... 56

OsPedWriteKey .............................................................................. 56

OsPedWriteTIK .............................................................................. 60

OsPedWriteKeyVar ........................................................................ 62

OsPedSetAsteriskLayout ............................................................... 63

XXIV
 OsPedSetPinIconLayout ................................................................ 64

OsPedGetPinBlock ......................................................................... 66

OsPedUpdatePinBlock ................................................................... 68

OsPedGetMac ................................................................................ 69

OsPedDes ...................................................................................... 70

OsPedGetKcv................................................................................. 71

OsPedDeriveKey ............................................................................ 73

OsPedSetPinBg ............................................................................. 74

OsPedCustomKeypad .................................................................... 75

6.6 DUKPT ..................................................................................................... 76

OsPedGetPinDukpt ........................................................................ 76

OsPedGetMacDukpt ...................................................................... 78

OsPedDesDukpt ............................................................................. 79

OsPedGetKsnDukpt ....................................................................... 81

OsPedIncreaseKsnDukpt ............................................................... 81

6.7 RSA .......................................................................................................... 82

OsPedReadRsaKey ....................................................................... 82

OsPedWriteRsaKey ....................................................................... 82

OsPedRsaRecover ......................................................................... 83

OsPedReadCipherRsaKey ............................................................. 83

OsPedWriteCipherRsaKey ............................................................. 84

6.8 AES .......................................................................................................... 84

XXV
 OsPedWriteAesKey ........................................................................ 84

OsPedAes ...................................................................................... 87

6.9 SM Algorithm............................................................................................ 88

OsPedGenSM2Pair ........................................................................ 88

OsPedWriteSM2Key ...................................................................... 88

OsPedSM2Sign .............................................................................. 89

OsPedSM2Verify ............................................................................ 90

OsPedSM2Recover ........................................................................ 91

OsPedSM3 ..................................................................................... 92

OsPedSM4 ..................................................................................... 93

OsPedGetMacSM .......................................................................... 94

OsPedGetPinBlockSM4 ................................................................. 95

6.10 DES FIRE................................................................................................. 96

OsPedDFAuthDiver ........................................................................ 96

OsPedDFAuthMerge ...................................................................... 97

6.11 RKI ........................................................................................................... 98

OsPedRkiInjectKey ........................................................................ 98

7 LCD .................................................................................................................... 99

7.1 OsScrContrast........................................................................................ 101

7.2 OsScrBrightness .................................................................................... 101

7.3 OsScrGetSize ........................................................................................ 102

8 Keyboard .......................................................................................................... 103

XXVI
 8.1 OsKbBacklight ........................................................................................ 105

9 Touch Screen ................................................................................................... 107

10 Signature Pad ............................................................................................... 108

11 Printer ........................................................................................................... 109

11.1 Return Code List .................................................................................... 109

11.2 Open and Close ..................................................................................... 110

OsPrnOpen .................................................................................. 110

OsPrnReset .................................................................................. 110

OsPrnClose .................................................................................. 111

11.3 Printer Settings ....................................................................................... 111

OsPrnSetSize ............................................................................... 111

OsPrnSetDirection ........................................................................ 111

OsPrnSetGray .............................................................................. 112

11.4 Type Setting ........................................................................................... 112

OsPrnSetSpace............................................................................ 112

OsPrnSetReversal ........................................................................ 113

OsPrnSetIndent ............................................................................ 113

OsPrnCheck ................................................................................. 113

OsPrnGetDotLine ......................................................................... 114

OsPrnSetFont............................................................................... 114

OsPrnSelectFontSize ................................................................... 114

OsPrnFeed ................................................................................... 115

XXVII
 OsPrnPrintf ................................................................................... 116

OsPrnPutImage .......................................................................... 116

OsPrnStart .................................................................................. 117

OsPrnClrBuf ................................................................................ 118

OsPrnSetParam .......................................................................... 118

11.5 POSIX .................................................................................................... 118

Open ............................................................................................ 119

Read ............................................................................................. 119

Write ............................................................................................. 119

Close ............................................................................................ 120

12 Font Library................................................................................................... 121

12.1 Data Structure ........................................................................................ 121

12.2 Font Operation ....................................................................................... 122

OsEnumFont ................................................................................ 122

OsOpenFont ................................................................................. 122

OsCloseFont ................................................................................ 123

OsGetFontDot .............................................................................. 123

13 Code ............................................................................................................. 126

13.1 Code Conversion ................................................................................... 126

OsCodeConvert............................................................................ 126

14 MSR .............................................................................................................. 128

14.1 Return Code List .................................................................................... 128

XXVIII
 14.2 Data Structure ........................................................................................ 129

14.3 MSR Control Interface ............................................................................ 129

OsMsrOpen .................................................................................. 129

OsMsrClose.................................................................................. 130

OsMsrReset ................................................................................. 130

OsMsrSwiped ............................................................................... 130

OsMsrRead .................................................................................. 131

OsMsrReadJIS ............................................................................. 131

15 IC Card Reader............................................................................................. 133

15.1 Return Code List .................................................................................... 133

15.2 Data Structure ........................................................................................ 134

APDU Request Structure.............................................................. 134

APDU Response Structure ........................................................... 135

15.3 Encapsulated Interfaces ......................................................................... 136

OslccOpen.................................................................................... 136

OsIccDetect .................................................................................. 136

OsIccInit ....................................................................................... 137

OsIccExchange ............................................................................ 139

OsIccClose ................................................................................... 140

16 RF Reader .................................................................................................... 141

16.1 Return Code List .................................................................................... 141

16.2 Data Structure ........................................................................................ 142

XXIX
 User Configuration Structure ........................................................ 142

16.3 Encapsulate Interfaces ........................................................................... 144

OsPiccOpen ................................................................................. 144

OsPiccClose ................................................................................. 144

OsPiccResetCarrier ...................................................................... 145

OsPiccPoll .................................................................................... 145

OsPiccAntiSel............................................................................... 145

OsPiccActive ................................................................................ 146

OsPiccTransfer............................................................................. 147

OsPiccRemove............................................................................. 147

OsMifareAuthority ......................................................................... 147

OsMifareOperate ........................................................................ 148

OsPiccInitFelica .......................................................................... 149

OsPiccIsoCommand ................................................................... 149

OsPiccSetUserConfig ................................................................. 150

OsPiccGetUserConfig ................................................................. 150

OsPiccApplePoll ......................................................................... 150

OsPiccOffCarrier ......................................................................... 151

OsPiccInitIso15693 ..................................................................... 151

16.4 Notes of Touch Screen and RF Reader Programming ........................... 152

17 Communication Port ..................................................................................... 153

17.1 Data Definition ........................................................................................ 153

XXX
 17.2 Communication Control .......................................................................... 154

OsPortOpen ................................................................................. 154

OsPortClose ................................................................................. 156

OsPortSend .................................................................................. 156

OsPortRecv .................................................................................. 157

OsPortReset ................................................................................. 158

OsPortCheckTx ............................................................................ 158

OsPortCheckRx............................................................................ 159

17.3 POSIX Interface ..................................................................................... 159

Open ............................................................................................ 160

Read ............................................................................................. 160

Write ............................................................................................. 160

Close ............................................................................................ 161

Query the Buffer Data of Communication Port ............................. 161

Clear the Buffer Data of Communication Port .............................. 161

Set the Configuration Parameters of Communication Port ........... 161

18 MODEM ........................................................................................................ 165

18.1 Return Code List .................................................................................... 165

18.2 Data Structure ........................................................................................ 173

18.3 OsModemOpen ...................................................................................... 177

18.4 OsModemClose ..................................................................................... 178

18.5 OsModemSwitchPower .......................................................................... 178

XXXI
 18.6 OsModemConnect ................................................................................. 178

18.7 OsModemCheck .................................................................................... 180

18.8 OsModemExCmd ................................................................................... 181

18.9 OsModemHangup .................................................................................. 182

18.10 OsModemSend ................................................................................... 182

18.11 OsModemRecv ................................................................................... 183

18.12 OsPppomLogin ................................................................................... 184

18.13 OsPppomCheck .................................................................................. 186

18.14 OsPppomLogout ................................................................................. 186

19 Network Communication ............................................................................... 187

19.1 TCP Programming ................................................................................. 187

19.2 UDP Programming ................................................................................. 190

20 Network Configuration .................................................................................. 193

20.1 Return Code List .................................................................................... 193

20.2 Data Definition ........................................................................................ 195

Physical Channel List ................................................................... 195

IPv6 Status Value List .................................................................. 196

Data Structure .............................................................................. 196

20.3 IPv4 Network Configuration Interface ..................................................... 198

OsNetAddArp ............................................................................... 198

OsNetPing .................................................................................... 199

OsNetPingEx ................................................................................ 199

XXXII
 OsNetDns ..................................................................................... 200

OsNetDnsEx................................................................................. 201

OsNetSetConfig ........................................................................... 202

OsNetGetConfig ........................................................................... 203

OsNetStartDhcp ........................................................................... 204

OsNetCheckDhcp ......................................................................... 205

OsNetStopDhcp .......................................................................... 205

OsPppoeLogin ............................................................................ 206

OsPppoeCheck ........................................................................... 206

OsPppoeLogout .......................................................................... 206

OsNetSetRoute ........................................................................... 207

OsNetGetRoute .......................................................................... 207

OsNetSetRouteTable .................................................................. 208

OsNetDelRouteTable .................................................................. 208

OsNetGetRouteTable.................................................................. 209

OsNetNat .................................................................................... 210

20.4 IPv4/IPv6 Network Configuration Interface............................................. 211

OsNetSetDns ............................................................................... 211

20.5 IPv6 Network Configuration.................................................................... 211

OsNetPing6 .................................................................................. 211

OsNetSetIPv6Addr ....................................................................... 212

OsNetGetIPv6Addr ....................................................................... 213

XXXIII
 OsNetGetRouteAdvertise6 ........................................................... 214

OsNetStartDhcp6 ......................................................................... 215

OsNetCheckDhcp6 ....................................................................... 216

OsNetStopDhcp6 ......................................................................... 216

OsNetSetRouteTable6 ................................................................. 217

OsNetGetRouteTable6 ................................................................. 218

21 GPRS/CDMA ................................................................................................ 219

21.1 Return Code List .................................................................................... 219

21.2 Wireless Module Interface ...................................................................... 220

OsWlLock ..................................................................................... 220

OsWlUnLock ................................................................................ 221

OsWlInit ........................................................................................ 221

OsWlInitEx.................................................................................... 222

OsWlSwitchPower ........................................................................ 223

OsWlSwitchSleep ......................................................................... 224

OsWlGetSignal ............................................................................. 225

OsWlCheck .................................................................................. 226

OsWlLogin .................................................................................... 226

OsWlLoginEx .............................................................................. 229

OsWlLogout ................................................................................ 231

21.3 Wireless Module Information Settings .................................................... 232

OsWlSelSim ................................................................................. 232

XXXIV
22 WiFi .............................................................................................................. 233

22.1 Return Code List .................................................................................... 233

22.2 Encryption Type List ............................................................................... 234

22.3 Data Structure ........................................................................................ 234

22.4 OsWifiOpen ............................................................................................ 237

22.5 OsWifiClose ........................................................................................... 237

22.6 OsWifiSwitchPower ................................................................................ 238

22.7 OsWifiScan ............................................................................................ 238

22.8 OsWifiConnect ....................................................................................... 239

22.9 OsWifiDisconnect ................................................................................... 240

22.10 OsWifiCheck ....................................................................................... 240

22.11 OsWifiCmd .......................................................................................... 242

22.12 OsWifiWpsConnect ............................................................................. 242

23 GPS .............................................................................................................. 244

23.1 Return Code List .................................................................................... 244

23.2 Data Definition ........................................................................................ 244

23.3 OsGpsOpen ........................................................................................... 245

23.4 OsGpsRead ........................................................................................... 245

23.5 OsGpsClose ........................................................................................... 246

24 Base ............................................................................................................. 247

24.1 Introduction ............................................................................................ 247

24.2 Macro Definition ..................................................................................... 248

XXXV
 24.3 API ......................................................................................................... 248

OsOnBase .................................................................................... 248

OsBaseOpen ................................................................................ 248

OsBaseCheck .............................................................................. 249

OsBaseClose ............................................................................... 250

OsBaseScan ................................................................................ 250

OsBaseConnect ........................................................................... 251

OsBaseDisconnect ....................................................................... 252

OsCheckPortStatus ...................................................................... 253

OsGetBaseInfo ............................................................................. 253

OsBaseCmd ................................................................................ 254

25 File System ................................................................................................... 256

26 System Information ....................................................................................... 257

27 Audio ............................................................................................................ 260

27.1 Return Code List .................................................................................... 260

27.2 OsRecordOpen ...................................................................................... 260

27.3 OsRecordStart ....................................................................................... 261

27.4 OsRecordStop........................................................................................ 263

27.5 OsRecordCheck ..................................................................................... 263

27.6 OsRecordClose ...................................................................................... 264

27.7 OsPlayWave .......................................................................................... 264

27.8 OsStopPlayWave ................................................................................... 265

XXXVI
 27.9 OsPlayAudio .......................................................................................... 266

27.10 OsStopPlayAudio ................................................................................ 267

28 Barcode and Camera .................................................................................... 268

28.1 General Definition .................................................................................. 268

28.2 Data Definition ........................................................................................ 269

Macro Definition of Camera .......................................................... 269

Image Resolution Macro Definition of Photography ..................... 269

Image Data Format Macro Definition of Photography .................. 270

The Attribute Structure of the Photography Parameter ................ 270

Return Code List .......................................................................... 270

28.3 Basic Interface ....................................................................................... 271

OsScanSetParam ......................................................................... 271

OsScanOpen ................................................................................ 272

OsScanRead ................................................................................ 272

OsScanClose ............................................................................... 273

OsCameraOpen ........................................................................... 273

OsCameraClose ........................................................................... 273

OsCameraGetParam .................................................................... 274

OsCameraSetParam .................................................................... 274

OsCameraCapture ....................................................................... 275

OsScanDecodeBuf ..................................................................... 276

OsCameraDetectMotion.............................................................. 277

XXXVII
29 Power Management ...................................................................................... 279

29.1 Return Code List .................................................................................... 279

29.2 Data Structure ........................................................................................ 279

29.3 OsCheckBattery ..................................................................................... 281

29.4 OsCheckPowerSupply ........................................................................... 282

29.5 OsSysSleep ........................................................................................... 283

29.6 OsSysSleepEx ....................................................................................... 284

29.7 OsSysSleepTime ................................................................................... 285

29.8 OsReboot ............................................................................................... 285

29.9 OsPowerOff............................................................................................ 286

29.10 OsPmGetEvent ................................................................................... 286

29.11 OsPmRequest..................................................................................... 287

29.12 OsWakeupSource ............................................................................... 287

29.13 OsCheckPowerStatus ......................................................................... 288

29.14 OsCheckBMSMode ............................................................................ 289

29.15 Get the Power Management Information ............................................ 290

29.16 Client Sends Request ......................................................................... 290

Appendix 1 PIN Block Format................................................................................. 291

Appendix 2 EPS PINBLOCK Format ...................................................................... 295

Appendix 3 Registry ............................................................................................... 296

Appendix 4 Validity of Models and Contents .......................................................... 305

XXXVIII
Table List

Table 2.1 Return code classification list .............................................................. 4

Table 2.2 General return code list ....................................................................... 5

Table 4.1 System function return code list........................................................... 8

Table 4.2 Definitions of file types ......................................................................... 8

Table 5.1 Encryption and decryption return code list ......................................... 36

Table 6.1 PED return code list ........................................................................... 43

Table 6.2 Key types ........................................................................................... 45

Table 6.3 Layout attributes of asterisk ............................................................... 46

Table 6.4 Color values of asterisk ..................................................................... 46

Table 11.1 Printer return code list ................................................................... 109

Table 14.1MSR return code list ....................................................................... 128

Table 15.1 IC Card reader return code list ...................................................... 133

Table 16.1 Return code list.............................................................................. 141

Table 17.1 Macro definition list of communication ports .................................. 153

Table 17.2 Return code list of USB port functions ........................................... 153

Table 18.1 Modem return code list .................................................................. 165

Table 18.2 Variable definitions of ST_MODEM_SETUP ................................. 174

Table 20.1 Network configuration return code list ........................................... 193

Table 20.2 Physical channel list ...................................................................... 195

Table 20.3 IPv6 status value list ...................................................................... 196

XXXIX
Table 21.1 GPRS/CDMA return code list ........................................................ 219

Table 22.1 Return code list.............................................................................. 233

Table 22.2 Encryption type list ........................................................................ 234

Table 27.1 Return code list.............................................................................. 260

Table 28.1 Camera definition list ..................................................................... 269

Table 28.2 Image resolution definition list ....................................................... 269

Table 28.3 Image data format definition list ..................................................... 270

Table 28.4 Return code list.............................................................................. 270

XL
 Prolin API Programming Guide

1 Introduction

1.1 Purpose

This documentation introduces the framework of Prolin applications and the key
points of GUI and other important frameworks. It provides programming guide for API
interfaces compatible with controlling hardware based on Prolin OS and offers
corresponding instructions conducive to a successful design for developers.

1.2 Target Readers

This documentation is targeted at Prolin OS developers who are committed to

developing Prolin local applications.

Prolin provides a series of interfaces based on Linux system calls and POSIX
interfaces. And a set of OSAL interfaces, beginning with the prefix “Os”, are
encapsulated for the compatibility demand of some background services and
applications. In addition, demo programming codes of POSIX interfaces and system
libraries are illustrated in this documentation to guide developers to access device or
system function.

In this documentation, all the interfaces beginning with “Os” are defined in osal.h of
SDK, unless otherwise specified.

PAX Computer Technology (Shenzhen) Co., Ltd. 1

 Prolin API Programming Guide

Prolin SDK provides necessary tools and resources for local Prolin applications.
Different from the background system applications, Prolin SDK can run independently
as executive programs on Prolin OS-based devices. Local applications enjoy a great
deal of privileges. They can access all Prolin OS features, save data in local file
system and even communicate with other installed programs through a special URL.

1.3 Prerequisites

Basic knowledge of Linux is necessary before reading this documentation. Related

notions include:

 Process, thread and Linux system functions and their roles in application
development;

 Memory management, including how to create and release an application;

 GUI application framework;

 Linux input subsystem and Framebuffer driver interface.

It is necessary to download and install Prolin SDK before developing Prolin

applications. With regard to Linux system, Linux 2.6.22 or higher version is required;
while for Windows system, Windows XP or higher version is required. For more
information about Prolin SDK, please visit PAX Partners Network
(https://support.paxsz.com/) or send email to support@paxsz.com if you haven’t
registered.

1.4 Document Conventions

Conventions used in this document and their corresponding meanings are listed
below:

Giving notes.

PAX Computer Technology (Shenzhen) Co., Ltd. 2

 Prolin API Programming Guide

Caution for general problems.

Warning for crucial problems.

PAX Computer Technology (Shenzhen) Co., Ltd. 3

 Prolin API Programming Guide

2 Return Code and

Parameter

2.1 Return Code Classification

Table 2.1 lists the types and value ranges of return codes involved in this document:

Table 2.1 Return code classification list

Value(Decimalis
Type Description
m)
General Return
-1000~-1999 General error code of API.
Value
System Function -2200~-2299
Power Management -2300~-2399
Encryption and
-2400~-2499
Decryption
Font Library -2500~-2599
LED display -2600~-2699
MSR -2700~-2799
IC Card Reader -2800~-2899

PAX Computer Technology (Shenzhen) Co., Ltd. 4

 Prolin API Programming Guide

Contactless IC Card
-2900~-2999
Reader
Communication
-3000~-3099
Port
MODEM -3100~-3299
IP Network
-3300~-3399
Configuration
PED -3800~-3899

2.2 General Return Code

Table 2.2 lists the macro definitions, values and corresponding descriptions of the
general return values in this documentation.

Table 2.2 General return code list

Macro Value Description

RET_OK 0 Succeeded.
ERR_INVALID_HANDLE -1000 Invalid handle.
ERR_TIME_OUT -1001 Timeout.
Application does not
ERR_APP_NOT_EXIST -1002
exist.
ERR_INVALID_PARAM -1003 Invalid parameter.
ERR_DEV_NOT_EXIST -1004 Device does not exist.
ERR_DEV_BUSY -1005 Device is busy.
ERR_DEV_NOT_OPEN -1006 Device is not open.
ERR_ACCESS_DENY -1007 Access denied.
ERR_FONT_NOT_EXIST -1008 Font does not exist.
ERR_FILE_FORMAT -1009 File format error.
ERR_USER_CANCEL -1010 Canceled by user.
No communication
ERR_NO_PORT -1011
port.
ERR_NOT_CONNECT -1012 Not Connected
ERR_MEM_FAULT -1013 Memory error.
System configuration
ERR_SYS_BAD -1014
error.
ERR_SYS_NOT_SUPPORT -1015 System does not

PAX Computer Technology (Shenzhen) Co., Ltd. 5

 Prolin API Programming Guide

support this function.

Character string is too
ERR_STR_LEN -1016
long.
ERR_TOO_MANY_HANDLE -1017 Too many handles
ERR_APP_MODE -1018 Mode error.
ERR_FILE_NOT_EXIST -1019 File does not exist.
Touch screen is not
ERR_TS_DISABLE -1020
open.
Character encoding
ERR_FONT_CODE -1021
error.
ERR_VERSION_TOO_LOW -1022 The version is too low.
ERR_BATTERY_ABSENT -1023 Battery is absent.
ERR_BATTERY_VOLTAGE_TO Battery voltage is too
-1024
O_LOW low.

2.3 Parameter

There are two types of API parameters: input parameter and output parameter. They
are distinguished with identifiers in this documentation.
All the input and output string parameters end with"\x00" and valid string length must
be clarified in parameter description.

PAX Computer Technology (Shenzhen) Co., Ltd. 6

 Prolin API Programming Guide

3 Thread

Prolin supports pthread of POSIX. The header file of pthread is located at the
installation directory of ProlinBuilder:
toolchains\arm-linux\arm-softfloat-linux-gnu\include\pthread.

PAX Computer Technology (Shenzhen) Co., Ltd. 7

 Prolin API Programming Guide

4 System Function

4.1 Return Code List

Table 4.1 System function return code list

Macro Value Description

ERR_FILE_NOT_FOUND -2201 File is not found.
ERR_VERIFY_SIGN_FAIL -2204 Fail to verify signature.
ERR_NO_SPACE -2205 System space is not enough.
ERR_NEED_ADMIN -2207 Need higher permission.
ERR_PUK_NOT_EXIST -2208 PUK doesn’t exist.
ERR_OS_VERSION_TOO
-2209 System version is too low.
_LOW
ERR_INVALID_PARAM -1003 Invalid parameter.
ERR_DEV_NOT_EXIST -1004 Device doesn’t exist.
ERR_DEV_BUSY -1005 Device is busy.
ERR_ACCESS_DENY -1007 Access denied.
ERR_SYS_NOT_SUPPOR
-1015 System does not support.
T
ERR_FILE_NOT_EXIST -1019 File doesn’t exist.

Table 4.2 Definitions of file types

PAX Computer Technology (Shenzhen) Co., Ltd. 8

 Prolin API Programming Guide

Macro Value Description

FILE_TYPE_APP 1 Application package.
FILE_TYPE_APP_PA
2 Application data file.
RAM
FILE_TYPE_SYS_LIB 3 System dynamic library file.
FILE_TYPE_PUB_KE
4 Public key file.
Y
FILE_TYPE_AUP 5 Application upgrade package.

4.2 Data Definition

LOG_T(LOG type enumeration):

LOG_T：

typedef enum{
LOG_DEBUG, /* Display debugging message*/
LOG_INFO, /* Display prompt message*/
LOG_WARN, /* Display warning message*/
LOG_ERROR, /* Display error message*/
} LOG_T;

ST_TIME(time structure):

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 (valid only in read time)*/
} ST_TIME;

ST_TIMER(timer structure):

ST_TIMER：

PAX Computer Technology (Shenzhen) Co., Ltd. 9

 Prolin API Programming Guide

typedef struct{
unsigned long Start;
unsigned long Stop;
unsigned long TimeLeft;
} ST_TIMER;

ST_APP_INFO(application information structure):

ST_APP_INFO：

typedef struct{
char Id[64];
char Name[64];
char Bin[64];
char Artwork[64];
char Desc[64];
char Vender[32];
char Version[32] ;
} ST_APP_INFO;

ST_OPT_INFO(optional system component information structure):

ST_OPT_INFO：

typedef struct {
char Name[64];
char Version[32];
} ST_OPT_INFO;

4.3 Time set

OsSetTime

Prototype int OsSetTime(const ST_TIME *Time);

Set system time and date. Prolin system does not contain time
Function
zone.
A pointer to ST_TIME structure that contains
Parameters Time[Input] system time. DayOfWeek is ignored in
ST_TIME structure; it can’t be NULL.
RET_OK Succeeded.
Return
ERR_NEED_ADMIN Permission denied.

PAX Computer Technology (Shenzhen) Co., Ltd. 10

 Prolin API Programming Guide

ERR_INVALID_PARA
Invalid parameter.
M
Only the main application has permission to set time; otherwise,
Instruction
it will fail and return ERR_NEED_ADMIN.

OsGetTime

Prototype void OsGetTime(ST_TIME *Time);

Function Get system time and date.
A pointer to ST_TIME structure that contains
system time.
Parameters Time[Output]
DayOfWeek is ignored in ST_TIME structure; it
can’t be NULL.
Return None.
Instruction

4.4 Timer

OsTimerSet

int OsTimerSet(ST_TIMER *Timer,

Prototype
unsigned long Ms);
Function Create a timer with a specified timeout value.
A poiner to ST_TIMER structure.
Timer[Output]
Parameters It can’t be NULL.
Ms[Input] Timeout.[unit:ms].
RET_OK Succeeded.
Return
ERR_INVALID_PARAM Invalid parameter.
The timer is irrelevant to system time, and it will be paused
Instruction
when system enters sleep mode.

OsTimerCheck

Prototype unsigned long OsTimerCheck(ST_TIMER *Timer);

Function Check the remaining time of a specified timer.
Parameters Timer[Input] Timer structure ST_TIMER.
>=0 Remaining time. [unit:ms]
Return
ERR_INVALID_PARA Invalid parameter.

PAX Computer Technology (Shenzhen) Co., Ltd. 11

 Prolin API Programming Guide

M
Instruction

4.5 Delay

OsSleep

Prototype void OsSleep(unsigned int Ms);

Function Suspend the current process or thread.
Parameters Ms [Input] Delay time.[unit:ms]
Return None
Instruction

4.6 Thread

Prolin thread is implemented by standard linux POSIX interface. Please refer to the
following code:

Example:
#include <pthread.h>
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;
}

PAX Computer Technology (Shenzhen) Co., Ltd. 12

 Prolin API Programming Guide

4.7 Log

OsLogSetTag

Prototype void OsLogSetTag(const char *Tag);

Function Set LOG information tag.
Parameters Tag[Input] LOG information tag.
Return None.
1. Call this function to set LOG tag; the default tag is NULL.
2. It is recommended to set tag to be an application name.
Instruction 3. The valid Tag length ranges from 0 to 32 bytes; only the
first 32 bytes will be used if Tag length exceeds 32 bytes.
4. OsLog() will not save LOG information for a NULL tag or an
empty string.

OsLog

int OsLog(LOG_T Prio,

Prototype const char *fmt,
…);
Function Save LOG information.
Prio[Input] LOG_T structure, type of LOG information.
Parameters
fmt [Input] Format of LOG information.
RET_OK Succeeded.
Return
ERR_INVALID_PARAM Invalid parameter.
OsLogSetTag() must be called to set tag before calling this
Instruction
function; otherwise, OsLog() will fail to save LOG information.

4.8 Get the Count Value

OsGetTickCount

Prototype unsigned long OsGetTickCount(void);

Get the cumulative running time from startup to present time,
Function
excluding sleeping time.[unit:ms]
Parameters None
Return >0 Count value.

PAX Computer Technology (Shenzhen) Co., Ltd. 13

 Prolin API Programming Guide

Instruction

4.9 Get Application Information

OsGetAppInfo

int OsGetAppInfo(ST_APP_INFO AppInfo[],

Prototype
int InfoCnt);
Function Get information of installed applications.
A pointer to application information
AppInfo[Output] structure of ST_APP_INFO array. It cannot
Parameters be NULL.
The number of App that can be stored in
InfoCnt[Input]
AppInfo array.
The number of App information that
>=0
has been obtained.
Return ERR_NEED_ADMIN Permission denied.
ERR_INVALID_PAR
Invalid parameter.
AM
1. Only the main application has permission to get App
information.(Note: This limitation is only valid for Prolin-2.4
platform, sub-application on other platform can also get
Instruction APP information.)
2. When the real number of application is larger than InfoCnt,
only the first InfoCnt number of applications will be
obtained.

OsGetOptInfo

int OsGetOptInfo(ST_OPT_INFO OptInfo[],

Prototype
int InfoCnt);
Function Get information of installed optional system components.
A pointer to application information
OptInfo [output] structure of ST_OPT_INFO array. It cannot
be NULL.
Parameters
The number of optional system
InfoCnt [input] components that can be stored in OptInfo
array.
Return >=0 The number of optional system
components information that has been

PAX Computer Technology (Shenzhen) Co., Ltd. 14

 Prolin API Programming Guide

obtained.
ERR_FILE_NOT_ The file path that stores optional system
FOUND components does not exist.
ERR_INVALID_P
ARAM Invalid parameter.
When the real number of optional system components is larger
Instruction
than InfoCnt, only the first InfoCnt number will be obtained.

4.10 Buzzer

OsBeep

void OsBeep(int ToneType,

Prototype
int DurationMs)；
Function Set the frequency and duration of buzzer.
Tone type.
ToneType [Input]
The valid ToneType ranges from 1 to 7.
Duration.[unit:ms]
The valid DurationMs ranges from 10 to
Parameters 10000.
DurationMs
[Input] If DurationMs<10, it will be set to 10 by
default;
If DurationMs>10000, it will be set to 10000
by default.
Return None.
Tone type and corresponding frequency:
Tone type Buzzer frequency(Hz)
≤1 1680
2 1850
3 2020
Instruction
4 2130
5 2380
6 2700
≥7 2750

PAX Computer Technology (Shenzhen) Co., Ltd. 15

 Prolin API Programming Guide

4.11 Key tone

OsSetKeyTone

void OsSetKeyTone(int OnOff,

Prototype
int DutyCycle);
Function Set the key tone switch and duty cycle.
0 represents turn off the keytone;
OnOff [Input] 1 represents turn on the keytone.
Keytone duty cycle, the ranges is [1,99].
Parameters If DutyCycle <1, or DutyCycle >99, keep the
DutyCycle[Input] same DutyCycle.
If DutyCycle=50, the volume is the
maximum.
Return None
Instruction

4.12 Run Application

OsRunApp

int OsRunApp(char *AppId,

char **Argv,
Prototype void *Data,
RUNAPP_CB CbOut,
RUNAPP_CB CbErr);
Function Switch to a specified sub-application.
AppId[Input] Sub-application ID.
Argv[Input] Input parameter list of sub-application.
If not needed, Argv can be set to NULL.
Parameters Data[Input] Customized data, which will be passed to
CbOut() and CbErr() for calling back.
CbOut[Input] Standard output message callback function.
CbErr[Input] Standard error message callback function.
RET_OK Succeeded.
Return ERR_APP_NOT_EXIS
Sub-application does not exist.
T

PAX Computer Technology (Shenzhen) Co., Ltd. 16

 Prolin API Programming Guide

ERR_ACCESS_DENY Access denied.

ERR_APP_MODE Mode error.

ERR_INVALID_PARAM Invalid parameter.
ERR_NEED_ADMIN Permission denied.
1. Only the main application has permission to switch
application; otherwise, ERR_NEED_ADMIN will be
returned.
2. OsRunApp() will switch to the sub-application specified by
AppId; the sub-application cannot be the main application;
otherwise, ERR_INVALID_PARAM will be returned.
Instruction 3. The standard output message and standard error message
of sub-application will be exported to CbOut() and CbErr(),
respectively; if there are multiple lines of messages, the
corresponding callback function will be called for several
times. The callback function is defined as:
typedef void (*RUNAPP_CB)(char *appid, char *str, void
*data).

OsGetAppExitCode

Prototype int OsGetAppExitCode(void);

Function Get the exit code of sub-application.
Parameters None
Return The exit code of sub-application
Users can call this function after OsRunApp() to get the exit code
Instruction
of sub-application.

4.13 Set and Read the Registry

OsRegSetValue

int OsRegSetValue(const char *Key,

Prototype
const char *Value);
Function Set value of the specified key in registry.
Key [Input] System configuration name,
beginning with “persist.sys.” , “rt.sys.”
Parameters or “rt.app.” and ending with “\0”.
The valid string length ranges from 0

PAX Computer Technology (Shenzhen) Co., Ltd. 17

 Prolin API Programming Guide

to 31 bytes.
Value [Input] Parameter value, ending with “\0”.
The valid string length ranges from 0
to 64 bytes, and it cannot be NULL.
RET_OK Succeeded.
ERR_INVALID_PARA
Invalid Parameter.
M
Return
ERR_NEED_ADMIN Permission denied.
ERR_SYS_NOT_SUP System doesn’t support this
PORT configuration name.
1. This function can only set the system configuration whose
name begins with “persist.sys” , “rt.sys” or “rt.app.”, such as
“persist.sys.app0.pic”. For more information, refer to
Appendix 3 Registry.
2. OsRegSetValue()supports both the keywords listed in
Instruction Appendix 3 and user-defined configurations.
3. Registry beginning with “rt.sys.” and “rt.app.” will be invalid
when POS restarts, if the original state needs to be
restored, it requires to be reset after restarting.
4. After setting the key value, it will take about 200
milliseconds for the key value to take effect.

OsRegGetValue

int OsRegGetValue(const char *Key,

Prototype
char *Value);
Function Get value of the specified key in registry.
Key [Input] System configuration name, ending
with“\0”.
Parameters Value [Output] Parameter value.
The valid string length is more than 64
bytes.
>=0 String length.
Return ERR_INVALID_PARA
Invalid Parameter.
M
1. This function can only get the system configuration whose
name begins “ro.fac.” , “rt.sys.” , “rt.app.” or “persist.sys.”.
Instruction For more information, refer to Appendix 3 Registry.
2. If the inquired parameter does not exist or is empty, it’ll
return 0 and the output parameter Value will be “ ”.

PAX Computer Technology (Shenzhen) Co., Ltd. 18

 Prolin API Programming Guide

4.14 Install and Uninstall Files

OsInstallFile

int OsInstallFile(const char *Name,

Prototype const char *FileName,
int FileType);
Install or update application software, application data, OPT
Function package, pubic user key and firmware of external device (FWP
package).
Name[Input] Pathname of the specified destination.
File path to be installed.
FileName[Input] The path includes the file name,it cannot
be NULL.
 FILE_TYPE_APP (application
package or AIP)
 FILE_TYPE_APP_PARAM
(application data file)
Parameters  FILE_TYPE_SYS_LIB (dynamic
library and other optional system
FileType components)
 FILE_TYPE_PUB_KEY (user public
key file)
 FILE_TYPE_AUP(application
upgrade package)
 FILE_TYPE_FWP (device firmware
package)
RET_OK Succeeded.
The specified user public key does
ERR_PUK_NOT_EXIST
not exist.
ERR_FILE_NOT_FOUN
FileName does not exist.
D
Return ERR_FILE_FORMAT FileName format error.
ERR_INVALID_PARAM Invalid parameter
ERR_VERIFY_SIGN_FAI
Signature error.
L
ERR_APP_MODE Mode error
1. Name is valid only when FileType is
Instruction FILE_TYPE_APP_PARAM; otherwise, it is invalid. Name is
the application name in “MAINAPP” and other terminals, if

PAX Computer Technology (Shenzhen) Co., Ltd. 19

 Prolin API Programming Guide

the application name doesn’t exist, the installation or

update will fail.
2. When FileType is FILE_TYPE_FWP, if it is the device
firmware of wireless module, models with battery require at
least 2 bars of power to ensure the normal installation of the
firmware.
3. Only the main application has permission to do the
installing or update operation.
4. When the FileType is FILE_TYPE_FWP, the return code
can be RET_OK, ERR_FILE_NOT_FOUND,
ERR_VERIFY_SIGN_FAIL, ERR_ACCESS_DENY,
ERR_NO_SPACE or ERR_APP_MODE; the
ERR_APP_MODE will be returned when mmap(), fork() or
execl() fails, or the updater in the FWP package returns an
error code.

OsUninstallFile

int OsUninstallFile(const char *AppName,

Prototype
int FileType);
Function Uninstall a specified application or an OPT package.
 When FileType is FILE_TYPE_APP,
AppName refers to the ID of application to
AppName[Inpu be uninstalled.
t]  When FileType is FILE_TYPE_SYS_LIB,
AppName refers to the name of OPT
Parameters package.
 FILE_TYPE_APP (application package,
including all installed files.)
FileType
 FILE_TYPE_SYS_LIB (OPT package,
including all files in OPT package.)
RET_OK Succeeded.
The application or OPT package
ERR_APP_NOT_EXIS
specified by AppName does not
Return T
exist.
ERR_FONT_NOT_EXI
Font library does not exist.
ST
1. This function is only used to uninstall application and OPT
package that have been installed by user. For more
information, refer to application package management in
Instruction Prolin2.X User Guide.
2. Only the main application has permission to do the
uninstalling operation.

PAX Computer Technology (Shenzhen) Co., Ltd. 20

 Prolin API Programming Guide

After calling this function, it is recommended to prompt user to

restart the terminal to complete the uninstallation.

4.15 System Firmware Upgrade

OsFirmwareGetVersion

Prototype int OsFirmwareGetVersion(char *Version, int Size);

Function Get system firmware version.
Parameters Version[outpu
Firmware version buffer.
t]
Length of version buffer, the recommended
Size[Input]
length is 64 bytes.
Return RET_OK Succeeded.
ERR_INVALID_PARA
Invalid parameter.
M
Instruction 1. The format of version information is
MAIN_VERSION-SVN_VERSION, such as in
“2.6.26-r1789”, "2.6.26" is the MAIN_VERSION and
"r1789"is the SVN_VERSION.
2. Whether the firmware needs to be upgraded or not can be
determined by SVN_VERSION.

OsFirmwareUpgrade

Prototype int OsFirmwareUpgrade(const char *FwFileName);

Function Upgrade system firmware.

Parameters FwFileName[Input] Firmware filename, in ZIP format.

RET_OK Update succeeded.

RR_FILE_NOT_FOUND FwFileName file doesn’t exist.

Return ERR_VERIFY_SIGN_F
Signature error.
AIL
ERR_SYS_NOT_SUPP
Incompatible with OS.
ORT

Instruction 1. Only the main application has permission to upgrade system

firmware.

PAX Computer Technology (Shenzhen) Co., Ltd. 21

 Prolin API Programming Guide

2. In Prolin-A.B.C, A means framework version, B means major

version and C means minor version. The framework version
and major version of firmware to be upgraded must be the
same as current firmwares’, because Prolin-2.4,
Prolin-phoenix-2.5 and Prolin-cygnus-2.6 are not
compatiable with each other; otherwise,
ERR_SYS_NOT_SUPPORT will be returned.
3. This function will keep blocking during the upgrading
process. If addition of interface prompt is required, start
another process.
4. The power can not be cut off during the upgrading process;
otherwise, the device will fail to work normally.
5. The upgrade will take effect only after reboot.
6. Models with battery require at least 2 bars of power to
ensure the normal upgrade of the system firmware.

4.16 Verify Signature

Prolin provides signature verification functions.

OsVerifySign

int OsVerifySign(const char *FileName,

Prototype int PUKType);
Verify the file signature specified by FileName, including the
Function signature data.
Path of file whose signature needs to be
FileName verified.
[Input]
Signature data is contained in this file.
 PUK_TYPE_M
Public key of manufacturers, which is
used to verify signature for the firmware
released by manufacturer.
Parameters
 PUK_TYPE_US_PUK
PUKType[Inpu
t] Public key of user signature certificate,
which is used to verify signature for the
public key certificate.
 PUK_TYPE_USER
Public key of users, which is used to verify
signature for user’s application.
RET_OK Succeeded.
Return ERR_VERIFY_SIGN_ Invalid signature.
FAIL

PAX Computer Technology (Shenzhen) Co., Ltd. 22

 Prolin API Programming Guide

ERR_FILE_NOT_EXIS
File does not exist.
T
ERR_DEV_BUSY Device is busy.
ERR_INVALID_PARA
Invalid parameter.
M
1. This function is only used to verify application parameter
files, for example, to verify the root certificate defined by the
application.
Instruction 2. Before installing file, it is not recommended to call this
function to verify the legitimacy of the file so that to avoid a
repeated verification, as OsInstallFile() will verify the file
automatically.

OsVerifySignExternal

int OsVerifySignExternal(const char *FileName,

Prototype const void *SignData,
int PUKType);
Function Verify file signature with specified signature data.
Path of file whose signature needs to be
verified.
FileName [Input]
The file cannot contain signature data;
otherwise, the verification will fail.
Signature data.
SignData[Input]
The valid length is 284 bytes.
 PUK_TYPE_M
Public key of manufacturers, which is
Parameters used to verify signature for the firmware
released by manufacturer.
 PUK_TYPE_US_PUK
PUKType[Input] Public key of user signature certificate,
which is used to verify signature for the
public key certificate.
 PUK_TYPE_USER
The public key of users, which is used to
verify signature for user’s application.
RET_OK Succeeded.
ERR_VERIFY_SIGN_ Invalid signature.
Return FAIL
ERR_FILE_NOT_EXIS
The file does not exist.
T

PAX Computer Technology (Shenzhen) Co., Ltd. 23

 Prolin API Programming Guide

ERR_DEV_BUSY Device is busy.

ERR_INVALID_PARA
Invalid parameter.
M
1. This function is only used to verify the application
parameter file, for example, to verify the root certificate
defined by the application.
Instruction 2. Before installing the file, it is not recommended to call this
function to verify the legitimacy of the file so that to avoid a
repeated verification, as OsInstallFile() will verify the file
automatically.

4.17 Get System Version

OsGetSysVer

void OsGetSysVer(int VerType,

Prototype
char *Version);
Get the version information of operating system and firmware
Function version information.
Version types:
TYPE_OS_VER: Operating system version;
VerType
TYPE_WIRELESS_VER: Wireless firmware
Parameters version;
Version[Outp Buffer of version information
ut] The valid length must be not less than 31 bytes.
Return None
1. If Version[0] is equal to 0x00, the corresponding module
does not exist.
Instruction
2. The buffer size of Version must be more than 31 bytes, and
the version information must end with “\0”.

4.18 Test Whether on the Base

Prolin can test whether the handset is on the base or not, which is not applicable to
models that do not have any base.

OsOnBase

Prototype int OsOnBase(void);

PAX Computer Technology (Shenzhen) Co., Ltd. 24

 Prolin API Programming Guide

Function Get the status of POS terminal.

Parameters None.
1 On the base
Return
0 Not on the base
Instruction This function only applies to POS terminals with a base.

4.19 Save the Crash Report

Prolin can monitor program state. Once the program crashes, it will save the crash
report in the directory“/data/tombstones” after calling OsSaveCrashReport(). .

OsSaveCrashReport

Prototype void OsSaveCrashReport(ing sig);

Function Save crash report.
Parameters Sig Signal value.
Return None.
1. Method one
Call signal(SIG_XXX, OsSaveCrashReport) to register
OsSaveCrashReport() as signal handler, for example:
signal(SIGILL, OsSaveCrashReport);
signal(SIGABRT, OsSaveCrashReport);
signal(SIGBUS, OsSaveCrashReport);
signal(SIGFPE, OsSaveCrashReport);
signal(SIGSEGV, OsSaveCrashReport);
signal(SIGSTKFLT, OsSaveCrashReport);
2. Method two
Instruction Call OsSaveCrashReport (sig) to save the error messages.
For example:
void mysighandler(int sig)
{
do_something();
OsSaveCrashReport(sig);
}
 The recommended signals are SIGILL, SIGABRT,
SIGBUS, SIGFPE, SIGSEGV and SIGSTKFLT.
 The corresponding signal of sig will be ignored. That is,
signal(sig, SIG_IGN) is called inside OsSaveCrashReport().

PAX Computer Technology (Shenzhen) Co., Ltd. 25

 Prolin API Programming Guide

 The crash report can be exported to USB-disk by Terminal

Manager(TM), for complete guide, please refer to “Prolin2.X
User guide” chapter xx
 When compiling, GCC parameter –g –funwind-tables needs
to be added to save the debugging information.

4.20 Mount and Unmount the External File System

OsMount

int OsMount(const char *Source,

const char *Target,
Prototype const char *FileSystemType,
unsigned long MountFlags,
const void *Data);
Mount/install an external storage system, such as USB flash
Function drive.
Source[Input] The orginal/source file system that needs to
be mounted.
It is usually a device and must be in
/dev/block/; the valid length cannot exceed
128 bytes.
Target[Input] The destination file directory.
It must be in /mnt/; the valid path length
cannot exceed 128 bytes.
FileSystemTyp Type of the file system to be mounted.
e[Input] The value of the file system type can be “vfat”.
Mount flag.
Parameters Here is a list of flags and their corresponding
meanings. The mount flag can be a flag or a
combination of the following flags.
MS_DIRSYNC: Update synchronous
directory.
MountFlags[In MS_MANDLOCK: Permit mandatory
put] locking on files in this file system.

 MS_NOATIME: Do not update the access

time of file.

 MS_NODEV: Do not allow to access

device file.

PAX Computer Technology (Shenzhen) Co., Ltd. 26

 Prolin API Programming Guide

 MS_NODIRATIME: Don't update the

access time of directory.

 MS_NOEXEC: Do not allow programs to

be executed on the mounted file system.

 MS_NOSUID: Donot follow the

set-user-ID and set-group-ID when
executing programs.

 MS_RDONLY: Specify the file system as

read-only.

 MS_RELATIME: Update the last access

time (atime) values if the last access time
(atime) is not larger than the last
modification time (mtime) or the last
status change time (ctime).

 MS_SILENT: Stop writing warning

messages to the system kernel log.

 MS_STRICTATIME: Always update the

last access time (atime) for each access.
MS_SYNCHRONOUS: Synchronize the
updates
Data[Input] User-defined data, it can be NULL.
RET_OK Mount succeeded.
ERR_INVALID_PARAM Invalid parameter.
Return
ERR_STR_LEN The string is too long.
ERR_NEED_ADMIN Permission denied.
1. Only the MAINAPP has permission to mount; otherwise,
ERR_NEED_ADMIN will be returned.
2. “/mnt” shall be included in the Target when setting the
target file directory, such as “/mnt/sdcard”.
3. The head file #include <sys/mount.h> shall be included in
the code, because this function involves macros that are
Instruction defined in “mount.h”, such as MS_DIRSYNC,
MS_MANDLOCK, etc.
Sample code
Mount a SD card:
ret = OsMount("/dev/block/mmcblk0p1", "/mnt/sdcard", "vfat", 0,
0);

PAX Computer Technology (Shenzhen) Co., Ltd. 27

 Prolin API Programming Guide

Folder “/mnt/sdcard” shall be created in advance with either

user-defined name or other names. If the mount succeeded, it
can conduct read-write operation to the SD card.
Mount a U disk：
ret = OsMount("/dev/block/sda1", "/mnt/udisk", "vfat", 0, 0);
Folder “/mnt/udisk” shall be created in advance with either
user-defined name or other names. If the mount succeeded, it
can read/write USB flash drive.
Notes:
1. SD card or USB flash drive hot-plugging may change
device path.
2. Above instructions only have one partition based on SD
card and USB flash drive.
3. Only FAT32 USB flash drive format is supported.

OsUmount

int OsUmount(const char *Target,

Prototype
int Flags);
Function Unmount file system.
File system that needs to be unmounted.
Target[Input] The path of the target file system must be in
the /mnt/ directory; the valid path length
cannot exceed 128 bytes.
Unmount flag.
Here is a list of flags and their corresponding
meanings. The unmount flag can be a flag or
a combination of the following flags:
Parameters  MNT_DETACH: Lazy unmount. The
mount point is inaccessible after
Flags[Input] executing, and it will unmount only when
the mount point is not busy.
 MNT_EXPIRE:Mark the mount point as
expired
 UMOUNT_NOFOLLOW: If the target is
a symbolic link, it will not reduce the
reference count.
RET_OK Succeeded.
ERR_INVALID_PAR Invalid parameter.
Return AM
ERR_STR_LEN The string is too long.
ERR_NEED_ADMIN Permission denied.

PAX Computer Technology (Shenzhen) Co., Ltd. 28

 Prolin API Programming Guide

1. Only the main application has permission to unmount;

otherwise, it will fail to unmount and return
ERR_NEED_ADMIN.
2. The head file #include <sys/mount.h> shall be included in
the code, because this function involves macros that are
defined in “mount.h”, such as MS_DIRSYNC,
MS_MANDLOCK, etc.
Instruction Note: Only FAT32 USB flash drive format is supported.
Sample code
Unmount a SD card:
ret = OsUmount("/mnt/sdcard", 0);

Unmount a USB flash drive：

ret = OsUmount ("/mnt/udisk", 0);

4.21 Encrypted File System Interface

OsCryptFormat

int OsCryptFormat(const char *Dev,

Prototype const char *Pwd,
const char *FsType);
Function Format the storage device to be an encrypted file system.
Device that needs to be formatted. This
Dev[Input] device is located at /dev/block/ directory, and
the path length can not exceed 128 bytes.
Parameters Password of encrypted file system, and it is a
Pwd[Input]
visible string ranging from 6 to 32 bytes.
The type of format file system, and this value
FsType[Input]
can be “vfat”.
> Succeeded
ERR_INVALID_PARA
Invalid parameter.
Return M
ERR_DEV_NOT_EXIS
The file or path doesn’t exist
T
1. When formatting a non-encrypted storage device to an
encrypted file system for the first time, this function needs to
Instruction be called to format the device.
2. If a storage device has been formatted to an encrypted file
system, then it doesn’t need to be formatted again when

PAX Computer Technology (Shenzhen) Co., Ltd. 29

 Prolin API Programming Guide

user uses it on another terminal, otherwise, the data will get

lost.

When formatting the device to an encrypted file system, it will

delete all the data files from the device, please make sure that all
the data files have been backed up.

OsCryptMount

int OsCryptMount(const char *Dev, const char *Pwd,

Prototype const char *Target,
const char *FsType);
Function Mount the encrypted file system.
Device that needs to be mounted, this
device is located at /dev/block/ directory,
Dev [Input]
and the path length cannot exceed 128
bytes.
Password of encrypted file system, it is a
Pwd [Input]
Parameters visible string ranging from 6 to 32 bytes.
The target file directory, it must be
Target [Input] located at /mnt/ directory, and the path
length cannot exceed 128 bytes.
The type of format file system, this value
FsType [Input]
can be “vfat”.
0 Succeeded.
ERR_INVALID_PARA
Invalid parameter
M
System doesn’t support (wrong
ERR_SYS_NOT_SUP
Return password or encryption format is
PORT
unsupported)
ERR_DEV_NOT_EXIS
Device doesn’t exist
T
ERR_ACCESS_DENY No permission to access
1. When calling this function to mount the non-encrypted
storage device for the first time, OsCryptFormat() shall be
called to format the device first.
Instruction 2. When the encrypted SD card password is wrong, the system
will not be able to decrypt data or get the encrypted
information in correct format, therefore whether it is wrong
password or unsupported encryption format,

PAX Computer Technology (Shenzhen) Co., Ltd. 30

 Prolin API Programming Guide

ERR_SYS_NOT_SUPPORT will be returned.

3. User can not mixedly use non-encryption interfaces
OsMount()/OsUmount() with encryption interfaces
OsCryptMount()/OsCryptUmount(). For example, after calling
OsMount() to mount a device, calling OsCryptUmount() will
not be allowed to unmount this device.

OsCryptUmount

Prototype int OsCryptUmount(const char *Target);

Function Unmount the encrypted file system.
The directory of encrypted SD card
Parameters Target [Input]
that needs to be unmounted.
0 Succeeded.
ERR_INVALID_PARA
Invalid parameter
M
Return ERR_DEV_BUSY Device is busy.
ERR_ACCESS_DENY Permission denied.
ERR_FILE_NOT_EXIS
The file directory doesn’t exist
T
File related operations such as read/write file system must be
Instruction stopped when calling OsCryptUmount(), otherwise,
ERR_DEV_BUSY will be returned.

4.22 LED

OsLed

int OsLed(int Id,

Prototype unsigned int Color,
const char *dev);
Function Control Led state and color.
Id [Input] Led number.
The color of Led can be set as
followings:
Parameters LED_OFF: off
Color [Input] LED_RED: red
LED_GREEN: green
LED_BLUE: blue

PAX Computer Technology (Shenzhen) Co., Ltd. 31

 Prolin API Programming Guide

LED_YELLOW: yellow
LED_CYAN: cyan
LED_MAGENTA: magenta

LED_WHITE: white
Device model.
When operating the led light
of remote device, this
parameter needs to be input
(such as card reader: "IM700",
dev [Input] "IM500" or "IM20");

When operating the led light

of the local device, this
parameter is NULL.

0 Succeeded.

Return ERR_INVALID_PARAM Invalid parameter

ERR_SYS_BAD System error.
ERR_SYS_NOT_SUPPORT System does not support.
IM500
Id = 1: red
IM300
Id = 2: green
IM310
Id = 1: blue
IM700
Id = 2: yellow
QR55
Id = 3: green
SP200
Id = 4: red
B920 Id = 1: red or green

Instruction IM20 Id = 1: red, green, blue, yellow,

Q20 cyan, magenta or white
Id = 1: green
Q28
Id = 2: red or green
Id = 1: red
Id = 2: green
Id = 3: blue
Q30
Id = 4: yellow
Id = 5: red or green
Id = 6: red or green

PAX Computer Technology (Shenzhen) Co., Ltd. 32

 Prolin API Programming Guide

4.23 Get Terminal Accumulated Usage Information

OsTerminalConsumeInfo

int OsTerminalConsumeInfo(const char *Key,

Prototype
int *Value);
Get accumulated usage information of each module on
Function
terminal.
Key [Input] Device information category.
Parameters
Value [Output] Device usage information
RET_OK Succeeded.
ERR_SYS_NOT_SUP
System does not support.
Return PORT
ERR_INVALID_PARA
Invalid parameter.
M
1. The unit of time is “minute”, the unit of print length is
“centimeter”;
2. Only when the return value is RET_OK can the required
device information be obtained from the Value.
3. The statistics are rough and not entirely accurate. After
erasing the data partition, the statistics will be cleared.
4. Real-time statistics of button times, touch screen clicks and
Instruction RF card taps; the number of magnetic card swipping, IC card
inserting, keystroke backlight time, LCD using time, battery
using time and total running time are detected and counted
every minute. The statistics will be saved to the file system
every half hour. If the POS terminal is powered down directly,
it is likely to lose the statistics within half an hour, so it is
recommended to long press the shutdown button or call the
OsReboot()/OsPowerOff() function to restart/shut down the
terminal.

The current supported device information is listed below:

Key value description

msr.swiped.count counts of swiping magnetic stripe card
msr.swiped.failure_count Counts of failed swiping magnetic stripe card
icc.inserted.count counts of interting card
picc.tapped.count counts of tapping RF card

PAX Computer Technology (Shenzhen) Co., Ltd. 33

 Prolin API Programming Guide

key.backlight.time Cumulative time of backlight on the button

lcd.display.time the display time of LED
counts of clicking on touch screen (Multi-touch
touchscreen.click.count
only counts one point)
key.pressed.count keystrokes
boot.count boot times
running.time Total run time, excluding sleep time
battery.used.time battery life, sleep time is not included

4.24 Digital IO

OsDigitalIOGetStat

Prototype int OsDigitalIOGetStat(int *value);

Function Get the input status of all digital IO.
The status of each IO is represented
by bit, 0 represents suspended or
Parameters Value[Output] high level, 1 represents low level. If
the IO is unreadable (write only), the
corresponding bit returns 0.
>=0 The number of bits of 1 in vaule.
ERR_INVALID_PARA
Invalid parameter.
Return M
ERR_SYS_NOT_SUP
System does not support.
PORT
In the case of a connected handset, if the handset supports digital IO,
Instruction
the interface will get the input status of the handset digital IO by default.

OsDigitalIOSetStat

Prototype int OsDigitalIOSetStat(int index, int value);

Function Set the output status of the specified IO.
Specify the sequence number of IO to
be set, and if the IO does not support
Parameters Index[Input] setting (read only),
ERR_SYS_NOT_SUPPORT will be
returned.

PAX Computer Technology (Shenzhen) Co., Ltd. 34

 Prolin API Programming Guide

0: the corresponding IO output is high

level;
Value[Input]
1: the corresponding IO output is low
level.
RET_OK Succeeded.
ERR_INVALID_PARA
Invalid parameter.
Return M
ERR_SYS_NOT_SUP
System does not support.
PORT
In the case of a connected handset, if the handset supports
Instruction digital IO, the interface will get the input status of the handset
digital IO by default.

PAX Computer Technology (Shenzhen) Co., Ltd. 35

 Prolin API Programming Guide

5 Encryption and
Decryption

5.1 Return Code List

Table 5.1 Encryption and decryption return code list

Macro Value Description

ERR_DATA_TOO_BIG -2400 RSA encrypted data 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 provides true random number interfaces for applications.

OsGetRandom

Prototype void OsGetRandom(unsigned char *Random,

PAX Computer Technology (Shenzhen) Co., Ltd. 36

 Prolin API Programming Guide

int RandomLen);
Function Generate true random number.
A pointer to sring that stores random
Random [Output]
number.
Parameters Length of random number which needs to
RandomLen[Input be read.
] The valid length is not more than 4096
bytes.
Return None.
Instruction

5.3 SHA Algorithm

Prolin supports SHA algorithms, including SHA-1, SHA-2(SHA-256, SHA-512) and

the truncation form of SHA-2 (SHA-224, SHA-384).

OsSHA

void OsSHA(int Mode,

const void *Data,
Prototype
int DataLen,
unsigned char* ShaOut);
Function Calculate the hash value of SHA (Secure Hash Algorithm).
Algorithm types:
 SHA_TYPE_1
 SHA_TYPE_224
Mode
 SHA_TYPE_256
 SHA_TYPE_384
 SHA_TYPE_512
Data[Input] Input data buffer.
Parameters
DataLen[Inpu Input data length.
t]
Output SHA value.
The memory space is recommended to be
ShaOut[Outp more than 64 bytes. The corresponding
ut] relationship between Mode value and the valid
length of ShaOut are listed below:
 SHA_TYPE_1 20

PAX Computer Technology (Shenzhen) Co., Ltd. 37

 Prolin API Programming Guide

 SHA_TYPE_224 28
 SHA_TYPE_256 32
 SHA_TYPE_38 48
 SHA_TYPE_512 64
Return None.
Instruction

5.4 DES Algorithm

Prolin supports DES&TDES algorithms.

OsDES

void OsDES(const unsigned char *Input,

unsigned char *Output,
Prototype const unsigned char *DesKey,
int KeyLen,
int Mode);
Function Encrypt or decrypt data with DES / TDES algorithm.
Input[Input] 8-byte input data.
Output[Outpu
8-byte output data.
t]
DesKey[Input
Parameters ] DES/TDES key.

KeyLen[Input] 8, 16 or 24 (bytes).
0- Decryption;
Mode
1- Encryption.
Return None.
1. Encryption or decryption is decided by Mode selection.
Instruction
2. For invalid parameter, it performs no action.

5.5 AES Algorithm

Prolin supports AES algorithm, including AES-128, AES-192 and AES-256.

PAX Computer Technology (Shenzhen) Co., Ltd. 38

 Prolin API Programming Guide

OsAES

void OsAES(const unsigned char *Input,

unsigned char *Output,
Prototype const unsigned char *AesKey,
int KeyLen,
int Mode);
Function Encrypt or decrypt data with AES algorithm
Input[Input] 16-byte input data.
Output[Outpu
16-byte output data.
t]
AesKey[Input
Parameters ] Key.

KeyLen 16, 24 or 32 (bytes).

0- Decryption;
Mode
1- Encryption.
Return None.
1. This function supports AES encryption and decryption of
Instruction 128, 192 or 256 bits.
2. For invalid parameter, it performs no action.

5.6 RSA Algorithm

Prolin supports RSA algorithm, including public/private key-pair generation, RSA

encryption and RSA decryption. Prolin supports a maximum modulus length of 4096
bits.

OsRSA

int OsRSA(const unsigned char *Modulus,

int ModulusLen,
const unsigned char *Exp,
Prototype
int ExpLen,
const unsigned char *DataIn,
unsigned char *DataOut);
Function Encrypt or decrypt data with RSA algorithm

Parameters Modulus[Input] A pointer that contains RSA

modulus (n=p*q). (stored in big

PAX Computer Technology (Shenzhen) Co., Ltd. 39

 Prolin API Programming Guide

endian)
ModulusLen[Input] Modulus length[unit:byte].
A pointer that contains RSA
Exp[Input] operation exponent. (stored in big
endian)
ExpLen Exponent length.[unit: byte]
A pointer to the input data buffer.
DataIn[Input] The valid length is equal to the
modulus length.
A pointer to the output data buffer.
DataOut[Output] The valid length is equal to the
modulus length.
RET_OK Succeeded.
ERR_INVALID_PARAM Invalid parameter.
Return
ExpLen is greater than
ERR_DATA_TOO_BIG
ModulusLen.
1. OsRSA() is used to encrypt/dencrypt DatatIn and its result
is stored in DataOut.
2. When (Modulus, Exp) is private key, if DataIn is ciphertext
that encrypted by PUK, then DataOut is plaintext of DataIn;
otherwise, DataOut is RSA ciphertext of DataIn.
Instruction
3. When (Modulus, Exp) is public Key, if DataIn is ciphertext
that encrypted by private key, then DataOut is plaintext of
DataIn; otherwise, DataOut is RSA ciphertext of DataIn.
4. OsRSA() can implement RSA operation whose modulus
length is not more than 4096 bits.

OsRSAKeyGen

Int OsRSAKeyGen(unsigned char *Modulus,

unsigned char *PriExp,
Prototype
int ModulusLen,
const unsigned char * PubExp);
Generate RSA key pair of specified exponent and modulus
Function
length.
Modulus[Output] Key modulus. (stored in big endian)
PriExp[Output] Private key exponent. (stored in big endian)
Parameters
Modulus length [unit: byte].
ModulusLen The modulus is valid only when it is 64, 128,
256 or 512 bytes.

PAX Computer Technology (Shenzhen) Co., Ltd. 40

 Prolin API Programming Guide

Public key exponent.

PubExp[Input] The valid value can only be
“\x00\x00\x00\x03” or “\x00\x01\x00\x01”.
RET_OK Succeeded.
ERR_INVALID_PARA
Invalid Parameters.
Return M
ERR_GEN_RANDOM Fail to generate random data.
ERR_GEN_FAIL Fail to generate RSA Key pair.
Instruction

PAX Computer Technology (Shenzhen) Co., Ltd. 41

 Prolin API Programming Guide

6 PED

Prolin provides a series of PED interfaces, including built-in PED, MK/SK, DUKPT,
RSA and other related interfaces.

The architecture of PED is desiged to contain three levels of key. From top to bottom,
its order is:

 TLK－Terminal Key Loading Key

Private key of acquirer or POS operator, which is directly written in by acquirer

and POS operator in secure environment.

Each PED terminal only has one TLK. Its index number is 1.

 TMK－Terminal Master Key＝Acquirer Master Key

Terminal master key or acquirer master key, each PED terminal can have 100
TMKs. The index number is from 1 to 100.

 TWK－Transaction working key = Transaction Pin Key + Transaction MAC Key

+Terminal DES Key

Transaction working key, which is used to perform PIN, MAC and other
operations.

PAX Computer Technology (Shenzhen) Co., Ltd. 42

 Prolin API Programming Guide

Each PED terminal can have 100 TMKs. The index number is from 1 to 100.

TPK：Calculate PIN Block after inputting PIN.

TAK：Calculate MAC in message communication.

TDK：Transmit or store sensitive data encrypted with DES/TDES algorithm.

Each key has its corresponding index number, length, purpose and tags which are
set through API before writing in the key so as to authorize the permission and avoid
abuse of the key.

 Mechanism of DUKPT：

DUKPT (Derived Unique Key Per Transaction) is the one-time pad system in which
different key (PIN、MAC) is used for each transaction. KSN (Key Serial Number)
concept which is the key factor to realize one-time pad is introduced in this system.

Each key corresponding to KSN can generate different keys according to the usage
and variant constants listed below.

Each PED terminal can have 100 DUKPT groups. Selection of group index is needed
when writing in TIK; select the corresponding index number when using DUKPT.

6.1 Return Code List

Table 6.1 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.
Key level error: Source
ERR_PED_DERIVE_ERR -3803 key level is lower than
target key level.

PAX Computer Technology (Shenzhen) Co., Ltd. 43

 Prolin API Programming Guide

ERR_PED_CHECK_KEY_FAIL -3804 Key verification failed.

ERR_PED_NO_PIN_INPUT -3805 No PIN input.
ERR_PED_PIN_INPUT_CANCEL -3806 PIN input is canceled.
The function is called
within the minimum time
ERR_PED_WAIT_INTERVAL -3807
interval (Calculate PIN
block/MAC).
ERR_PED_KCV_MODE_ERR -3808 KCV mode error.
ERR_PED_KEY_TAG_ERR -3809 Key tag error.
ERR_PED_KEY_TYPE_ERR -3810 Key type error.
ERR_PED_PIN_LEN_ERR -3811 PIN length error.
ERR_PED_DSTKEY_IDX_ERR -3812 Target 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.
IC card initialization
ERR_PED_ICC_INIT_ERR -3817
error.
DUKPT group index
ERR_PED_GROUP_IDX_ERR -3818
error.
ERR_PED_LOCKED -3819 PED is locked.
ERR_PED_NOMORE_BUF -3820 No free buffer.
ERR_PED_NORMAL_ERR -3821 PED normal error.
ERR_PED_NEED_ADMIN -3822 Permission denied.
ERR_PED_DUKPT_KSN_OVERFLO
-3823 DUKPT overflow.
W
ERR_PED_KCV_CHECK_FAIL -3824 KCV check failed.
ERR_PED_SRCKEY_TYPE_ERR -3825 Source key type error.
ERR_PED_UNSPT_CMD -3826 Unsupported command.
ERR_PED_ADMIN_ERR -3827 Administration error.
PED download function
ERR_PED_DOWNLOAD_INACTIVE -3828
is not activated.
ERR_PED_KCV_ODD_CHECK_FAI KCV odd parity check
-3829
L failed.
ERR_PED_PED_DATA_RW_FAIL -3830 Fail to read PED data.
ERR_PED_ICC_CMD_ERR -3831 IC card operation failed.

PAX Computer Technology (Shenzhen) Co., Ltd. 44

 Prolin API Programming Guide

ERR_PED_DUKPT_NEED_INC_KS DUKPT KSN needs to

-3832
N increase 1 first.
ERR_PED_DUKPT_NO_KCV -3833 NO KCV.
PED doesn’t have
ERR_PED_NO_FREE_FLASH -3834
enough space.
Press [CLEAR] key to
ERR_PED_INPUT_CLEAR -3835
exit PIN input.
ERR_PED_INPUT_BYPASS_BYFU Press FN/ATM4 to
-3836
NCTION cancel PIN input.
PIN input mode is not
ERR_PED_NO_PIN_MODE -3837
set.
ERR_PED_DATA_MAC_ERR -3838 Data MAC check error.
ERR_PED_DATA_CRC_ERR -3839 Data CRC check error.
The work key value
ERR_PED_KEY_VALUE_INVALID -3840 already exists or does
not meet requirements.

6.2 Data Definition

Key Type

Table 6.2 Key types

Macro Value Description

PED_TLK 0x01 Loading Key
PED_TMK 0x02 Master Key
PED_TPK 0x03 PIN Key
PED_TAK 0x04 MAC Key
PED_TDK 0x05 Data Key
PED_TIK 0x10 DUKPT Initial Key
PED_TRK 0x07 MSR Key
PED_TAESK 0x20 AES Key
PED_SM2_PVT_KEY 0x30 SM2 Private Key
PED_SM2_PUB_KEY 0x31 SM2 Public Key
PED_SM4_TMK 0x32 SM4 Master Key
PED_SM4_TPK 0x33 SM4 PIN Key
PED_SM4_TAK 0x34 SM4 MAC Key

PAX Computer Technology (Shenzhen) Co., Ltd. 45

 Prolin API Programming Guide

PED_SM4_TDK 0x35 SM4 Data Key

DisplayAttribute of Asterisk

Table 6.3 Layout attributes of asterisk

Macro Value Description

PED_ASTERISK_ALIGN_LEFT 0 Left-aligned.
PED_ASTERISK_ALIGN_CEN
1 Center-aligned.
TER
PED_ASTERISK_ALIGN_RIGH
2 Right-aligned.
T

Table 6.4 Color values of asterisk

Macro Value Description

To generate 16-bit color
RGB(_r, _g, _b) ... value with the three
primary colors.

6.3 Data Structure

Structure of RSA Key

ST_RSA_KEY
typedef struct{
int ModulusLen; /*Modulus length(bits) */
unsigned char Modulus[512]; /*Modulus.When modulus length is less
than 512 bytes, add 0x00 on the left. */
int ExponentLen; /* Exponent length (bits) */
unsigned char Exponent [512]; /*Exponent.When exponent is less than
512 bytes, add 0x00 on the left.*/
unsigned char KeyInfo[128]; /* RSA key information */
}ST_RSA_KEY;

RSA Key Structure for Verifying the Ciphertext IC Card PIN

ST_RSA_PINKEY

PAX Computer Technology (Shenzhen) Co., Ltd. 46

 Prolin API Programming Guide

typedef struct{
int ModulusLen; /*Modulus length of PIN public key(unit: 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 from IC card*/
unsigned char IccRandom[8]; /*Random data from IC card*/
}ST_RSA_PINKEY;

6.4 Basic PED

OsPedOpen

Prototype int OsPedOpen(void);

Function Open PED service.
Parameters None.
RET_OK Succeeded.
Return
ERR_DEV_BUSY Device is busy.
OsPedOpen() must be called to open PED device; otherwise,
Instruction other PED related functions won’t work.

OsPedGetVer

Prototype int OsPedGetVer (unsigned char * PedVer);

Function Get current PED version information.
PED version information buffer, the buffer
Parameters PedVer[Output] size is 6 bytes.
RET_OK Succeeded.
Return ERR_DEV_NOT_OPEN PED device is not open.
ERR_INVALID_PARAM Invalid parameter.
Instruction

OsPedSetInterval

Prototype int OsPedSetInterval(unsigned long TpkIntervalMs);

Function Set the minimum time interval of two PIN block calculations.
=0 Use the default value(30s)
Parameters TpkIntervalMs
<1000 Automatically set to 1,000(1s)

PAX Computer Technology (Shenzhen) Co., Ltd. 47

 Prolin API Programming Guide

Automatically set to
>600000
600,000(10 min)
Current settings remain
=0xffffffff
unchanged.
RET_OK Succeeded.
Return ERR_DEV_NOT_OPE
PED device is not open.
N
Restrictions of PIN input intervals：
Each PIN input function can only be called for not more than 4
times during 4*TPKIntervalMs. The default value of
TpkIntervalMs is 30s which can be set by calling
OsPedSetInterval(). For example, if the TPKIntervalMs is
Instruction 20,000(ms), then the same PIN input function can be called 4
times at most within 80 seconds.
PIN input functions include OsPedGetPinBlock(),
OsPedGetPinDukpt(), OsPedVerifyPlainPin() and
OsPedVerifyCipherPin().
TpkIntervalMs will be restored to the default value after reboot.

OsPedVerifyPlainPin

int OsPedVerifyPlainPin(int IccSlot,

const char *ExpPinLen,
Prototype int Mode,
unsigned long TimeoutMs,
unsigned char *IccRsp);
Function Verify offline plaintext PIN.
IccSlot IC card slot number, IccSlot=0.
A pointer to valid password length string
which is an enumeration set from 0 to 12.
Application enumerates all valid password
ExpPinLen[Input] length and separate each length with “,”.
For example, if no PIN, 4 and 6 digits of
PIN are allowed, the string will be set to “0,
Parameters 4, 6”. “0” means no PIN is required and can
return directly by pressing “Enter”.
0x00: IC card command mode.
Mode It supports the IC card command that
conforms to EMV2000.
Timeout of PIN input.[unit:ms]
TimeoutMs
The valid timeout ranges from 0 to 300000

PAX Computer Technology (Shenzhen) Co., Ltd. 48

 Prolin API Programming Guide

ms. “0” means no timeout, and PED has no

timeout control.
Card response status code (2 bytes:
IccRsp[Output] SWA++SWB)
The valid length is 2 bytes.
RET_OK Succeeded.
ERR_DEV_NOT_OPE
PED device is not open.
N
Return
ERR_INVALID_PARA
Invalid parameter.
M
Others Refer to PED Return Code List .
Call OsPedVerifyPlainPin() will operate the frame buffer, which
might cause the resource conflict. If there is some kind of
exception on the interface of application which is running XUI,
Instruction
call XuiSuspend() to suspend XUI before calling
OsPedVerifyPlainPin(), after a while, call XuiResume() to
resume XUI.
Internal processing steps to verify PIN block:
1. Prompt cardholder to input PIN;
2. Prompt that it is under processing;
3. Convert plaintext PIN to PIN block form.

OsIccexchange() is used to verify interaction with card. The

process is:
ST_APDU_REQ apdu_s;
Internal ST_APDU_RSP apdu_r;
handling
porcess
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;

OsPedVerifyCipherPin

int OsPedVerifyCipherPin(int IccSlot,

Prototype const ST_RSA_PINKEY
*RsaPinKey,

PAX Computer Technology (Shenzhen) Co., Ltd. 49

 Prolin API Programming Guide

const char *ExpPinLen,

int Mode,
unsigned long TimeoutMs,
unsigned char *IccRsp);
Verify ciphertext PIN, steps are as follows:
1. Get the plaintext PIN;
Function 2. Encrypt the plaintext with RsaPinKey provided by
application in accordance with EMV specification;
3. Send ciphertext PIN to card according to card command
and card slot number provided by application.
IccSlot ICC slot number, IccSlot=0.
A pointer to ST_RSA_PINKEY that needs
RsaPinKey[Input]
to be encrypted.
A pointer to valid password length string,
which is an enumeration set from 0 to 12.
Application enumerates all valid
password length and separate each
ExpPinLen[Input] length with “,”. For example, if no PIN, 4
and 6 digits of PIN are allowed, the string
will be set to “0, 4, 6”. “0” means no PIN is
Parameters required and can return directly by
pressing “Enter”.
0x00, IC card command mode.It supports
Mode the IC card command that conforms to
EMV2000.
Timeout of inputting PIN. [unit:ms]
TimeoutMs The valid timeout value ranges from 0 to
300000 ms. “0” means no timeout, and
PED has no timeout control.
Status code of card’s response. (2 bytes:
IccRsp[Output]
SWA+SWB)
RET_OK Succeeded.
ERR_DEV_NOT_
PED device is not open.
OPEN
Return
ERR_INVALID_PA
Invalid parameter.
RAM
Others Refer to the PED Return Code List .
Call OsPedVerifyCipherPin() will operate the framebuffer, which
Instruction might cause the resource conflict. If there is some kind of
exception on the interface of application which is running XUI,
call XuiSuspend() to suspend XUI before calling

PAX Computer Technology (Shenzhen) Co., Ltd. 50

 Prolin API Programming Guide

OsPedVerifyCipherPin(), after a while, call XuiResume() to

resume XUI.

Encryption algorithm:
Get ciphertext PIN by using the public key to calculate the data
which are listed in following table with RSA algorithm.

Field name Length Description Format

Hexadecimal, the value is

Header of data 1 b
“7F”

PIN Block 8 PIN block b

Random Random number gotten

number of IC 8 from card, stored in b
card ST_RSA_PINKEY

Random padding bytes

Random NIC–1 gotten from terminal
b
padding bytes 7 application, stored in
ST_RSA_PINKEY.

The internal processing steps are:

1. Prompt cardholder to input PIN;
2. Prompt cardholder that it is processing;
3. Convert plaintext PIN to PIN block;
4. Generate data, used for encryption(the data are listed in
above table);
5. Use the public key to encrypt data which is generated in
step 4 with RSA algorithm, and get the enciphered PIN
finally.
Internal
handling OsIccExchange() is used to send verification command to card.
porcess The process is 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, 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;

PAX Computer Technology (Shenzhen) Co., Ltd. 51

 Prolin API Programming Guide

icc_resp[1] = apdu_r.SWB;

OsPedEraseKeys

Prototype int OsPedEraseKeys(void);

Function Clear all key information saved in PED.
Parameters None.
RET_OK Succeeded.
ERR_DEV_NOT_OP
Return PED device is not open.
EN
Others Refer to PED Return Code List .
Instruction

OsPedSetFunctionKey

Prototype int OsPedSetFunctionKey(int KeyFlag);

Function Set the function of some function keys:
0x00: When the PIN has already been cleared or there
is no PIN input, pressing CLEAR button will exit
from the input status and
ERR_PED_INPUT_CLEAR will be returned.
0x01: When interfaces (OsPedGetPinBlock(),
OsPedGetPinDukpt(), OsPedVerifyPlainPin(),
OsPedVerifyCipherPin() etc) are inputting PIN,
pressing CLEAR button will clear the latest input
PIN digit by digit. Pressing CLEAR button after
cleared all PIN will have no response and it will
not exit the PIN input function.
0x02: Press ATM4 button to end the PIN input. This
rule does not apply to the POS terminals without
Parameters KeyFlag ATM button.
0x03: Press FN button to end the PIN input. This rule
does not apply to the POS terminals without FN
button.
0x04: Press INFO button to end the PIN input. This
rule does not apply to the POS terminals without
INFO button.
0x05: When the password input interface is inputting
PIN, pressing CANCEL button will clear all input
PIN. Pressing CANCEL button after cleared all
PIN will have no response and it will not exit the
PIN input function.
0xff: Restore the default function of function keys

PAX Computer Technology (Shenzhen) Co., Ltd. 52

 Prolin API Programming Guide

(press CLEAR button to clear all PIN, press

CANCEL button to exit the PIN input function and
pressing ATM4/FN/INFO key does not exit from
the PIN input).
RET_OK Succeeded.
ERR_DEV_NOT_OPE
PED device is not open.
Return N
ERR_INVALID_PARAM Invalid parameter.
Others Refer to the PED Return Code List .
After PED is powered on, the default function of CLEAR button is to
Instruction clear inputted PIN when the cardholder is inputting the PIN. And call
this interface to set other functions of the CLEAR button.

When inputting PIN, if the function of pressing button to exit or to

clear the PIN bit by bit is needed, call this function after startup.

OsPedClose

Prototype void OsPedClose(void);

Function Disconnect PED service.
Parameters None.
Return None.
Instruction Call this function to close device before exiting program.

OsPedCancelPinEntry

Prototype int OsPedCancelPinEntry(void);

Function Terminate the process of PIN input.
Parameters None.
Return RET_OK Succeeded.
Instruction This function does not require PED service, so there is no need
to call OsPedOpen() before using it.

OsPedSetOfflinePin

Prototype int OsPedSetOfflinePin(uchar Mode,

PAX Computer Technology (Shenzhen) Co., Ltd. 53

 Prolin API Programming Guide

uchar TpkIdx,
uchar *PinBlock,
ushort PinBlockLen);
Function Set verification mode for off-line plain / cipher text.
Verification mode:
 0-Input PIN with internal code
keypad;
Mode [Input]
 1- Input PIN with external code
keypad, and the PIN is imported by
parameter PinBlock.
TPK index:
 When Mode is 0, it is meaningless;
Parameters TpkIdx [Input]  When Mode is 1, the TPK of this
index will be used to decrypt the
imported PinBlock, and the result is
PIN in plain-text.
PIN block:
 When Mode is 0, it is meaningless;
PinBlock [Input]  When Mode is 1, it represents PIN
in cipher -text encrypted by TPK in
ISO9564 Format1.
PinBlockLen [Input] Length of PIN block
RET_OK Succeeded
ERR_DEV_NOT_OP
PED device is not open
EN
Return
ERR_INVALID_PAR
Invalid parameter
AM
Others Refer to the PED Return Code List
Instruction

OsPedEndPinEntry

Prototype int OsPedEndPinEntry(void);

Function Send the confirmation key to end PIN input.
Parameters None

Return RET_OK Succeeded

Instruction This function does not require PED service, so there is no need
to call OsPedOpen() before using it.

PAX Computer Technology (Shenzhen) Co., Ltd. 54

 Prolin API Programming Guide

OsPedPinKeyNotify

int OsPedPinKeyNotify(int *KeyCacheCnt,

Prototype
uchar *KeyCache);
Listen and get the number of PIN keys entered by users in the
Function current state and the sequence of historical keys between this
listening and the last listening.
KeyCacheCnt The number of obtained historical key
[Output] values.
 The key values are stored into the
buffer in chronological order from
little-endian to big-endian. And the
size of this output buffer must be not
less than 64 bytes.
 The maximum of obtained historical
Parameters key sequence is 64, if the key buffer
KeyCache [Output] in the key sequence is more than
64, the latest 64 key sequences will
be output.
 The obtained key can only be “PIN”,
“ENTER”, “CLEAR”, “CANCEL”,
“FN”, and “ATM4”, and “PIN” is
replaced by “*”. If there is no key
input, the obtained value will be 0.
Succeeded, and the returned value
>= 0 represents the number of “*” in the PIN
input interface.
ERR_DEV_NOT_OP
Return PED device is not open
EN
ERR_INVALID_PAR
Invalid parameter
AM
Others Refer to the PED Return Code List
1. This function does not support listening for PIN input events
by multi-process.
2. When first calling this function, PED will create a listening
service for PIN input event, clear the key buffer when PED
Instruction service is closed, and deregister the PED service.
Therefore, users should call this function before calling PIN
input function to get the completed key buffer.
3. PED will clear the key buffer when a new PIN input event
occurs.

PAX Computer Technology (Shenzhen) Co., Ltd. 55

 Prolin API Programming Guide

6.5 MK/SK

OsPedWriteKey

Prototype int OsPedWriteKey(const unsigned char *KeyBlock);

Write in a key, including TLK, TMK, TWK, SM4_TMK; write in

Function and diverge the SM4_TMK key; and verify the validity of keys
using KCV.

1 byte Format: 0x03

SrcKeyType:
 PED_TLK
 PED_TMK
 PED_TPK/PED_TAK/PED
1 byte
_TDK
 PED_SM4_TMK
 PED_SM4_TPK/PED_SM
_TAK/PED_SM4_TDK
SrcKeyIdx:
 When SrcKeyType =
PED_TLK,
SrcKeyIdx = 1;
 When SrcKeyType =
PED_TMK,
Parameters KeyBlock[Input] SrcKeyIdx = [1~100];
 When
1 byte ucSrcKeyType=PED_TPK/PE
D_TAK/PED_TDK,
ucSrcKeyIdx = [1~100];
 When ucSrcKeyType =
PED_SM4_TMK,
ucSrcKeyIdx = [1~100];
 When ucSrcKeyType =
PED_SM4_TPK/PED_SM4_T
AK/PED_SM4_TDK,
ucSrcKeyIdx = [1~100];
DstKeyIdx:
 When DstKeyType =
1 byte PED_TLK,
DstKeyIdx = 1;
 When DstKeyType =

PAX Computer Technology (Shenzhen) Co., Ltd. 56

 Prolin API Programming Guide

PED_TMK,
DstKeyIdx = [1~100];
 When DstKeyType =
PED_TPK or PED_TAK or
PED_TDK or
PED_TDFK,DstKeyIdx =
[1~100].

Reserved domain; random

7 bytes
number.

DstKeyType:
 PED_TLK
 PED_TMK
 PED_TPK/PED_TAK/PED_T
1 byte DK
 PED_SM4_TMK
 PED_SM4_TPK/PED_SM4_T
AK/PED_SM4_TDK
 PED_TDFK

DstKeyLen: 8/16/24
 When DstKeyType is
PED_SM4_TMK/PED_SM4_
1 byte
TPK/PED_SM4_TAK/PED_S
M4_TDK,
DstKeyLen=16.
DstKeyValue.
8/16/24
bytes Destination key plaintext /
ciphertext.
KcvMode:
0x00: No verification.
0x01: KCV is the first 3 bytes of
ciphertext after encrypting
the 8-byte 0x00 with
DES/TDES algorithm.
0x02: KCV is the first 3 bytes of
1 byte ciphertext after odd parity
check on the plaintext of
key and DES/TDES
encryption on the
“\x12\x34\x56\x78\x90\x12\
x34\x56”.
0x03: KCV is an 8-byte MAC
value that is a result of

PAX Computer Technology (Shenzhen) Co., Ltd. 57

 Prolin API Programming Guide

specified mode of MAC

calculation on [ciphertext of
destination key + input
KcvData] with source key
pair.
0x04: KCV is the first 4 bytes of
ciphertext after encrypting
the16-byte 0x00 with SM4
algorithm.
Note: Mode 0x01, 0x02 and 0x03
can only be used for
checking MK/SK key
injection. Mode 0x04 is
only used for checking
SM4 key injection.
KcvData:
 When KcvMode is
0x00/0x01/0x02, padding with
random numbers.
128  When KcvMode is 0x03, the
bytes first byte of KcvData is the
length of KCV data involved in
the calculation, and the rest is
KCV data. The first byte after
the KCV data represents the
mode of MAC calculation.
 When KcvMode = 0x00,
padding with random
numbers.
8 bytes  When KcvMode
=0x01/0x02/0x03/0x04,
KcvValue points to the KCV
value.
10 bytes Padding with random data.
RET_OK Succeeded.
ERR_DEV_NOT_OPEN PED device is not open.
ERR_INVALID_PARAM Invalid parameter.
ERR_SYS_BAD System error.
Return
ERR_PED_KEY_IDX_ER
R Key index error.

ERR_PED_KEY_TYPE_E
RR Key type error.

PAX Computer Technology (Shenzhen) Co., Ltd. 58

 Prolin API Programming Guide

ERR_PED_TAMPERED PED is locked.

ERR_PED_NO_MORE_B
UF System memory is not enough.

ERR_PED_NORMAL_ER PED normal error (KeyBlock

R Format error).

ERR_PED_DERIVE_ERR Key divergence error.

ERR_PED_KCV_MODE_
ERR PED KCV verification mode error.

ERR_PED_KCV_CHECK_
FAIL PED KCV verification failed.

Refer to the PED Return Code

Others
List .
When calling this function to write the ciphertext and plaintext of
a key to a specific index position of the specific key type area,
please pay attention to the following notes:
1. When SrcKeyIdx=0, DstKeyValue is regarded as the
plaintext of key. And the system will directly write
DstKeyValue to DstKeyIdx in DstKeyType area without
judging SrcKeyType and SrcKeyIdx.
2. Only when PED_TLK does not exist, plaintext is allowed to
be written and key is allowed to be downloaded.
3. When PED_TLK exists, plaintext is not allowed to be written
in and key is not allowed to be downloaded. The length of
PED_TLK can either be 16 or 24 bytes and the 8-byte key is
not allowed to be injected.
Instruction 4. Before writing in PED_TLK, all keys that have been
downloaded must be cleared.
5. If SrcKeyIdx is valid, DstKeyValue will be regarded as the
key ciphertext. And the system will decrypt DstKeyValue
with SrcKeyIdx key in SrcKeyType key area and write it to
DstKeyIdx in DstKeyType area. (DstKeyType >=
SrcKeyType)
6. DstKeyLen can only be 8, 16 or 24 bytes. If DstKeyLen = 8
bytes, the key can only be used for DES calculation. If
DstKeyLen = 16 or 24 bytes, the key can be used for TDES
calculation.(DstKeyLen <= SrcKeyLen)
7. Key type is specified by DstKeyType. When
DstKeyType=PED_TPK, the key can only be used for PIN
block calculation; when DstKeyType=PED_TAK, the key
can only be used for MAC calculation; When

PAX Computer Technology (Shenzhen) Co., Ltd. 59

 Prolin API Programming Guide

DstKeyType=PED_TDK, the key can only be used for

DES/TDES encryption and decryption to limit their
application field and ensure the uniqueness of their
function.
8. KCV is used to verify plaintext of key. If plaintext is typed-in
directly and the KcvMode of KeyIn is not 0, the system will
perform KCV verification on plaintext of key according to
the specified KcvMode.
9. Prolin-phoenix-2.5 supports the uniqueness of key injection,
while Prolin-2.4 allows the same key to exist in different key
slots.
10. When PED_TLK exists and its length isn’t 16 bytes,
PED_SM4_TMK/PED_SM4_TPK/PED_SM4_TAK/PED_S
M4_TDK can not be injected. In SM algorithm key system,
PED_TLK must be 16 bytes, too.

1. The valid KeyBlock must be 184 bytes.

2. The incoming parameters must be valid; otherwise, an error
may occur.

OsPedWriteTIK

Prototype int OsPedWriteTIK(const unsigned char *KeyBlock);

Function Write in a TIK key, and it is optional to verify the key by KCV.
1 byte Format: 0x03
SrcKeyType:
1 byte
 PED_TLK
SrcKeyIdx:
 When SrcKeyType =
PED_TLK,
1 byte
SrcKeyIdx = 1;
Parameters KeyBlock[Input]  When writing in plaintext,
SrcKeyIdx = 0.
DstKeyIdx:
1 byte
DstKeyIdx = [1~100];
Reserved domain. Random
7 bytes
number.
1 byte DstKeyType:

PAX Computer Technology (Shenzhen) Co., Ltd. 60

 Prolin API Programming Guide

 PED_TIK
1 byte DstKeyLen: 8/16
DstKeyValue.
24
bytes The destination key plaintext /
ciphertext
KcvMode:
0x00: No verification.
0x01: KCV is the first 3 bytes of
ciphertext after encrypting
the 8-byte 0x00 with
DES/TDES algorithm.
0x02: KCV is the first 3 bytes of
ciphertext after odd parity
check on the plaintext of key
1 byte and DES/TDES encryption
on
“\x12\x34\x56\x78\x90\x12\x
34\x56”.
0x03: The KCV is an 8-byte MAC
value, that is, a result of
specified mode of MAC
calculation on [ciphertext of
destination key + input
KcvData] with source key
pair.
KcvData:
 When the KcvMode is
0x00/0x01/0x02, padding with
random numbers.
128  When the KcvMode is 0x03,
bytes the first byte of KcvData is the
length of KCV data involved in
the calculation, and the rest is
KCV data. The first byte after
the KCV data represents the
mode of MAC calculation.
When KcvMode = 0x00,
padding with random numbers.
8 bytes  When KcvMode =
0x01/0x02/0x03, KcvValue
points to the KCV value.
10
Initialize KSN.
bytes

PAX Computer Technology (Shenzhen) Co., Ltd. 61

 Prolin API Programming Guide

RET_OK Succeeded.
ERR_DEV_NOT_OPE
PED device is not open.
N
Return
ERR_INVALID_PARA
Invalid parameter
M
Others Refer to PED Return Code List .
When calling this function to write the ciphertext or plaintext of a
key to a specific index position of the specific key type area,
please pay attention to the following notes:
1. When SrcKeyIdx=0, DstKeyValue is regarded as the
plaintext of key. The system will directly write the
DstKeyValue to DstKeyIdx in DstKeyType area without
judging SrcKeyType and SrcKeyIdx.
2. Only when PED_TLK does not exist, plaintext is allowed to
be written and key is allowed to be downloaded.
Instruction 3. When PED_TLK exists, plaintext is not allowed to be written
and key is not allowed to be downloaded.
4. If SrcKeyIdx is valid, DstKeyValue is regarded as the
ciphertext of the key. The system will decrypt DstKeyValue
with SrcKeyIdx key in SrcKeyType area and write the key to
DstKeyIdx in DstKeyType. (DstKeyType >= SrcKeyType)
5. KVC is used to verify plaintext. If plaintext is typed-in
directly, and the KcvMode of KeyIn is not 0, the system will
perform KCV verification on plaintext according to the
specified KcvMode.

The incoming parameters must be valid; otherwise, an error may

occur. The valid KeyBlock must be 184 bytes.

OsPedWriteKeyVar

int OsPedWriteKeyVar(int KeyType,

int SrcKeyIdx,
Prototype
int DstKeyIdx,
const unsigned char *KeyVar);
Use the key plaintext specified by source key index and key
Function type to operate with data string and write the result to specified
destination key index in the same key type area.
Parameters KeyType Key types:

PAX Computer Technology (Shenzhen) Co., Ltd. 62

 Prolin API Programming Guide

 PED_TMK
 PED_TPK
 PED_TAK
 PED_TDK
Source key index.The valid range is from 1
SrcKeyIdx
to 100.
Destination key index. The valid range is
DstKeyIdx
from 1 to 100.
A 24-byte string involoved in calculation.
KeyVar[Input] The string is used to xor with the source key.
The string length should be the same as the
key’s, and it is extensible.
RET_OK Succeeded.
ERR_DEV_NOT_OPEN PED device is not open.
Return
ERR_INVALID_PARAM Invalid parameter
Others Refer to PED Return Code List .
Instruction

Please refer to AS2805.6.

OsPedSetAsteriskLayout

int OsPedSetAsteriskLayout(int x,
int y,
Prototype int fontSize,
int fontColor,
uchar align);
Function Set the layout attributes of asterisk while inputting PIN.
x X-coordinate
y Y-coordinate
Font size of asterisk:
Parameters  fontSize = 16: the character size is 16 dots;
fontSize  fontSize = 24: the character size is 24 dots;
 fontSize = 32: the character size is 32 dots;
 fontSize = 48: the character size is 48 dots.

PAX Computer Technology (Shenzhen) Co., Ltd. 63

 Prolin API Programming Guide

Note ： The asterisk is displayed with PED

internal font, which has no relation with the
installed system font library.
Font color of asterisk.
fontColor Macro definition RGB (_r, _g, _b) is used; the
16-bit color value will be generated according to
the input three primary colors.
Alignment:
 PED_ASTERISK_ALIGN_LEFT:
Display asterisk from left to right; the left
starting position is fixed.
 PED_ASTERISK_ALIGN_CENTER:
align Display asterisk from the middle to both right
side and left side symmetrically; the middle
position is fixed.
 PED_ASTERISK_ALIGN_RIGHT:
Display asterisk from right to left; the right
starting position is fixed.
RET_OK Succeeded.
ERR_DEV_NOT_OP
PED device is not open.
EN
Return
ERR_INVALID_PAR
Invalid parameter.
AM
Others Refer to the PED Return Code List.
1. This function is only used to display asterisk, while PIN
input interface is displayed by application.
2. This function should be called to set the layout of asterisk
Instruction
before calling OsPedVerifyPlainPin(),
OsPedVerifyCipherPin() OsPedGetPinBlock() or
OsPedGetPinDukpt ().

OsPedSetPinIconLayout

int OsPedSetPinIconLayout(int X,
int Y,
int Interval,
uchar IconNum,
Prototype
char *PinIcon,
int PinIconLen,
char *PinIconBG,
int PinIconBGLen);

PAX Computer Technology (Shenzhen) Co., Ltd. 64

 Prolin API Programming Guide

Function Set the layout attributes of foreground and background icons.

The initial x coordinate of foreground
X [Input]
and background icons.
The initial y coordinate of foreground
Y [Input]
and background icons.
Interval [Input] The interval of two adjacent icons.
IconNum [Input] The number of background icon
Absolute path of foreground icon,
PinIcon [Input]
BMP and PNG icons are supported.
The length of absolute path of
Parameters PinIconLen [Input] foreground icon, the valid length is
not more than 256 bytes.
Absolute path of background icon,
BMP and PNG icons are supported,
PinIconBG [Input]
and it can be set to NULL if icon is
not needed.
The path length of absolute path of
background icon, the valid length is
PinIconBGLen [Input] not more than 256 bytes, and set it to
0 when background icon is not
needed.
RET_OK Succeeded
ERR_DEV_NOT_OPE
PED device is not open.
Return N
ERR_INVALID_PARAM Invalid parameters
Others Refer to the PED Return Code List
1. If user calls this function before inputting PIN, the icon
specified by the parameter will be used as PIN background
and the foreground icon will replace asterisk to prompt PIN
input.
2. After calling OsPedSetAsteriskLayout() , the asterisk will
replace icon to prompt PIN input and the PIN icon attribute
settings will all be cleared;
Instruction 3. Enable/disable the dynamic center display function of the
foreground image by setting the value of
“persist.sys.ped.pin.icon.align” in the registry shown as
below:
 When persist.sys.ped.pin.icon.align=1, while inputting PIN,
the foreground image which is passed in after calling
OsPedSetPinIconLayout() will be centered and displayed
dynamically, and the background image will not be
displayed at the same time;

PAX Computer Technology (Shenzhen) Co., Ltd. 65

 Prolin API Programming Guide

 When persist.sys.ped.pin.icon.align=0, the foreground

image will restore to normal display, and the default value is
“0”.

OsPedGetPinBlock

int OsPedGetPinBlock(int KeyIdx,

const unsigned char *DataIn,
const char *ExpPinLen,
Prototype
int Mode,
unsigned long TimeoutMs,
unsigned char *PinBlock);
Scan input PIN whose length is specified by ExpPinLenIn within
Function specified time and output PIN block which is encrypted with
algorithm specified by Mode.
TPK Index.
KeyIdx
The value range is from 1 to 100.
 When Mode=0x00, DataIn points to
the16-bit primary account number
which is generated after shifting card
number.
 When Mode=0x01, DataIn is
meaningless, and it can be an
arbitrary value. PED will use random
number instead of DataIn in the
calculation of PinBlock.
 When Mode=0x02, DataIn is the
16-bit primary account number
which is generated after shifting card
Parameters DataIn[Input] number.
 When Mode=0x03, DataIn is the
transaction serial number ISN [6
Bytes, ASCII code].
 When Mode=0x10, DataIn is
meaningless, and it can be an
arbitrary value. PED will use random
number instead of DataIn in the
calculation of PinBlock.
 When Mode=0x50, DataIn is
meaningless, and it can be an
arbitrary value.
A pointer to valid password length string,
ExpPinLen[Input] which is an enumeration set from 0 to
12.

PAX Computer Technology (Shenzhen) Co., Ltd. 66

 Prolin API Programming Guide

Application enumerates all valid

password length and separate each
length with “,”. For example, if no PIN, 4
and 6 digits of PIN are allowed, the
string will be set to “0, 4, 6”. “0” means
no PIN is required and can return directly
by pressing “Enter”.
When Mode=0x50, the valid password
length string that can be entered is an
enumeration set of 0~16.
PIN block format:
Format of PinBlock encrypted with
DES-ECB (3DES-ECB) algorithm:
 0x00 0x00 ISO9564 format 0
 0x01 0x01 ISO9564 format 1
 0x02 0x02 ISO9564 format 3
 0x03 0x03 HK EPS proprietary
format
Mode Format of PinBlock encrypted with
DES-CBC (3DES-CBC) algorithm:
 0x50 0x50 SIN MCCS proprietary
format
Format of PinBlock encrypted with
AES-ECB algorithm:
 0x10: the first 8 bytes of plaintext
PinBlock is in ISO9564 format 1, the
last 8 bytes will be filled in #PKCS7
which is a 8-byte of 0x08.
Timeout of PIN input [unit:ms]
TimeoutMs The valid timeout ranges from 0 to
300000 ms. “0” means no timeout. PED
has no timeout control.
Point to the generated PIN block.
The valid length is 8 or 16 bytes.
PinBlock[Output]
When Mode=0x10, the length of
PinBlock is 16 bytes.
RET_OK Succeeded.
ERR_DEV_NOT_OPEN PED device is not open.
Return
ERR_INVALID_PARAM Invalid parameter.
Others Refer to PED Return Code List .
1. Press [CANCEL]key to cancel input.
Instruction
2. Call OsPedGetPinBlock() will operate the framebuffer,

PAX Computer Technology (Shenzhen) Co., Ltd. 67

 Prolin API Programming Guide

which might cause the resource conflict. If there is some

kind of exception on the interface of application which is
running XUI, call XuiSuspend() to suspend XUI before
calling OsPedGetPinBlock(), after a while, call
XuiResume() to resume XUI. If the background of PIN input
is set by calling OsPedSetPinBg() before the PIN input
interface is called, XuiSuspend() and XuiResume() cannot
be called.
3. The key which is used for encrypting PinBlock with
DES(3DES) algorithm is PED_TPK, and the key which is
used for encrypting PinBlock with AES algorithm is
PED_AES_TPK.

OsPedUpdatePinBlock

int OsPedUpdatePinBlock(int UpdateFlag,

const unsigned char *KeyInfo,
Prototype const unsigned char *DataIn,
unsigned char *PinBlock,
int Mode);
Recalculate PIN block and replaced TPK according to
Function
UpdateFlag.
0: Do not replace TPK,
UpdateFlag
Others: Replace TPK
Please refer to the definition of KeyBlock in
OsPedWriteKey(). The valid length is 184
bytes.
KeyInfo[Input]
When UpdateFlag is 0, only DstKeyIdx is valid
in KeyBlock. PIN block is recalculated with TPK
specified by DstKeyIdx.
 When UpdateFlag is 0 and Mode=0x03,
DataIn is the transaction serial number ISN
Parameters [6 Bytes, ASCII code].
 When UpdateFlag is 0 and Mode=0x00, the
first 16 bytes of DataIn is the old PAN, and
DataIn[Input] the last 16 bytes of DataIn is the new PAN.
PAN is the 16-bit primary account number
which is generated after shifting card
number.
 When UpdateFlag is not 0, DataIn can be
NULL.
Input original PIN block data and output new
PinBlock[Out PIN block.
put]
The valid value is 8 bytes.

PAX Computer Technology (Shenzhen) Co., Ltd. 68

 Prolin API Programming Guide

0x00: ISO9564 format 0;

Mode 0x03: HK EPS proprietary format [Refer to
Appendix 2 EPS_PINBLOCK Format].
RET_OK Succeeded.
ERR_DEV_NOT_OPEN PED device is not open.
Return
ERR_INVALID_PARAM Invalid parameter.
Others Refer to the PED Return Code List .
Instruction This function only applies to EPS.

OsPedGetMac

int OsPedGetMac(int KeyIdx,

const unsigned char *DataIn,
Prototype int DataInLen,
unsigned char *Mac,
int Mode);
Function Calculate data with specified Mode and MAC key.
TAK index.
KeyIdx
The valid KeyIdx ranges from 1 to 100.
Data that needs to do MAC operation.
DataIn[Input]
The valid length is not more than 8192 bytes.
The length of data package. If the length is not
DataInLen a multiple of 8, 0x00 will be padded
automatically.
MAC output.
Mac[Output]
The valid length is 8 bytes
DataIn is blocked into 8-byte as BLOCK1，
Parameters BLOCK2，BLOCK3, etc.
0x00: Perform DES/TDES encryption on
BLOCK1 with MAC key and bitwise xor
the encryption result with Block2. Then
perform DES/TDES encryption on the
Mode xor result with TAK key to get an 8-byte
encrypted result.
0x01: Bitwise xor BLOCK1 with BLOCK2; use
the xor result to bitwise xor with
BLOCK3; continue in this way, we can
get an 8-byte xor result. Then perform
DES/TDES encryption with TAK on the
final xor result.

PAX Computer Technology (Shenzhen) Co., Ltd. 69

 Prolin API Programming Guide

0x02: According to ANSIX9.19 standard,

perform DES encryption on BLOCK1
with TAK (only take the first 8 bytes of
the key). Then bitwise xor the encrypted
result with BLOCK2, and perform DES
encryption on the xor result with TAK to
get an 8 bytes encryption result. Finally
perform DES/TDE encryption on the
8-byte result.
RET_OK Succeeded.
ERR_DEV_NOT_OPE
PED device is not open.
N
Return
ERR_INVALID_PARA
Invalid parameter.
M
Others Refer to PED Return Code List .
Instruction

OsPedDes

int OsPedDes(int KeyIdx,

unsigned char * InitVector,
const unsigned char *DataIn,
Prototype
int DataInLen,
unsigned char *DataOut,
int Mode);
Use DES/TDES algorithm and TDK to encrypt or decrypt data
whose length is specified by DataInLen and output ciphertext or
Function
plaintext into DataOut.A specified TDK can be used either in
encryption or decryption.
TDK index.
KeyIdx
The valid KeyIdx ranges from 1 to 100.
Initialization vector. The valid length is 8
bytes.
When Mode=0x02/0x03/0x04/0x05, the
initialization vector is needed in encryption or
Parameters decryption; when InitVecto is NULL, the
InitVecto[Input]
initialization vector is set to
“\x00\x00\x00\x00\x00\x00\x00\x00” by
default.
When Mode=0x00/0x01, the initialization
vector is not needed and can be set to NULL.
DataIn[Input] A pointer to the data that needs to be

PAX Computer Technology (Shenzhen) Co., Ltd. 70

 Prolin API Programming Guide

calculated.
Length of data that needs to be
calculated.[unit: byte]
The valid data length should be less than or
DataInLen
equal to 1024 bytes.
When Mode=0x00~0x05, the data length
must be a multiple of 8.
DataOut[Outpu
A pointer to the data that has been calculated.
t]
 0x00: ECB Decryption
 0x01: ECB Encryption
 0x02: CBC Decryption
 0x03: CBC Encryption
Mode
 0x04: OFB Decryption
 0x05: OFB Encryption
 0x06: CFB8 Decryption
 0x07: CFB8 Encryption
RET_OK Succeeded.
ERR_DEV_NOT_OPEN PED device is not open.
Return
ERR_INVALID_PARAM Invalid parameter.
Others Refer to PED Return Code List .
Instruction

The key length decides the encryption or decryption aglorithm is

DES or TDES.Whether to use DES or TDES algorithm depends
on the key length.

OsPedGetKcv

int OsPedGetKcv(int KeyType,

int KeyIdx,
int KcvMode,
Prototype
int KcvDataLen,
unsigned char *KcvData,
unsigned char *Kcv);

Function Get KCV value to verify the key for both sides of session: when
the KeyType is not TIK, KCV is the first 3-byte of data encrypted

PAX Computer Technology (Shenzhen) Co., Ltd. 71

 Prolin API Programming Guide

with specified key and algorithm; when the KeyType is TIK,

KCV is an 8-byte calculation result which is injected together
with TIK.
Key type:
 PED_TLK
 PED_TMK
 PED_TAK
 PED_TPK
KeyType  PED_TDK
 PED_TIK
 PED_SM4_TMK
 PED_SM4_TPK
 PED_SM4_TAK
 PED_SM4_TDK
Key index number, for example:
 TLK can only be 1.
KeyIdx  TMK ranges from 1 to 100.
 TWK ranges from 1 to 100.
 TIK ranges from 1 to 100.
KCV check mode.
Parameters
0x00: Calculate the KCV of the key with DES
algorithm ;
KcvMode 0x04: Calculate the KCV of SM4 key with SM4
algorithm, and the key types can only be SM4
series keys (KeyType can only be
PED_SM4_TMK/PED_SM4_TPK/PED_SM4_T
AK/PED_SM4_TDK).
Length of data that needs to be calculated.
The valid data length ranges from 0 to
KcvDataLen 128bytes and must be a multiple of 8. When
KeyType is TIK, KcvDataLen can be set to 0;
When the KCV check mode is 0x04, the data
length must be divisible by 16.
A pointer to the data that needs to be
KcvData[Inpu calculated.
t]
NULL pointer is valid when KeyType is TIK.
KCV.
Kcv[Output] The valid length of Kcv is 8 bytes when
KeyType is TIK, and 3 bytes for rest KeyType.
RET_OK Succeeded.
Return
ERR_DEV_NOT_OP PED device is not open.

PAX Computer Technology (Shenzhen) Co., Ltd. 72

 Prolin API Programming Guide

EN
ERR_INVALID_PAR
Invalid parameter.
AM
Others Refer to the PED Return Code List .
Instruction

OsPedDeriveKey

int OsPedDeriveKey(int SrcKeyType,

int SrcKeyIdx,
int DstKeyType,
Prototype
int DstFromKeyIdx,
int DstToKeyIdx,
int Mode);
Use the key specified by SrcKeyIdx to encrypt or decrypt the
Function key specified by DstFromKeyIdx, derive a new key and save it
at the destination key specified by DstToKeyIdx.
Source key types:
 PED_TLK
 PED_TMK
SrcKeyType
 PED_TAK
 PED_TPK
 PED_TDK
Index number of source key, for example:
 TLK can only be 1.
SrcKeyIdx
 TMK ranges from 1 to 100.
 TWK ranges from 1 to 100.
Parameters Destination key types :
 PED_TLK
 PED_TMK
DstKeyType
 PED_TAK
 PED_TPK
 PED_TDK
DstFromKeyI
Source index of destination key.
dx
DstToKeyIdx Destination index of destination key.
0x00: DES/TDES decryption;
Mode
0x01: DES/TDES encryption.
Return RET_OK Succeeded.

PAX Computer Technology (Shenzhen) Co., Ltd. 73

 Prolin API Programming Guide

ERR_DEV_NOT_OPEN PED device is not open.

ERR_INVALID_PARAM Invalid parameter.
Others Refer to PED Return Code List .
The level of source key type cannot be lower than destination
Instruction
key.

OsPedSetPinBg

int OsPedSetPinBg(uchar Mode,

Prototype const uchar *Bg,
int BgLen);
Set the background of the PIN input interface using
Function
Framebuffer data or image data.
The setting mode of the PIN input
background.
1. If Mode=0x00,the setting of this function
will be cleared.
Mode[Input] 2. If Mode=0x01, the background of the PIN
input interface will be set using
Framebuffer data.
Parameters 3. If Mode=0x02, the background of the PIN
input interface will be set using image
data.
The buffer to store Framebuffer data or image
Bg[Input]
data.
The buffer length of the stored Framebuffer
BgLen[Input]
data or image data.
RET_OK Succeeded.
ERR_DEV_NOT_OPEN PED device is not open.
Return
ERR_INVALID_PARAM Invalid parameter.
Others Refer to PED Return Code List .
1. When Mode=0x00, parameter Bg and BgLen are
meaningless;
2. When Mode is not equal to 0x00, parameter Bg cannot be
null and BgLen > 0;
Instruction 3. The size of the Framebuffer data which is provided by users
must be consistent with the Framebuffer data size of the
screen, and the image resolution must be consistent with
the resolution of the screen;
4. The image data represents the data which is read from
image file by users and cached into memory, and only

PAX Computer Technology (Shenzhen) Co., Ltd. 74

 Prolin API Programming Guide

“bmp” and “png” format images are supported;

5. The PIN input background set in this interface will be
cached in PED until it is cleared or the terminal is powered
off;
6. XUI provides XuiImgToFrameBuffer() to get the
Framebuffer data of the whole screen, and it can be used
with this interface. The detailed description and
corresponding sample code are in the 10.2 section of
“Prolin Application Development Manual”.

OsPedCustomKeypad

int OsPedCustomKeypad(char *IconPath,

Prototype uchar *KeypadColor,
uchar Mode);
Function Customize the PED soft keypad.
The absolute path of keypad icons, and
relative path is not supported. It cannot be
IconPath more than 256 bytes and it can be NULL.
[Input]
When IconPath is NULL, the default icon will
be used.
RGBA value of the keypad background color,
KeypadColorBg it has 4 bytes and it can be NULL.
Parameters
[Input] When KeypadColorBg is NULL, the default
keypad background will be used.
When Mode = 0x00, the default icon and
keypad background color will be used.
Mode
[Input] When Mode = 0x01, the icon and keypad
background color specified by users will be
used.
RET_OK Succeeded.
ERR_DEV_NOT_OPEN PED device is not open.
ERR_INVALID_PARAM Invalid parameter.

Return Resource file of keypad icon does

ERR_FILE_NOT_EXIST
not exist.
ERR_VERIFY_SIGN_FAI Failed to verify the resource file of
L keypad icon.
Others Refer to PED Return Code List .
1. Before inputing PIN, call this function to set the icon in the
Instruction specified path as the PIN input keypad icon, and to set the
canvas backround color as the PIN input keypad

PAX Computer Technology (Shenzhen) Co., Ltd. 75

 Prolin API Programming Guide

background color.
2. Support replacing parts of keypad icons. The system will
only obtain the icon resource file which corresponds to
relevant model in KeypadPath, if no corresponding keypad
icon resource file is found, the system will use the default
resource file.
3. Each keypad icon provided by users needs to be signed by
MF_PVK. If the signature verification is failed, it indicates
the setting is failed, and ERR_VERIFY_SIGN_FAIL will be
returned.
4. When Mode = 0x01, KeypadPath and KeypadColorBg
cannot be NULL at the same time. If none of keypad icon in
KeypadPath meets the requirement, this API will cancel the
setting and return ERR_FILE_NOT_EXIST.
5. Please refer to section 10.3 in “Prolin Application
Development Manual” for the usage and requirements of
relevant models’ keypad icon resource.
6. Soft keypad background color does not support
transparency temporarily, so only RGB in KeypadColorBg
takes effect, and A (Alpha) has no effect.

6.6 DUKPT

OsPedGetPinDukpt

int OsPedGetPinDukpt(int GroupIdx,

const unsigned char *DataIn,
const char *ExpPinLen,
Prototype int Mode,
unsigned long TimeoutMs,
unsigned char *Ksn,
unsigned char *PinBlock);
Scan input PIN and output PIN block which is a result of
Function
DUKPT PIN key calculation within specified time.
DUKPT group index number.
GroupIdx
The valid GroupIdx ranges from 1 to 100.
1. If Mode=0x20, DataIn points to the 16-bit
Parameters primary account number after shifting card
number.
DataIn[Input]
2. If Mode=0x21, DataIn has no meaning.
3. If Mode=0x22, DataIn points to the 16-bit
primary account number after shifting card

PAX Computer Technology (Shenzhen) Co., Ltd. 76

 Prolin API Programming Guide

number.
4. If Mode=0x23, DataIn is ISN [6 Bytes,
ASCII code]
A pointer to valid password length string
which is an enumeration set from 0 to 12.
Application enumerates all valid password
ExpPinLen[Inp length and separates each length with “,”. For
ut] example, if no PIN, 4 and 6 digits of PIN are
allowed, the string will be set to “0, 4, 6”. “0”
means no PIN is required and can return
directly by pressing “Enter”.
Choose the format of PIN block:
 0x20 ISO9564 format 0, KSN does not
increase 1 automatically.
 0x21 ISO9564 format 1, KSN does not
Mode increase 1 automatically.
 0x22 ISO9564 format 3, KSN does not
increase 1 automatically.
 0x23 HK EPS format, KSN does not increase
1 automatically.
Timeout of PIN input[unit:ms]
TimeoutMs The valid timeout ranges from 0 to 300000ms.
“0” means no timeout, and PED has no
timeout control.
A pointer to the current KSN.
Ksn[Output]
The valid length of KSN is 10 bytes.
PinBlock[Outp A pointer to the generated PIN block result.
ut] The valid length of PIN block is 8 bytes.
RET_OK Succeeded.
ERR_DEV_NOT_OPEN PED device is not open.
Return
ERR_INVALID_PARAM Invalid parameter.
Others Refer to PED Return Code List .
1. When KSN does not increase 1, a DUKPT PIN key can only
calculate the PIN block once.
2. Calling OsPedGetPinDukpt() will operate the framebuffer,
Instruction which might cause the resource conflict. If there is some
kind of exception on the interface of application which is
running XUI, call XuiSuspend() to suspend XUI before
calling OsPedGetPinDukpt(), after a while, call
XuiResume() to resume XUI.

PAX Computer Technology (Shenzhen) Co., Ltd. 77

 Prolin API Programming Guide

OsPedGetMacDukpt

int OsPedGetMacDukpt(int GroupIdx,

const unsigned char *DataIn,
int DataInLen,
Prototype
unsigned char *Mac,
unsigned char *Ksn,
int Mode);
Function Calculate MAC with DUKPT key.
DUKPT group index number.
GroupIdx
The value range is from 1 to 100.
A pointer to the data that needs to calculate
DataIn[Input]
MAC.
Data length.
DataInLen The valid length is not more than 8192 bytes
and must be a multiple of 8; otherwise,
padding with“\x00” automatically.
Mac[Output] A pointer to the generated MAC.
Ksn[Output] A pointer to the current KSN.
DataIn is blocked into 8-byte BLOCK1 ，
BLOCK2，BLOCK3, etc.
0x20: Perform TDES encryption on BLOCK1
with MAC key and bitwise xor the
encryption result with Block2. Then
Parameters
perform TDES encryption on the xor
result with TAK key to get an 8-byte
encrypted result.
0x21: Bitwise xor BLOCK1 with BLOCK2; Use
the xor result to bitwise xor with
BLOCK3; Continue in this way, we can
Mode get an 8-byte xor result. Then perform
DES/TDES encryption with TAK on the
8-byte xor result.
0x22: According to ANSIX9.19 standard,
perform DES encryption on BLOCK1
with TAK (only take the first 8 bytes of
the key). Then bitwise xor the encrypted
result with BLOCK2, and perform DES
encryption on the xor result with TAK to
get an 8 bytes encryption result. Finally
perform TDE encryption on the 8-byte
result.

PAX Computer Technology (Shenzhen) Co., Ltd. 78

 Prolin API Programming Guide

1. 0x20/0x21/0x22/0x40/0x41/0x42: KSN
does not increase1 automatically.
2. 0x40/0x41/0x42: MAC calculation method
is the same as 0x20/0x21/0x22’s.
3. 0x40/0x41/0x42: Choose to respond to
MAC key.
0x20/0x21/0x22: KSN choose to request
or respond to MAC key
4. Other values are reserved for extended
MAC algorithm.
RET_OK Succeeded.
ERR_DEV_NOT_OPEN PED device is not open.
Return
ERR_INVALID_PARAM Invalid parameter.
Others Refer to PED Return Code List .
If KSN does not increase 1, both the response MAC key and
Instruction
the request MAC key can calculate MAC for unlimited times.

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 Encrypt or decrypt input data with DUKPT key.
DUKPT group index.
GroupIdx
The valid range is from 1 to 100.
0x00: Use response or request MAC key.
0x01: Use DUKPT DES key
0x02: Use PIN variant to encrypt data.
Parameters Only ECB and CBC encryption is
KeyVarType[Inpu available, which means Mode can be
t] 0x01 or 0x03. When the length of
DUPKT key is 8 bytes, the standard
DES algorithm is not adopted but
the special DES algorithm defined in
ANSI9.24-1998 is adopted.

PAX Computer Technology (Shenzhen) Co., Ltd. 79

 Prolin API Programming Guide

0x03：Use response MAC key, only the

encryption mode is supported, which
means Mode can only be 0x01, 0x03
or 0x05.
0x04：Use DES response key, only the
encryption mode is available, that
means Mode can only be 0x01, 0x03
or 0x05.
Initialization vector for
encryption/decryption. The valid length is 8
bytes.
When Mode=0x02/0x03/0x04/0x05, the
initialization vector is needed in encryption
or decryption; If InitVector is NULL, the
InitVector[Input]
initialization vector is set to
“\x00\x00\x00\x00\x00\x00\x00\x00” by
default.
When Mode=0x00/0x01, initialization
vector is not needed and can be set to
NULL.
Length of data that needs to be encrypted
DataInLen or decrypted. The valid length is not more
than 8192 bytes.
A pointer to the input data that needs to be
DataIn [Input]
calculated.
A pointer to the data that has been
DataOut[Output]
calculated.
A pointer to the current KSN.
Ksn[Output]
The valid length of KSN is 10 bytes.
Encryption/decryption mode:
 0x00: ECB decryption
 0x01: ECB encryption
Mode  0x02: CBC decryption
 0x03: CBC encryption
 0x04: OFB decryption
 0x05: OFB encryption

RET_OK Succeeded
ERR_DEV_NOT_OPEN PED device is not open.
Return
ERR_INVALID_PARAM Invalid parameter.
Others Refer to PED Return Code List .
Instruction If KSN does not increase 1 automatically, a DUKPT group can

PAX Computer Technology (Shenzhen) Co., Ltd. 80

 Prolin API Programming Guide

perform DES operations for 256 times at most when

KeyVarType is 0x00/0x01; a DUKPT group can only do one
DES operation when KeyVarType is 0x02.

OsPedGetKsnDukpt

int OsPedGetKsnDukpt(int GroupIdx,

Prototype
unsigned char *Ksn);
Function Read the current KSN value.
DUKPT group index.
GroupIdx
The value range is from 1 to 100.
Parameters
A pointer to the current KSN.
Ksn[Output]
The valid length of KSN is 10 bytes.
RET_OK Succeeded.
ERR_DEV_NOT_OPE
PED device is not open.
N
Return
ERR_INVALID_PARA
Invalid parameter
M
Others Refer to PED Return Code List .
Instruction

OsPedIncreaseKsnDukpt

Prototype int OsPedIncreaseKsnDukpt(int GroupIdx);

Function Increase the KSN value of the specified DUKPT group.
DUKPT group index.
Parameters GroupIdx
The value range is from 1 to 100.
RET_OK Succeeded.
ERR_DEV_NOT_OPEN PED device is not open.
Return
ERR_INVALID_PARAM Invalid parameter.
Others Refer to PED Return Code List .
Instruction

PAX Computer Technology (Shenzhen) Co., Ltd. 81

 Prolin API Programming Guide

6.7 RSA

OsPedReadRsaKey

int OsPedReadRsaKey(int RsaKeyIdx,

Prototype
ST_RSA_KEY *RsaKey);
Function Read the RSA public key.
RSA Key index, the value range is from 1 to
RsaKeyIdx
Parameters 10.
RsaKey[Output] A pointer to ST_RSA_KEY structure.
RET_OK Succeeded.
ERR_DEV_NOT_OPEN PED device is not open.
Return
ERR_INVALID_PARAM Invalid parameter.
Others Refer to PED Return Code List .
OsPedReadRsaKey() can only be used to read RSA public key;
Instruction
When reading private key, an error will be returned.

OsPedWriteRsaKey

int OsPedWriteRsaKey(int RsaKeyIdx,

Prototype
ST_RSA_KEY *RsaKey);
Function Inject RSA key into PED.
RSA Key index.
RsaKeyIdx
The value range is from 1 to 10.
Parameters
A pointer to ST_RSA_KEY structure that will
RsaKey[Input]
be injected into PED.
RET_OK Succeeded.
ERR_DEV_NOT_OPEN PED device is not open.
Return
ERR_INVALID_PARAM Invalid parameter.
Others Refer to PED Return Code List .
1. The type of RSA key depends on ExponentLen and
ModulusLen in RsaKey. It is a private key if ExponentLen is
equal to ModulusLen (ExponentLen=ModulusLen);
otherwise, it is public key.
Instruction
2. For a RSA public key, ExponentLen in RsaKey must be 32
which means its exponent length is 4 bytes; if its length is
less than 4 bytes, pad with 0x00 at the left side of
Exponent.

PAX Computer Technology (Shenzhen) Co., Ltd. 82

 Prolin API Programming Guide

1. The supported RSA key length is not more than 512 bytes.

2. RSA key can be rewritten at any time.

OsPedRsaRecover

int OsPedRsaRecover(int KeyIdx,

int DataInLen,
Prototype unsigned char *DataIn,
unsigned char *DataOut,
unsigned char *KeyInfo);

Function Calculate RSA data with RSA key stored in PED.

RSA Key index. The value range is from 1 to
RsaKeyIdx
10.
Length of data that needs to be calculated.
It is equal to the modulus length of RSA key.
DataInLen
The valid length ranges from 64 to 512 and
Parameters must be a multiple of 8.
A pointer to the data that needs to be
DataIn[Input]
calculated.
A pointer to the data that has been
DataOut[Output]
calculated.
KeyInfo[Output] A pointer to key information.
RET_OK Succeeded.
ERR_DEV_NOT_OPE
PED device is not open.
N
Return
ERR_INVALID_PARA
Invalid parameter.
M
Others Refer to PED Return Code List .
Instruction

OsPedReadCipherRsaKey

int OsPedReadCipherRsaKey(int RsaKeyIdx,

Prototype unsigned char
*CipherRsaKey);

PAX Computer Technology (Shenzhen) Co., Ltd. 83

 Prolin API Programming Guide

Function Read the ciphertext of RSA key.

RSA key index. The valid range is from 1
RsaKeyIdx
to 10.
Parameters
CipherRsaKey[Out A pointer to the ciphertext data of RSA
put] key.
>0 Ciphertext length of RSA key.
ERR_DEV_NOT_OPEN PED device is not open.
Return
ERR_INVALID_PARAM Invalid parameter.
Others Refer to PED Return Code List .
Instruction

OsPedWriteCipherRsaKey

int OsPedWriteCipherRsaKey(int RsaKeyIdx,

int CipherRsaKeyLen,
Prototype
unsigned char
*CipherRsaKey);
Function Write the ciphertext of RSA key.
RSA key index.
RsaKeyIdx
The value range is from 1 to 10.
Ciphertext length of RSA key.
Parameters CipherRsaKeyLe The valid length is not more than 1024
n
bytes.
CipherRsaKey[In
A pointer to ciphertext of RSA key.
put]
RET_OK Succeeded.
ERR_DEV_NOT_OPEN PED device is not open.
Return
ERR_INVALID_PARAM Invalid parameter.
Others Refer to PED Return Code List .
Instruction

6.8 AES

OsPedWriteAesKey

Prototype intOsPedWriteAesKey(const unsigned char *KeyBlock);

PAX Computer Technology (Shenzhen) Co., Ltd. 84

 Prolin API Programming Guide

Write AES key’s ciphertext or plaintext into a position of

Function specified index within the AES key area, and it is optional to use
KCV to verify the validity of the key.
1 byte Format: 0x03
SrcKeyType:
1 byte  PED_TLK
 PED_TMK
SrcKeyIdx:
 When SrcKeyType =
PED_TLK,
SrcKeyIdx = 1;
1 byte  When SrcKeyType =
PED_TMK,
SrcKeyIdx = [1~100];
 If ucSrcKeyIdx = 0, key will be
written in PED as plaintext.
1 byte DstKeyIdx: [1-100].
7 bytes Reserved field, random number.
DstKeyType:
 PED_TAESK
KeyBlock[Input 1 byte  PED_AES_TPK
Parameters
]  PED_AES_TAK
 PED_AES_TDK
1 byte DstKeyLen: 16/24/32
DstKeyValue:
32 bytes Destination key plaintext or
ciphertext.
KcvMode:
0x00: No verification.
0x01: KCV is the first 3 bytes of
ciphertext after encrypting
the 16-byte 0x00 with
AES/ECB algorithm.
1 byte 0x02: KCV is the first 3 bytes of
ciphertext after odd parity
check on the plaintext of
key and AES/ECB
encryption on
“\x12\x34\x56\x78\x90\x12\
x34\x56”.
0x03: KCV is an 8-byte MAC value,

PAX Computer Technology (Shenzhen) Co., Ltd. 85

 Prolin API Programming Guide

that is, a result of specified

mode of MAC calculation on
[ciphertext of destination key
+ input KcvData] with source
key.
KcvData:
 When KcvMode is
0x00/0x01/0x02, pad with
random numbers.
128  When KcvMode is 0x03, the
bytes first byte of KcvData is the
length of KCV data involved in
the calculation, and the rest is
KCV data. The first byte after
the KCV data represents the
MAC operation mode.
 When KcvMode = 0x00, pad
with random numbers.
8 bytes  When KcvMode
=0x01/0x02/0x03, KcvValue
points to the KCV value.
2 bytes Padding with random number.
RET_OK Succeeded.
ERR_DEV_NOT_OPEN Device is not open.
Return
ERR_INVALID_PARAM Invalid parameter.
Others Refer to PED Return Code List.
1. When SrcKeyIdx=0, DstKeyValue is regarded as the
plaintext of key. The system will directly write DstKeyValue
into DstKeyIdx position within DstKeyType area without
judging SrcKeyType and SrcKeyIdx.
2. Only when PED_TLK does not exist, plaintext is allowed to
be written and key is allowed to be downloaded.
Instruction
3. When SrcKeyIdx is valid, DstKeyValue is regarded as the
ciphertext of the key. The system will decrypt DstKeyValue
with SrcKeyIdx key in SrcKeyType area and write the key to
DstKeyIdx position within DstKeyType area.
4. PED_TAESK is the same as PED_AES_TDK, it is used for
encrypting/decrypting with AES algorithm.

PAX Computer Technology (Shenzhen) Co., Ltd. 86

 Prolin API Programming Guide

The input parameter must be valid; otherwise, an error may

occur. Valid KeyBlock length must be 184 bytes.

OsPedAes

intOsPedAes(intKeyIdx,
unsigned char *InitVector,
const unsigned char *DataIn,
Prototype
intDataInLen,
unsigned char *DataOut,
int Mode);
Use TAESK or PED_AES_TDK to do AES encryption or
Function
decryption for DataIn whose length is specified by DataInLen.
TAESK index.
KeyIdx[Input]
The value range is from 1 to100.
Initialization vector.
When Mode=0x02/0x03/0x04/0x05,
initialization vector is needed in
encryption/decryption. If InitVector is
NULL, the initialization vector is set to
16-byte 0x00 by default.
InitVector[Input/Out When Mode=0x00/0x01, the initialization
put] vector is not needed and can be set to
NULL.
When Mode=0x06/0x07, the initialization
vector represents a 16-byte temporary
counter which is required for calculation,
Parameters
and the counter will be updated after
calculated successfully.
A pointer to the data that needs to be
DataIn[Input]
calculated.
Length of data that needs to be
calculated.
The valid length is not more than 1024
DataInLen[Input]
bytes and must be a multiple of 16.
When the calculation mode is in CTR
mode, there is no limit to the data length.
A pointer to the data that has been
DataOut[Output]
calculated.
Mode [Input] 0x00: ECB Decryption

PAX Computer Technology (Shenzhen) Co., Ltd. 87

 Prolin API Programming Guide

0x01: ECB Encryption

0x02: CBC Decryption
0x03: CBC Encryption
0x04: OFB Decryption
0x05: OFB Encryption
0x06: CTR Decryption
0x07: CTR Encryption
RET_OK Succeeded.
ERR_DEV_NOT_OPEN Device is not open.
Return
ERR_INVALID_PARAM Invalid parameter.
Others Refer to PED Return Code List .
Instruction

6.9 SM Algorithm

OsPedGenSM2Pair

int OsPedGenSM2Pair(uchar *PvtKey,

Prototype uchar *PubKey,
int KeyLenBit);
Function Generate SM2 key pair.
PvtKey[Output] A pointer to SM2 private key.
The valid length is 32 bytes.
Parameters PubKey[Output] A pointer to SM2 public key.
The valid length is 64 bytes.
KeyLenBit[Input] Private key bit, 256 bits.
RET_OK Succeeded.
ERR_DEV_NOT_OPEN Device is not open.
Return
ERR_INVALID_PARAM Invalid parameter.
ERR_SYS_BAD System error
Instruction 256 bits of SM2 private key and 512 bits of public key are valid.

OsPedWriteSM2Key

int OsPedWriteSM2Key(int KeyIdx,

Prototype
int KeyType,

PAX Computer Technology (Shenzhen) Co., Ltd. 88

 Prolin API Programming Guide

uchar *KeyValue);
Function Inject SM2 private key or pubic key into PED.
SM2 key index.
KeyIdx[Input]
The valid range is from 1 to 20.
Key types:
KeyType[Input] PED_SM2_PVT_KEY 0x30 private key
Parameters PED_SM2_PUB_KEY 0x31 public key
When KeyType=0x30, the valid length of
KeyValue is 32 bytes.
KeyValue[Input]
When KeyType=0x31, the valid length of
KeyValue is 64 bytes.
RET_OK Succeeded.
ERR_DEV_NOT_OPEN Device is not open.
ERR_INVALID_PARAM Invalid parameter.
ERR_SYS_BAD System error
Return
ERR_PED_KEY_IDX_ERR Key index error
ERR_PED_KEY_TYPE_ER
Key type error
R
Others Refer to PED Return Code List .
Instruction

OsPedSM2Sign

int OsPedSM2Sign(int PubKeyIdx,

int PvtKeyIdx,
uchar *Uid,
Prototype int UidLen,
uchar *Input,
int InputLen,
uchar *Signature);
Function Use SM2 algorithm to get signature information.
PubKeyIdx[Input] SM2 public key index.
The value range is from 1 to 20.
PvtKeyIdx[Input] SM2 private key index.
Parameters The value range is from 1 to 20.
Uid[Input] User ID.
The length of user ID is 16 bytes. The
default value of Uid is 0x31, 0x32,

PAX Computer Technology (Shenzhen) Co., Ltd. 89

 Prolin API Programming Guide

0x33, 0x34, 0x35, 0x36, 0x37, 0x38,

0x31, 0x32, 0x33, 0x34, 0x35, 0x36,
0x37, 0x38, unless otherwise specified.
UidLen[Input] Length of user ID, the maximum length
is 512 bytes.
Input[Input] Data that needs to be signed.
InputLen[Input] Data length, the maximum length is
2048 bytes.
Signature[Input] 64-byte signature value.
RET_OK Succeeded.
ERR_DEV_NOT_OPEN Device is not open.
ERR_INVALID_PARAM Invalid parameter.
ERR_SYS_BAD System error.
ERR_PED_KEY_IDX_ERR Key index error.
Return
ERR_PED_KEY_TYPE_ERR Key type error.
ERR_PED_NO_KEY Key doesn’t exist.
ERR_PED_TAMPERED PED is tampered.
Refer to PED Return Code
Others
List .
Instruction

OsPedSM2Verify

int OsPedSM2Verify(int PubKeyIdx,

uchar *Uid,
int UidLen,
Prototype
uchar *Input,
int InputLen,
const uchar *Signature);
Function Use SM2 public key to verify signature.
PubKeyIdx[Input] SM2 pubic key index.
The value range is from 1 to 20.
Uid[Input] User ID.
Parameters The length of user ID is 16 bytes. The
default value of Uid is 0x31, 0x32,
0x33, 0x34, 0x35, 0x36, 0x37, 0x38,
0x31, 0x32, 0x33, 0x34, 0x35, 0x36,
0x37, 0x38, unless otherwise specified.

PAX Computer Technology (Shenzhen) Co., Ltd. 90

 Prolin API Programming Guide

UidLen[Input] Length of user ID, the maximum length

is 512 bytes.
Input[Input] Data that needs to be signed.
InputLen[Input] Data length, the maximum length is
2048 bytes.
Signature[Input] 64-byte signature value.
RET_OK Succeeded.
ERR_DEV_NOT_OPEN Device is not open.
ERR_INVALID_PARAM Invalid parameter.
ERR_SYS_BAD System error.
ERR_VERIFY_SIGN_FAIL Verification failed.
Return ERR_PED_KEY_IDX_ERR Key index error.
ERR_PED_KEY_TYPE_ERR Key type error.
ERR_PED_NO_KEY Key doesn’t exist.
ERR_PED_TAMPERED PED is tampered
Refer to PED Return Code
Others
List .
Instruction

OsPedSM2Recover

int OsPedSM2Recover(int KeyIdx,

uchar *Input,
int InputLen,
Prototype
uchar *Output,
int *OutputLen,
int Mode);
Encrypt data with SM2 public key or decrypt data with private
Function
key.
KeyIdx[Input] SM2 private key index.
The value range is from 1 to 20.
Input[Input] Data that needs to be encrypted or
decrypted.
Parameters
InputLen[Input] Data length.
For encryption: The maximum length is
(2048-96) bytes,
For decryption: The maximum length is

PAX Computer Technology (Shenzhen) Co., Ltd. 91

 Prolin API Programming Guide

2048 bytes.
Output[Output] Encrypted or decrypted data.
OutputLen[Output] Length of encrypted or decrypted data.
The length of encrypted data is equal to
the original data length +96 bytes.
The length of decrypted data is equal to
the original data length -96 bytes.
Mode[Input] PED_DECRYPT 0x00 ： use SM2
private key to decrypt data.
PED_ENCRYPT 0x01：use SM2 public
key to encrypt data.
RET_OK Succeeded.
ERR_DEV_NOT_OPEN Device is not open.
ERR_INVALID_PARAM Invalid parameter.
ERR_SYS_BAD System error.
ERR_PED_KEY_IDX_ERR Key index error.
Return
ERR_PED_KEY_TYPE_ERR Key type error.
ERR_PED_NO_KEY Key doesn’t exist.
ERR_PED_TAMPERED PED is tampered.
Refer to PED Return Code
Others
List .
Instruction

OsPedSM3

int OsPedSM3(uchar *Input,

int InputLen,
Prototype
uchar *Output,
int Mode);
Function Use SM3 algorithm to calculate the hash value.
Input[Input] Input data
InputLen[Input] Length of input data
Parameters Output[Output] 32-byte hash value
Mode 0x00 is supported.
Mode[Input]
Other values are reserved.
Return RET_OK Succeeded.

PAX Computer Technology (Shenzhen) Co., Ltd. 92

 Prolin API Programming Guide

ERR_DEV_NOT_OPEN Device is not open.

ERR_INVALID_PARAM Invalid parameter.
ERR_SYS_BAD System error.
Instruction

OsPedSM4

int OsPedSM4(int KeyIdx,

uchar *InitVector,
uchar *Input,
Prototype
int InputLen,
uchar *Output,
int Mode);
Function Use SM4 algorithm to encrypt or decrypt data.
KeyIdx[Input] PED_SM4_TDK index, the value range
is from 1 to 100.
InitVector[Input] 16-byte initialization vector.
For ECB mode, it is a NULL pointer.
Input[Input] Data that needs to be encrypted or
decrypted.
InputLen[Input] Data length, the data length is not more
than 1024 and must be a multiple of 16.
Output[Output] Encrypted or decrypted data.
Parameters
The data length is the same as the
length of input data.
Mode[Input] PED_SM4_ECB_DECRYPT 0x00:SM4
ECB decryption
PED_SM4_ECB_ENCRYPT 0x01:SM4
ECB encryption
PED_SM4_CBC_DECRYPT 0x02:SM4
CBC decryption
PED_SM4_CBC_ENCRYPT 0x03:SM4
CBC encryption
RET_OK Succeeded.
ERR_DEV_NOT_OPEN Device is not open.
Return ERR_INVALID_PARAM Invalid parameter.
ERR_SYS_BAD System error.
ERR_PED_KEY_IDX_ERR Key index error.

PAX Computer Technology (Shenzhen) Co., Ltd. 93

 Prolin API Programming Guide

ERR_PED_KEY_TYPE_ERR Key type error.

ERR_PED_NO_KEY Key doesn’t exist.
ERR_PED_TAMPERED PED is tampered.
ERR_PED_KEY_LEN_ERR Key length error.
Refer to PED Return Code
Others
List.
Instruction

OsPedGetMacSM

int OsPedGetMacSM(int KeyIdx,

uchar *InitVector,
uchar *Input,
Prototype
int InputLen,
uchar *MacOut,
int Mode);
Function Use SM4 algorithm to calculate MAC.
KeyIdx[Input] PED_SM4_TAK key index, the value
range is from 1 to 100.
InitVector[Input] 16-byte initialization vector.
Input[Input] Input data that needs to perform MAC
calculation.
InputLen[Input] Length of data that needs to be
calculated, the valid length is not more
than 1024 and must be a multiple of 16.
MacOut[Output] MAC value
Parameters Mode[Input] 0x00: Use SM4 CBC algorithm to
calculate MAC value. Firstly, bitwise xor
InitVecotor with BLOCK1, and use SM4
algorithm to encrypt the xor result with
TAK. Then, bitwise xor the encrypted
result with BLOCK2, and use SM4
algorithm to encrypt the xor result with
TAK. MacOut is the 16-byte encryption
result.
0x01: Calculate SM3 Hash of the input
data with SM4-TAK key and get the
32-byte MacOut.
RET_OK Succeeded.
Return
ERR_DEV_NOT_OPEN Device is not open.

PAX Computer Technology (Shenzhen) Co., Ltd. 94

 Prolin API Programming Guide

ERR_INVALID_PARAM Invalid parameter.

ERR_SYS_BAD System error.
ERR_PED_KEY_IDX_ERR Key index error.
ERR_PED_KEY_TYPE_ERR Key type error.
ERR_PED_NO_KEY Key doesn’t exist.
ERR_PED_TAMPERED PED is tampered.
ERR_PED_KEY_LEN_ERR Key length error.
Refer to PED Return Code
Others
List.
Instruction

OsPedGetPinBlockSM4

int OsPedGetPinBlockSM4(int KeyIdx,

const char *ExpPinLenIn,
uchar *DataIn,
Prototype
uchar *PinBlockOut,
int Mode,
ulong TimeoutMs);
Within specified TimeoutMs, scan the input PIN on the
Function keyboard and output PIN block which is encrypted by SM4
algorithm.
KeyIdx[Input] PED_SM4_TPK key index, the value
range is from 1 to 100.
ExpPinLenIn[Input] A pointer to valid password length string,
which is an enumeration set from 0 to 12.
Application lists all the valid passwords
and separates them with “,”. For example,
if 4 and 6 digits of passwords are allowed,
then the string should be set to “4, 6”.

Parameters DataIn[Input] When Mode=0x00, DataIn points to the

16-bit primary account number generated
after shifting the card number.
PinBlockOut[Outpu Encrypted PIN block
t] The valid length is 16 bytes.
Mode[Input] Format of PIN block.
0x00 ISO9564 format 0
TimeoutMs[Input] Timeout of inputting PIN.[unit: ms]
The maximum timeout is 300,000ms; the

PAX Computer Technology (Shenzhen) Co., Ltd. 95

 Prolin API Programming Guide

default timout is 30,000 ms; 0 means

using the default timeout.
RET_OK Succeeded.
ERR_DEV_NOT_OPEN Device is not open.
ERR_INVALID_PARAM Invalid parameter.
ERR_SYS_BAD System error.
ERR_PED_KEY_IDX_ERR Key index error.
ERR_PED_KEY_TYPE_ERR Key type error.
ERR_PED_NO_KEY Key doesn’t exist.
Return
ERR_PED_TAMPERED PED is tampered.
ERR_PED_KEY_LEN_ERR Key length error.
ERR_PED_NO_PIN_INPUT No input.
ERR_PED_PIN_INPUT_CANC
Cancel input.
EL
ERR_PED_WAIT_INTERVAL Interval is too short.
Refer to PED Return Code
Others
List.
Call OsPedGetPinBlockSM4() will operate the framebuffer,
which might cause the resource conflict. If there is some kind of
exception on the interface of application which is running XUI,
Instruction
call XuiSuspend() to suspend XUI before calling
OsPedGetPinBlockSM4(), after a while, call XuiResume() to
resume XUI.

6.10 DES FIRE

OsPedDFAuthDiver

int OsPedDFAuthDiver(int SrcKeyIdx,

int KeySetVer,
int DivType,
Prototype uchar Mode,
uchar *Uid,
uchar *EncRndB,
uchar *EncSessionKey);
Check session key B passed from DESFire card, and generate
Function session key A. Merge A and B into a complete session key,
then encrypt and output it.

PAX Computer Technology (Shenzhen) Co., Ltd. 96

 Prolin API Programming Guide

The index of DESFire key, it can be

SrcKeyIdx[Input]
valued from 1 to 100..
Key version, it is used to check the
KeySetVer[Input]
DESFire version.
Key divergent mode:
 When DivType = 0x00, it
represents non-divergent, and
DESFire key will be used to
DivType[Input] encrypt the session key;
 When DivType = 0x01, combine
with Uid to diverge key, the
divergent key will be used to
encrypt the session key.

Parameters Mode[Input] Encryption mode of the session key:

0x02: 3DES encryption of 16 bytes
User data, the data length is fixed to
Uid[Input] 8 bytes. And it is used to diverge the
session key.
The session key B generated by
DESFire card:
 When the length of session key
is 8 or 16 bytes, the length of
EncRndB[Input]
EncRndB is 8 bytes;
 When the length of session key
is 24 bytes, the lenth of
EncRndB is 16 bytes.
EncSessionKey[Output] The encrypted (RndA + RndB’).
RET_OK Succeeded
ERR_DEV_NOT_OPEN PED device is not open.
Return
ERR_INVALID_PARAM Invalid parameter
Others Refer to PED Return Code List

Instruction

OsPedDFAuthMerge

int OsPedDFAuthMerge(uchar *EncRndA,

Prototype
int DataLen);
Check the cipher-text session key A’ passed from DESFire
Function
card.

PAX Computer Technology (Shenzhen) Co., Ltd. 97

 Prolin API Programming Guide

EncRndA[Input] Cipher-text of A’.

The length of EncRndA.
 When the length of session key is
Parameters 8 or 16 bytes, the length of
DataLen[Imput] EncRndA is 8 bytes;
 When the length of session key is
24 bytes, the length of EncRndA
is 16 bytes.
RET_OK Succeeded
ERR_DEV_NOT_OPE
PED device is not open.
Return N
ERR_INVALID_PARAM Invalid parameter
Others Refer to PED Return Code List
Instruction

6.11 RKI

OsPedRkiInjectKey

int OsPedRkiInjectKey(int KeyBlkLen,

Prototype uchar *KeyBlk,
uchar DstKeyIdx);
Function Inject RKI key.
KeyBlkLen [Input] Length of the RKI key
KeyBlk [Input] RKI key data
Parameters
Index of the destination key,
DstKeyIdx [Input] currently, it is meaningless and it can
be an arbitrary value.
RET_OK Succeeded
ERR_DEV_NOT_OPE
PED device is not open.
Return N
ERR_INVALID_PARAM Invalid parameter
Others Refer to PED Return Code List
Instruction

PAX Computer Technology (Shenzhen) Co., Ltd. 98

 Prolin API Programming Guide

7 LCD

Prolin supports Minigui, QT and other GUI support system to manage the display on
LCD. Prolin provides interfaces that can directly access physical device of LCD for
applications to configure light, set contrast and retrieve screen size of LCD.

Prolin’s Framebuffer provides display function. Framebuffer supports XUI, a kind of

GUI that is developed by PAX (please refer to “Prolin XUI Programming Guide”). The
popular GUI, such as Minigui and QT, and other GUIs based on Framebuffer are
supported too. Applications can use XUI graphical interfaces provided by PAX or
develop GUI system.

Details about basic FrameBuffer operations are as follows:

1. Open the FrameBuffer device, the device node is “/dev/fb”;

2. Get the fixed screen information through ioctl;

3. Get the variable screen information through ioctl;

4. Map device memory to the process space through mmap;

5. Write framebuffer.

PAX Computer Technology (Shenzhen) Co., Ltd. 99

 Prolin API Programming Guide

int open_screen(void)
{
char vtname[128];
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);

PAX Computer Technology (Shenzhen) Co., Ltd. 100

 Prolin API Programming Guide

}
memset(sb->buffer, 0, fbmemlen);
return 0;
}

6. 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 Set LCD contrast.
Contrast level. The value range is [0~7].
0: darkest
Parameters Contrast 7: brightest
The default value is 4.
Other values: no action.
Return None.
Instruction OsScrContrast() only applies to monochrome LCD.

7.2 OsScrBrightness

Prototype void OsScrBrightness(int Brightness);

Function Set screen brightness.
Brightness level [0~10].
Parameters Brightness
0: turn off the backlight

PAX Computer Technology (Shenzhen) Co., Ltd. 101

 Prolin API Programming Guide

10: brightest
The default value is 8.
Other values: no action.
Return None.
Instruction The settings will become invalid after exiting the application.

7.3 OsScrGetSize

void OsScrGetSize(int *Width,

Prototype
int *Height);
Function Get the LCD physical screen size.
Width[Output] Width. (unit: pixel)
Parameters Height[Output
Height. (unit: pixel)
]
Return None.
1. The screen size is read-only.
Instruction 2. OsScrGetSize() is only applicable to applications that do
not use GUI.

PAX Computer Technology (Shenzhen) Co., Ltd. 102

 Prolin API Programming Guide

8 Keyboard

Prolin’s keyboard input is managed by GUI.

Definitions of key value

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”
KEYENTER 28 KEY“ENTER”
KEYALPHA 69 KEY“ALPHABET”
KEYF1 59 The first key from left to right

PAX Computer Technology (Shenzhen) Co., Ltd. 103

 Prolin API Programming Guide

at the bottom of S800 LCD.

KEYF2 60
KEYF3 61
KEYF4 62
KEYFUNC 102 Key“Function”
KEYUP 103 The second key from left to
right at the bottom of S800
LCD.
KEYDOWN 108 The third key from left to
right at the bottom of S800
LCD.
KEYPOWER 116 Power key of D200 on the
upper right corner.
KEYMENU 139 The fourth key from left to
right at the bottom of S800
LCD.
KEYCAMERA 212 Independent key of Q90s
Camera.

The input subsystem can directly be used to test keyboard drivers or transplant other
GUI systems. The device node of keyboard is "/dev/keypad".

Details of calling the input subsystem are shown as follows:

#include <stdio.h>
#include <stdlib.h>
#include <fcntl.h>
#include <linux/input.h>
static int keypad_fd = -1;
struct input_event ev0[64];
//for handling/key/event
static int handle_event0() {
int button = 0, realx = 0, realy = 0, i, rd;
rd = read(keypad_fd, ev0, sizeof(struct input_event) * 64);
if ( rd < sizeof(struct input_event) ) return 0;
for (i = 0; i < rd / sizeof(struct input_event); i++) {
printf("", ev0[i].type, ev0[i].code, ev0[i].value);
if (ev0[i].type == 3 && ev0[i].code == 0)
realx = ev0[i].value;

PAX Computer Technology (Shenzhen) Co., Ltd. 104

 Prolin API Programming Guide

else if (ev0[i].type == 3 && ev0[i].code == 1)

realy = ev0[i].value;
else if (ev0[i].type == 1) {
if (ev0[i].code == 158) {
//if key esc then exit
return 0;
}
}
else if (ev0[i].type == 0 && ev0[i].code == 0 && ev0[i].value == 0) {
realx = 0, realy = 0;
}
printf("event(%d): type: %d; code: %3d; value: %3d; realx: %3d;
realy: %3d\n", i,
ev0[i].type, ev0[i].code, ev0[i].value, realx, realy);
}
return 1;
}

int main(void) {
int done = 1;
printf("sizeof(struct input_event) = %d\n", sizeof(struct input_event));
keypad_fd = open("/dev/keypad", O_RDWR);
if ( keypad_fd < 0 )
return -1;
while ( done ) {
printf("begin handel_event0...\n");
done = handle_event0();
printf("end handel_event0...\n");
}
if ( keypad_fd > 0 ) {
close(keypad_fd);
keypad_fd = -1;
}
return 0;
}

8.1 OsKbBacklight

Prototype void OsKbBacklight(int OnOff);

PAX Computer Technology (Shenzhen) Co., Ltd. 105

 Prolin API Programming Guide

Function Switch on/off the keyboard backlight.

0: Turn off the backlight.
Parameters OnOff
Non-zero: Turn on the backlight.
Return None.
When the application exits, the setting will be resumed to the
Instruction state before the application is started.

PAX Computer Technology (Shenzhen) Co., Ltd. 106

 Prolin API Programming Guide

9 Touch Screen

Prolin’s touch screen input is managed by GUI.

Application developers can directly use the input subsystem to test touchscreen
drivers or transplant other GUI systems.

About input subsystem calling, please refer to Chapter 8 Keyboard. The node of touch
screen is “/dev/tp”.

PAX Computer Technology (Shenzhen) Co., Ltd. 107

 Prolin API Programming Guide

10Signature Pad

For more details, please refer to the “Prolin XUI Programming Guide”.

PAX Computer Technology (Shenzhen) Co., Ltd. 108

 Prolin API Programming Guide

11Printer

Prolin supports both physical printing and virtual printing, and provides developers
with uniform printing interfaces.

Physical printer supports POSIX interface of Linux.

Virtual printer generates BMP images and saves the printing result in local disk space.

11.1 Return Code List

Table 11.1 Printer return code list

Macro Value Description

ERR_PRN_BUSY -3701 Printer is busy.
ERR_PRN_PAPEROUT -3702 Out of paper.
ERR_PRN_WRONG_PACKA Data package format
-3703
GE error.
ERR_PRN_OVERHEAT -3704 Printer is overheated.
The print data is too
ERR_PRN_OUTOFMEMORY -3705 large and exceeds the
buffer length.
ERR_PRN_OVERVOLTAGE -3706 Voltage is too high.

PAX Computer Technology (Shenzhen) Co., Ltd. 109

 Prolin API Programming Guide

11.2 Open and Close

This part includes three functions: opening, resetting and closing printer.

OsPrnOpen

int OsPrnOpen(unsigned int printertype,

Prototype
const char*targetname );
Function Open a printer device, including physical or virtual printer.
Printer Types:
 PRN_REAL: Physical printer.
printertype[Input]  PRN_BMP: Virtual printer, the printing
result is saved in bmp format in local
position.
Parameters
For physical printer, targetname must be
NULL;
targetname[Input] For virtual printer, targetname points to the
local bmp file. If the specified file has
already existed, overwrite it.
RET_OK Succeeded.
ERR_DEV_NOT_EXIST Device does not exist.
ERR_INVALID_PARAM Invalid parameter.
Return ERR_DEV_BUSY Device is busy.
ERR_BATTERY_ABSENT Battery is absent.
ERR_BATTERY_VOLTAG
Battery voltage is too low.
E_TOO_LOW
1. OsPrnOpen() must be called successfully to open printer
device; otherwise, other related functions of printer will fail to
work.
2. S920 mobile terminal must be powered by battery;
Instruction
otherwise, printer cannot work and returns
ERR_BATTERY_ABSENT.
3. When the battery level is 0, the module cannot work and
returns ERR_BATTERY_VOLTAGE_TOO_LOW.

OsPrnReset

Prototype void OsPrnReset(void);

Function Reset printer parameters and clear printing buffer.
Parameters None.

PAX Computer Technology (Shenzhen) Co., Ltd. 110

 Prolin API Programming Guide

Return None.
Instruction

Font library settings will be restored to default font status (only

support English).

OsPrnClose

Prototype void OsPrnClose(void);

Function Close printer.
Parameters None.
Return None.
Instruction Call OsPrnClose() to close printer device when program exits.

11.3 Printer Settings

OsPrnSetSize

int OsPrnSetSize(unsigned int Width,

Prototype
unsigned int Height);
Function Set parameters for virtual printer.
Width[Input] Width
Parameters
Height[Input] Height
RET_OK Succeeded.
Return ERR_INVALID_PAR Invalid parameter.
AM
1. OsPrnSetSize() is only applicable to virtual printer.
2. The default size is 384×5000 and the maximum size is 600
Instruction ×5000.(unit: dot)
3. Only the first calling of this function is valid and the settings
will remain unchanged even it is called again later.

OsPrnSetDirection

Prototype int OsPrnSetDirection(unsigned char Mode);

PAX Computer Technology (Shenzhen) Co., Ltd. 111

 Prolin API Programming Guide

Function Set printing direction.

Mode [Input] 0: print horizontally.
Parameters
1: print vertically.
RET_OK Succeeded.
Return
ERR_INVALID_PARAM Invalid parameter.
Instruction This function applies to both physical printer and virtual printer.

OsPrnSetGray

Prototype void OsPrnSetGray(int Level);

Function Set printing gray level.
Level  Level =0: reserved.
 Level =1: normal printing; default level.
 Level =2: reserved.
 Level =3: two-layer thermal printing.
Parameters  Level =4: two-layer thermal printing, higher
gray level than 3.
 The default level is 1.
 Invalid parameter won’t change current
settings.
Return None.
Instruction This function just applies to physical printer.

11.4 Type Setting

OsPrnSetSpace

void OsPrnSetSpace(int CharSpace,

Prototype
int LineSpace);
Function Set printing space.
Character space. (unit: pixel)
CharSpace (It is invalid to the mandatory non-monospaced
Parameters fonts, such as Arabic fonts, Thai fonts.)
LineSpace Line space. (unit: pixel)
Return None.

Instruction 1. After a successful call of this function, the settings will

remain valid until OsPrnSetSpace() is called again or

PAX Computer Technology (Shenzhen) Co., Ltd. 112

 Prolin API Programming Guide

OsPrnReset( ) is called.
2. The default character space is 0 pixel.
3. The default line space for thermal printer and stylus printer
is 0 pixel and 2 pixels, respectively.
4. The maximum line space is 255 pixels.
5. The maximum character space is 255 pixels.
6. Invalid parameter will not change current settings.

OsPrnSetReversal

Prototype int void OsPrnSetReversal(int Attr);

Set reverse attribute of font. The default setting is to print
Function normally.
Attr 0: normal printing.
Parameters
1: reversal printing
Return None.
1. This function applies to both physical printer and virtual
Instruction printer.
2. The reverse attribute doesn’t work for printing images.

OsPrnSetIndent

int OsPrnSetIndent(unsigned int Left,

Prototype
unsigned int Right);
Function Set left and right margins.
Left margin.
Left[Input] The valid range is from 0 to 100 and default
value is 0.
Parameters
Right margin.
Right[Input] The valid range is from 0 to 100 and default
value is 0.
RET_OK Succeeded.
Return
ERR_INVALID_PARAM Invalid parameter.
If physical printer is set to print vertically, left margin
corresponds to the top page margin, while right margin
Instruction corresponds to the bottom page margin.

OsPrnCheck

Prototype int OsPrnCheck(void);

PAX Computer Technology (Shenzhen) Co., Ltd. 113

 Prolin API Programming Guide

Check the current status of printer. It only applies to physical

Function printer.
Parameters None.
RET_OK Succeeded.
ERR_PRN_BUSY Printer is busy.

Return ERR_PRN_PAPERO
Out of paper.
UT
ERR_PRN_OVERHE
Printer is overheated.
AT
Instruction

OsPrnGetDotLine

Prototype int OsPrnGetDotLine(void);

Function Get the number of printed dot lines.
Parameters None.
Return >=0 The number of printed dot lines.
Used for slip alignment (seldom used).
Instruction
This function applies to both physical printer and virtual printer.

OsPrnSetFont

Prototype int OsPrnSetFont(const char *fontname);

Function Select font.
Parameters fontname[Input] Font (file) name.
RET_OK Succeeded.
ERR_FONT_NOT_E
Font does not exist.
Return XIST
ERR_INVALID_PAR
Invalid parameter.
AM
1. This function is used to choose different font styles and
sizes for printing.
Instruction
2. The built-in font (file) name can be obtained by calling
OsEnumFont().

OsPrnSelectFontSize

Prototype void OsPrnSelectFontSize(int SingleCodeWidth,

PAX Computer Technology (Shenzhen) Co., Ltd. 114

 Prolin API Programming Guide

int SingleCodeHeight,
int MultiCodeWidth,
int MultiCodeHeight);
Function Set font size.
Width control of single code font. (For
SingleCodeWi non-monospaced font, the real width of each
dth character may not meet the setting).
The value ranges from 8 to 64.
SingleCodeHei Height control of single code font.
Parameters ght The value ranges from 8 to 64.
MultiCodeWidt Width control of multiple code font.
h The value ranges from 12 to 64.
MultiCodeHeig Height control of multiple code font.
ht The value ranges from 12 to 64.
Return None.
1. After the first calling of OsPrnOpen(), the font width and
height are both set to the default values, for single-code, it is
Instruction (12×24) , for multi-code, it is (24×24).
2. This function applies to both physical printer and virtual
printer.

For signle-code font, it is recommended the width should be half

of the height. For multi-code font, The height and width should be
the same, otherwise, font may be displayed abnormally.

OsPrnFeed

Prototype void OsPrnFeed(int Pixel);

Function Feed printing paper for some number of pixels in print buffer.
Number of pixels
>0: feed paper.
Parameters Pixel
<0: unreeling.
=0: no action.
Return None.
Instruction 1. This function applies to both physical and virtual printer.

PAX Computer Technology (Shenzhen) Co., Ltd. 115

 Prolin API Programming Guide

This is a one-time action which will become invalid once

implemented.

OsPrnPrintf

Prototype void OsPrnPrintf(const char *Str, ...);

Function Format and output string to print buffer.
Parameters Str[Input] A pointer to string that needs to be printed.
Return None.
1. Support variable-length parameters.
2. Support ‘\n’ (new line) and ‘\f’ (form feed) control characters
in the string.
3. If the package of printing data is too long, the program will
overflow.
Instruction 4. If printing string is beyond print range, it will automatically
change line and continue printing.
5. The maximum buffer size is 2048 bytes.
6. This function is used to store str in printing buffer. After
calling OsPrnStart(), data will be printed in the same
sequence as it is written into the buffer.

OsPrnPutImage

Prototype void OsPrnPutImage(const unsigned char *Logo);

Function Output image to print buffer.
Logo[Input] A pointer to logo information;
Parameters
The valid length is not more than 20,000 bytes.
Return None.
Steps of generating bitmap data are as follows:
1. Draw a logo: use paintbrush program under Windows to
draw a bitmap, and save the bitmap drawn at the previous
step as a “monochromatic, bmp format” file.
Instruction 2. Use “Bitmap Converter” provided by PAX to convert the
bmp file into a header file, for instance, Logo.h. (After
conversion, the number of arrays in the head file will be
same as the number of selected .bmp files. The definition of
array name is related to BMP filename.)

PAX Computer Technology (Shenzhen) Co., Ltd. 116

 Prolin API Programming Guide

Printing bitmap size limit: For thermal printer, up to 384 pixels in

width are allowed; for stylus printer, 180 pixels are allowed. The
height is unlimited.
The generated array can be directly used as the input parameter
of this function.
If the bitmap width is larger than the limit of printer, the redundant
data on the right will be removed.
If the size of data packet is too large, the redundant LOGO
message will be removed.

Format description of image array in header file:

First byte [1 byte]: row numbers of the bitmap;
Byte size of the first bitmap line [2 Bytes, MSB ahead (most
significant byte)];
Bitmap data of the first bitmap line;
Byte size of the second bitmap line [2 Bytes, MSB ahead];
Bitmap data of the second bitmap line;
So on and so forth.
This function only stores logo into printing buffer. After calling
OsPrnStart (), the system begins to print data in printing buffer in
the same sequence as they are written into the buffer.

OsPrnStart

Prototype int OsPrnStart(void);

Function Start printing the data in the buffer.
Parameters None.
RET_OK Succeeded.
ERR_PRN_BUSY Printer is busy.
ERR_PRN_PAPEROU
Out of paper.
T

Return ERR_PRN_WRONG_
Data package format error.
PACKAGE
ERR_PRN_OVERHEA
Printer is overheated.
T
ERR_PRN_OUTOFME
Data size is too large.
MORY

PAX Computer Technology (Shenzhen) Co., Ltd. 117

 Prolin API Programming Guide

1. OsPrnStart() will begin printing task and will not return until
the task is completed.
2. After completing printing task, OsPrnStart() will return the
printer status in return value. Therefore, it is not necessary to
check printer status.
3. After the printing task is finished, slip will be reprinted if this
function is called again.
Instruction 4. After setting parameter persist.sys.continue.print in the
registry to enable the function of continuing to print after a
shutdown, if event like lacking paper or the printer is
overheated occurs during the printing process,after adding
some more paper or waiting for the machine to cool down,
call this function again will continue the printing from where it
left off. But it doesn’t support continue to print after the
terminal has been rebooted.

OsPrnClrBuf

Prototype void OsPrnClrBuf(void);

Function Clear print buffer.

Parameters None
Return None
Instruction

OsPrnSetParam

Prototype int OsPrnSetParam(unsigned int cmd);

Function Set whethere to pre-feed printing paper.
1: No pre-feeding printing paper
Parameters cmd [Input]
2: Pre-feeding printing paper
RET_OK Succeeded

Return ERR_INVALID_PARA
Invalid parameter
M
1. This setting only affect the pre-feeding printing paper
Instruction function, and pre-feeding is enabled by default.
2. This function only applies to thermal printer.

11.5 POSIX

Prolin physical printer driver provides application developers with POSIX interface.

PAX Computer Technology (Shenzhen) Co., Ltd. 118

 Prolin API Programming Guide

Open

Open physical printer.

The device name is “/dev/printer”.

int handle = open(“/dev/printer”, O_RDWR).

Read

Read printer status.

The first byte of Read buffer is buf[0]. The format is:

buf[0] Description

0x00 Normal

0x01 Printer is busy.

0x02 Out of paper.
0x03 Printer is overheated.
0x04~0xFF Reserved.

Sample code:
unsigned char buf[10];
int ret = read(handle, buf, 2);
if (ret > 0) {
//buf[0]
}

Write

Configure printer and start printing buffer.

The first two bytes of buffer are gray setting and reserved bit.Suppose that the buffer
is char buf[50], bit0~bit2 in the buf[0] represent the printing gray control values.
bit3~bit7 are reserved.

bit0~2 in buf[0] Description

000 Reserved

PAX Computer Technology (Shenzhen) Co., Ltd. 119

 Prolin API Programming Guide

001 Default gray level

010 Reserved
011 Two-layer thermal printing A
100 Two-layer thermal printing B
101 Reserved
110 Reserved
111 Reserved

The second byte buf[1]: reserved.

From buf[2] on, every line is composed of 48 characters (384 dots), if less than 48
characters, the driver will be padded with 0x00.
Sample code:
unsigned char buf[50];

buf[0] = 0x01;
memset(buf + 2, 0xff, 48);

int ret = write(handle, buf, 50);

if (ret < 0) {
/*Error handling……*/
}

The maximum data length is described as below:

1. For 384 dots thermal printer, when printing horizontally, the driver can deal with
5000 dot lines each time at most; otherwise, the printer will not work.

2. When printing vertically, the driver can deal with 384 lines each time at most, and
each line can print 5000 dots at most; otherwise, the printer will not work.

3. The maximum length of a write buffer should be 384×5000/8 + 2 = 240,002 bytes.

Close

Close file handles of printer.

close (handle);

PAX Computer Technology (Shenzhen) Co., Ltd. 120

 Prolin API Programming Guide

12Font Library

Prolin uses Freetype as the system font library. Therefore, the system supports a
series of vector font and bitmap font.

12.1 Data Structure

FT_FONT font tructure:

FT_FONT
typedef struct {
char FileName[64]; /* Font file name */
char FontName[64]; /* Font name */
}FT_FONT;

FT_DOT matrix structure:

FT_DOT
typedef struct {
unsigned char Left; /*Left base-line shift*/
unsigned char Top; /* Top base-line shift*/
unsigned char Width; /* Font width */
unsigned char Height; /* Font height */
unsigned char Dot[3072]; /*Valid font data */

PAX Computer Technology (Shenzhen) Co., Ltd. 121

 Prolin API Programming Guide

}FT_DOT;

12.2 Font Operation

OsEnumFont

Prototype int OsEnumFont(FT_FONT **FontList);

Function Get the vector font list fron FreeType library.
FontList[Outpu Vector font list of FT_FONT structure.
Parameters t]

>=0 The number of vector fonts.

ERR_INVALID_PAR
Invalid parameter.
Return AM
ERR_FONT_NOT_E
Font library does not exist.
XIST
Example:
int i, num;
FT_FONT *FontList;
num = OsEnumFont(&FontList);
if(num <= 0)
Instruction
return -1;
for(i=0; i<num; i++)
printf("[%d]file name: %s, font name : %s\n",
i, FontList[i].FileName,
FontList[i].FontName);

OsOpenFont

Prototype int OsOpenFont( const char *FileName);

Function Load vector fonts.
FileName[Inpu Font file name.
Parameters t]

>=0 Font handle

ERR_INVALID_PARA
Invalid parameter.
Return M
ERR_FONT_NOT_EXI
Font library does not exist.
ST
Instruction Dot-matrix data needs to be cached after the fonts were

PAX Computer Technology (Shenzhen) Co., Ltd. 122

 Prolin API Programming Guide

opened. It is recommended to wait 3 seconds before calling

OsGetFontDot().

OsCloseFont

Prototype void OsCloseFont( int Handle);

Function Close vector fonts.
Parameters Handle[Input] Font handle
Return None.
After using vector fonts, please close it to release the system
Instruction resources.

OsGetFontDot

int OsGetFontDot( int Handle,

const char *Utf8Code,
const int Width,
Prototype
const int Height,
const int Style,
FT_DOT *FtDot);
Get the type matrix which conforms to UTF-8 encoding
Function
standards.
Handle [Input] Font handle
Character which conforms to UTF-8
Utf8Code [Input]
encoding standards
Font width.
Width [Input]
The value range is from 8 to 128.
Font height.
Height [Input]
Parameters The value range is from 8 to 128.
Font styles:
FONT_STYLE_NON 0 No
E style
Style [Input] FONT_STYLE_BOL 0x000000 Bold
D 01
FONT_STYLE_ITAL 0x000000 italic
IC 02

PAX Computer Technology (Shenzhen) Co., Ltd. 123

 Prolin API Programming Guide

“|” can be used to combine different font

styles together when several styles are
needed, for example,
FONT_STYLE_BOLD |
FONT_STYLE_ITALIC means bold and
italic font.
FtDot [Output] Output FT_DOT structure.
RET_OK Succeeded.
ERR_INVALID_PARAM Invalid parameter.
Return ERR_FILE_NOT_EXIST File does not exist.
ERR_FONT_CODE Font code error.
ERR_INVALID_HANDLE Invalid handle
Utf8Code input:
1. UTF-8 code is of variable-length and shall end with “\0”;
2. When the code is composed of letters, Utf8Code requires
two bytes in which Utf8Code[0] represents letter and
Utf8Code[1] represents “\ 0”;
3. When the code is composed of Chinese, Utf8Code requires
four bytes in which Utf8Code[0-2] represents Chinese and
Utf8Code[3] represents “\ 0”.
The italic style dot matrix:
1. Please pay special attention to the layout in type setting as
the obtained dot matrix width may be wider than the set
value when using italics effect.
Instruction 2. Dot matrix size is not recommended to be less than 24;
otherwise, the dot matrix may fail to be displayed in italic
effect. For example, when Song typeface dot matrix is less
than 19 and Black dot matrix is less than 21, italic effect
cannot be applied to all the Chinese characters, but it is
available for English letters.
Font data format:
1. All the font dot matrixes are arranged in horizontal mode;
2. A byte contains all dots of a row. The MSB (0x80) and LSB
(0x01) of the byte correspond the most left and most right
dot, respectively;
3. If the character width is not an integer multiple of 8, each
line of dot matrix is (width+7)/8 bytes.
For example: For the character “>”, with 10(width)x20(height)

PAX Computer Technology (Shenzhen) Co., Ltd. 124

 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,
0x20, 0x00,
0x00, 0x00
The following characters will be returned:
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. 125

 Prolin API Programming Guide

13Code

Prolin uses UTF-8 as the default code and provides interfaces to converse code.

13.1 Code Conversion

OsCodeConvert

int OsCodeConvert (const char *FromCharset,

const char *ToCharset,
Prototype const char *InBuf,
char *OutBuf,
unsigned int LenOut);
Function Convert character encoding.
FromCharset[Inp
Original character encoding
ut]
ToCharset[Input] Target character encoding
Original encoding string, ending with“\0”.
InBuf [Input]
Parameters “Unicode” should end with“\0\0’’.
Target encoding string that has been
OutBuf [Output]
converted.
Size of OutBuf array.
LenOut [Input]
It should be at least 1.5 times of the InBuf

PAX Computer Technology (Shenzhen) Co., Ltd. 126

 Prolin API Programming Guide

array.
Conversion succeeded. Return the
>=0
Return length of converted string.
ERR_INVALID_PARAM Invalid parameter
The system 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,1
258)
GBK/GB18030(2 bytes part)
BIG5
SHIFT_JIS
Instruction EUC-KR
UNICODE
UTF-8
Notes:
1. The above codes are only suggested to convert with UTF-8
code, conversions between other codes might fail.
2. UNICODE uses the Little-Endian mode.

PAX Computer Technology (Shenzhen) Co., Ltd. 127

 Prolin API Programming Guide

14MSR

Prolin provides interfaces to read data from MSR. Additionally, the customized MSR
decoding logic can be implemented by application which can access the driver of card
reader and directly get the bit-stream of magnetic stripe through POSIX interface.

14.1 Return Code List

Table 14.1MSR return code list

Macro Valu Description

e
ERR_MSR_FAILED -2701 Fail to operate MSR.
ERR_MSR_HEADERR -2702 Head mark is not found.
ERR_MSR_ENDERR -2703 End mark is not found.
ERR_MSR_LRCERR -2704 LRC check error.
ERR_MSR_PARERR -2705 Check error of a certain bit of MSR.
ERR_MSR_NOT_SWIPED -2706 No card is swiped.
ERR_MSR_NO_DATA -2707 No data in Mag card.
ERR_MSR_END_ZEROERR -2708 Magnetic stripe card format error.
ERR_MSR_PED_DECRYPT
-2709 PED decryption failed.
ERR
ERR_MSR_NO_TRACK_ER -2710 The corresponding magnetic track in

PAX Computer Technology (Shenzhen) Co., Ltd. 128

 Prolin API Programming Guide

R the magnetic card has not been

detected.

14.2 Data Structure

MSR data structure: Record information and status of each magnetic track.

ST_MSR_DATA:
typedef struct {
unsigned char TrackData[256]; /* Decoded bit stream*/
int DataLen; /* Track data length*/
int Status; /*Track data status, 0 means succeeded, other value means
failed*/
}ST_MSR_DATA;

When track data status is 0, it means reading track data

successfully, pay attention to the following two situations:
1. If data format is correct or there is no data in track, judge
according to the valid data length DataLen ;
2. If OsMsrRead() isn’t called to read track data within 30
seconds after swiping card successfully, the data will be
cleared automatically.

14.3 MSR Control Interface

OsMsrOpen

Prototype int OsMsrOpen(void);

Function Open magnetic stripe reader.
Parameters None.
RET_OK Succeeded.
ERR_DEV_NOT_E
Device does not exist.
XIST
Return
ERR_DEV_BUSY Device is busy.
ERR_DEV_NOT_O
Fail to open device.
PEN
Instruction OsMsrOpen() shall be called to open the device; otherwise, the

PAX Computer Technology (Shenzhen) Co., Ltd. 129

 Prolin API Programming Guide

related functions will not work.

Magnetic stripe reader works in interrupt mode. Once the

magnetic stripe reader is opened, it can read the magnetic track
data as long as card is swiped even if no function is called to
read card. So it is better to close magnetic stripe reader when it
is not in use.

OsMsrClose

Prototype void OsMsrClose(void);

Function Close magnetic stripe reader.
Parameters None.
Return None.
OsMsrClose() must be called to close device when program
Instruction exits.

OsMsrReset

Prototype void OsMsrReset(void);

Soft reset magnetic stripe reader and clear the obtained
Function magnetic card data.
Parameters None.
Return None.
Instruction

OsMsrSwiped

Prototype int OsMsrSwiped(void);

Function Detect a swiping action.
Parameters None.
TRUE Swiped.
FALSE No swiping.
Return
ERR_DEV_NOT_OPE
Device is not open.
N
Instruction 1. OsMsrSwiped() will return immediately no matter whether

PAX Computer Technology (Shenzhen) Co., Ltd. 130

 Prolin API Programming Guide

there is a card-swiping action or not.

2. OsMsrOpen(), OsMsrRead() or OsMsrReset() can clear the
swiped status of magnetic card.

OsMsrRead

int OsMsrRead(ST_MSR_DATA *Track1,

Prototype ST_MSR_DATA *Track2,
ST_MSR_DATA *Track3);
Function Read MSR data.
Track1[Output] Output Track1 data
Parameters Track2[Output] Output Track2 data
Track3[Output] Output Track3 data
RET_OK Succeeded.
ERR_MSR_NOT_SWIP
No card is swiped.
Return ED
ERR_INVALID_PARAM Invalid parameter.
ERR_DEV_NOT_OPEN Device is not open.
1. If any track’s data is not needed, set the corresponding pointer
to NULL, then the data will not be outputted.
Instruction 2. All track data must be read out within 30 seconds after swiping
card successfully; otherwise, all track data will be cleared
automatically and output data are all 0x00.

OsMsrReadJIS

int OsMsrReadJIS(ST_MSR_DATA *Track1,

ST_MSR_DATA *Track2,
Prototype
ST_MSR_DATA *Track3，
ST_MSR_DATA *Track4);
Read the MSR data of general single side magnetic stripe card or
Function
double side magnetic stripe card decoded with JIS.
Track1[Output] Output Track1 data
Track2[Output] Output Track2 data
Parameters
Track3[Output] Output Track3 data
Track4[Output] Output Track4 data
RET_OK Succeeded.
Return
ERR_MSR_NOT_SWIP No card is swiped.

PAX Computer Technology (Shenzhen) Co., Ltd. 131

 Prolin API Programming Guide

ED
ERR_INVALID_PARAM Invalid parameter.
ERR_DEV_NOT_OPEN Device is not open.
1. If any track’s data is not needed, set the corresponding pointer
to NULL, then the data will not be outputted.
2. All track data must be read out within 30 seconds after swiping
card successfully; otherwise, all track data will be cleared
automatically and output data are all 0x00.
Instruction
3. Track 4 is used to store the JCB (JIS II) data, and track 1-3 is
used to store the data in other formats.
4. If the magnetic head of one side has not detected any tracks,
ERR_MSR_NO_TRACK_ERR will be returned to the Status of
the corresponding Track.

Call OsMsrSwiped() first to make sure there is a card swiping

action before calling OsMsrRead() to obtain the data of magnetic
track. Otherwise, when the function returns, the data in the buffer
is invalid.

When reading magnetic card conforming to ISO7812 standard:

The length of Track1 is 79 bytes.
The length of Track2 is 37 bytes.

The length of Track3 is 107 bytes.

PAX Computer Technology (Shenzhen) Co., Ltd. 132

 Prolin API Programming Guide

15IC Card Reader

In this chapter, all protocol interfaces for IC card are based on ISO7816/EMV.

15.1 Return Code List

Table 15.1 IC Card reader return code list

Macro Value Description

ERR_SCI_HW_NOCAR
-2800 No card.
D
No initialization when
ERR_SCI_HW_STEP -2801 exchanging data; no power
when warm reseting.
ERR_SCI_HW_PARITY -2802 Parity check error.
ERR_SCI_HW_TIMEO
-2803 Timeout.
UT
ERR_SCI_TCK -2804 TCK error.
ERR_SCI_ATR_TS -2810 ATR TS error.
ERR_SCI_ATR_TA1 -2811 ATR TA1 error.
ERR_SCI_ATR_TD1 -2812 ATR TD1 error.
ERR_SCI_ATR_TA2 -2813 ATR TA2 error.
ERR_SCI_ATR_TB1 -2814 ATR TB1 error.

PAX Computer Technology (Shenzhen) Co., Ltd. 133

 Prolin API Programming Guide

ERR_SCI_ATR_TB2 -2815 ATR TB2 error.

ERR_SCI_ATR_TC2 -2816 ATR TC2 error.
ERR_SCI_ATR_TD2 -2817 ATR TD2 error.
ERR_SCI_ATR_TA3 -2818 ATR TA3 error.
ERR_SCI_ATR_TB3 -2819 ATR TB3 error.
ERR_SCI_ATR_TC3 -2820 ATR TC3 error.
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 ATRPCK error in PPS.
Transmitted data is too long in
ERR_SCI_T0_PARAM -2840
T0.
Too many character repetitions
ERR_SCI_T0_REPEAT -2841
in T0.
ERR_SCI_T0_PROB -2842 Procedure byte error in T0.
Transmitteddata is too long in
ERR_SCI_T1_PARAM -2850
T1.
ERR_SCI_T1_BWT -2851 BWT is oversize in T1.
ERR_SCI_T1_CWT -2852 CWT is oversize in T1.
Too many block repetitions in
ERR_SCI_T1_BREP -2853
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 Invalid parameter.

15.2 Data Structure

APDU Request Structure

ST_ APDU_REQ

PAX Computer Technology (Shenzhen) Co., Ltd. 134

 Prolin API Programming Guide

typedef struct
{
Unsigned char Cmd[4]; /*CLA, INS, P1, P2*/
int LC; /* The valid length of DataIn sent to IC card */
unsigned char DataIn[512];/* The data sent to ICC */
int LE; /* The expected length of returned data*/
}ST_ APDU_REQ;

ST_APDU_REQ structure:

1. LE is the expected length of returned data. The actual length

is related to specific command. LE is only an expected length
and the actual length can be obtained by LenOut in
ST_APDU_RSP response structure.

2. LE and LC can be used in combination:

 LC=0, LE=0. No data is sent or returned.

 LC=0, LE>0.No data is sent, but returned expected data.

If the expected data length is unknown, set LE to 256;
otherwise, it will be a constant.

 LC>0, LE=0. Send data, but no expected data is

returned.

 LC>0, LE>0. Send data and returned expected data. If

expected data length is unknown, set LE to 256;
otherwise, it will be a constant.

APDU Response Structure

ST_ APDU_RSP:
typedef struct
{
Int LenOut; /* Data length returned from ICC*/
unsigned char DataOut[512]; /*Data pointer returned from ICC */
unsigned char SWA; /*status word 1 of ICC */

PAX Computer Technology (Shenzhen) Co., Ltd. 135

 Prolin API Programming Guide

unsigned char SWB; /* status word 2 of ICC */

}ST_ APDU_RSP;

15.3 Encapsulated Interfaces

OslccOpen

Prototype int OsIccOpen(int Slot);

Function Open IC card reader.
Parameters IC card channel number:
 ICC_USER_SLOT User
card
 ICC_SAM1_SLOT SAM
card slot 1
Slot  ICC_SAM2_SLOT SAM
card slot 2
 ICC_SAM3_SLOT SAM
card slot 3
 ICC_SAM4_SLOT SAM
card slot 4
Return RET_OK Succeeded.
ERR_DEV_NOT_EXI
Device does not exist.
ST
ERR_DEV_BUSY Device is busy.
Instruction

1. Other functions can be used only after successfully opening

IC card device.

2. Slot number and type may be different for different models,

please refer to manual or consult professional staff for
specific slot number.

OsIccDetect

Prototype int OsIccDetect(int Slot);

PAX Computer Technology (Shenzhen) Co., Ltd. 136

 Prolin API Programming Guide

Function Test whether there is a card in specified slot.

Parameters IC card channel number:
 ICC_USER_SLOT User
card
 ICC_SAM1_SLOT SAM
card slot 1
Slot  ICC_SAM2_SLOT SAM
card slot 2
 ICC_SAM3_SLOT SAM
card slot 3
 ICC_SAM4_SLOT SAM
card slot 4
Return RET_OK Card is inserted.
Please refer to IC Card Return Code
Others
List.
Instruction 1. OsIccDetect () will return immediately no matter whether
there is a card in slot or not.
2. For USER_SLOT, if card is inserted or pulled out, system
will send SIGICC message to application to open the
device. This mechanism doesn’t apply to SAM card.

This interface will power off the SAM card. Please ensure this
interface is called before resetting SAM card.

OsIccInit

Prototype int OsIccInit(int Slot,

unsigned long Option,
unsigned char *Atr);
Function Initialize IC card device.
Parameters IC card channel number:
 ICC_USER_SLOT User
card
Slot  ICC_SAM1_SLOT SAM
card slot 1
 ICC_SAM2_SLOT SAM
card slot 2
 ICC_SAM3_SLOT SAM

PAX Computer Technology (Shenzhen) Co., Ltd. 137

 Prolin API Programming Guide

card slot 3
 ICC_SAM4_SLOT SAM
card slot 4.
(Bit 0~1) Card voltage options:
00 - 5V, 01 - 1.8V,
10 - 3V
(Bit 2)Support PPS protocol:
0 – Unsupported;
1 – Supported.
(Bit 3~4)Rate used in power-onreset:
00 – Standard rate 9600;
10 – Four times rate 38400.
The rate mentioned here is a
reference value in typical frequency
(3.57MHz).
Option The communication rate between IC
card and card reader is closely related
to working clock frequency provided by
a specific machine.
(Bit 5) Supported standards:
0 – EMV;
1 - ISO7816.
If EMV mode is specified, the power
on rate will be marked as invalid and it
will use the standard rate by default.
(Bit 6 ~31)Reserved
“Option” is set to 0 by default (that is,
5V, non-PPS, standard rate, and
conforming to EMVx).
1. Answer To Reset (ATR). The card
will return response data of 34
Atr [Output] bytes at most.
2. Contents: Length of ATR (1 byte)
and ATR.
Return RET_OK Succeeded.
Please refer to IC Card Return Code
Others
List.
Instruction 1. ATR output buffer should be allocated at least 34 bytes.
2. Whether PPS communication parameters negotiation
protocol is supported or not depends on the specific card.
3. Some terminals can only work with one SAM card at a time.
If several cards need to be operated at the same time,

PAX Computer Technology (Shenzhen) Co., Ltd. 138

 Prolin API Programming Guide

initialize cards one by one: (OsIccInit ( )) - > operation

(OsIccExchange()) - > close (OsIccClose( )).

Most SAM cards only support ISO7816, so the “Option” should

be set to 0x20 instead of 0x00.

OsIccExchange

Prototype int OsIccExchange(int Slot,

int CtrlFlag,
constST_APDU_REQ *ApduReq,
ST_APDU_RSP *ApduRsp);
Function Interact with IC card using commands.
Parameters IC card channel number:
 ICC_USER_SLOT User
card
 ICC_SAM1_SLOT SAM
card slot 1
Slot  ICC_SAM2_SLOT SAM
card slot 2
 ICC_SAM3_SLOT SAM
card slot 3
 ICC_SAM4_SLOT SAM
card slot 4
1. Bit0: Whether to send "GET
RESPONSE" command
automatically under T=0 protocol.
CtrlFlag 1 Yes
0 No
2. Bit1~Bit31: Reserved
A pointer to APDU request structure
ApduReq [Input] ST_APDU_REQ : terminal request
message.
A pointer to APDU response structure
ApduRsp [Output] ST_APDU_RSP :card response
message.
Return RET_OK Succeeded.
Others Please refer to IC Card Return Code

PAX Computer Technology (Shenzhen) Co., Ltd. 139

 Prolin API Programming Guide

List.
Instruction

OsIccClose

Prototype int OsIccClose(int Slot);

Function Close IC card device.
Parameters IC card channel number:
 ICC_USER_SLOT User
card
 ICC_SAM1_SLOT SAM
card slot 1
Slot  ICC_SAM2_SLOT SAM
card slot 2
 ICC_SAM3_SLOT SAM
card slot 3
 ICC_SAM4_SLOT SAM
card slot 4
Return RET_OK Succeeded.
Please refer to IC Card Return Code
Others
List.
Instruction

PAX Computer Technology (Shenzhen) Co., Ltd. 140

 Prolin API Programming Guide

16RF Reader

This chapter mainly describes application programming interface of RF reader, which

is conforming to the ISO14443 and “EMV Contactless Book D V2.1” regulation.

16.1 Return Code List

Table 16.1 Return code list

Macro Value Description

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 Multiple cards collision.
PCD_ERR_ECD_FLAG -2905 Frame format error.
PCD_ERR_EMD_FLAG -2906 Interference.
Chip error, fail to
PCD_ERR_COM_FLAG -2907
communicate correctly.
PCD_ERR_AUT_FLAG -2908 M1 authentication error.
PCD_ERR_TRANSMIT_FLAG -2909 Transmission error.
PCD_ERR_PROTOCOL_FLAG -2910 Protocol error.
PCD_ERR_PARAMFILE_FLAG -2911 Configuration file does

PAX Computer Technology (Shenzhen) Co., Ltd. 141

 Prolin API Programming Guide

not exist.
PCD_ERR_USER_CANCEL -2912 Transaction is cancelled.
PCD_ERR_CARRIER_OBTAIN_
-2913 No obtained carrier
FLAG
PCD_ERR_CONFIG_FLAG -2914 Fail to configure register.
The returned data length
PCD_ERR_RXLEN_EXCEED_FL
-2915 exceeds the set
AG
receiving length
PCD_ERR_NOT_ALLOWED_FL Parameter error or
-2951
AG invalid value.
Chip is abnormal or does
PCD_CHIP_ABNORMAL -2952
not exist.
PCD_CHIP_NOT_OPENED -2953 Module is not open.
PCD_CHIP_CARDEXIST -2954 Card is not removed.
PCD_ERR_NOT_IDLE_FLAG -2955 Card is not in idle state.
PCD_ERR_NOT_POLLING_FLA
-2956 No polling
G
PCD_ERR_NOT_WAKEUP_FLA
-2957 Card does not wakeup.
G
PCD_ERR_NOT_ACTIVE_FLAG -2958 Card is not activated.
PCD_ERR_NOT_SUPPORT -2959 Chip is unsupported.
ERR_BATTERY_VOLTAGE_TO Battery voltage is too
-1024
O_LOW low.

16.2 Data Structure

For more information about the request data structure and response data structure,
please refer to Chapter IC Card Reader 15.2.1 and 15.2.2.

User Configuration Structure

PCD_USER_ST
typedef struct pcd_user_t{
unsigned char wait_retry_limit_w; /* S(WTX) responds to write
permission of sending times*/
unsigned int wait_retry_limit_val; /*S(WTX)responds to the maximum
repetition times.*/
unsigned char check_cancel_key_w; /*respond to write permission of
the cancel key*/

PAX Computer Technology (Shenzhen) Co., Ltd. 142

 Prolin API Programming Guide

unsigned char check_cancel_key_val; /* 0: No response to the cancel

key; 1: Respond to the cancel key
*/
int (*check_cancel_key_function)(void);/*Check whether the cancel key is
pressed. If set
check_cancel_key_w=1 and
check_cancel_key_val=1,
check_cancel_key_function () will
be called during RF card
transaction process. If
check_cancel_key_function ()
returns 0, it means the cancel key
is not pressed. If the function
returns non-zero, it means the
cancel key is pressed and will exit
transaction by force,*/
unsigned char os_picc_transfer_set_w; /*1 means
“os_picc_transfer_set_val”
value is valid, 0 means
“os_picc_transfer_set_val”
value is invalid*/
unsigned char os_picc_transfer_set_val; /* Set OsPiccTransfer
receive/send: Bit0=0: send
disable CRC; Bit0=1: send
enable CRC; Bit1=0: receive
disable CRC; Bit1=1: receive
enable CRC*/
unsigned char anti_interference_flag; /*Anti-interference setting when
searching the card; 1- enable
anti-interference, 0- disable
an-interference.*/
unsigned char protocol_layer_fwt_set_w; /*1 indicates that the value of
protocol_layer_fwt_set_val is
valid, 0 indicates that the
value of
protocol_layer_fwt_set_val is
invalid */
unsigned int protocol_layer_fwt_set_val; /* Set the frame wait time for
the protocol layer (value of
FWT)*/
unsigned char os_picc_transfer_rxlen_set_w; /*1 indicates that the
value of
os_picc_transfer_rxlen_set_v
al is vaild, 0 indicates that the
value of
os_picc_transfer_rxlen_set_v
al is invalid */

PAX Computer Technology (Shenzhen) Co., Ltd. 143

 Prolin API Programming Guide

unsigned int os_picc_transfer_rxlen_set_val ； /*Set the maximum

allowable data length in the
half-duplex block
(OsPiccTransfer) transfer*/
unsigned char os_picc_transfer_direct_transmit_set_w; /* 1 means the
data is transmitted in the way
of data stream, that is, the
half-duplex block
transmission protocol is not
applicable;0 represents data
transfer using the half duplex
block transfer protocol */
unsigned char reserved[36]; /* Reserved byte, for future use.
sizeof(PCD_USER_ST)= 76*/
} PCD_USER_ST;

16.3 Encapsulate Interfaces

OsPiccOpen

Prototype int OsPiccOpen(void);

Function Power on PCD module and make it prepared for work.
Parameters None.
0 Succeeded.
Fail to open device. (Details refer to
Others
Return Code List.)

Return ERR_BATTERY_V
OLTAGE_TOO_LO Battery voltage is too low.
W
ERR_BATTERY_A
Battery is absent.
BSENT
1. D200 and S920 POS models must be powered by battery
to operate RF module; otherwise,
Instruction ERR_BATTERY_ABSENT will be returned.
2. When the battery voltage is 0,
ERR_BATTERY_VOLTAGE_TOO_LOW is returned.

OsPiccClose

Prototype int OsPiccClose(void);

Function Power off PCD module.

PAX Computer Technology (Shenzhen) Co., Ltd. 144

 Prolin API Programming Guide

Parameters None.
0 Succeeded.
Return Failed.(Details refer to Return Code
Others
List.)
Instruction

OsPiccResetCarrier

Prototype int OsPiccResetCarrier(void);

Function Reset the carrier wave.
Parameters None.
0 Succeeded.
Return Failed. (Details refer to Return Code
Others
List.)
This function implements the carrier reset for RF reader and the
Instruction statue of card in the RF field will be changed to idle status.

OsPiccPoll

int OsPiccPoll( char *pcPiccType,

Prototype
unsigned char *pucATQx );
Function Poll cards, only support the roll polling of A card and B card.
Card type:
pcPiccType[Output]  “A” - card A
 “B” - card B
Parameters
Response data:
pucATQx [Output] The valid length of A card is 2 bytes.
The valid length of B card is 12 bytes.
0 Succeeded.
Return Failed. (Details refer to Return Code
Others
List.)
1. Mifare card is a special kind of A card.
Instruction
2. The returned card type of M card is type A.

OsPiccAntiSel

int OsPiccAntiSel( const char pcPiccType,

Prototype
unsigned char *pucUID,

PAX Computer Technology (Shenzhen) Co., Ltd. 145

 Prolin API Programming Guide

const unsigned char ucATQ0,

unsigned char *pucSAK );
Function Do anti-collision and selection operations for cards.
Card type:
pcPiccType[Input]  “A” - card A
 “B” - card B
Unique identifier of card:
pucUID[Output]  Card A-- 4, 7 or 10 bytes.
 Card B—4 bytes.
Parameters
ucATQ0[Input] The parameter is unused.
Response data to card selection.
SAK is the response data to the last
pucSAK[Output] selected command of card A. This
parameter is ignored by card B.
The valid length is 1 byte.
0 Succeeded.
Return Failed. (Details refer to Return Code
Others
List.)
The value of pucSAK can be used to differentiate card A and
Instruction Mifare card.

OsPiccActive

int OsPiccActive( const char pcPiccType,

Prototype
unsigned char *pucRATS );
Function Activate card.
Card type:
pcPiccType[Input]  “A”– A card
 “B”– B card
Response data to card activation:
Parameters  For A card, pucRATS is the
pucRATS[Output] response data to ATS command.
 For B card, PucRATS is the
response data to ATTRIB command.

0 Succeeded.
Return Fail to activate card. (Details refer to
Others
Return Code List.)
Instruction

PAX Computer Technology (Shenzhen) Co., Ltd. 146

 Prolin API Programming Guide

Data outputted by pucRATS, mainly includes card frame waiting

time, buffer size, transmission rate etc. For details, see the
section 5.7 and 6.4 of “EMV Contactless Book D V2.1”.

OsPiccTransfer

int OsPiccTransfer(const unsigned char*pucTxBuff,

int iTxLen,
Prototype
unsigned char* pucRxBuff,
int *piRxLen );
Implement transparent transmission/reception function in
Function accordance with the half-duplex communication protocol of
ISO14443-4.
pucTxBuff[Input] Transmision data buffer.
iTxLen [Input] Transmission data length. (unit: byte)
Parameters
pucRxBuff[Output] Response data buffer.
piRxLen [Output] Response data length.
0 Succeeded.
Return
Others Failed. (Refer to Return Code List.)
Instruction

OsPiccRemove

Prototype int OsPiccRemove(void );

Function Remove card in accordance with EMV mode.
Parameters None.
0 Succeeded.
Return
Others Failed. (Refer to Return Code List.)
Instruction

OsMifareAuthority

int OsMifareAuthority(unsigned char *uid,

unsigned char blk_no,
Prototype
unsigned chargroup,
unsigned char *psw);

PAX Computer Technology (Shenzhen) Co., Ltd. 147

 Prolin API Programming Guide

Function VerifyMifare card.

Card ID.
uid [Input]
The valid length is 4 bytes.
blk_no[Input] Block number.
Parameters
group [Input] Password types: “A”/“B”.
Authentication password.
psw[Input]
The valid length is 6 bytes.
0 Succeeded.
Return
Others Failed. (Refer to Return Code List.)
Instruction

OsMifareOperate

int OsMifareOperate(unsigned charucOpCode,

unsigned charucSrcBlkNo,
Prototype
unsigned char*pucVal,
unsigned char ucDesBlkNo );
Read or write a specific block of Mifare card; Increase,
Function decrease or backup the data in specified block of Mifare card,
and update it into another specified data block.
 “r”or“R”:read;
 “w”or“W”: write;
ucOpCode [Input]  “+”: increase;
 “-“: decrease;
 “>”: transfer/backup.
Specify the block number that will be
ucSrcBlkNo[Input]
accessed.
 For reading operation, pucVal
Parameters outputs block contents. The buffer
size of pucVal is 16 bytes.
 For writing operation, pucVal
inputs block contents. The buffer
size of pucVal is 16 bytes.
pucVal[Input/Output]
 For “+”or “-”operation, pucVal is
buffer head address. The buffer
size of pucVal is 4 bytes.
 For transfer operation, pucVal has
no practical meaning, but the
incoming pointer cannot be NULL.

PAX Computer Technology (Shenzhen) Co., Ltd. 148

 Prolin API Programming Guide

Specify the block number which is

used to write in the operation result.
ucUpdateBlkNo [Input]
(When reading or writing block,
ucUpdateBlkNo is a NULL pointer.)
0 Succeeded.
Return
Others Failed. (Refer to Return Code List.)
Instruction

OsPiccInitFelica

int OsPiccInitFelica(unsigned char ucSpeed,

Prototype
unsigned char ucModInvert );
Function Initialize the configuration of FeliCa card.
Set transmission rate of interaction with
card:
ucSpeed[Input]
 1: 424Kbp
Parameters  Others: 212Kbps
Set modulation mode of FeliCa.
ucModInvert[Input]  1: positive modulation output;
 Others: reverse modulation output.
Return 0 Succeeded.
Instruction

OsPiccIsoCommand

int OsPiccIsoCommand(int cid,

Prototype ST_APDU_REQ *ApduReq,
ST_APDU_RSP *ApduRsp);
Send APDU data to card and receive response in specified
Function
channel.
Specify logical channel number of card.
cid
[Input] The valid value of cid ranges from 0 to 14,
the value is set to 0 currently.
Parameters ApduReq Command data structure ST_APDU_REQ
[Input] sent to PICC card.
ApduRsp Response data structure ST_APDU_RSP
[Output] returned from PICC card.
0 Succeeded.
Return
Others Failed. (Refer to Return Code List.)

PAX Computer Technology (Shenzhen) Co., Ltd. 149

 Prolin API Programming Guide

Instruction

OsPiccSetUserConfig

int OsPiccSetUserConfig(PCD_USER_ST
Prototype
*pcd_user_config) ;
Function Set user configuration.
pcd_user_config A pointer to user configuration structure
Parameters
[Input] PCD_USER_ST.
0 Succeeded.
Return
Others Failed. (Refer to Return Code List.)
Instruction

OsPiccGetUserConfig

int OsPiccGetUserConfig(PCD_USER_ST
Prototype
*pcd_user_config);
Function Get user configuration.
pcd_user_config A pointer to user configuration structure
Parameters
[Output] PCD_USER_ST.
0 Succeeded.
Return
Others Failed. (Refer to the Return Code List.)
Instruction

OsPiccApplePoll

int OsPiccApplePoll(char *pcPiccType,

Prototype unsigned char *pucATQx,
unsigned char *pucSendData);
Detect cards, including the roll polling of type A card, type B
Function
card and type V card.
Card types:
 A – type A card
pcPiccType[Output]
 B – type B card
 V – type V card
Parameters
Response data of the detected card:
pucATQx [Output]  The response data length of type A
card is 2 bytes.
 The response data length of type B

PAX Computer Technology (Shenzhen) Co., Ltd. 150

 Prolin API Programming Guide

card is 12 bytes.
 The response data length of type V
card is 2 bytes.
When the first byte is 0x01, enter a fixed
four-byte length:
 "\x01\x00\x00\x00" represents
Terminal in VAS App OR Payment
Mode.
 "\x01\x00\x00\x01" represents
Terminal in VAS App AND Payment
Mode.
 "\x01\x00\x00\x02", represents
pucSendData[Input] Terminal in VAS App Mode Only.
 "\x01\x00\x00\x03", represents
Terminal in Payment Mode Only.
When the first byte is 0x02, enter a
variable-length byte, the lower nibble of
the second byte X represents the length
of Terminal Data:
 "\x02\x8X\x00\x00"+X-byte Terminal
Data.
0 Succeeded.
Return
Others Failed. (Refer to the Return Code List.)
1. Mifare card is a special kind of A card.
Instruction
2. The returned card type of M card is type A.

OsPiccOffCarrier

Prototype int OsPiccOffCarrier(void);

Function Close the carrier.
Parameters None
0 Succeeded.
Return
Others Failed. (Refer to the Return Code List.)
Close the carrier for the Non-contact IC card reader, and then
Instruction
all cards in RF field will be in power-off state.

OsPiccInitIso15693

Prototype int OsPiccInitIso15693(unsigned char ucDataCodeMode);

PAX Computer Technology (Shenzhen) Co., Ltd. 151

 Prolin API Programming Guide

Function Initialize the ISO15693 card.

The transmission rate that used to
ucDataCodeMode[I interact with the card:
Parameters
nput]  0: 26.48 kbits/s
 Other values: reserved
0 Succeeded.
Return
Others Failed. (Refer to the Return Code List.)
int iRet = 0;
unsigned char aucDataSend[256], aucDataResp[256];
int iSendLen = 0, iRespLength = 0;
memset(aucDataSend, 0, sizeof(aucDataSend));
memset(aucDataResp, 0, sizeof(aucDataResp));
memcpy(aucDataSend, "\x26\x01\x00", 3);
Instruction
iSendLen = 3;
iRet = OsPiccOpen();
iRet = OsPiccInitIso15693(0);
iRet = OsPiccTransfer(aucDataSend, iSendLen, aucDataResp,
&iRespLength);
OsPiccClose();

16.4 Notes of Touch Screen and RF Reader Programming

As model S900 and S920 are equipped with both touch screen and RF reader,
application developers should pay special attention to the following notes:

1. Touch screen cannot be used in the whole process A/B transaction.

2. After finishing the transaction, OsPiccRemove() must be called to remove the

card.

3. For Mifare card, OsPiccRemove() or OsPiccClose() must be called at last.

4. For FeliCa card, OsPiccClose() must be called at last.

PAX Computer Technology (Shenzhen) Co., Ltd. 152

 Prolin API Programming Guide

17Communication Port

17.1 Data Definition

Table 17.1 Macro definition list of communication ports

Macro Value Description

PORT_COM1 0 Serial port 1UART.
PORT_COM2 1 Serial port2.
PORT_COM3 2 Serial port 3.
PORT_PINPAD 3 Built-out PinPad.
USB device mode port.(Host
PORT_USBDEV 11
port 0)
PORT_USBHOST 12 USB host mode port.
PORT_USBHID 13 USB HID device port.
USB host mode port.(Host port
PORT_USBHOST1 14
1)
PORT_USBDEV1 19 USB device mode port

Table 17.2 Return code list of USB port functions

Macro Value Description

USB_ERR_NOT_OPEN -3403 Channel is not open.

PAX Computer Technology (Shenzhen) Co., Ltd. 153

 Prolin API Programming Guide

USB_ERR_BUF -3404 Send buffer error.

USB_ERR_NOT_FREE -3405 No free port.
Enumeration and configuration
USB_ERR_NO_CONF -3411
process are not completed.
USB_ERR_DISCONN -3412 Disconnected with the host.
USB_ERR_MEM_SYST
-3413 System memory is abnormal.
EM
USB_ERR_BUSY -3414 USB system is busy.
USB_ERR_RC_SYSTE Fail to apply for system
-3415
M resources.
USB_ERR_DEV_ABSE
-3416 The device is absent.
NT
USB communication state is
USB_ERR_INVALID -3417
invalid.

17.2 Communication Control

OsPortOpen

int OsPortOpen(int Channel,

Prototype
const char *Attr);
Function Open communication port and set port attributes.
Channel Please refer to the Macro definition list of
communication ports.
For S800, PORT_COM2 and
PORT_PINPAD are multiplex, and only one
of them can be used at a time.
S920 only has two ports: PORT USBDEV
and PORT USBHOST, pease refer to
Appendix 4.
Attr[Input] A pointer to communication port attributes.
Parameters
When Channel is PORT_USBDEV ,
PORT_USBHOST or PORT_USBHID,
parameter Attr is ignored and can be NULL.
When Channel is UART port, its format is:
“baud rate, data bits, parity check bit, stop
bit”, each of which are separated by a
comma.
1. Baud rate: 1200, 2400, 4800, 9600,
19200, 38400, 57600, or 115200.

PAX Computer Technology (Shenzhen) Co., Ltd. 154

 Prolin API Programming Guide

2. Data bit: 7 or 8.
3. Parity check method: “o” - odd parity; “e”
- even parity; “n” - no parity.
4. Stop bit: 1 or 2.
For example, “9600, 8, n, 1\0”.
1. attr =“9600, 8, n, 1”, it represents that the
baud rate is 9600bps; 8 data bits; no
parity; 1 stop bit.
RET_OK Succeeded.
ERR_DEV_BUSY Device is busy.

Return ERR_DEV_NOT_EXIS
Port does not exist.
T
ERR_INVALID_PARA
Invalid parameter.
M
1. When program starts, OsPortOpen() must be called
successfully to open communication port; otherwise, the
related functions will fail to work.
2. Soft flow control and hard flow control will be closed.
3. Only PX7 and PX5 support 921,600 baud rate, while other
models don’t .
4. For device which conforms to HID Category Specification
Instruction and connects to terminal with USB device, PORT_USBHID
port can be used to read data. For example, it supports the
common USB barcode scanner device.
5. For terminal with only one USB HOST port, channel
PORT_USBHOST should be used to open the USB HOST
port; For terminal with two USB HOST ports, channel
PORT_USBHOST and PORT_USBHOST1 should be used
to open their corresponding USB HOST port, respectively.

1. Prolin-2.4 system will start the XCB service with USB by

default. OsRegSetValue("persist.sys.xcb.enable", "0")
should be called in main() to close the XCB service if
application needs to use USB or serial port so as to avoid
resource conflict.
2. XCB service can be opened in following ways:
 Call OsRegSetValue("persist.sys.xcb.enable", "1") in the
main application;
 Select a connection mode among COM, USB and Network in

PAX Computer Technology (Shenzhen) Co., Ltd. 155

 Prolin API Programming Guide

TM.

OsPortClose

Prototype void OsPortClose(int Channel);

Function Close specified port.
Channel Please refer to Macro definition list of
Parameters communication ports .
Return None.
This function shall be called to close device while program
Instruction exits.

OsPortSend

int OsPortSend(int Channel,

Prototype const void *SendBuf,
int SendLen);
Function Send data to specified communication port.
Please refer to Macro definition list of
Channel
communication ports .
SendBuf[Inpu
Send buffer.
Parameters t]
Length of data that will be sent.
SendLen The valid data length is not more than 8*1024
bytes.
RET_OK Succeeded.
Return ERR_DEV_NOT_OPEN Port is not open.
ERR_INVALID_PARAM Invalid parameter.
1. The size of send buffer for every port is allocated 8k bytes
by Prolin. If SendLen is less than the free space of send
buffer, this function will return immediately and all the send
data is only stored in the send buffer.
Instruction
2. When calling OsPortClose(), the system will keep blocking
until the data in send buffer has been sent out.
3. When using PORT_USBHID port, sending data is not
supported by this function.

PAX Computer Technology (Shenzhen) Co., Ltd. 156

 Prolin API Programming Guide

OsPortRecv

int OsPortRecv(int Channel,

void *RecvBuf,
Prototype
int RecvLen,
int TimeoutMs);
Function Receive data from specified communication port.
Please refer to the Macro definition list of
Channel
communication ports.
RecvBuf[Output] Received buffer.
Expected length of received data;
RecvLen RecvLen=0 means clearing the receive
Parameters buffer.
Timeout[unit:ms]
The minimum timeout is 100ms.
TimeoutMs The maximum value is 25,500 ms. When
TimeoutMs exceeds this value,
ERR_INVALID_PARAM will be returned.
>=0 Actual length of received data.
ERR_DEV_NOT_
Port is not open.
Return OPEN
ERR_INVALID_PA
Invalid parameter
RAM
1. The function will return immediately if received data length
equals to RecvLen.
2. The function will wait until timeout if length of received data
is less than RecvLen.
3. When using PORT_USBHID port to receive data from HID
device, system buffer can cache data with 500 characters
at most. If the cached data exceeds the limit and this
function has not been called, the cached data will be
overwritten, and it will result in incomplete data.
Instruction 4. When using PORT_USBHID port to receive data from HID
device, the following two scanner are supported:
1) A scanner whose scanned data ending with an end
character: with this scanner, the RecvLen can be
greater than or equal to 500 characters and all the
system buffer data can be read at once.
2) A scanner whose scanned data ending without an end
character: with this scanner, set RecvLen to 1 (that is
reading in single-byte) and timeout to 100ms. If a value
is scanned, an additional loop is added to continuously

PAX Computer Technology (Shenzhen) Co., Ltd. 157

 Prolin API Programming Guide

call OsPortRecv(), and the data of OsPortRecv() is

appended after each result until the timeout, the last
obtained string data is the result of the scan. In the
process of calling OsPortRecv(), the return value needs
to be determined, if the return value is greater than
RecvLen, the return value is subtracted from ReveLen
to get a difference, and append the difference value of
the single character on the data that is received by the
character. For example, if the string obtained by the
previous loop is "123", and the character '0' is received
this time, and the return value is 3, then "000" needs to
be appended to the total number of characters obtained
by the previous loop, and the result is "123000".
3) Note: the scanner only needs to scan once before the
timeout. If the scanner is performed several times
before the timeout, the resulting string will be
superimposed.

OsPortReset

Prototype int OsPortReset(int Channel);

Reset communication port and clear all the data in send and
Function receive buffers.
Channel Please refer to Macro definition list of
Parameters [Input] communication ports.
RET_OK Succeeded.
ERR_DEV_NOT_OPE
Return Port is not open.
N
ERR_INVALID_PARAM Invalid parameter.
Instruction

OsPortCheckTx

Prototype int OsPortCheckTx(int Channel);

Check the remaining bytes in sending buffer of specified
Function communication port.
Channel Please refer to Macro definition list of
Parameters [Input] communication ports.
The remaining data size in sending
>=0
buffer.
Return
ERR_DEV_NOT_OPE
Port is not open.
N

PAX Computer Technology (Shenzhen) Co., Ltd. 158

 Prolin API Programming Guide

ERR_INVALID_PARAM Invalid parameter.

Instruction

OsPortCheckRx

Prototype int OsPortCheckRx(int Channel);

Check the remaining bytes in receiving buffer of specified
Function communication port.
Channel Please refer to Macro definition list of
Parameters [Input] communication ports.
The remaining data size in receiving
>=0
buffer.
ERR_DEV_NOT_OPE
Port is not open.
N
Return
ERR_INVALID_PARAM Invalid parameter.
ERR_SYS_NOT_SUPP
System does not support.
ORT
1. When the return value is greater than 0, OsPortRecv() can
receive data;
2. Since OsPortRecv() can continue to receive data which is
Instruction
updated in the buffer during the timeout until the length of
the received data is RecvLen, the actual length of the
received data is based on the return value of OsPortRecv().

17.3 POSIX Interface

Prolin serial ports are allowed to be accessed by POSIX interfaces. Only PX7 and PX5
series models suppport soft flow control and hard flow control.

For Prolin-2.4 and Prolin-phoenix-2.5 platforms, since there is no soft link for serial
port, the corresponding relation between device nodes and serial ports can refer to
the following table. For Prolin-cygnus-2.6 and later platforms, the device nodes
corresponding to each serial port need to be determined by the soft links of
/dev/ttycom1 and /dev/ttycom2, and the specific terminals will not be updated in the
list.

Corresponding Applicable
Device node Serial port
module models
/dev/ttyAMA0 Modem Modem S800

PAX Computer Technology (Shenzhen) Co., Ltd. 159

 Prolin API Programming Guide

/dev/ttyAMA1 Wireless Wireless S800/S900

S800/S900/S300/
/dev/ttyAMA2 PORT_COM1 COM1
D200
/dev/ttyAMA3 PORT_PINPAD Pinpad S800
/dev/ttyAMA3 PORT_COM2 COM2 PX5/PX7
S800/S900/S300/
PORT_USBHOS
/dev/ttyhost USB D200/S920//PX5/P
T X
7
S800/S900/S300/
/dev/ttydev PORT_USBDEV USB D200/S920//PX5/P
X
7

Specific operations of serial port are as follows:

Open

Open communication port and the device names are ttyAMA0, ttyAMA1, ttyAMA2,
ttyAMA3.

Sample code:
int fd;
fd = open(“/dev/ttyAMA1”, O_RDWR);
if(-1 == fd){
perror(“Open uart error”);
}

Read

Read data from communication port.

Sample code:
charbuff [1024];
int Len = 1024;
int readByte = read (fd, buff, Len);

Write

Write data to communication port. (Send)

Sample code:
charbuffer [1024];

PAX Computer Technology (Shenzhen) Co., Ltd. 160

 Prolin API Programming Guide

int Length = 1024;

int nByte;
nByte = write (fd, buffer, Length);

Close

Close communication port.

close(fd);

Query the Buffer Data of Communication Port

Sample code:

int remain;
int count;
/* Inquiry the number of bytes remained in send buffer */
ioctl(fd, TIOCOUTQ, &remain);
/* Inquiry the number of bytes remained in receive buffer */
ioctl(fd, TIOCINQ, &count);

Clear the Buffer Data of Communication Port

Sample code:

/* clear the buffer data*/

tcflush(fd, TCIOFLUSH);

Set the Configuration Parameters of Communication Port

Sample code:

/* Set 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 configuration messages of UART */

if (tcgetattr (fd, &oldtio) != 0)
{
printf("Get serial error\n");
return -1;
}

PAX Computer Technology (Shenzhen) Co., Ltd. 161

 Prolin API Programming Guide

/* Initialize configuration messages*/

bzero (&newtio, sizeof (newtio));
newtio.c_cflag |= CLOCAL | CREAD;
newtio.c_cflag &= ~CSIZE;

/* Close soft flow control*/

newtio.c_iflag &= ~(ICRNL | IXON | IXOFF);

/* Close hard flowcontrol*/

newtio.c_cflag &= ~CRTSCTS;

/* Set data bits */

switch (nBits)
{
case 7:
newtio.c_cflag |= CS7;
break;
case 8:
newtio.c_cflag |= CS8;
break;
}

/* Set parity bit*/

switch (cEvent)
{
case 'o':
newtio.c_cflag |= PARENB;
newtio.c_cflag |= PARODD;
newtio.c_iflag |= (INPCK | ISTRIP);
break;
case 'e':
newtio.c_iflag |= (INPCK | ISTRIP);
newtio.c_cflag |= PARENB;
newtio.c_cflag &= ~PARODD;
break;
case 'n':
newtio.c_cflag &= ~PARENB;
break;
}

PAX Computer Technology (Shenzhen) Co., Ltd. 162

 Prolin API Programming Guide

/* Set 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:
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;
}

PAX Computer Technology (Shenzhen) Co., Ltd. 163

 Prolin API Programming Guide

/* set stop bits */

if (nStop == 1)
newtio.c_cflag &= ~CSTOPB;
else if (nStop == 2)
newtio.c_cflag |= CSTOPB;
/* Set waiting time and the minimum number of characters*/
newtio.c_cc[VTIME] = 0;
newtio.c_cc[VMIN] = 0;
/* Clear send buffer*/
tcflush (fd, TCIFLUSH);
/* Set new configuration message */
if ((tcsetattr (fd, TCSANOW, &newtio)) != 0)
{
printf("Set serial error\n");
return -1;
}
return 0;
}

PAX Computer Technology (Shenzhen) Co., Ltd. 164

 Prolin API Programming Guide

18MODEM

Prolin system implements Modem communication through built-in serial ports to send
AT commands to Modem. Besides, there are a series of encapsulated interfaces for
developers to realize Modem communication.

18.1 Return Code List

Table 18.1 Modem return code list

Macro Value Description

MODEM_CONNECTING 10 Dialing.
MODEM_CONNECTED 0 Connected.
Sending numbers (used
only when switching
from automatically
MODEM_HAVE_DIALED 6
sending mode to
manually answering
mode).
Receive buffer is not
MODEM_RECV_POOL_HAVE_D
8 empty (have received
ATA
remote data).
Receive buffer is not
MODEM_RECVDATA_SEND_IS_
9 empty, and send buffer
FULL
is full.

PAX Computer Technology (Shenzhen) Co., Ltd. 165

 Prolin API Programming Guide

Send buffer is full. (In

OsModemCheck(), the
full status means send
MODEM_SEND_POOL_FULL 1 buffer is being used, at
this time, the
OsModemSend() cannot
be used.)
MODEM_IDLE 11 Idle.
Send buffer is full. (It is a
return error. If
synchronous, it means
the system is using the
ERR_MDM_TXOVER -3100
send buffer; If
asynchronous, it means
the send buffer
overflows. )
Parallel line is busy.
ERR_MDM_BYPASS_BUSY -3101 Not applicable for Prolin
S800 which has no
bypass telephone port.
Telephone line is not
ERR_MDM_LINE_BUSY -3102 properly connected, or
parallel line is occupied.
Carrier wave of
telephone is lost. (Fail to
ERR_MDM_NO_CARRIER -3103
build synchronization
chain.)
ERR_MDM_NO_ANSWER -3104 Not answered.
ERR_MDM_CALLEE_BUSY -3105 Line is busy.
Telephone line is not
ERR_MDM_NO_LINE -3106 connected (Line voltage
is 0).
The excommand() buffer
ERR_MDM_CMD_BUF_FULL -3108
is full.
Command of
ERR_MDM_CMD_TOO_LONG -3109 excommand() is too
long, exceeding 100.
ERR_MDM_CMD_NOT_SUPPOR excommand() does not
-3110
T support the command.
-3XXX Abnormal error code is
OTHERS ( used for abnormal error.
-3111 It is not frequently used
~ and it is just to keep the

PAX Computer Technology (Shenzhen) Co., Ltd. 166

 Prolin API Programming Guide

-3199 completeness and

) maintainability of
programming. Its
meaning is not
impsortant.
Calling synchronization
-3115 handshake receiving
process 1 error.
Calling synchronization
-3116 handshake receiving
data package error.
Calling synchronization
-3117 handshake receiving
package type error.
Calling synchronization
-3118 handshake receiving
process 2errors.
Calling synchronous
communication
-3119
receiving process 1
error.
Calling synchronous
-3120 communication chip is
on-hook.
Calling synchronous
communication
-3121
receiving packet series
number error.
Calling synchronous
communication
-3122
receiving process 2
errors.
Calling synchronous
-3123 communication send
overload.
Calling synchronous
-3124 communication send
underload.
Calling synchronous
-3130 communication line rate
is illegal.
Calling synchronous
-3131 communication sending
state packet 1 error.

PAX Computer Technology (Shenzhen) Co., Ltd. 167

 Prolin API Programming Guide

Calling synchronous
communication sending
-3132
data packets retry more
than specified times.
Calling synchronous
-3133 communication sending
data packets timeout.
Calling synchronous
communication
receiving
-3134
acknowledgement
packets retry more than
specified times.
Calling synchronous
-3135 communication sending
state packet 2 errors.
Calling synchronous
-3136 communication sending
state packet 3 errors.
Calling synchronous
-3137 communication sending
state packet 4 errors.
Calling synchronous
communication
-3138 receiving data packets
retry more than
specified times.
Calling synchronous
-3139 communication sending
state packet 5 errors.
Calling synchronous
-3140 communication sending
state packet 6 errors.
Bypass telephone and
parallel telephone are
both idle (used only
when switching from
automatically sending
-3144 number to manually
answering).
In automatically sending
number mode, the
phone is not picked up
timely.

PAX Computer Technology (Shenzhen) Co., Ltd. 168

 Prolin API Programming Guide

Called synchronization
-3145 handshake fails to send
handshake packet.
Called synchronization
handshake fails to
-3146
receive handshake
packet.
Called synchronization
-3147 handshake more than
specified times.
Called synchronous
-3148 communication sending
state packet 1 error.
Called synchronous
communication
-3149
receiving process 1
error.
Called synchronous
-3150 communication chip is
on-hook.
Called synchronous
communication
-3151
receiving process 2
errors.
Called synchronous
communication
-3152
receiving retry more
than specified times.
Called synchronous
-3153 communication sending
state packet 2 errors.
Called synchronous
-3154 communication sending
data packet error
Called synchronous
communication
-3155
receiving process 3
errors.
Called synchronous
communication
-3156 receiving packet retry
more than specified
times.

PAX Computer Technology (Shenzhen) Co., Ltd. 169

 Prolin API Programming Guide

Called synchronous
-3157 communication sending
state packet 3 errors.
Called connection
-3160 receiving ring
information error.
Called connection fails
-3161
to detect line voltage.
Called connection
-3162 detecting line voltage
data format error.
Called connection
-3163 voltage is less than
threshold value.
Called connection
-3164
timeout.
Called asynchronous
-3165
line rate format error.
Called asynchronous
-3166
line rate is illegal.
Called connection
-3167
information format error.
Called connection fails
-3170
to set command string 1.
Called connection fails
-3171
to set command string 2.
Called connection fails
-3172 to set extended
command string.
Calling connection fails
-3175
to set command string 1.
Calling connection fails
-3176
to set command string 2.
Calling connection fails
-3177
to set command string 3.
Calling connection fails
-3178
to set command string 4.
Calling connection fails
-3179
to set command string 5.

-3180 Calling connection fails

to set the threshhold of

PAX Computer Technology (Shenzhen) Co., Ltd. 170

 Prolin API Programming Guide

the answering tone.

Calling connection
-3181 asynchronous line rate
is illegal.
Calling connection fails
-3182 to get the voltage of
telephone line.
Calling connection fails
-3183 to set extended
command string.
Calling connection fails
-3184 to set the transmission
level.
Calling connection has
-3185
no dial tone.
Calling connection chip
-3186
indicator error.
Calling connection
-3187
digital lines is detected.
Calling connection has
-3188 no dial tone and the
voltage is too low.
Calling connection has
-3189
other abnormal errors.
Non-pre-dial-up dial up
-3192
timeout (300s).
When FSK sends data,
-3193
DCD signal timeout.
When FSK sends data,
-3194
CTS signal timeout.
FSK sending data
-3195
timeout.
Called synchronous
-3196 communication sending
data packet format error.
Asynchronous
communication does not
-3197 support the
ConnectFormat
parameter.
Daemon fails to create
-3198
thread.

PAX Computer Technology (Shenzhen) Co., Ltd. 171

 Prolin API Programming Guide

Communication with
-3199 Daemon communication
fails or error.
Modem is using the
-3200
binding serial port.
-3201 Fail to create Socket.
-3202 Fail to connect Socket.
-3203 Fail to send Socket.
Fail to create
-3204
semaphore.
Fail to set semaphore
-3205
value.
Semaphore is
-3206
pre-occupied.
Fail to release
-3207
Semaphore.
Fail to initialize
-3208
Semaphore.
-3209 Fail to gettimeofday.
More than 2 links are
-3210
using modem daemon.
Received cancel button
ERR_MDM_CANCEL_CONNECT -3211
in dial-up process.
The request of receiving
data is rejected.
-3212
(Receive buffer is
empty.)
Calling connection fails
-3213
to set command string 7.
Calling connection fails
-3214
to set command string 8.
FSK sending timeout,
-3215 but still has data in send
buffer.
Invalid data length
-3216 (len=0 or len>2048),
won’t send data.
ERR_MDM_INIT -3217 Fail to initialize Modem.
If no or error
-3218 implementation of
OsModemConnect(),

PAX Computer Technology (Shenzhen) Co., Ltd. 172

 Prolin API Programming Guide

then implement
OsPppomLogin()
orOsPppomCheck().
Modem or ModemPPP
-3219 is being used, Modem
cannot be powered off.
Modem is not powered
-3220
on.

18.2 Data Structure

ST_MODEM_SETUP structure of MODEM:

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;

PAX Computer Technology (Shenzhen) Co., Ltd. 173

 Prolin API Programming Guide

int DialTimes;

int IdleTimeout;

int Pppom;

int Reserved[9];
}ST_MODEM_SETUP;

Table 18.2 Variable definitions of ST_MODEM_SETUP

MODEM_PRE_DIA
Pre-dial.
L
CallMode MODEM_DIAL Dial.
MODEM_WAIT_CA
Called/Answer the call.
LL
MODEM_COMM_S
Synchronization.
YNC
CommMode
MODEM_COMM_A
Asynchronization.
SYNC
MODEM_CODE_D DTMF(Dual Tone Multiple
TMF Frequency) dialing.
Pulse dialing 1(Pulse rate 10/s;
MODEM_CODE_P
break-make ratio1.6:1; signal
ULSE1
CodeType interval>=500ms).
Pulse dialing 2(Pulse rate 10/s;
MODEM_CODE_P
break-make ratio2:1; signal
ULSE2
interval >=600ms).
Other values Reserved.

The duration time of dual-tone dial-up a single

CodeDuration number[Unit:10ms].
The valid value ranges from 5 to 25.
The interval time between two numbers of dual-tone
dial-up.[Unit:10ms]
CodeSpacing Chip 93011 cannot set this value and S800 does not
support it.
The valid value ranges from 5 to 25.
 Detect whether the parallel
DetectLineVolta
TRUE telephone is occupied (used in
ge
Caller dialing or

PAX Computer Technology (Shenzhen) Co., Ltd. 174

 Prolin API Programming Guide

none-manually-answering
mode).
Do not detect whether the
parallel telephone is occupied
FALSE (used in Caller dialing or
none-manually-answering
mode).
Detect dial tone.
TRUE Refer to the instruction of
DetectDialTone DialTone Timeout.
FALSE Do not detect dial tone.
DialToneTimeou 1. If detecting dial tone:
t DialToneTimeout () refers to the longest waiting time for
the dial tone after off-hook. During this process, system
will exit waiting as long as the dial tone is detected.[Unit:
100ms]
2. If not detecting dial tone:
DialToneTimeout () refers to the waiting time from
off-hook to dialing.[Unit: 100ms]
The valid timeout ranges from 20 to 50. Minimum value
and the default value are both set to 20.
In both cases above, the time is started about 450~500ms
after off-hook.
CommaPauseTi “,”waiting time when dialing an outside line.[Unit: 100ms]
me This value should be set according to the actual
application environment. Some interfaces should be
reserved for manual setting.
The valid range is from 0 to 255. The value range doesn’t
apply to S800 whose valid range is from 1 to 26s. (It is
inconsistent with the Datasheet because of the modem
patch).
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 */

PAX Computer Technology (Shenzhen) Co., Ltd. 175

 Prolin API Programming Guide

“12000”/*12000 bps*/
“14400”/*14400 bps */
“19200”/*19200 bps */
“24000”/*24000 bps */
“26400”/*26400 bps */
“28800”/*28800 bps */
“31200”/*31200 bps */
“33600”/*33600 bps */
“48000”/*48000 bps */
“56000”/*56000 bps */
For null string "\ 0"，the system will select “1200” by default
in synchronous communication and select the maximum
rate that the chip supports by default in asynchronous
communication.
S800 supports baud rate.
Asynchronization:
“1200”/*1200 bps */
“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*/
“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 */
“31200”/*31200 bps */
“33600”/*33600 bps */
“48000”/*48000 bps */
“56000”/*56000 bps */

Synchronization:
“1200”/*1200 bps */
“1200,V22”/*1200 bps normal connect */
“2400,FC”/*2400 bps fast connect */
“2400”/*2400 bps*/

PAX Computer Technology (Shenzhen) Co., Ltd. 176

 Prolin API Programming Guide

“9600”/*9600 bps*/
ConnectFormat[ Format of connection and communication(Expressed as a
20 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.
Connection timeout. [unit: second]
ConnectTimeout
The valid timeout ranges from 0 to 60s.
The total number of dial-up cycle.
The valid range is 1 to 255. 0 will be converted to 1
DialTimes
automatically.
Dialing all the dialer numbers is one dial-up cycle.
If there is no data exchange in application-layer within
specified time, MODEM will hang up.[Unit: 10s]
IdleTimeout
0 means no timeout. The maximum timeout is 900s. This
value is invalid to ModemPPP.
TRUE Modem PPP communication
Pppom
FALSE Common Modem communication
Reserved[9] Reserved.

18.3 OsModemOpen

Prototype int OsModemOpen(void);

Function Open Modem device.
Parameters None.
RET_OK Succeeded.
ERR_DEV_NOT_EXIST Device does not exist.
Return
ERR_DEV_BUSY Device is busy.
ERR_NO_PORT No communication port.
1. This function must be called successfully to open Modem
Instruction device; otherwise, other related functions will not work.

PAX Computer Technology (Shenzhen) Co., Ltd. 177

 Prolin API Programming Guide

2. OsModemSwitchPower() must be called to power on the

device before calling OsModemOpen().

18.4 OsModemClose

Prototype void OsModemClose(void);

Function Close Modem device.
Parameters None.
Return None.
This function can only close the modem that is opened by the
Instruction same application. If the modem device is not open, this function
will not work.

18.5 OsModemSwitchPower

Prototype int OsModemSwitchPower(int OnOff);

Function Manage Modem power.

Parameter
int OnOff OnOff=1, power on,
s
OnOff=0, power off.
RET_OK Succeeded.

Return -3219 Modem or ModemPPP is being used, and

Modem cannot be powered off.
-3220 Modem isn’t powered on.
1. Modem must be powered on before calling Modem or
ModemPPP.
Instructio 2. This function is independent of the interfaces in Modem
n module.
3. OsModemClose() is not automatically performed when
Modem module is powered off.

18.6 OsModemConnect

int OsModemConnect(const ST_MODEM_SETUP *Setup,

Prototype
const unsigned char *TelNo);

PAX Computer Technology (Shenzhen) Co., Ltd. 178

 Prolin API Programming Guide

Establish Modem communication link suitable for both dialing

Function
and called mode.
A pointer to Modem parameter
structure ST_MODEM_SETUP.
While mdm_setup==NULL, default
dialing parameter will be used.
Setup[Input]
Parameters The default dialing mode is
synchronous, 1200, DTMF,
connection timeout for 10 seconds,
idle hang up for 60 seconds.
TelNo[Input] Telephone number.
RET_OK Succeeded.
ERR_MDM_BYPASS_BUSY Parallel line is busy.
Telephone line is not
ERR_MDM_LINE_BUSY properly connected, or
parallel line is occupied.
ERR_MDM_NO_ANSWER Not answered.
ERR_MDM_CALLEE_BUSY Line is busy.
Telephone line is not
ERR_MDM_NO_LINE connected (Line voltage is
0).

Return Carrier wave of telephone is

ERR_MDM_NO_CARRIER
lost.
ERR_INVALID_PARAM Invalid parameter.
Dial is canceled during the
dialing process. When
OsModemConnect() is
blocking (that is,
ERR_MDM_CANCEL_KEY_DO
CallMode==MODEM_DIAL),
WN
dialing can be canceled by
creating a thread to call
OsModemConnect(NULL,N
ULL).
ERR_DEV_NOT_OPEN Device is not open.
1. The function can also be used to set Modem mode to be
called.
2. Telephone icon is controlled by modem driver. It shows
Instruction hang-up icon when connecting; it shows pickup icon when
communication is established, or during switching time of
pre-dial after hang-up.
3. The OsModemCheck()is used to query the result of

PAX Computer Technology (Shenzhen) Co., Ltd. 179

 Prolin API Programming Guide

pre-dial.
4. For ModemPPP, OsModemConnect() should be called first
and set ST_MODEM_SETUP.Pppom to 1
(OsModemOpen() doesn’t need to be executed), then call
OsPppomLogin().
5. After Modem dialed successfully, calling OsSysSleep() or
OsSysSleepEx(2) will return ERR_DEV_BUSY, and the
system cannot sleep. After Modem is hung up, the system
can sleep by calling sleep function.

Code meanings of telephone numbers:

0-9,*, #,A~D — Telephone numbers
, — Dialing delayed.
; — Transmitting next telephone number.
. — End mark of numbers, which is used to keep connecting
with application after sending numbers.
.. — Extended end mark of numbers, which is used when
switching to manual answering after sending numbers.

18.7 OsModemCheck

Prototype int OsModemCheck(void);

Function Check the status of Modem and telephone line.
Parameters None.
MODEM_CONNECTING It is dialing.
MODEM_CONNECTED Connected.
MODEM_IDLE
Idle.
MODEM_RECV_POOL_HA
Receive buffer is not empty
VE_DATA
(Have received remote data).
MODEM_SEND_POOL_FU
Send buffer is full.
LL
Return
ERR_MDM_BYPASS_BUS
Parallel line is busy.
Y
Telephone line is not properly
ERR_MDM_LINE_BUSY connected, or parallel line is
occupied.
ERR_MDM_NO_ANSWER Not answered.
ERR_MDM_CALLEE_BUS Line is busy.

PAX Computer Technology (Shenzhen) Co., Ltd. 180

 Prolin API Programming Guide

Y
Telephone line is not connected
ERR_MDM_NO_LINE
(Line voltage is 0).
ERR_MDM_NO_CARRIER Carrier wave of telephone is lost.
ERR_DEV_NOT_OPEN Device is not open.
1. This function can be used to check whether the pre-dial is
successfully connected.
Instruction 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);
Set additional AT control command for OsModemConnect() to
Function
control the connection behavior of Modem dialing.
Cmd[Input] Input AT control command.
Rsp[Output] Response data.
Parameters
RespLen[Output] Length of response data.
TimeoutMs Waiting time for response.[unit:ms]
RET_OK Succeeded.
ERR_INVALID_PARAM Invalid parameter.
ERR_MDM_CMD_BUF_FULL Command buffer overflow.
ERR_MDM_CMD_TOO_LON
Command is too long.
Return G
Does not support the
ERR_MDM_CMD_NOT_SUPP command. (command that
ORT doesn’t begin with
AT,S3,S7,WT=)
ERR_DEV_NOT_OPEN Device is not open.
1. The function needs to be called before
OsModemConnect(); it is only valid during the current
Instruction
calling process of OsModemConnect().
2. While executing this function, the current dialing or

PAX Computer Technology (Shenzhen) Co., Ltd. 181

 Prolin API Programming Guide

communication process will automatically hang up.

3. The function can be called 100 times continuously at most
and the exceeding callings will be discarded and report
error.

1. The maximum string length is 100 bytes for each call. If

more than 100 bytes, the entire control command will be
discarded and report error.
2. The input control command must be the AT control
command supported by this Modem chip. Otherwise, it
will lead to OsModemConnect( ) failure.

18.9 OsModemHangup

Prototype void OsModemHangup(void);

Function Hang up Modem or terminate 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 so as to allow PABX to
finish hanging up action and transmitting dialing tone again.

18.10 OsModemSend

int OsModemSend(const void *SendBuf,

Prototype
int SendLen);
Function Send data packets through Modem.
SendBuf[Input] Send buffer.
Parameters Length of packets which will be sent.[unit:
SendLen
bytes]
RET_OK Succeeded.
Return
ERR_NOT_CONNECT Not connected.

PAX Computer Technology (Shenzhen) Co., Ltd. 182

 Prolin API Programming Guide

ERR_MDM_TXOVER Send buffer is full.

ERR_MDM_NO_CARRIE
No carrier waves.(Disconnected)
R
ERR_INVALID_PARAM Invalid parameter.
ERR_DEV_NOT_OPEN Device is not open.
The maximum length of sent data is 2048 bytes each time. As
there are 5 additional control characters when called in
Instruction
synchronous communication, the maximum length of received
and sent data are both 2053 bytes.

18.11 OsModemRecv

int OsModemRecv(void *RecvBuf,

Prototype int BufSize,
int Timeout);
Function Receive packets returned from MODEM.
Buffer of received packets. [Buffer size
RecvBuf[Output] can be defined according to actual
practice.]
Parameters Size of RecvBuf.
BufSize The valid buffer size is not more than
2048 bytes.
Timeout Timeout.[ms]
The actual number of received
>= 0
data.
ERR_NOT_CONNECT Not connected.
Return ERR_MDM_NO_CARRIE
No carrier waves.(Disconnected)
R
ERR_INVALID_PARAM Invalid parameter
ERR_DEV_NOT_OPEN Device is not open.
1. The maximum length of received packet is 2048 bytes each
time. As there are 5 additional control characters when
called in synchronous communication, the maximum length
of received and sent data are both 2053 bytes.
Instruction
2. If the size of actually received data is not larger than the
size of specified receive buffer within specified time, it will
return immediately.
3. If there is line error when receiving data, it will immediately

PAX Computer Technology (Shenzhen) Co., Ltd. 183

 Prolin API Programming Guide

return corresponding error code.

4. For SDLC synchronous communication, it will immediately
return after receiving any packet. (Even if the received
packet length is less than the BufSize.)
5. For asynchronous communication, it will return after
receiving BufSize bytes of data; otherwise, it will wait until
timeout.
6. For synchronous receiving, it will receive a complete frame
each time, and its length is not limited by BufSize.
7. For FSK, timeout does not work.

18.12 OsPppomLogin

int OsPppomLogin(const char *Name

const char *Password,
Prototype
long Auth,
int TimeOutMs);
Function Establish Modem PPP network link.
User name.
The valid string length is not more than 50
bytes.
Name[Input] For the 96169 background of China
Telecom, any user name with at least one
character can be entered.
It can’t be NULL.
Password.
The valid string length is not more than 50
bytes.
Parameter Password[Input] For the 96169 background of China
s Telecom, any user name with at least one
character can be entered.
It can’t be NULL.
Authentication algorithms.
The supported authentication algorithms are:
PPP_ALG_PA 0x00 PAP
Auth P 0000 Authentication
01 Algorithm
PPP_ALG_CH 0x00 CHAP
AP 0000 Authentication
02 Algorithm

PAX Computer Technology (Shenzhen) Co., Ltd. 184

 Prolin API Programming Guide

PPP_ALG_MS 0x00 MSCHAPV1

CHAPV1 0000 Authentication
04 Algorithm
PPP_ALG_MS 0x00 MSCHAPV2
CHAPV2 0000 Authentication
08 Algorithm
PPP_ALG_ALL 0xff All
Authentication
Algorithms
Either one type of authentication or several
authentications with (+) or (|) should be
used, for example, PPP_ALG_PAP|
PPP_ALG_CHAP.
If the algorithm is unknown, fill in
PPP_ALG_ALL.
Timeout.[unit:ms]
The valid timeout ranges from 0 to 3600000.
TimeOutMs If timeout<0, it will be automatically set to 0.
If timeout >3600000, it will be automatically
set to 3600000.
PPP_LOGINING In the process of logging in.
RET_OK The link established successfully.

Return ERR_INVALID_PARAM Invalid parameter.

ERR_NET_PASSWD Wrong password.
ERR_NET_SERVER_BUS Server is busy, communication
Y failed.
1. Before calling this function, OsModemConnect() must be call
first and set the ST_MODEM_SETUP.Pppom to 1
(OsModemOpen() doesn’t need to be called).
2. TimeOutMs=0 means no wait time and will return
immediately.
3. Call OsPppomCheck() to check the link status.
4. The login time varies according to the settings of
Instructio
ST_MODEM_SETUP.The maximum asynchronous baud
n rate supported by S800 modem chip is 33600. Dialing-up
when baud rate is not more than 33600 will enjoy a low
re-training rate and high success rate.
5. For 96169 background (Guidway A8010), if re-training
occurrs and the duration time is more than 20 seconds after
sending number, then the background communication will no
longer conform to ppp protocol and fail to establish link.
6. After successfully setup the link, it can communicate through

PAX Computer Technology (Shenzhen) Co., Ltd. 185

 Prolin API Programming Guide

the IP network communication function.

7. If users want to hang up by pressing the cancel button in the
dialing process, operate as follows:
Start a thread and take a 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.13 OsPppomCheck

Prototype int OsPppomCheck(void);

Function Check the link status of Modem network.
Parameters None.
PPP_LOGOUTI
Disconnected.
NG
PPP_LOGINING In the process of logging in.
RET_OK Link is established successfully.
Return ERR_NET_PAS
Wrong password.
SWD
ERR_NET_LOG OsPppomLogout() is called to disconnect
OUT the link.
ERR_NET_IF Link is disconnected.
Instruction

18.14 OsPppomLogout

Prototype int OsPppomLogout(void);

Function Exit network and disconnect Modem PPP link.
Parameters None.
Return RET_OK Succeeded.
Instruction

PAX Computer Technology (Shenzhen) Co., Ltd. 186

 Prolin API Programming Guide

19Network
Communication

Prolin uses unified network protocol stack to manage different physical links. Prolin
provides a standard socket programming for network communication.

19.1 TCP Programming

TPC programming sample code:

/* Server code in C language*/

#include <sys/types.h>
#include <sys/socket.h>
#include <netinet/in.h>
#include <arpa/inet.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <unistd.h>

int main(void)

PAX Computer Technology (Shenzhen) Co., Ltd. 187

 Prolin API Programming Guide

{
struct sockaddr_in stSockAddr;
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);
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)*/
if (-1 == shutdown(ConnectFD, SHUT_RDWR))
{
perror("cannot shutdown socket");

PAX Computer Technology (Shenzhen) Co., Ltd. 188

 Prolin API Programming Guide

close(ConnectFD);
exit(EXIT_FAILURE);
}
close(ConnectFD);
}
return EXIT_SUCCESS;
}
/* Client code in C language*/
#include <sys/types.h>
#include <sys/socket.h>
#include <netinet/in.h>
#include <arpa/inet.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <unistd.h>
int main(void)
{
struct sockaddr_in stSockAddr;
int Res;
int KeepAlive = 1;
int SocketFD = socket(PF_INET, SOCK_STREAM, IPPROTO_TCP);
if (-1 == SocketFD)
{
perror("cannot create socket");
exit(EXIT_FAILURE);
}
Res = setsockopt(SocketFD, SOL_SOCKET, SO_KEEPALIVE, (void
*)&KeepAlive, sizeof(KeepAlive));
if (-1 == Res)
{
perror("cannot set keepalive");
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);
if (0 > Res)
{

PAX Computer Technology (Shenzhen) Co., Ltd. 189

 Prolin API Programming Guide

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;
}

Prolin TCP communication complies with Linux standard.

KeepAlive function is disabled by default, which can be enabled
by calling setsocktopt() to set SO_KEEPALIVE parameter. If
Keepalive is enabled, a detection packet will be sent every 30
seconds when TCP is idle.

19.2 UDP Programming

UDP programming sample code:

#include <stdio.h>
#include <errno.h>
#include <string.h>
#include <sys/socket.h>
#include <sys/types.h>

PAX Computer Technology (Shenzhen) Co., Ltd. 190

 Prolin API Programming Guide

#include <netinet/in.h>
#include <unistd.h> /* for close()socket */
#include <stdlib.h>

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 <stdlib.h>
#include <stdio.h>
#include <errno.h>
#include <string.h>

PAX Computer Technology (Shenzhen) Co., Ltd. 191

 Prolin API Programming Guide

#include <sys/socket.h>
#include <sys/types.h>
#include <netinet/in.h>
#include <unistd.h>
#include <arpa/inet.h>

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. 192

 Prolin API Programming Guide

20Network Configuration

Prolin provides network configuration interfaces, including ARP setting, Ping service,
DNS configuration, network card configuration, DHCP service, routing setting and
PPPoE service etc.

20.1 Return Code List

Table 20.1 Network configuration return code list

Macro Value Description

ERR_NET_SERVER_BAD -3301 IP server is abnormal.
IP server is busy; it can
serve for at most 5
ERR_NET_SERVER_BUSY -3302
applications at the same
time.
ERR_NET_NO_ROUTE -3305 Router is not configured.
Connection is full;
application can establish
ERR_NET_FULL -3306
at most 20 connections
at the same time.
Network interface link
ERR_NET_IF -3307 cannot be used. (The
link is not established or
has no corresponding

PAX Computer Technology (Shenzhen) Co., Ltd. 193

 Prolin API Programming Guide

device.)
TCP / UDP session is
ERR_NET_SESS_BROKEN -3308
disconnected.
ERR_NET_PASSWD -3309 Wrong password.
Application logout
ERR_NET_LOGOUT -3310
actively.
ERR_NET_INIT -3311 Initialization failed.
DHCP Server is not
ERR_NET_DHCP_DISCOVER -3312
found.
DHCP cannot get the IP
ERR_NET_DHCP_OFFER -3313
address.
ERR_NET_DHCP_START -3314 DHCP is not started.
DNS cannot analyze the
ERR_NET_DNS -3315
corresponding domain.
The port specified by the
ERR_NET_SERV_USING -3316
server is in use.
Domain name server is
ERR_NET_NODNServer -3317
not configured.
Link is disconnected by
ERR_NET_LINKDOWN -3318
the server.
Cannot connect to the
ERR_NET_CONN -3319
specified server.
ERR_NET_TIMEOUT -3320 Connection timeout.
ERR_NET_PPP -3321 PPP connection error.
PPPoE server is not
ERR_NET_SERV -3322
found.
Request resource is not
ERR_NET_AGAIN -3323
found, please try again.
Cannot connect to
ERR_NET_AUTH -3324
RADIUS server.
Windows server is not
ERR_PPP_SERV_NOTREADY -3325 ready when connected
to ppp_direc.
ERR_NET_ICMPV6_UNREACH -3327 Target is unreachable.
ERR_NET_ICMPV6_PKT_TOOBI SIZE is greater than the
-3328
G minimum MTU.
TTL exceeds the
ERR_NET_ICMPV6_TIME_EXCE
-3329 maximum value
ED
(default value：64).

PAX Computer Technology (Shenzhen) Co., Ltd. 194

 Prolin API Programming Guide

Protocol parameter
ERR_NET_ICMPV6_PARAMPRO error; cannot process
-3330
B middle route or target
node.
Unrecognizable
ERR_NET_DHCPV6_DNS -3331 keywords or illegal IP
address in Resolv.conf.

DHCPv6 server has no

ERR_NET_DHCP6_SOLICITE -3335
response.

ERR_NET_DHCP6_START -3336 DHCPv6 is not started.

Send request command;
ERR_NET_DHCP6_REQUEST -3337
no correct response.
Send information
ERR_NET_DHCP6_INFORMATIO
-3338 request; no correct
N
response.
ERR_NET_DHCP6_VALID_LIFE -3339 Expired address.
ERR_NET_DHCP6_NOADDRSA
-3340 No available address.
VAIL
ERR_NET_DHCP6_DUPLICATE_
-3341 Address conflict.
ADDR
ERR_ROUTE_EXIST -3360 Route already exists.
The specified route
ERR_ROUTE_NONEXIST -3361
doesn’t exist.
Related operations are
NET_DOING 1 in process (such as
PPP login, DHCP).

20.2 Data Definition

Physical Channel List

Table 20.2 Physical channel list

Macro Description
NET_LINK_ETH Ethernet.
Wireless network, including GPRS, CDMA,
NET_LINK_WL
TDSCDMA

PAX Computer Technology (Shenzhen) Co., Ltd. 195

 Prolin API Programming Guide

NET_LINK_WIFI WiFi
NET_LINK_PPPOE ADSL link
NET_LINK_MODEM Modem PPP link
NET_LINK_PPPDIRECT ppp_direct link
NET_LINK_BT Bluetooth link
NET_LINK_USB USB link

1. All of the macro values listed above are positive integers.

2. For more details, refer to “osal.h”.

IPv6 Status Value List

Table 20.3 IPv6 status value list

Macro Value Description

IP6_STATELESS_ADDR_AUTOCO 0 Stateless address
NFIG auto-configuration.
IP6_DHCP6_STATEFULL_ADDR_C 1 DHCPv6 statefull address
ONFIG configuration.
IP6_DHCP6_STATELESS_ADDR_C 2 DHCPv6 stateless address
ONFIG configuration.

Data Structure

Structure: struct IPv6Info

IPv6Info is used to get an existed IPV6 address, and link address, site address and
global address are different.

Struct IPv6Info
Struct IPv6Info{
char LinkAddr[64]; /*Link address of IPv6,at most 1 link address*/
int NumSiteAddr; /*Number of site address of IPv6*/
char SiteAddr[4][64]; /*Site address of IPv6,at most 4 site
addresses*/
int NumGlobalAddr; /*Number of global address of IPv6*/
char GlobalAddr[8][64]; /*Global address of IPv6,at most 8

PAX Computer Technology (Shenzhen) Co., Ltd. 196

 Prolin API Programming Guide

addresses*/
int NumDns; /*Number of DNS*/
char Dns[2][64]; /*DNS address*/
}

Structure: struct IPv6RouteTable

Get all IPv6 route information in OS:

IPv6RouteTable
struct IPv6RouteTable{
Char RouteNum; /* The number of items in the routing table
*/
Struct {
char DestAddr[64]; /*Prefix of destination address*/
char DestAddrPrefixLen; /*Not supported*/
char NextHop[64]; /*Next hop address*/
}RouteTable[16];
}

Structure: struct DnsAddrInfo

Save the result of domain name resolution:

DnsAddrInfo
struct DnsAddrInfo{
int NumIPv4Addr; /*numbers of IPv4 addr*/
char IPv4Addr[4][16]; /*IPv4 addr*/
int NumIPv6Addr; /*numbers of IPv6 addr*/
char IPv6Addr[4][64]; /*IPv6 addr*/
};

Structure: IPv4RouteTable

Get operating system IPv4 route table:

IPv4RouteTable
struct IPv4RouteTable{
int RouteNum;/* number of Route*/
struct{
char DestAddr[16];/* dest addr*/

PAX Computer Technology (Shenzhen) Co., Ltd. 197

 Prolin API Programming Guide

char GenMask[16]; /* gen mask */

char GateWay[16]; /* Gateway*/
}RouteTable4[16];
}

20.3 IPv4 Network Configuration Interface

The following interfaces only apply to IPv4 network environment.

OsNetAddArp

int OsNetAddArp(int NetLink,

Prototype const char *Addr,
const char MAC[6]);
Function Add IP address to static mapping table of MAC address.
NetLink Physical channel:
 NET_LINK_ETH: Ethernet;
 NET_LINK_WIFI: WiFi;
 NET_LINK_USB: USB

IP address.
Parameters The format is “XXX.XXX.XXX.XXX”. The value
Addr[Input] range of XXX is from 0 to 255. e.g.:
“192.168.0.1”.
It can’t be NULL.
The MAC address corresponding to the IP
MAC[Input] address;
The size of MAC is 6 bytes. It can’t be NULL.
RET_OK Succeeded.
ERR_INVALID_PARAM Invalid parameter.
Return
The network link cannot be used
ERR_NET_IF
(not established or disconnected).
Instruction

1. Static ARP table is used to resist the attack from ARP Cheat.
2. Static ARP table is obtained dynamically, so application
doesn’t need to configure it.

PAX Computer Technology (Shenzhen) Co., Ltd. 198

 Prolin API Programming Guide

OsNetPing

int OsNetPing(const char *Addr,

Prototype
int TimeOutMs);
Send ICMP ECHO_REQUEST request to specified network
Function host and check whether the host can be reachable.
The IP address of target device;
Addr[Input] Format is “XXX.XXX.XXX.XXX”; The value
range of XXX is from 0 to 255, e.g.:
Parameters “192.168.0.3”.
Timeout.[unit:ms]
TimeOutMs The valid timeout ranges from 3000 to
3600000.
RET_OK Succeeded.
The network link cannot be used (not
ERR_NET_IF
established or disconnected).
Return
ERR_INVALID_PARA
Invalid parameter.
M
ERR_TIME_OUT Timeout.
1. The communication is performed with default route.
Instruction
2. Call OsNetGetRoute()to query the current default route.

OsNetPingEx

Prototype int OsNetPingEx(const char *Addr,

int TimeOutMs,
int Size);
Function Ping a specific IP address to check the status of the network
connection.
Parameters IP address of the target device.
Addr[Input] The format is “XXX.XXX.XXX.XXX”. The
value range of XXX is 0~255, e.g.:
“192.168.0.3”.
Timeout[unit:ms]
TimeOutMs
[Input] The valid timeout ranges from 3000 to
3600000.
The size of the data
Size [Input] The valid data size is not more than 1024
bytes.

PAX Computer Technology (Shenzhen) Co., Ltd. 199

 Prolin API Programming Guide

Return Succeeded, the time it takes to

>0
ping.
The network link cannot be used
ERR_NET_IF
(not established or disconnected).
ERR_INVALID_PARAM Invalid parameter.
ERR_TIME_OUT Timeout.
Instruction 1. The communication is performed with default route.
2. Call OsNetGetRoute() to query the current route.

OsNetDns

int OsNetDns(const char *Name,

Prototype char *Addr,
int TimeOutMs);
Analyze the IP address corresponding to the domain name and
Function store the results in structure struct DnsAddrInfo.
Domain name, for example:
[www.sina.com.cn].
Name[Input]
The valid Name is not more than 255
characters and it can’t be NULL.
Addr stores the IP address mapped by the
domain name.
The format is “XXX.XXX.XXX.XXX”. The
Parameters Addr[Output] value range of XXX is from 0 to 255, e.g.:
“192.168.0.3”.
The valid length of Addr should be at least 16
bytes and it can’t be NULL.
Timeout[unit:ms].
TimeOutMs The valid timeout ranges from 1000 to
3600000.
RET_OK Succeeded.
Network link cannot be used (not
ERR_NET_IF
established or disconnected).
ERR_INVALID_PARA
Invalid parameter
Return M
ERR_TIME_OUT Timeout.
Domain name resolution failed, and
ERR_NET_DNS corresponding domain name may not
exist.
Instruction 1. The communication is performed with default route.

PAX Computer Technology (Shenzhen) Co., Ltd. 200

 Prolin API Programming Guide

2. Call OsNetGetRoute() to query the current route.

OsNetDnsEx

int OsNetDnsEx(const char *Name,

Prototype struct DnsAddrInfo *Addr,
int TimeOutMs);
IP address of the corresponding domain name resolution, which
Function will be saved in structure DnsAddrInfo.
Domain name, for example:
[www.sina.com.cn].
Name[Input]
The valid Name is not more than 255
characters and it can’t be NULL.
Parameters Store the IP address mapped by the
Addr[Output]
domain name.
Timeout[unit：ms]the valid value ranges
TimeOutMs [Input]
from 1000 to 3,600,000.
RET_OK Success
Network link cannot be used (not
ERR_NET_IF
established or disconnected).
ERR_INVALID_PARAM Invalid parameter
ERR_TIME_OUT Timeout
Return Domain name resolution failed, and
ERR_NET_DNS corresponding domain name may
not exist.
ERR_NET_SERVER_BA
IP server exception.
D
The domain name server is not
ERR_NET_NODNServer
configured.
1. The default router has been adopted to do the
communication, OsNetGetRoute() can be called to check
the current default router;
2. OsNetDnsEx() supports IPv4 and IPv6 domain name
Instruction resolution;
3. OsNetDnsEx() can return a maximum number of 4 IPv4
addresses and 4 IPv6 addresses for one domain name;
4. It is recommended to call OsNetDnsEx() to do the domain
name resolution instead of OsNetDns().

PAX Computer Technology (Shenzhen) Co., Ltd. 201

 Prolin API Programming Guide

OsNetSetConfig

int OsNetSetConfig(int NetLink,

const char *Addr,
Prototype const char *Mask,
const char *Gateway,
const char *DNSServer);
Function Configure the local network.
Physical channel:
 NET_LINK_ETH: Ethernet;
NetLink  NET_LINK_WIFI: WiFi;
 NET_LINK_BT: Bluetooth;
 NET_LINK_USB: USB.

POS terminal address.

The format is
“XXX.XXX.XXX.XXX”.The value range
of XXX is from 0 to 255, e.g.:
Addr[Input]
“192.168.0.3”.
If the address is “” or NULL, the
previous configuration will remain
unchanged.
POS terminal mask code.
Format is “XXX.XXX.XXX.XXX”; e.g.:
“255.255.255.0”;
Parameters Mask[Input] If the mask code is “” or NULL, the
previous configuration will remain
unchanged.
Address of the default gateway.
Format is “XXX.XXX.XXX.XXX”.XXX
ranges from 0 to 255, e.g.:
Gateway[Input] “192.168.0.1”.
If the address is “” or NULL, the
previous configuration will remain
unchanged.
DNS server address
Format is “XXX.XXX.XXX.XXX”. XXX
ranges from 0 to 255. e.g.:
DNSServer[Input] “192.168.0.1”;
If the address is “” or NULL, the
previous configuration will remain
unchanged.

PAX Computer Technology (Shenzhen) Co., Ltd. 202

 Prolin API Programming Guide

RET_OK Succeeded
Network link cannot be used (not
ERR_NET_IF
Return established or disconnected).
ERR_INVALID_PAR
Invalid parameter.
AM
1. The DHCP function will be stopped after calling this function
successfully.
2. The function only checks the validity of Addr, Mask and
Gateway’s formats without checking the matching relation
Instruction between them.
3. Wireless link, PPPoE, and ModemPPP is dynamically
allocated and cannot be configured by this interface.
4. After configuring network information successfully, this link
will be set as the default route.

OsNetGetConfig

int OsNetGetConfig(int NetLink,

char *Addr,
Prototype char *Mask,
char *Gateway,
char *DNSServer);
Function Get the network information.
Physical channel:
 NET_LINK_ETH: Ethernet;
NetLink  NET_LINK_WIFI: WiFi.
 NET_LINK_BT: Bluetooth;
 NET_LINK_USB: USB.

POS terminal address.

The size of Addr should be at least 16 bytes.
Addr[Output] The format is “XXX.XXX.XXX.XXX”, XXX
Parameters ranges from 0 to 255, e.g.: “192.168.0.3” and it
can be NULL.
POS terminal mask code.
Mask[Output] The size should beat least 16 bytes. Format is
“XXX.XXX.XXX.XXX”, e.g.: “255.255.255.0”
and it can be NULL.
Address of the default gateway.
Gateway[Out The size of Gateway should be at least 16
put] bytes. Format is “XXX.XXX.XXX.XXX”. XXX
ranges from 0 to 255, e.g.: “192.168.0.1” and it

PAX Computer Technology (Shenzhen) Co., Ltd. 203

 Prolin API Programming Guide

can be NULL.
DNS server address.
The size of DNSServer should be at least 16
DNSServer[In
bytes. Format is “XXX.XXX.XXX.XXX”, XXX
put]
ranges from 0 to 255.
e.g.: “192.168.0.1” and it can be NULL.
RET_OK Succeeded.
Return Network link cannot be used (not established or
ERR_NET_IF
disconnected).
Instruction

If Addr, Mask, Gateway and DNSServer returns the string “”, it

means the network has not been configured.

OsNetStartDhcp

Prototype int OsNetStartDhcp(int NetLink);

Function Start DHCP to obtain dynamic address.
Physical channel:
 NET_LINK_ETH: Ethernet;
Parameters NetLink  NET_LINK_WIFI: WiFi;
 NET_LINK_BT: Bluetooth;
 NET_LINK_USB: USB

RET_OK Succeeded.
Return
ERR_NET_IF Ethernet or WiFi module is not configured.
1. This interface is just used to start the DHCP and will not wait
for the address allocation process.
2. OsNetCheckDhcp() can be called to check the status of
Instruction
address allocation.
3. After obtaining the address successfully, this link will be set
as the default route.

PAX Computer Technology (Shenzhen) Co., Ltd. 204

 Prolin API Programming Guide

Please close all the connections before starting DHCP;

otherwise, these connections may fail to communicate.

OsNetCheckDhcp

Prototype int OsNetCheckDhcp(int NetLink);

Function Check DHCP status.
Physical channel:
 NET_LINK_ETH: Ethernet;
Parameters NetLink  NET_LINK_WIFI:WiFi;
 NET_LINK_BT: Bluetooth;
 NET_LINK_USB: USB

NET_DOING DHCP is getting the address.

RET_OK Dynamic allocation succeeded.
ERR_NET_DHCP_DISC
DHCP Server is not found.
OVER
Return
ERR_NET_DHCP_OFFE
DHCP cannot get IP address.
R
ERR_NET_DHCP_STAR
DHCP is not started.
T
Instruction

OsNetStopDhcp

Prototype void OsNetStopDhcp(int NetLink);

Function Stop DHCP.
Physical channel:
 NET_LINK_ETH: Ethernet;
Parameters NetLink  NET_LINK_WIFI:WiFi;
 NET_LINK_BT: Bluetooth;
 NET_LINK_USB: USB

Return None.
1. If the DHCP is stopped, OsNetSetConfig() shall be called to
re-configure the network;
Instruction 2. After a successful DHCP, the system will update the
configuration information at regular interval; if the update
fails, the network will be unavailable.

PAX Computer Technology (Shenzhen) Co., Ltd. 205

 Prolin API Programming Guide

OsPppoeLogin

int OsPppoeLogin(const char *Name,

Prototype const char *Password,
int TimeOutMs);
Function PPPoE link login.
User name.
The valid length ranges from 0 to 50 bytes.
Name[Input]
It can’t be NULL. If there is no user name, a null
string “” can be used instead.
Password.
Parameters
Password[Inp The valid length ranges from 0 to 50 bytes.
ut] It can’t be NULL. If there is no password, a null
string “” can be used instead.
Timeout.[unit:ms]
TimeOutMs
The valid timeout ranges from 0 to 3600000.
NET_DOING Logging in/out.
Return RET_OK Succeeded.
<0 Failed.
After established successfully, this link will be set as the default
Instruction
route.

OsPppoeCheck

Prototype int OsPppoeCheck(void);

Function Check the status of PPPoE link.
Parameters None.
NET_DOING Logging in/out.
Return RET_OK The link is established successfully.
<0 The link is disconnected.
Instruction

OsPppoeLogout

Prototype void OsPppoeLogout(void);

Function Disconnect the PPPoE link.
Parameters None.

PAX Computer Technology (Shenzhen) Co., Ltd. 206

 Prolin API Programming Guide

Return None.
Instruction

OsNetSetRoute

Prototype int OsNetSetRoute(int NetLink);

Function Set system default route.
Physical channel, please refer to Physical
Parameters NetLink
channel list
Succeeded, the new route came into
RET_OK
effect.
Return
ERR_INVALID_PARAM Invalid parameter.
ERR_NET_IF This link has not been set up.
1. It is not necessary to call this function to set the default route
if there is only one link.
2. If there are several links, this function can be called to
switch the default route.
Instruction 3. It is allowed to switch default only when the network link has
been set up successfully, otherwise ERR_NET_IF will be
returned.
4. Switching the default route during communication process
will cause communication failure.

OsNetGetRoute

Prototype int OsNetGetRoute(void);

Function Get the default route.
Parameters None
Physical channel, please refer to
>0
Physical channel list .
Return
ERR_NET_NO_ROU
No default route.
TE
In following situations, ERR_NET_NO_ROUTE will be returned.
1. No link has been set up.
2. The last used link is logged out, as any link that has been
Instruction set up successfully will be configured as the default route. If
the last used link is logged out, the route will be deleted. At
this time, OsNetSetRoute() shall be called to set route
again.

PAX Computer Technology (Shenzhen) Co., Ltd. 207

 Prolin API Programming Guide

OsNetSetRouteTable

int OsNetSetRouteTable(int NetLink,

const char *DestAddr,
Prototype
const char *GenMask,
const char *GateWay)；
Function Add IPv4 static address to the route table.
Physical channel, please refer to
NetLink
Physical channel list.

Parameters DestAddr Destination network address

GenMask Mask address of destination network
GateWay Gateway address
RET_OK Success
ERR_INVALID_PAR
Invalid parameter
AM
ERR_NET_SERVE
IP server exception
Return R_BAD
ERR_NET_SERVE
IP server busy
R_BUSY
ERR_ROUTE_EXIS
Route already exists
T
1. Calling this function will add IPv4 static address to the
route table. Normally, the network communication data will
go through the default route, there is no need to add the
route information manually.
2. For Prolin system, only one default route is allowed. When
there are multiple network cards, application may need to
call OsNetSetRouteTable() add the static route to the
Instruction
specified link to make sure each link can communicate
with the external network at the same time.
3. When application calls this function to add static route, the
system will only check the validity of each parameter, to
ensure the communication will not have exception,
application needs to check that the inputting parameters
actually apply to the current network.

OsNetDelRouteTable

int OsNetDelRouteTable(int NetLink,

Prototype const char *DestAddr,
const char *GenMask);

PAX Computer Technology (Shenzhen) Co., Ltd. 208

 Prolin API Programming Guide

Function Delete the specified IPv4 address from the router.

Physical channel, please refer to
NetLink
Physical channel list.
Parameter
s DestAddr Destination network address
GenMask Mask of destination address
RET_OK Success
ERR_INVALID_PARA
Invalid parameter
M
ERR_NET_SERVER_
IP server exception
Return BAD
ERR_NET_SERVER_
IP server busy
BUSY
ERR_ROUTE_NONE
Route doesn’t exist
XIST
When application calls this function to delete a certain route,
system will only check the validity of each parameter,
Instruction
application also needs to ensure that the current communication
will not be affected after the specified route has been deleted.

OsNetGetRouteTable

int OsNetGetRouteTable(int NetLink,

Prototype struct IPv4RouteTable
*RouteTable)；
Function Acquire the specified IPv4 route.
Physical channel, please refer to
NetLink
Physical channel list.
Parameters Structure that is used to receive the
RouteTable IPv4 route table information:
IPv4RouteTable.
RET_OK Success
ERR_INVALID_PAR
Invalid parameter
AM
ERR_NET_SERVE
IP server exception.
Return R_BAD
ERR_NET_SERVE
IP server is busy
R_BUSY
ERR_SYS_BAD System error
ERR_MEM_FAULT Memory error

PAX Computer Technology (Shenzhen) Co., Ltd. 209

 Prolin API Programming Guide

ERR_NET_SESS_B
Connection error
ROKEN
Application can call OsNetGetRouteTable() to acquire the
Instruction
route information of IPv4 address.

OsNetNat

Prototype int OsNetNat(int DestLink);

Function Set up network data forwarding.
A link used to forward packets out.
The value of DestLink can refer to the
definition of physical channel list; When
DestLink is 0, the data will be forwarded from
Parameters DestLink [Input] the link where the default route of the current
system is located. To avoid forwarding failure
due to routing table configuration problems, it
is recommended to set the data to be
forwarded from the link where the default
route is located.
RET_OK Succeeded
Return ERR_NET_IF This link has not been set up.
ERR_NET_SERVER_BAD IP server exception
1. Before configuring forwarding, please ensure that the
network parameters set in the forwarding device are
normal, and the forwarding device can communicate with
the destination host which the packet sent by the forwarded
device normally;
2. When forwarding data in multi-link devices, please
configure a reasonable routing table, otherwise the data
may not be forwarded normally due to improper
Instruction configuration of the routing table;
3. After the application successfully calls this function, the
system will forward the non-native packets in the
destination address received through DestLink link;
4. This function can be called multiple times in the forwarding
device to set up different forwarding links, so that different
packets in the destination host can be forwarded from
different links together with reasonable routing table
configuration.

PAX Computer Technology (Shenzhen) Co., Ltd. 210

 Prolin API Programming Guide

20.4 IPv4/IPv6 Network Configuration Interface

The following interfaces apply to both IPv4 and IPv6 network environment.

OsNetSetDns

Prototype int OsNetSetDns(const char *Dns);

Function Set DNS address.
Parameters Dns[Input] DNS address.
RET_OK Succeeded.
Return ERR_INVALID_PARA
Invalid parameter.
M
1. The system can set 2 DNS addresses at most (doesn’t
distinguish IPv4 or IPv6). If two addresses are needed,
users should call this function to set the slave DNS
address first, and then call this function to set the master
DNS address.
2. The settings will remain valid after a system reboot.
3. DNS is stored in /etc/resolv.conf, through which
Instruction applications can check the current DNS.
4. By default, if DHCP is enabled, DNS server address set by
this function may fail, and the DNS server address set by
this function may be overridden by the address of DHCP
DNS server. If DNS server address set by this function is
needed when DHCP is enabled, users can call
OsRegSetValue() to set “persist.sys.dns.static” to “1”, and
then call this function to set static DNS server address,
and enable DHCP in the end.

20.5 IPv6 Network Configuration

The following interfaces only apply to IPv6 network environment.

OsNetPing6

int OsNetPing6(const char *DestAddr,

const char *SrcAddr,
Prototype
int TimeOutMs,
int size);
Send request message ICMPv6 ECHO_REQUEST to the
Function
specified network host.

PAX Computer Technology (Shenzhen) Co., Ltd. 211

 Prolin API Programming Guide

IPv6 address of the target network host.

DestAddr[input]
E.g.: “2015:10::5”.
Source IPv6 address. E.g.: “2015:10::6”.
SrcAddr[input] SrcAddr is the default address allocated by
the system when it is NULL.
Parameters
Timeout[unit: ms]
TimeOutMs The valid timeout ranges from 3,000 to
3,600,000.
The load size of the request message.
size
The valid size is not more than 1,500 bytes.
Succeeded. Time spent by ping(unit:
>=0
ms).
The link is not established or is
ERR_NET_IF
disconnected.
ERR_INVALID_PARA
Invalid parameter.
M
ERR_TIME_OUT Timeout.

Return ERR_NET_ICMPV6_P SIZE is greater than the minimum

KT_TOOBIG MTU.
ERR_NET_ICMPV6_U
Target is unreachable.
NREACH
ERR_NET_ICMPV6_TI TTL exceeds the maximum value
ME_EXCEED (TTL default value is 64).
Protocol parameter error. Cannot
ERR_NET_ICMPV6_P
process the middle route or
ARAMPROB
destination node.
For example:
Instruction int ret;
ret=OsNetPing6("2015:10::5","2015:10::6",9000,56).

OsNetSetIPv6Addr

int OsNetSetIPv6Addr(int NetLink,

Prototype const char *Addr,
int PrefixLength);
Function Set static IPV6 address.
Physical channel:
Parameter NetLink  NET_LINK_ETH: Ethernet.
s
Addr IPv6 address.

PAX Computer Technology (Shenzhen) Co., Ltd. 212

 Prolin API Programming Guide

[Input] E.g.: “2015:30::10”.

Length of the IPv6 address prefix.
PrefixLength The valid length ranges from 1 to 128 bits.
[Input] The PrefixLength will be set to 64 by default
if it is 0.
RET_OK Succeeded.
The link is not established or is
ERR_NET_IF
disconnected.
Return The setting address is in conflict with
ERR_NET_DHCP6_DU
a certain node address in local area
PLICATE_ADDR
network, setting address failed.
ERR_INVALID_PARAM Invalid parameter.
1. The static IPV6 address doesn’t need to be set manually; it
can be obtained automatically from the router by terminal or
obtained by DHCPv6 server after starting DHCPv6.
2. All static IPv6 addresses will be cleared when device is
Instructio
powered down.
n
3. Prolin supports link address, site address and global
address. And each kind of address can only be set for one
address. For example, if a global address has been set, the
new setting will replace the original global address.

OsNetGetIPv6Addr

int OsNetGetIPv6Addr(int NetLink,

Prototype
struct IPv6Info *AddrInfo);
Function Get IPv6 and DNS address of specified physical channel.
Physical channel:
NetLink
 NET_LINK_ETH: Ethernet.
Parameters
AddrInfo Output classified IPv6 and DNS address,
[Output] IPv6Info structure.
RET_OK Succeeded.
The link is not established or is
ERR_NET_IF
Return disconnected.
ERR_INVALID_PARA
Invalid parameter.
M
For example：
Instruction struct IPv6Info AddrInfo;
ret = OsNetGetIPv6Addr(NET_LINK_ETH,&AddrInfo);

PAX Computer Technology (Shenzhen) Co., Ltd. 213

 Prolin API Programming Guide

OsNetGetRouteAdvertise6

int OsNetGetRouteAdvertise6(int NetLink,

Prototype int TimeOutMs,
int *RouteMode);
Function Get the working mode of router within specified time.
Physical channel:
NetLink
NET_LINK_ETH: Ethernet.
Waiting time for router to respond. (Unit: ms)
TimeOutMs The valid timeout ranges from 1,000 to
5,000.
[Input]
If the value <1,000, it will be set to 1,000; If
the value> 5,000, it will be set to 5,000.
Working modes of router:
Parameters 1.
IP6_STATELESS_ADDR_AUTOCONFIG:
Stateless address auto-configuration.
RouteMode 2.IP6_DHCP6_STATEFULL_ADDR_CONFI
[Output] G:
DHCPv6 stateful address configuration.
3.IP6_DHCP6_STATELESS_ADDR_CONFI
G:
DHCPv6 stateless address configuration.
RET_OK Succeeded.
Return
ERR_TIME_OUT Timeout; have no response.
1. Stateless address auto-configuration: IPV6 address is
automatically generated according to the address prefix
assigned by router RA; but DNS needs to be set manually.
2. DHCPv6 stateful address configuration: get IPv6 address
and DNS address.
3. DHCPv6 stateless address configuration: get DNS
information.
Instruction For example：
int ret,route_mode;
ret=OsNetGetRouteAdvertise6(NET_LINK_ETH,3000,&
route_mode);
if(ret == RET_OK)
{
switch (route_mode)
{

PAX Computer Technology (Shenzhen) Co., Ltd. 214

 Prolin API Programming Guide

Case IP6_STATELESS_ADDR_AUTOCONFIG:
break; /*do not need to call DHCPv6*/
Case IP6_DHCP6_STATEFULL_ADDR_CONFIG :
ret=OsNetStartDhcp6(NET_LINK_ETH,IP6_DHC
P6_STATEFULL_ADDR_CONFI
G);
if(ret != RET_OK)
{……};
break;
Case IP6_DHCP6_STATELESS_ADDR_CONFIG:
ret=OsNetStartDhcp6(NET_LINK_ETH,IP6_DHC
P6_STATELESS_ADDR_CONFI
G);
if(ret != RET_OK)
{……};
break;
}
}
……

OsNetStartDhcp6

int OsNetStartDhcp6(int NetLink,

Prototype
int state);
Start DHCPv6 function to get the dynamically assigned IPv6
Function
address and DNS address.
Physical channel:
NetLink
 NET_LINK_ETH: Ethernet.
IP6_DHCP6_STATEFULL_ADDR_CONFIG
:
Parameters
state DHCPv6 stateful address configuration.
[Input] IP6_DHCP6_STATELESS_ADDR_CONFIG
:
DHCPv6 stateless address configuration.
RET_OK Succeeded.
NET_DOING Repetitive execution.
The link cannot be used (not
Return ERR_NET_IF
established or disconnected).

ERR_INVALID_PARA
Invalid parameter (AddrInfo is NULL).
M

PAX Computer Technology (Shenzhen) Co., Ltd. 215

 Prolin API Programming Guide

1. DHCPv6 stateful address configuration mode can get the

IPv6 address and DNS information.
2. DHCPv6 stateless address mode can only get DNS
Instruction
information.
3. OsNetGetRouteAdvertise6() shall be called first to select
the type of DHCPv6.

OsNetCheckDhcp6

Prototype int OsNetCheckDhcp6(int NetLink);

Function Get the current working status of DHCPv6.
Physical channel:
Parameters NetLink
 NET_LINK_ETH: Ethernet.
RET_OK Succeeded.
The link cannot be used (not
ERR_NET_IF
established properly or disconnected)
In process of assigning IPv6 and DNS
NET_DOING
address.
ERR_NET_DHCP_ST
OsNetStartDhcp6() is not executed.
ART
ERR_NET_DHCP6_S
DHCPv6 server has no respon
OLICITE
ERR_NET_DHCP6_R DHCPv6 server has not responded
Return
EQUEST correctly to REQUEST command.
DHCPv6 server has not responded
ERR_NET_DHCP6_IN
correctly to INFORMATION
FORMATION
REQUEST command.
Only DHCPv6 stateful mode can be
returned: the valid life time has been
ERR_NET_DHCP6_V
expired, and the IPv6 address, for
ALID_LIFE
which previously applied has been
released.
ERR_NET_DHCP6_N DHCPv6 server has no available
OADDRSAVAIL address to assign.
1. DHCPv6 stateful mode can get the IPv6 and DNS address.
Instruction 2. DHCPv6 stateless working mode can only get DNS
address.

OsNetStopDhcp6

Prototype int OsNetStopDhcp6(int NetLink);

PAX Computer Technology (Shenzhen) Co., Ltd. 216

 Prolin API Programming Guide

Function Stop DHCPv6 server from running.

Physical channel:
Parameters NetLink
 NET_LINK_ETH: Ethernet.
RET_OK Succeeded.
Return
ERR_NET_IF The link cannot be used.
The existing IPV6 and DNS address are reserved. The DNS will
Instruction
not be renewed, and address will be invalid after restarting.

OsNetSetRouteTable6

int OsNetSetRouteTable6(int NetLink,

const char *DestAddr,
Prototype
int DestAddrPrefixLength,
const char *NextHop);
Function Set IPv6 static routing table
Physical link:
NetLink
 NET_LINK_ETH Ethernet
Destination address:
DestAddr[Input]
E.g. : “2001:20::”; “::”.
Parameters DestAddrPrefixLen
gth The length of prefix destination address,
ranging from 0 to 128.
[Input]
Gateway address:
NextHop[Input]
E.g.: “fe80:9::23”; “::”.
RET_OK Succeeded
The link is not established or is
ERR_NET_IF
Return disconnected.
ERR_INVALID_PARA
Invalid parameter
M
For example:
int ret;
ret=OsNetSetRouteTable6(NET_LINK_ETH,"2016::",128,"
fe80:99::99");
Instruction
1. The setting addresses will be all cleared if the device
powers down.
2. The terminal will automatically acquire the static routing
table from the router without any manual setting.

PAX Computer Technology (Shenzhen) Co., Ltd. 217

 Prolin API Programming Guide

OsNetGetRouteTable6

int OsNetGetRouteTable6(int NetLink,

Prototype struct IPv6RouteTable
*RoutingTable);
Function Get the information of specified routing table.
Physical link:
NetLink
 NET_LINK_ETH Ethernet
Parameters
RoutingTable[Outp
IPv6RouteTable structure
ut]
RET_OK Succeeded
The link is not established or is
ERR_NET_IF
Return disconnected.
ERR_INVALID_PARA
Invalid parameter
M
Example:
struct IPv6RouteTable routing_table;
Instruction ret=
OsNetGetRouteTable6(NET_LINK_ETH,&routing_table);
The acquired content doesn’t include network interface “lo”.

PAX Computer Technology (Shenzhen) Co., Ltd. 218

 Prolin API Programming Guide

21GPRS/CDMA

Prolin supports GPRS and CDMA network and provides a series of related APIs for
developers.

21.1 Return Code List

Table 21.1 GPRS/CDMA return code list

Macro Value Description

PPP_LOGINING 1 PPP is logging in.
PPP_LOGOUTING 2 PPP is logging out.
CSD dialup serviceis
WL_CSD_READY 3
ready
GPRS and CSD dialup
WL_GPRS_CSD_READY 4
service are ready.
In the process of
ERR_WL_POWER_ONING -3501 powering on the wireless
module.
Wirless module is
ERR_WL_POWER_OFF -3502
powered off.
Module fails to be
ERR_WL_NOT_INIT -3503 initialized and cannot
work normally.

PAX Computer Technology (Shenzhen) Co., Ltd. 219

 Prolin API Programming Guide

ERR_WL_NEEDPIN -3504 SIM card needs PIN.

ERR_WL_RSPERR -3505 Module response error.
ERR_WL_NORSP -3506 Module has no response.
ERR_WL_NEEDPUK -3507 SIM card needs PUK.
ERR_WL_WRONG_PIN -3508 PIN error of SIM card.
ERR_WL_NOSIM -3509 No SIM card.
ERR_WL_NOREG -3510 Cannot register network.
ERR_WL_AUTO_RST -3511 Automatic reset.
ERR_WL_BUF -3512 Module memory error.
Module is getting signal,
ERR_WL_GET_SIGNAL -3513
please wait 3s.
ERR_WL_NOTYPE -3514 Unrecognisable module.
PPP is on line; it cannot
ERR_WL_PPP_ONLINE -3515
sleep.
ERR_WL_ERR_BUSY -3516 Module is busy.
Module is entering sleep
ERR_WL_SLEEP_ONING -3517
mode.
ERR_WL_SLEEP_FAIL -3518 Fail to sleep.
ERR_WL_SIM_FAILURE -3519 Fail to operate SIM card.

21.2 Wireless Module Interface

OsWlLock

Prototype int OsWlLock(void);

Open wireless module, set up a link with Prolin wireless server
Function and acquire the permission to wireless device/module.
Parameters None.
RET_OK Succeeded.
ERR_DEV_BUSY Module/device is busy.
Module/device does not
ERR_DEV_NOT_EXIST
Return exist.
ERR_BATTERY_VOLTAGE_TOO
Battery voltage is too low.
_LOW
ERR_BATTERY_ABSENT Battery is absent.
Instruction 1. This function must be called to open the wireless module

PAX Computer Technology (Shenzhen) Co., Ltd. 220

 Prolin API Programming Guide

first before calling OsWlInit(), OsWlPowerSwitch(),

OsWlLogin() or OsWlLogout().
2. OsWlUnLock() shall be called to close wireless module
after finishing the operation.
3. S920 and D200 mobile terminals need to be powered by
battery; otherwise, ERR_BATTERY_ABSENT will be
returned.
4. When the battery voltage is 0, module cannot work normally
and ERR_BASENT_VOLTAGE_TOO_LOW will be
returned.

OsWlUnLock

Prototype void OsWlUnLock(void);

Release the usage rights of wireless device and disconnect
Function from Prolin wireless service.
Parameters None.
Return None.
Instruction

OsWlInit

Prototype int OsWlInit(const char *SimPin);

Function Initialize wireless device.
A pointer to SIM card PIN.
The valid string length is less than 50
Parameters SimPin[Input] bytes.
It can be NULL, which means it doesn’t
need any password.
RET_OK Succeeded.
ERR_DEV_NOT_OPEN Module/device is not open.
ERR_DEV_NOT_EXIST Module/device does not exist.
ERR_NO_PORT Physical serial port is not enough.
ERR_WL_NEEDPIN SIM card needs PIN.
Return
ERR_WL_RSPERR Module/device response error.
ERR_WL_NORSP No response.
ERR_WL_NEEDPUK SIM card needs PUK.
ERR_WL_WRONG_PIN PIN error.
ERR_WL_NOSIM No SIM card.

PAX Computer Technology (Shenzhen) Co., Ltd. 221

 Prolin API Programming Guide

ERR_WL_NOTYPE Unrecognizable module.

ERR_WL_NOREG Fail to register GPRS network.
1. OsWlLock() needs to be called successfully before calling
this function.
2. The password is automatically checked by SIM card.
3. Prolin OS ensures wireless device/module is powered on.
4. When SIM card is absent, OsWlInit() returns
Instruction ERR_WL_NOSIM and the application can only use some
functions that do not need SIM card.
5. After calling OsWlSwitchPower(), wireless module/device
needs around 15 seconds to initialize itself. Application
should wait at least 15 seconds until the module becomes
stable; otherwise, OsWlInit() may fail.

OsWlInitEx

intOsWlInitEx(constchar*SimPin,
intTimeOutMs,
Prototype
char*CmeString,
int Size);
Function Initialize wireless device.
A pointer to SIM card PIN.
The valid string length is less than 50
SimPin[Input] bytes.
It can be NULL, which means it doesn’t
need any password.
Timed out time,[unit:ms];
Parameters Valid range is from 25000 to 100000;
TimeOutMs[Input] When the time is less than 25000, it will
be set to 25000 automatically;
When the time is more than 100000, it
will be set to 100000 automatically.
CmeString[Output] Reserved. Current value is NULL.
Size[Input] Reserved. Current value is 0.
WL_CSD_READY CSD dialupservice is ready.
WL_GPRS_CSD_RE GPRS and CSD dialup service are
ADY ready.
Return
ERR_DEV_NOT_OP
Device/ module is not open.
EN
ERR_DEV_NOT_EXI Wireless device/ module does not

PAX Computer Technology (Shenzhen) Co., Ltd. 222

 Prolin API Programming Guide

ST exist.
There’s no physics serial port for
ERR_NO_PORT
terminal.
ERR_WL_NEEDPIN SIM card needs PIN.
ERR_WL_RSPERR Device/ module response error.
ERR_WL_NORSP Module has no response.
ERR_WL_NEEDPUK SIM card needs PUK.
ERR_WL_WRONG_
PIN error.
PIN
ERR_WL_NOSIM There’s no SIM card.
ERR_WL_PPP_ONLI
PPP online.
NE
ERR_WL_NOREG Could not register to the network.
ERR_INVALID_PAR
Invalid parameter.
AM
1. Before calling this function,OsWlLock() needs to be called
successfully;
2. SIM card will check PIN automatically;
3. ProlinOS will ensure wireless device/ module has powered
up;
4. When there’s no SIM card inside the terminal, application
can only use the functions which do not need SIM card;
5. After calling OsWlSwitchPower() to power up, application
program needs to wait more than 15 seconds to execute
OsWlInitEx(), otherwise, it may return failure which caused
Instruction by unstable module;
6. When ERR_WL_NOREG is returned, application program
should stop dialing and other operations.
7. When WL_CSD_READY is returned, it indicates that
application program can process CSD service;
8. When WL_GPRS_CSD_READY is returned, it indicates that
application program can process GPRS or CSD service;
9. If CSD service is being used now, and GPRS service will be
used in the future, OsWlInitEx() needs to be called to
reinitialize.
10. When PPP is online, calling OsWlInitEx() will return error.

OsWlSwitchPower

Prototype int OsWlSwitchPower(int OnOff);

Function Power on /off wireless module.
Parameters OnOff[Input] The state of wireless device:

PAX Computer Technology (Shenzhen) Co., Ltd. 223

 Prolin API Programming Guide

 1: on
 0: off
RET_OK Succeeded.
ERR_DEV_NOT_E
Wireless module does not exist.
Return XIST
ERR_DEV_NOT_O
Fail to call OsWlLock().
PEN
1. Please reboot terminal to reset wireless module in special
cases such as always failing to call OsWlLogin().
2. Unless it is a special occasion, it is not recommended to call
this function. Because after calling this function to power off
Instruction the wirelss module,the wireless network needs to be
registered again when powering on the wireless device,
which will descrease the success rate of OsWlLogin().

1. The power-on duration depends on wireless module itself.

2. Power off module will cut off module’s power supply.
3. If a terminal has wireless module/deivce, the wirelss
module/device will be powered on by default during the
startup of Prolin OS.
4. The time interval between power-off and power-on again
should be at least 8 seconds. If application has not wait long
enough and is being powered on right away, it will be blocked
long enough first and then be powered on.
5. Prolin will disconnect ppp link automatically as soon as
wireless module/deice is powered off.
6. After wireless module/device is switched from power-off to
power-on, Prolin wireless service will be blocked for 15
seconds before responding to operations such as
OsWlInit(). The system will wait 15 seconds to work normally
to initialize module, get signal and other operations. For
example, when performing login operation, the system will
wait 15 seconds before logging in, resulting in a long login
time.

OsWlSwitchSleep

Prototype int OsWlSwitchSleep(int OnOff);

Function Set wireless device to be slept or woken up.
 1: Sleep.
Parameters OnOff[Input]  0: Wake up.
 Others: Unknown error.

PAX Computer Technology (Shenzhen) Co., Ltd. 224

 Prolin API Programming Guide

RET_OK Succeeded.
ERR_DEV_NOT_EXIS
Module does not exist.
T
Return ERR_DEV_NOT_OPE
Fail to call OsWlLock().
N
ERR_WL_PPP_ONLI
PPP is online.
NE
Instruction It is reserved and yet not supported.

If PPP is on line, wireless module/device will be unable to sleep.

For MG323, it will not sleep in the following cases:

 no SIM card,

 deactivated PIN,

 not registered to network.

OsWlGetSignal

Prototype int OsWlGetSignal(void);

Function Get wireless signal strength.
Parameters None.
Signal strength.
0~5 0 means no signal; 5 means the
strongest signal.

Return ERR_DEV_NOT_EXIST Module does not exist.

ERR_WL_RSPERR Module response error.
ERR_WL_POWER_ONI In the process of powering on the
NG module.
1. OsWLock() does not need to be called before calling this
function;
2. When the wireless link is not established, the signal values
will be directly gotten from module through AT commands.
Instruction
3. After establishing a wireless link, the module is in the data
exchange mode and can’t obtain the real-time signal
strength. Calling OsWlGetSignal()at this time will return
ERR_WL_RSPERR.

PAX Computer Technology (Shenzhen) Co., Ltd. 225

 Prolin API Programming Guide

4. This function shall not be called until OsWlInit() returns

RET_OK.

OsWlCheck

Prototype int OsWlCheck(void);

Function Query the status of wireless link.
Parameters None.
PPP_LOGOUTING Module is disconnecting link.
bPPP_LOGINING Module is establishing link.
RET_OK Establish link successfully.
ERR_DEV_NOT_EXIST Module does not exist.
ERR_WL_POWER_ONI In the process of powering on the
NG module.
Return
ERR_WL_POWER_OF
Module is powered off.
F
ERR_WL_NOT_INIT Fail to initialize module.
ERR_NET_PASSWD Wrong password.
ERR_NET_LOGOUT OsWlLogout() disconnects the link.
Link cannot be used (not established
ERR_NET_IF
or disconnected).
Instruction

OsWlLogin

int OsWlLogin(const char *APN,

const char *Name,
const char *Password,
Prototype long Auth,
int TimeOutMs,
int KeepAlive,
int ReserParam);
Function Login wireless network and set up a wireless link.
For GPRS communication, APN is access
point name. For CDMA, APN is the dialing
number.
Parameters APN[Input]
The valid length is from 0 to 50 characters.
When it is NULL, the protocol stack will
directly login PPP after the application

PAX Computer Technology (Shenzhen) Co., Ltd. 226

 Prolin API Programming Guide

dialing up.
User name.
The valid string length ranges from 0 to 50
Name[Input] characters.
It can’t be NULL. If there is no user name, a
null string “” can be used instead.
Password.
The valid length ranges from 0 to 50
Password[Input] characters.
It can’t be NULL. If there is no password, a
null string “” can be used instead.
Authentication algorithms.
The system supports the following
algorithms:
PPP_ALG_PA 0x000000 PAP
P 01 authenticat
ion
algorithm
PPP_ALG_CH 0x000000 CHAP
AP 02 authenticat
ion
algorithm
PPP_ALG_MS 0x000000 MSCHAPV
CHAPV1 04 1
authenticat
ion
Auth
algorithm
PPP_ALG_MS 0x000000 MSCHAPV
CHAPV2 08 2
authenticat
ion
algorithm
PPP_ALG_ALL 0xff All
algorithms
are
supported
At least one type of authentication or several
authentications with (+) or (|) should be used, for
example, PPP_ALG_PAP| PPP_ALG_CHAP.
If the algorithm is unknown, fill in parameter
PPP_ALG_ALL.
Timeout.[unit:ms]
TimeOutMs
The valid timeout ranges from 0 to 3600000.

PAX Computer Technology (Shenzhen) Co., Ltd. 227

 Prolin API Programming Guide

If timeout <0, it will be automatically set to 0.

If timeout >3600000, it will be automatically
set to 3600000.
Interval for link check.[unit:ms]
The valid value ranges from 0 to 3600000.
When it is 0, KeepAlive function is disabled;
KeepAlive When it is 0~10,000, it will be set to 10,000
automatically;
When it is 10,000 ~360,000, the
corresponding setting value will be used.
ReserParam Reserved parameter, used for extension.
PPP_LOGINING Module is logging in.
PPP_LOGOUTING Module is logging out.
The link is established
RET_OK
successfully.
ERR_DEV_NOT_EXIST Module does not exist.
ERR_DEV_NOT_OPEN Fail to perform OsWlLock().
ERR_INVALID_PARAM Invalid parameter.
Return ERR_WL_POWER_ONI In the process of powering on the
NG module.
ERR_WL_POWER_OFF Module is powered off.
ERR_WL_NOT_INIT Fail to initialize Module.
ERR_NET_PASSWD Wrong password.
ERR_NET_SERVER_BU Server is busy, communication
SY fails.
ERR_NET_AUTH Cannot connect to RADIUS server.
1. OsWlLock() must be called successfully before calling this
function.
2. OsWlInit() must be called successfully before calling this
function.
3. When TimeOutMs=0, the function will return immediately.
4. The login duration depends on wireless module and
Instruction network environment. In general, if the login duration is over
60 seconds, it means login failure or module exception.
5. It is recommended to restart the terminal after three
consecutive failure of login.
6. After successfully establishing the link, the link will be set as
the default route and IP network communication can be
created.

PAX Computer Technology (Shenzhen) Co., Ltd. 228

 Prolin API Programming Guide

7. When the return value is PPP_LOGOUTING, OsWlCheck()

can be called to check the logout status. The system has
logged out successfully when OsWlCheck() returns
ERR_NET_LOGOUT.
8. When KeepAlive function is disabled, according to base
station configuration, if no data communication has been
detected for a long time, the base station may disconnect
the link. When KeepAlive function is enabled, if the link
receives no message within the KeepAlive time interval,
then system will send ICMP message to the 8.8.8.8
automatically every time interval. .

OsWlLoginEx

int OsWlLoginEx(const char *DialNum,

const char *APN,
const char *Name,
const char *Password,
Prototype
long Auth,
int TimeOutMs,
int KeepAlive,
int ReserParam);
Login wireless network and set up wireless link (dialing
Function command can be modified).
PPP dialing command.
DialNum[Input] When DialNum is NULL, the default dialing
command will be used. The valid string
length is not more than 50 bytes.
For GPRS: APN is the access point name;
For CDMA: APN is the dialing number.
APN[Input]
The valid length is not more than 50
characters. It can’t be NULL.

Parameters User name.

The valid length is no more than 50
Name[Input] characters. It can’t be NULL. If there is no
user name, a null string “” can be used
instead.
Password.
The valid length is not more than 50
Password[Input] characters. It can’t be NULL. If there is no
password, a null string “” can be used
instead.

PAX Computer Technology (Shenzhen) Co., Ltd. 229

 Prolin API Programming Guide

Authentication algorithm.
The system supports the following
authentication algorithms:
PPP_ALG_PA 0x000000 PAP
P 01 authenticat
ion
algorithm
PPP_ALG_CH 0x000000 CHAP
AP 2 authenticat
ion
algorithm
PPP_ALG_MS 0x000000 MSCHAPV
CHAPV1 04 1
authenticat
ion
Auth algorithm
PPP_ALG_MS 0x000000 MSCHAPV
CHAPV2 08 2
authenticat
ion
algorithm
PPP_ALG_ALL 0xff All
algorithms
are
supported
At least one type of authentication or several
authentications with (+) or (|) should be used, for
example, PPP_ALG_PAP| PPP_ALG_CHAP.
If the algorithm is unknown, fill in parameter
PPP_ALG_ALL.
Timeout.[unit:ms]
The valid timeout ranges from 0 to 3600000.
TimeOutMs If timeout <0, it will be automatically set to 0.
If timeout >3600000, it will be automatically
set to 3600000.
Time interval for link check.[unit:ms]
The valid value ranges from 0 to 3600000.
When it is 0, KeepAlive function is disabled;
KeepAlive When it is 0~10,000, it will be set to 10,000
automatically;
When it is 10,000 ~360,000, the
corresponding setting value will be used.

PAX Computer Technology (Shenzhen) Co., Ltd. 230

 Prolin API Programming Guide

ReserParam Reserved parameter, used for extension.

PPP_LOGINING Module is logging in.
RET_OK Link is set up successfully.
ERR_DEV_NOT_EXIST Wireless module does not exist.
ERR_DEV_NOT_OPEN Module/device is not open.
ERR_INVALID_PARAM Invalid parameter.

Return ERR_WL_POWER_ONIN In the process of powering on the

G module.
ERR_WL_POWER_OFF Module is powered off.
ERR_WL_NOT_INIT Fail to initialize module.
ERR_NET_PASSWD Wrong password.
ERR_NET_SERVER_BUS Server is busy, communication
Y fails.
1. This function is similar to OsWlLogin(). If DialNum is NULL,
the two functions share totally the same functionality.
2. OsWlLock() must be called successfully before calling this
function.
3. When TimeOutMs=0, the function will return immediately.
4. When the function returns PPP_LOGINING, it means
module is logging in and the login status can be checked by
OsWlCheck().
5. The login duration depends on wireless module and
network environment. In general, if the login duration is over
60 seconds, it means login failure or module exception.
Instruction 6. It is recommended to restart the terminal after three
consecutive failure of login.
7. After the link is successfully established, it will be set as the
default route and IP network communication can be
created.
8. When KeepAlive function is disabled, according to base
station configuration, if no data communication has been
detected for a long time, the base station may disconnect
the link. When KeepAlive function is enabled, if the link
receives no message within the KeepAlive time interval,
then system will send ICMP message to the 8.8.8.8
automatically every time interval.

OsWlLogout

Prototype int OsWlLogout(void);

PAX Computer Technology (Shenzhen) Co., Ltd. 231

 Prolin API Programming Guide

Function Log out wireless network and disconnect wireless link.

Parameters None
PPP_LOGOUTING Module is disconnecting link.
Return
ERR_DEV_NOT_OPEN Fails to call OsWlLock().
1. OsWlLock() must be called successfully before calling this
function.
Instruction 2. The logout status can be checked by calling OsWlCheck(). It
has logged out successfully if OsWlCheck() returns
ERR_NET_LOGOUT.

21.3 Wireless Module Information Settings

OsWlSelSim

Prototype int OsWlSelSim(int simno);

Function Select SIM card.
 0: Select the SIM card in slot 1.
Parameters simno [Input]  1: Select the SIM card in slot 2.
 Others: Parameter error.

RET_OK Succeeded.
ERR_DEV_NOT_EXIST Module does not exist.
Return ERR_DEV_NOT_OPEN Fail to call OsWlLock().
ERR_WL_ERR_BUSY Module is busy.
Other non-zero value Refer to Return Code List.
1. OsWlLock() must be called successfully before calling this
function.
2. OsWlInit() shall be called again to initialize module after
successfully calling OsWlSelSim(). In this process, the
Instruction module will be powered off and then powered on, this
function will block for about 15 seconds.
3. If the selected card slot has a bad card or has no card, the
function will still return; when logging in, whether it is a bad
card or no card can be detected.

PAX Computer Technology (Shenzhen) Co., Ltd. 232

 Prolin API Programming Guide

22WiFi

Prolin WiFi supports two modes: Station and IBSS work mode.

Station mode: the communication between the terminal and Access Point (AP), such
as wireless router.

IBSS mode: not supported.

22.1 Return Code List

Table 22.1 Return code list

Macro Value Description

ERR_MODE_NOT_SUPPORT -3350 Mode setting error.
ERR_WIFI_POWER_OFF -3351 Module is powered off.
ERR_NOT_FOUND_AP -3352 AP is not found.
Authentication mode or
ERR_AUTH_SEC_MODE -3353
encryption mode error.
ERR_WIFI_BAD_SIGNAL -3354 WiFi signal is weak.
RET_CONNECTING 1 Module is connecting.
Certificate chain error or
ERR_EAP_ID -3359
certificate verification failure

PAX Computer Technology (Shenzhen) Co., Ltd. 233

 Prolin API Programming Guide

22.2 Encryption Type List

Table 22.2 Encryption type list

Macro Value Description

PARE_CIPHERS_NONE 0x00000000 No encryption.
PARE_CIPHERS_WEP64 0x00000001 WEP 40-bit key.
PARE_CIPHERS_WEP128 0x00000002 WEP 104-bit key.
PARE_CIPHERS_WEPX 0x00000004 WEP encryption, unknown
key bits.
PARE_CIPHERS_CCMP 0x00000010 AES encryption.
PARE_CIPHERS_TKIP 0x00000020 TKIP encryption.

22.3 Data Structure

Authentication Modes:

WIFI_AUTH_MODE
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:

PAX Computer Technology (Shenzhen) Co., Ltd. 234

 Prolin API Programming Guide

WEP_SEC_KEY
typedef struct _WepSecKey{
char Key[4][40]; /* WEP key data */
int KeyLen; /* Length of WEP key data */
int Idx; /* WEP key index [0,3] */
} WEP_SEC_KEY;

WiFi connection doesn’t support EAP encryption.

Extension for WPA/WPA2-PSK:

WPA_PSK_KEY
typedef struct _WpaPskKey{
char Key[64]; /* PSK-Key data */
int KeyLen; /* PSK-Key data length */
} WPA_PSK_KEY;

Extension for EAP:

WPA_EAP_KEY
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]; /*Private key file from file path to client */
char PriKeyPwd[132]; /* Private key file of password */
} WPA_EAP_KEY;

Scan the AP information:

PAX Computer Technology (Shenzhen) Co., Ltd. 235

 Prolin API Programming Guide

ST_WifiApInfo
typedef struct _WifiApInfo
{
char Essid[33]; /* AP name */
char Bssid[20]; /* MAC address */
int Channel; /* Information channel */
int Mode; /* Connection mode, 0:Station; 1:IBSS */
int Rssi; /* Signal value, the value range is [-99,0] */
int AuthMode; /* Authentication mode*/
int SecMode; /* Encryption mode, NONE,WEP,TKIP,CCMP */
}ST_WifiApInfo;

Connect to AP settings:

ST_WifiApSet
typedef struct _WifiApSet
{
char Essid[33]; /* AP name, valid length is not more than 32 bytes,
ending with ‘\0’*/
char Bssid[20]; /* MAC address, ending with ‘\0’; Bssid can be‘\0’ if there
is no AP with the same ESSID*/
int Channel; /* Information channel, which is valid only in IBSS
mode; 0: default setting */
int Mode; /* Connection mode, 0:Station; 1:IBSS */
int AuthMode; /* Authentication mode */
int SecMode; /*Encryption mode, NONE,WEP,TKIP,CCMP*/
union KEY_UNION{ /* Key setting */
WEP_SEC_KEY WepKey; /* WEP mode */
WPA_PSK_KEY PskKey; /*wpa,wpa2-psk mode*/
WPA_EAP_KEY EapKey; /* wpa,wpa2-eap mode*/
} KeyUnion;
}ST_WifiApSet;

WPS mode enumeration:

WPS Mode

enum WPS_MODE
{
WPS_MODE_PBC = 1; /* Use keypad to connect, it is also called PBC
connection */

PAX Computer Technology (Shenzhen) Co., Ltd. 236

 Prolin API Programming Guide

WPS_MODE_PIN_CLIENT; /*Use PIN code generated from terminal to

connect */
WPS_MODE_PIN_AP /*Use PIN code from AP side to connect */
};

22.4 OsWifiOpen

Prototype int OsWifiOpen(void);

Function Connect with WiFi server and obtain usage rights of WiFi
module.
Parameters None
RET_OK Succeeded.
ERR_DEV_NOT_EXIS Abnormal loading of module driver or
T module error.
ERR_DEV_BUSY WiFi is busy.
Return
ERR_BATTERY_VOLT
AGE Battery voltage is too low.
_TOO_LOW
ERR_BATTERY_ABS
Battery does not exist.
ENT
1. D200 and S920 POS models must be powered by battery
before accessing Wifi; otherwise,
ERR_BATTERY_ABSENT will be returned.
Instruction
2. When the battery voltage is 0, the module fails to work
normally and returns
ERR_BATTERY_VOLTAGE_TOO_LOW.

22.5 OsWifiClose

Prototype voidOsWifiClose(void);
Function Release the usage right of WiFi module.

Parameters None

Return None

Instruction Call this function will not affect WiFi communication.

PAX Computer Technology (Shenzhen) Co., Ltd. 237

 Prolin API Programming Guide

22.6 OsWifiSwitchPower

Prototype int OsWifiSwitchPower(int Type);

Function Power on/off the WiFi module.
 0: power off module hardware.
Parameters Type
 1: power on module hardware.
RET_OK Succeeded.
ERR_INVALID_PARA
Invalid parameter.
M
Return ERR_DEV_NOT_EXI Abnormal loading of module driver or
ST module error.
ERR_DEV_NOT_OP
Fail to access WiFi device.
EN
1. WiFi module is automatically powered on with booting up
Instruction of Prolin, thus this function doesn’t need to be called.
2. It is a reserved interface and is not supported.

22.7 OsWifiScan

Prototype int OsWifiScan(ST_WifiApInfo **Aps);

Function Scan the existing network.

Parameters A pointer to ST_WifiApInfo structure, storing

Aps[Output]
the scanned network information.
>=0 Number of AP that has been found.
ERR_MEM_FAULT Memory error
ERR_INVALID_PARA
Invalid parameter
Return M
ERR_WIFI_POWER_
WiFi module is powered off.
OFF
ERR_DEV_NOT_OP
Fail to access WiFi device.
EN
/*For example:*/
int i, num;
Instruction ST_WifiApInfo * Aps;
num = OsWifiScan (&Aps);
if(num <= 0)

PAX Computer Technology (Shenzhen) Co., Ltd. 238

 Prolin API Programming Guide

return -1;
for(i=0; i<num; i++)
printf("[%d] AP name: %s\n", i,Aps[i].Essid);

22.8 OsWifiConnect

int OsWifiConnect(const ST_WifiApSet *Ap,

Prototype
int TimeOutMs);
Function Connect to a specified wireless network.
A pointer to ST_WifiApSet structure,
Ap [Input] storing the attributes of the specified
wireless network.
Parameters
Timeout.[unit:ms]
TimeOutMs[Input] The valid timeout ranges from 0 to
3600000.
RET_OK Succeeded.
RET_CONNECTING Module is connecting.
ERR_NOT_CONNEC Connection failed.
T
ERR_WIFI_BAD_SIG WiFi signal is weak.
NAL
ERR_NOT_FOUND_
AP can’t be found.
AP
Return ERR_ NET_PASSWD Wrong password.
ERR_AUTH_SEC_M Authentication mode or
ODE encryption mode error
ERR_WIFI_POWER_
WiFi module is powered off.
OFF
ERR_DEV_NOT_OP
Fail to access WiFi device.
EN
ERR_INVALID_PARA
Invalid parameter.
M
1. OsWifiCheck() can be used to check the connection status
after RET_CONNECTING is returned.
Instruction 2. After a successful connection, OsNetStartDhcp() can be
used to get the dynamic IP address; the OsNetSetConfig()
can be used to set the static IP address.
3. In IBSS mode, ERR_NOT_CONNECT will be returned

PAX Computer Technology (Shenzhen) Co., Ltd. 239

 Prolin API Programming Guide

when the connection time exceeds 90 seconds; while in

Station mode, a specific error code will be returned when
the connection fails.
4. In IBSS mode, if the connection fails, RET_CONNECTING
will be returned and the terminal will create a new network
according to the connection parameters. RET_OK will be
returned if any terminal is connected to the network within
90 seconds; otherwise, ERR_NOT_CONNECT will be
returned and the network will be terminated if no terminal is
connected to the network.
5. Steps of checking whether the terminal has successfully
connected to the specified network in IBSS mode: firstly
ensure RET_OK is returned; then set IP; finally ping the
opposite end IP. The connection is successful if ping
succeeds.
6. User can set the member Bssid of ST_WifiApSet structure
to connect to the specified AP, it is used particularly to
distinguish the same ESSID network environments. If
roaming is needed, Bssid must be set to “\0”.

22.9 OsWifiDisconnect

Prototype int OsWifiDisconnect(void);

Function Disconnect from the current network.

Parameters None.

RET_OK Succeeded.
Return ERR_DEV_NOT_OP
Fail to access WiFi device.
EN
Instruction

22.10 OsWifiCheck

int OsWifiCheck(char *Essid,

Prototype char *Bssid,
int *Rssi);
Function Acquire the current network status.
The current connected ESSID
Parameters Essid[Output]
The valid size is 33 bytes; it can’t be NULL.

PAX Computer Technology (Shenzhen) Co., Ltd. 240

 Prolin API Programming Guide

The current connected BSSID.

Bssid[Output]
The valid size is 20 bytes; it can be NULL.
Signal strength.
Rssi [Output] The valid value ranges from -99 to 0. 0 is the
strongest signal strength. It can’t be NULL.
RET_OK Succeeded.
RET_CONNECTING Module is connecting.
ERR_NOT_CONNE Not connected to network.
CT
ERR_WIFI_BAD_SI WiFi signal is weak.
GNAL
Return ERR_NOT_FOUND AP is not found.
_AP
ERR_NET_PASSW Wrong password.
D
ERR_AUTH_SEC_ Authentication mode or
MODE encryption mode error.
ERR_INVALID_PAR
Invalid parameter.
AM
1. The OsWifiCheck() can be implemented at any time, even
before calling OsWifiOpen().
2. ERR_NOT_ CONNECT is returned in any of the following
cases:
a) OsWifiConnect() is not called by any of the
application;
Instruction
b) OsWifiDisconnect() is called and RET_OK is
returned;
c) The connection time exceeds 90 seconds in IBSS
mode.
3. In Station mode, if the connection fails, it will return error
codes except ERR_NOT_ CONNECT.

The default status is “not connected” before a successful

connection. That is, calling OsWIFICheck before
OsWIFIConnect() will return ERR_NOT_CONNECT.

PAX Computer Technology (Shenzhen) Co., Ltd. 241

 Prolin API Programming Guide

22.11 OsWifiCmd

int OsWifiCmd(const char *Argv[],

int Argc,
Prototype
char *Result,
int Len);

Function Send directly commands to the WPA_Supplicant, and obtain

the return results.
Command supported by WPA_Supplicant.
Argv [Input]
It can’t be NULL.
The number of commands or parameters that
Argc[Input]
are stored in Argv two-dimensional array.
Parameters Results returned from WPA_Supplicant.
Result[Outp
ut] The valid length is more than 2048 bytes. It
can’t be NULL.

Len [Input] Length of Result array.

RET_OK Succeeded.
ERR_INVALID_PAR
Invalid parameter.
AM
Return ERR_WIFI_POWER
WiFi module is powered off.
_OFF
ERR_DEV_NOT_O
Fail to access WiFi device.
PEN
1. Argv can be all the commands and parameters supported
by WPA_Supplicant, such as ‘SCAN’ command.
2. If there is only one command in Argv, set Argc to 1.
Instruction
3. This function is called only when other WiFi APIs cannot
meet requirements.
4. Result is the original return value of WPA_Supplicant.

22.12 OsWifiWpsConnect

int OsWifiWpsConnect(WPS_MODE Mode,

Prototype
char *WpsPin);
Function Connect to AP through WPS mode.
Parameters Mode [Input] WPS connection mode: WPS_MODE.

PAX Computer Technology (Shenzhen) Co., Ltd. 242

 Prolin API Programming Guide

1． If the connection mode is

WPS_MODE_PBC, then WpsPin
is NULL.
2． If the connection mode is
WPS_MODE_PIN_CLIENT, then
WpsPin [Input/Output] WpsPin will output the PIN code
generated from terminal, the buffer
that WpsPin points to is 8 bytes.
3． If the connection mode is
WPS_MODE_PIN_AP, WpsPin is
the PIN code of AP, and the buffer
that WpsPin points to is 8 bytes.
RET_ CONNECTING In the process of connecting
ERR_DEV_NOT_OPEN Open failed
ERR_INVALID_PARAM Invalid parameter
Return
ERR_SYS_NOT_SUPPO WiFi module is not supported by
RT system.
ERR_PIN_FAIL PIN code error
1. WPS connection includes the following three different types
of method:
a) For PCB method (push the QSS(WPS) button of AP),
WpsPin is NULL.
b) The method of using PIN code generated from terminal
to do the connection, WpsPin is an output parameter,
and the value is a PIN code generated from terminal
automatically.
Instruction
c) The method of using PIN code from AP to do the
connection, WpsPin is an input parameter; the value is
AP built-in PIN code.
2. When the return value is RET_CONNECTING,
OsWifiCheck() can be called to check the connection
state, the connection is normally finished within 2 minutes.
3. OsWifiDisconnect() can be called to disconnect the link
during the connection process.

PAX Computer Technology (Shenzhen) Co., Ltd. 243

 Prolin API Programming Guide

23GPS

23.1 Return Code List

Macro Value Description

GPS_NAVIGATING 1 GPS positioning..
GPS module is being
ERR_GPS_POWER_ONING -3901
powered on.

23.2 Data Definition

Structure of location information

GPS_LOCATION
typedef struct {
double latitude; /*Latitude, unit: degree.*/
double longitude; /*Longitude, unit: degree.*/
double altitude; /*Altitude, unit: meter.*/
} GPS_LOCATION;

PAX Computer Technology (Shenzhen) Co., Ltd. 244

 Prolin API Programming Guide

23.3 OsGpsOpen

int OsGpsOpen(int Mode,

Prototype
const char *Attr);
Function Open and initialize GPS module.
Positioning mode:
GPS_MODE: normal GPS positioning
Mode mode.
AGPS_MODE: AGPS positioning
mode.
Parameters
Positioning parameter.
When Mode is GPS_MODE, Attr will be
Attr[Input] ignored.
When Mode is AGPS_MODE, it needs
to pass in AGPS server address.
RET_OK Succeeded.
ERR_DEV_NOT_EXI
Device does not exist.
ST
ERR_INVALID_PAR
Invalid parameter.
AM
Return ERR_SYS_NOT_SU
System does not support.
PPORT
ERR_DEV_NOT_OP
GPS module is not open.
EN
ERR_GPS_POWER_
GPS module is being powered on.
ONING
Call this function will initialize GPS module and start GPS
background service. The first calling of this function may need
Instruction up to 6s due to the handshake between backstage service and
hardware.

23.4 OsGpsRead

Prototype int OsGpsRead(GPS_LOCATION *Location);

Function Read GPS location information.
GPS location structure,
Parameters Location GPS_LOCATION.
Return GPS_NAVIGATING GPS is navigating.

PAX Computer Technology (Shenzhen) Co., Ltd. 245

 Prolin API Programming Guide

RET_OK Succeeded.
ERR_INVALID_PAR
Invalid parameter.
AM
ERR_DEV_NOT_EXI
Device does not exist.
ST
ERR_DEV_NOT_OP
GPS module is not open.
EN
1. Only when RET_OK is returned, can GPS location
information be read correctly.
2. Influenced by GPS signal, the positioning may take several
minutes, and the correct location information cannot be
read until the positioning is completed. In an extreme case
(places without GPS signal such as indoor, tunnel etc.),
when GPS signal cannot be searched, GPS_NAVIGATING
will be returned all the time until the positioning is
completed.
Instruction
3. For the terminals with ro.fac.gps equal to 3, because the
their GPS modules are integrated into the wireless module,
therefore, during the process of using GPS, if
OsWlSwitchPower() is called to power off the wireless
module, ERR_DEV_NOT_OPEN will be returned for
OsGpsRead(). At this point, the application needs to call
OsGpsClose() to release the resources. After powering on
the wireless module, call OsGpsOpen() again to open GPS
device.

23.5 OsGpsClose

Prototype void OsGpsClose(void);

Function Close GPS module.
Parameters None
Return None

1. GPS module can only be closed by the same application

which was used to open it firstly. If GPS module is not open,
this function does not do anything.
Instruction
2. As long as RET_OK is returned after calling OsGpsOpen(),
OsGpsClose() must be called to close GPS module when
program exits.

PAX Computer Technology (Shenzhen) Co., Ltd. 246

 Prolin API Programming Guide

24 Base

24.1 Introduction

Newly added base APIs are used for operating base-set, including detecting whether
the handset is on base and opening/detecting/closing the communication mode of
handset-base.
When the communication mode is enabled on the handset-base, functions will be
extended on base; (B920 extends the Ethernet function, and Px Dock extends printer
and scanner functions). When the communication mode is closed on the
handset-base, extended functions are invalid on base.
Mode instructions

 Local mode: The handset is used as an independent device. In this mode,

applications can only access to the local physical device on the phone (such as
printer, scanner and Ethernet).
 Communication mode: The handset is used as a handset with base
cooperatively. And then the base works as a extention device of the handset,
Prolin applications can access to local physical device on base by calling OSAL
API, such as B920 Ethernet, Px Dock printer and scanner.

PAX Computer Technology (Shenzhen) Co., Ltd. 247

 Prolin API Programming Guide

24.2 Macro Definition

Add two return values for handset-base model.

Macro Value Description

ERR_BASE_ABSEN
-1025 Base is absent.
T
ERR_BASE_COMM -1026 Communication failure
ERR_LIB_NOT_FOU
-1028 Bluetooth library does not exist
ND
ERR_USB_MODE -1029 USB mode error

Add virtual net channel for base.

Macro Value Description

NET_LINK_TAP 8 tap vlan

24.3 API

OsOnBase

Prototype int OsOnBase(void);

Function Check whether the handset is connected to the base.
Parameters None
RET_OK Handset is on the base.
ERR_BASE_ABS
Base is absent.
ENT
Return ERR_SYS_NOT_
System does not support this function.
SUPPORT
ERR_TIME_OUT Timeout
ERR_SYS_BAD System error
This function only applies to handsets connected to the base
Instruction via USB or serial ports.

OsBaseOpen

Prototype int OsBaseOpen(void);

Function Open the communication mode on the handset.

PAX Computer Technology (Shenzhen) Co., Ltd. 248

 Prolin API Programming Guide

Parameters None
RET_OK Succeeded
ERR_SYS_NOT_SUPP System does not support this
ORT function.
ERR_SYS_BAD System error.
ERR_TIME_OUT Timeout
Return ERR_NOT_CONNECT Bluetooth has not connected.
ERR_DEV_BUSY Device is busy.
ERR_BASE_ABSENT Base is absent.
ERR_USB_MODE USB mode error
Return values of the Bluetooth
Others
module
1. After opening the handset mode, API of serial port, modem
and Ethernet will be switched to the port which is
corresponding to the operation base side;
Instruction 2. When the connection mode between the handset and the
base is USB, please ensure the USB works in single
channel mode, otherwise the interface will return
ERR_USB_MODE.

OsBaseCheck

Prototype int OsBaseCheck(void);

Function Check the base state.
Parameters None
BASE_STATE_CONNE Bluetooth is connected but base is
CTED not open.
BASE_STATE_CONNE
Connecting
CTING
RET_OK Base is open.
ERR_DEV_NOT_OPEN Base is not open.
Return ERR_SYS_NOT_SUPP System does not support this
ORT function.
ERR_SYS_BAD System error.
ERR_TIME_OUT Timeout
ERR_NOT_CONNECT Bluetooth has not connected.
Others Return values of the Bluetooth

PAX Computer Technology (Shenzhen) Co., Ltd. 249

 Prolin API Programming Guide

module
Call this function in the Bluetooth base, the Bluetooth
connecting state and base state will be returned.
Enumeration as follow:
enum {
BASE_STATE_OPENED = 0, /* Base is open */
Instruction
BASE_STATE_CONNECTING, /* Connecting*/
BASE_STATE_CONNECTED, /* Bluetooth is
connected but base is not open. */
};

OsBaseClose

Prototype int OsBaseClose(void);

Function Close the communication mode on the handset.
Parameters None
RET_OK Succeeded
Return ERR_SYS_NOT_SU
System does not support this function.
PPORT
Instruction

OsBaseScan

int OsBaseScan(ST_HandsetLinkInfo *links,

Prototype int n,
int timeout);
Function Scan the Bluetooth base information.
Address of the incoming base
links
information structure
Parameters n Number of the incoming structure
arrays, the maximum value is 32.
timeout Timeout period, [unit: second]
The number of the scanned base
>=0 information. 0 indicates no base has
been scanned.
Return ERR_SYS_NOT_SU
System does not support this function.
PPORT
ERR_SYS_BAD System error

PAX Computer Technology (Shenzhen) Co., Ltd. 250

 Prolin API Programming Guide

ERR_TIME_OUT Timeout
ERR_INVALID_PAR
Invalid parameter.
AM
ERR_MEM_FAULT Memory application failed.
ERR_DEV_BUSY Device is busy.
ERR_LIB_NOT_FOU
Bluetooth library cannot be found.
ND
Others Return values of the Bluetooth module
Instruction

Sample code
typedef struct _HandsetLinkInfo {
int type; //Reserved for future use
union {
struct {
char name[32]; //Bluetooth name
char mac[32]; //Bluetooth MAC address
} bt; //Bluetooth base information
unsigned char reserved[160];
} u;
} ST_HandsetLinkInfo;

The timeout period of Bluetooth scanning is not accurate.

OsBaseConnect

int OsBaseConnect(ST_HandsetLinkSet lk,

Prototype
int timeout);
Function Connect to the Bluetooth base.
lk Base connection information.
Parameters
timeout Timeout period
RET_OK Succeeded.
Return
ERR_SYS_NOT_SU System does not support this function.

PAX Computer Technology (Shenzhen) Co., Ltd. 251

 Prolin API Programming Guide

PPORT
ERR_SYS_BAD System error
ERR_TIME_OUT Timeout
ERR_INVALID_PAR
Invalid parameter.
AM
ERR_DEV_BUSY Device is busy.
ERR_LIB_NOT_FOU
Bluetooth library cannot be found.
ND
Others Return values of the Bluetooth module
This function is non-blocking. When 0 is returned, it indicates
the calling succeeded. Application can check the connecting
Instruction state by calling OsBaseCheck(). When
BASE_STATE_CONNECTING is returned, it indicates the
Bluetooth base is in the connecting process.

Sample code
typedef struct _HandsetLinkSet {
int type; //Reserved for future use
union {
struct {
char mac[32]; //Bluetooth MAC address
} bt;
unsigned char reserved[1024];
} u;
} ST_HandsetLinkSet;

Bluetooth connection result is returned through the callback

function, so the timeout parameter is temporarily ignored and
reserved for future use.

OsBaseDisconnect

Prototype int OsBaseDisconnect(void);

Function Disconnect the Bluetooth base connection.
Parameters None
Return RET_OK Succeeded.

PAX Computer Technology (Shenzhen) Co., Ltd. 252

 Prolin API Programming Guide

ERR_SYS_NOT_SU
System does not support this function.
PPORT
ERR_SYS_BAD System error
ERR_TIME_OUT Timeout
ERR_DEV_BUSY Device is busy.
Only the process which has opened the base can close the
Instruction base.

OsCheckPortStatus

Prototype int OsCheckPortStatus(int Channel);

Check if a physical connection exists at the specified
Function communication port.
PORT_BASE_DEV: usbdev
module of base
PORT_BASE_ETH0: Ethernet
Parameters Channel[Input] module of base
PORT_BASE_WLAN0: WIFI
module of base
RET_OK Succeeded.
ERR_NOT_CONNECT It is not connected.
ERR_INVALID_PARAM Invalid parameter

Return ERR_SYS_NOT_SUPP System does not support this

ORT function
ERR_BASE_ABSENT Base is absent.

ERR_SYS_BAD System error

1. Please ensure the handset is connected to the base before
using it.
Instruction 2. When channel= PORT_BASE_WLAN0, it is used to check
whether the WIFI module of base exists, 0 is present, and
-1012 is absent.

OsGetBaseInfo

int OsGetBaseInfo(const char *Key,

Prototype
char *Value);
Get the contents of the system configuration specified by the
Function base.

PAX Computer Technology (Shenzhen) Co., Ltd. 253

 Prolin API Programming Guide

Key [Input] System configuration name, ending

with“\0”.
Parameters Value [Output] Parameter value.
The valid string length must be more
than 64 bytes.
>=0 String length.
ERR_INVALID_PARAM Invalid Parameter
ERR_NOT_CONNECT Not connected
ERR_BASE_ABSENT Base is absent.
Return
ERR_TIME_OUT Timeout
ERR_SYS_NOT_SUPP
System does not support
ORT
ERR_SYS_BAD System error
1. Please ensure that the handset is connected to the base
before use.
2. For more values configured by system, refer to Appendix 3
Registry.
3. Additional system configurations supported by the base are
as follows:
System configuration name Description
Whether there is a number
ro.fac.digital_io IO(None means it does not
Instruction exist by default.)
Whether com1 port that
corresponds to
ro.fac.com1 PORT_BASE_A port exists,
(None means it does not
exist by default.)
Whether com2 port that
corresponds to
ro.fac.com2 PORT_BASE_B port exists,
(None means it does not exist
by default.)

OsBaseCmd

int OsBaseCmd(int cmd,

Prototype void *inparm,
void *outparm);
Function Send commands to base.

PAX Computer Technology (Shenzhen) Co., Ltd. 254

 Prolin API Programming Guide

cmd[Input] BASE_CMD_REBOOT: Restart

base.
Parameters inparm[Input] Reserved for future use.
outparm[Output] Reserved for future use.
RET_OK Succeeded.
ERR_INVALID_PARAM Invalid Parameter
ERR_NOT_CONNECT Not connected
ERR_BASE_ABSENT Base is absent.
Return
ERR_TIME_OUT Timeout
ERR_SYS_NOT_SUPP
System does not support
ORT
ERR_SYS_BAD System error
Please ensure that the handset is connected to the base before
Instruction use.

PAX Computer Technology (Shenzhen) Co., Ltd. 255

 Prolin API Programming Guide

25File System

Prolin file system adopts standard ANSI.C file operation API.

PAX Computer Technology (Shenzhen) Co., Ltd. 256

 Prolin API Programming Guide

26System Information

In Prolin, the system messages of hardware device are implemented by

asynchronous notification. The system provides two kinds of hardware system
messages:

 SIGMAG (magnetic card message)

 SIGICC (IC card message)

The SIGMAG is valid only when the magnetic stripe reader is open.

To register asynchronous notification function, the sample code is shown as follows:

Example
#include <stdio.h>
#include <stdlib.h>
#include <signal.h>
#include <pthread.h>
#include <osal.h>
#include <cutils/log.h>
#define printf(...) LOGI(__VA_ARGS__)
static sigset_t mask;
void * handler_sigwait(void * arg)
{

PAX Computer Technology (Shenzhen) Co., Ltd. 257

 Prolin API Programming Guide

int ret, signo;

while(1){
ret = sigwait(&mask, &signo);
if(ret != 0){
printf("sigwait err, ret=%d\n", ret);
break;
}
switch(signo){
case SIGMAG:
printf("Capture msr signal\n");
break;
case SIGICC:
printf("Capture icc signal\n");
break;
default:
printf("Capture other signal %d\n", signo);
break;
}
}
}
int main()
{
int ret;
sigset_t oldmask;
pthread_t tid;
ret = OsMsrOpen();
if (ret < 0)
exit(-1);
ret = OsIccOpen(ICC_USER_SLOT);
if (ret < 0){
OsMsrClose();
return -1;
}
sigemptyset(&mask);
sigaddset(&mask, SIGMAG);
sigaddset(&mask, SIGICC);
ret = pthread_sigmask(SIG_SETMASK, &mask, &oldmask);
if(ret != 0){
printf("pthread_sigmask error, ret=%d\n", ret);
exit(-1);

PAX Computer Technology (Shenzhen) Co., Ltd. 258

 Prolin API Programming Guide

}
ret = pthread_create(&tid, NULL, handler_sigwait, 0);
if(ret != 0){
printf("pthread_create error, ret=%d\n", ret);
exit(-1);
}
pthread_join(tid, NULL);

OsMsrClose();
OsIccClose(ICC_USER_SLOT);

PAX Computer Technology (Shenzhen) Co., Ltd. 259

 Prolin API Programming Guide

27Audio

Prolin audio device is a speaker. In general, the volume settings are unified and can
be set in TM interface.

27.1 Return Code List

Table 27.1 Return code list

Macro Value Description

RET_RECORDING 1 In the recording.
ERR_NOT_RECORD -1027 No recording

27.2 OsRecordOpen

Prototype int OsRecordOpen(void);

Function Establish a connection with Prolin recording service to obtain the

permission of the recording device.
Parameters None.
0 Succeeded.
Return
ERR_DEV_NOT_EXI Device does not exist.

PAX Computer Technology (Shenzhen) Co., Ltd. 260

 Prolin API Programming Guide

ST
ERR_DEV_BUSY Device is occupied by other application
programs.
1. OsRecordOpen() should be called before calling
OsRecordStart() or OsRecordStop().
Instruction
2. After all the operations have been completed, OsRecordClose()
should be called to release the voice recording device.

27.3 OsRecordStart

int OsRecordStart(const char *FileName,

const char *Type,
unsigned int Channel,
Prototype
const char *Format,
unsigned int Rate,
unsigned int Duration);
Start recording and save it as a specified audio file after the
Function recording.
Path name to the recording file, including
path and file name. It cannot be NULL. It is
FileName[Input]
recommended to be stored in the local
directory of the application.
Audio format, “wav” is supported.The format
Type[Input]
is “wav” when it is NULL.
The number of channels, “1” indicates single
Channel[Input] track, “2” indicates dual track. Currently, Q90
only supports single track.
Parameters Sample format, it supports “U8” or “S16_LE”.
The sample format is “S16_LE” when it is
Format[Input] NULL. “S” indicates signed, “U” indicates
unsigned; “LE” indicates little endian; “8/16”
indicates sample length.
Sample frequency, [Unit: Hz], the valid value
Rate[Input] can be 8000, 11025, 16000, 22050, 24000,
32000, 44100 or 48000.
Recording time, [Unit: s], the valid value
Duration[Input]
ranges from 1 to 600.
RET_OK Succeseded.
Return
ERR_ACCESS_DENY Access denied.

PAX Computer Technology (Shenzhen) Co., Ltd. 261

 Prolin API Programming Guide

ERR_DEV_NOT_OPE
Recording not available.
N
ERR_INVALID_PARAM Invalid parameter.
Insufficient space available in
ERR_NO_SPACE
system.
1. The audio file occupies a large space. For example, sample
in the format of S16_LE, 44100Hz, single track, the
recording time is 600s, and it is saved as “wav” format, then
the audio file occupies about 50MB space. It is not
recommended to record for too long time. And it is
recommended to clear the unnecessary audio files in time
Instruction to release the storage space. The recording will be
terminated when the remaining space is less than 10M.
2. In the recording, OsRecordStop() can be called to stop
recording, otherwise, the recording will keep up until the
specified recording time (Duration) or the storage space is
insufficient.

Audio sample code:

Example
if (OsRecordOpen())
return -1;
OsRecordStart("/data/app/MAINAPP/test.wav", NULL, 1, NULL, 44100, 20);
while (1)
{
if (!XuiHasKey())
continue;
key = XuiGetKey();
if (key == XUI_KEY1)
OsRecordStop();
else if (key == XUI_KEY2)
ret = OsRecordCheck();
else if (key == XUI_KEYCANCEL)
break;
}
OsRecordClose();

PAX Computer Technology (Shenzhen) Co., Ltd. 262

 Prolin API Programming Guide

27.4 OsRecordStop

Prototype int OsRecordStop(unsigned int *Time);

Function Stop recording.
Parameters Time[Input] Duration of audio file.
RET_OK Success.
ERR_SYS_BAD System error.
Return ERR_DEV_NOT_OP
Recording not available.
EN
ERR_NO_SPACE Insufficient space available in system.
1. In the recording, OsRecordStop() can be called to stop the
recording, and the duration of the audio file will be returned.
2. When calling OsRecordStop():
Instruction 1) if the recording has been stopped due to the arrival of the
specified recording time (Duration), RET_OK will be returned.
2) if the recording has been stopped due to the insufficient storage
space, ERR_NO_SPACE will be returned.

27.5 OsRecordCheck

Prototype int OsRecordCheck(void);

Function Get the current recording status.
Parameters None
RET_RECORDING In the recording.
RET_OK Finish recording.
Return ERR_NOT_RECORD No recording.
ERR_SYS_BAD System error.
ERR_NO_SPACE Insufficient space available in system.
1. If no application calls OsRecordStart(), RET_NOT_RECORD
will be returned.
Instruction
2. If the recording has been stopped due to the insufficient storage
space, ERR_NO_SPACE will be returned.

PAX Computer Technology (Shenzhen) Co., Ltd. 263

 Prolin API Programming Guide

27.6 OsRecordClose

Prototype void OsRecordClose(void);

Function Release the access to the recording device and disconnect the
device from the Prolin recording service.
Parameters None
Return None

Instruction

27.7 OsPlayWave

int OsPlayWave(const char *Buf,

int Len,
Prototype
int Volume,
int DurationMs);
Function Play a specified wav audio file.
Buf [Input] Audio data buffer.
Len[Input] Length of the data buffer.
Volume.
Parameters
Volume[Input] The valid volume ranges from 0 to 4;
0 means mute.
DurationMs[Input] Play duration.[Unit:ms].
RET_OK Success.
ERR_FILE_FORMAT File format error.
Return ERR_ACCESS_DENY Access denied.
ERR_INVALID_PARAM Invalid parameter.
ERR_USER_CANCEL The user stop operating.
1. The value range of Volume is from 0 to 4. When Volume<0,
it will be set to the value of persist.sys.sound.volume, which
is the system volume and can be set in TM; When
Volume>4, it will be set to 4 automatically.
Instruction 2. The play duration has three cases：
a) If DurationMs>Len, loop playback；
b) If DurationMs<Len, DurationMs will be used；
c) If DurationMs=0, the actual length of the audio data will

PAX Computer Technology (Shenzhen) Co., Ltd. 264

 Prolin API Programming Guide

be used.
3. The system supports single track and double track WAVE
audio file.
4. The system supports 8-bit sampling and 16-bit sampling
WAVE audio file. The supported sample frequencies are
8000 Hz, 11025 Hz, 16000 Hz, 22050 Hz, 24000 Hz, 32000
Hz, 44100 Hz and 48000 Hz.

Audio sample code (FILENAME is the name of an audio file):

Example
int fd, ret = 0;
char *buff;
int len;
struct stat state;
stat(FILENAME, &state);
len = state.st_size;
buff = (char *) malloc(len * sizeof(char));
fd = open(FILENAME, O_RDONLY);
if(fd<0)
printf("Open File Fail\n");
ret = read(fd, buff, len);
ret = OsPlayWave(buff, len, 3, 0);
if(ret != RET_OK)
printf("PlayWave Fail\n");
close(fd);
free(buff);

27.8 OsStopPlayWave

Prototype int OsStopPlayWave(void);

Function Stop playing audio.
Parameters None
RET_OK Succeeded.
ERR_SYS_BAD System error.
Return ERR_DEV_NOT_OP
Audio device is not open.
EN
ERR_SYS_NOT_SU System does not support this feature.

PAX Computer Technology (Shenzhen) Co., Ltd. 265

 Prolin API Programming Guide

PPORT
1. When a thread calls OsPlayWave() to play an audio,
OsStopPlayWave() can be called by another thread to stop
Instruction
playing the audio.
2. If no audio is playing, ERR_DEV_NOT_OPEN will be returned.

27.9 OsPlayAudio

int OsPlayAudio(const char *Buf,

Prototype int Len,
int Volume);
Function Play the specified MP3 audio.
Buf [Input] The buffer area for audio data.

Parameters Len[Input] The length of data buffer

Volume[Input] Volume value, and the value range is [0,4],
0 represents mute.
RET_OK Succeeded.
ERR_FILE_FORMAT File format error.
ERR_ACCESS_DEN
Failed to access device.
Return Y
ERR_INVALID_PARA
Invaild parameter.
M
ERR_USER_CANCE
User canceled the operation.
L
The value range of Volume is [0,4], if the value is less than 0, the
Instruction system volume (persist.sys.sound.volume) will be taken, and it can
be set in TM; if the value is larger than 4, it will be set to 4
automatically.

The sample code of playing MP3 audio is shown as below, the FILENAME is the
audio file name.

Sample code
int fd = 0, ret = 0;
char *buf;
struct stat state;
fd = open(FILENAME, O_RDONLY);

PAX Computer Technology (Shenzhen) Co., Ltd. 266

 Prolin API Programming Guide

if (fstat(fd, &stat) == -1 || stat.st_size == 0) {

printf(“audio file error\n”);
return -1;
}
buf = mmap(0, stat.st_size, PROT_READ, MAP_SHARED, fd, 0);
if (buf == MAP_FAILED)
return -1;
ret = OsPlayAudio(buf, stat.st_size, 1);
printf("PlayAudio result = %d\n", ret);
munmap(buf, stat.st_size);
close(fd);

27.10 OsStopPlayAudio

Prototype int OsStopPlayAudio(void);

Function Stop playing MP3 audio.
Parameters None
RET_OK Succeeded.
Return ERR_DEV_NOT_OP
Audio device is not open.
EN
1. When a thread calls OsPlayWave() to play an audio,
OsStopPlayWave() can be called by another thread to stop
Instruction
playing the audio.
2. If no audio is playing, ERR_DEV_NOT_OPEN will be returned.

PAX Computer Technology (Shenzhen) Co., Ltd. 267

 Prolin API Programming Guide

28Barcode and Camera

28.1 General Definition

Prolin supports one-dimensional, two-dimensional barcode, scanning barcode and

taking photos through camera.

One-dimensional code is composed of vertical black and white bars of different widths,
and generally there are letters or digits at the bottom of these bars. The code is
commonly used to identify the basic information of products, such as name, price, etc.

Two-dimensional code is in a dot matrix form usually with square structure.

Chequered with black and white bars of different widths, the code is dotted with
polygonous images within its code area. In addition to the identification function,
two-dimensional code can contain much more detailed contents.

Camera’s scanning barcode function is implemented by acquiring image information

through camera module, and it supports operations of supplementary light and
positioning light.

Photography is implemented by calling API to operate camera module to open and

capture the image content of current shooting, and return the content with specified
image data format.

PAX Computer Technology (Shenzhen) Co., Ltd. 268

 Prolin API Programming Guide

28.2 Data Definition

Macro Definition of Camera

Table 28.1 Camera definition list

Macro Value Description

USE_BACK_CAMERA 1 Use the back camera.
USE_FRONT_CAMERA 2 Use the front camera.
OPEN_BACK_ADDBRILAM Open the back
10
P supplementary light.
CLOSE_BACK_ADDBRILA Close the back
11
MP supplementary light.
OPEN_BACK_POSITIONLA Open the back positioning
12
MP light.
CLOSE_BACK_POSITIONL Close the back positioning
13
AMP light.
OPEN_FRONT_ADDBRILA Open the front
20
MP supplementary light.
CLOSE_FRONT_ADDBRILA Close the front
21
MP supplementary light.
OPEN_FRONT_POSITIONL Open the front positioning
22
AMP light.
CLOSE_FRONT_POSITION Close the front positioning
23
LAMP light.
OPEN_SCAN_LEDLIGHT 24 Open the scanning LED
CLOSE_SCAN_LEDLIGHT 25 Close the scanning LED

Image Resolution Macro Definition of Photography

Table 28.2 Image resolution definition list

Macro Value Description

Image resolution is
RESOLUTION_WIDTH_640_
1<<0 640*480,and it is the only
HEIGHT_480
supported resolution.
Image resolution is
RESOLUTION_WIDTH_1024
1<<1 1024*480,and it is the only
_HEIGHT_480
supported resolution.

PAX Computer Technology (Shenzhen) Co., Ltd. 269

 Prolin API Programming Guide

Image Data Format Macro Definition of Photography

Table 28.3 Image data format definition list

Macro Value Description

CAMERA_PIXEL_FORMAT_ The captured image data
1<<0
YUYV format is yuyv.
CAMERA_PIXEL_FORMAT_ The captured image data
1<<1
RGB565 format is rgb565.
CAMERA_PIXEL_FORMAT_ The captured image data
1<<2
SBGGR8 format is sbggr8.

The Attribute Structure of the Photography Parameter

CameraAttribute
typedef struct SCameraAttribute
{
int SupportResolution; /*Read only, describes all the resolutions which the
device supports in bits.*/
int CurrentResolution; /*Read and write, it is the current resolution.*/
int SupportPixelFormat; /*Read only, it is the format of output pixel data,
and it only supports yuyv and rgb565 formats.*/
int CurrentPixelFormat; /* Read and write, it is the format of current output
data, and it only support yuyv format*/
char Reserved[128]; /*Reserved for future use.*/
}CameraAttribute;

Return Code List

Table 28.4 Return code list

Macro Value Description

ERR_BAR_CAMER_INIT_FAILE
-3601 Failed to initialize camera.
D
ERR_BAR_ZSDECODE_INIT_F
-3602 Failed to initialize zsdcode
AILED
ERR_BAR_SRECODE_INIT_FAI
-3603 Failed to initialize srcode.
LED
ERR_BAR_NOT_ENOUGH_BU
-3604 Output buffer is not enough.
FFER
ERR_BAR_READ_CAMERA_B -3605 Failed to read the data in

PAX Computer Technology (Shenzhen) Co., Ltd. 270

 Prolin API Programming Guide

UFFE_FAILED camera buffer.

ERR_BAR_DECODE_FAILED -3606 Failed to decode.

28.3 Basic Interface

OsScanSetParam

Prototype int OsScanSetParam(unsigned int Param);

Open/Close the supplementary light, positioning light or
Function
scanning LED of camera.
 OPEN_BACK_ADDBRILAMP: Open the
back supplementary light.
 CLOSE_BACK_ADDBRILAMP: Close the
back supplementary light.
 OPEN_BACK_POSITIONLAMP: Open the
back positioning light.
 CLOSE_BACK_POSITIONLAMP: Close the
back positioning light.
 OPEN_FRONT_ADDBRILAMP: Open the
front supplementary light.
 CLOSE_FRONT_ADDBRILAMP: Close the
Param front supplementary light.
Parameters
[Input]  OPEN_FRONT_POSITIONLAMP: Open the
front positioning light.
 CLOSE_FRONT_POSITIONLAMP: Close
the front positioning light.
 OPEN_SCAN_LEDLIGHT: Open the
scanning LED
 CLOSE_SCAN_LEDLIGHT: Close the
scanning LED
 USE_BACK_CAMERA: Use the back
camera.
 USE_FRONT_CAMERA: Use the front
camera.
=0 Succeeded.
ERR_INVALID_PAR
Invalid parameter.
Return AM
ERR_DEV_NOT_O
Device is not open.
PEN
1. QR55 has front supplementary light;
D190/D195/D220/Q92 hs back supplementary light;
Instruction
IM10/IM20 has scanning LED.
2. This function should be called after OsScanOpen()

PAX Computer Technology (Shenzhen) Co., Ltd. 271

 Prolin API Programming Guide

succeeds.
3. If device only has one camera, this function will return 0
when the front or back camera is set, and scanning code
function will be normal.

OsScanOpen

Prototype int OsScanOpen(void);

Function Open the barcode scanning module.
Parameters None.
RET_OK Succeeded.
ERR_DEV_BUSY Device is busy.
Return ERR_DEV_NOT_OP
Device is not open.
EN
ERR_DEV_NOT_EXI
Device does not exist.
ST
Because taking photo and scanning barcode are using the same
Instruction camera device, if this function is called after OsCameraOpen(),
ERR_DEV_BUSY will be returned, and vice versa.

OsScanRead

int OsScanRead(char *Buf,

Prototype int Len,
int TimeoutMs);
Function Scan and read the barcode in specified time.
Buffer of barcode data.
For one-dimensional barcode, the buffer size
Buf [Output] is recommended to be more than 512 bytes;
For two-dimensional code, the buffer size is
recommended to be more than 3072 bytes.
Len[Input] Buffer length.
Parameters Timeout of barcode reading.[unit:ms]
The valid timeout value ranges from 1500ms
to 36000ms. Any timeout value that is less
TimeoutMs[Inpu than 1500ms will be set to 1500ms; while
t] more than 36000ms, it will be set to
36000ms. There may be an error less than 1
second between the actual timeout and the
set value.

PAX Computer Technology (Shenzhen) Co., Ltd. 272

 Prolin API Programming Guide

The timeout is recommended to be 3000ms.

>=0 The actual length of barcode data.

ERR_DEV_NOT_OPE
Device is not open.
N
Return
ERR_TIME_OUT Timeout.
ERR_INVALID_PARA
Invalid parameter
M
Instruction

OsScanClose

Prototype void OsScanClose(void);

Function Close scanning device.
Parameters None.

Return None.
Instruction

OsCameraOpen

Prototype int OsCameraOpen(int Index);

Function Open camera device.

Parameters Camera index, 0 represents rear

Index[Input]
camera; 1 represents front camera.
RET_OK Succeeded.
ERR_INVALID_PAR
Invalid parameter.
AM
Return
ERR_DEV_NOT_EX
Device does not exist.
IST
ERR_DEV_BUSY Camera device is busy.
Because taking photo and scanning barcode are using the
Instruction same camera device, if this function is called after OsScanOpen
(), ERR_DEV_BUSY will be returned, and vice versa.

OsCameraClose

Prototype void OsCameraClose(void);

PAX Computer Technology (Shenzhen) Co., Ltd. 273

 Prolin API Programming Guide

Function Close camera device.

Parameters None.

Return None.
Instruction

OsCameraGetParam

Prototype int OsCameraGetParam(CameraAttribute *CameraParam);

Function Obtain camera parameters.

Parameters CameraParam[Outpu Camera parameters, including the

t] attribute settings of camera.
RET_OK Succeeded.
ERR_DEV_NOT_OP
Return Camera device is not open.
EN
ERR_INVALID_PAR
Invalid parameter.
AM
Instruction

OsCameraSetParam

Prototype int OsCameraSetParam(CameraAttribute *CameraParam);

Function Set camera parameters.

Parameters Camera parameters, including the

CameraParam[Intput]
attribute settings of camera.
RET_OK Succeeded.
ERR_DEV_NOT_OPEN Camera device is not open.
Return ERR_INVALID_PARAM Invalid parameter.
ERR_SYS_NOT_SUPP
System does not support.
ORT
This function can only set the read-write member in
CameraAttribute structure. For example, the value of
Instruction CurrentResolution must be supported by camera. Before setting
camera parameter, it is recommended to call
OsCameraGetParam() to obtain all the resolution types
supported by system.

PAX Computer Technology (Shenzhen) Co., Ltd. 274

 Prolin API Programming Guide

OsCameraCapture

int OsCameraCapture(char* Buf,

Prototype
int Size);
Function Take photo through camera.

Buf[Output] The data buffer of photography.

Parameters
Size[Input] The memory size of Buf.
>0 Actual collected data length.
ERR_DEV_NOT_OPEN Camera device is not open.
ERR_INVALID_PARAM Invalid parameter.
ERR_DEV_BUSY Device is busy.
Return ERR_BAR_CAMER_INI
Camera initialization failed.
T_FAILED
ERR_BAR_NOT_ENOU
Insufficient buffer.
GH_BUFFER
ERR_BAR_READ_CAM
Obtain photography data failed.
ERA_BUFFE_FAILED
1. Buf is used to buffer the photography data, the calculation
formula of the data size is [height]* [width]* [the number of
bytes occupied by each pixel]. For example, the Size of an
image with 480*640 resolution in yuyv/ rgb565 format (each
pixel occupies 2byte) should be 480*640*2 = 614400; while
the Size of an image with 1024*480 resolution in sbggr8
format (each pixel occupies 1byte) should be 1024*480*1 =
491520;. the Size of an image with 640*480 resolution in
NV21 format (each pixel occupies 3byte) should be
640*480*3/2 = 460800.
2. For image data in rgb565, the rgb information is stored by
the byte stream. For example, the first pixel point is stored
Instruction
by Buf[0] and Buf[1], and the rgb information is shown as
below:
r = Buf[0] & 0xF8;
g = ((Buf[0] << 5) & 0xE0) | ((Buf[1] >> 3) & 0x1C);
b = Buf[1] << 3;
or Buf[0] and Buf[1] can be combined into a temporary
variable in short data type:
unsigned short tmp_pixel = ((unsigned short)Buf[0] << 8) |
Buf[1];
r = (tmp_pixel >> 8) & 0xF8;
g = (tmp_pixel >> 3) & 0xFC;

PAX Computer Technology (Shenzhen) Co., Ltd. 275

 Prolin API Programming Guide

b = tmp_pixel << 3;
3. For image data in yuyv, all Y values will be assigned to
r.g.b, and U and V can be ignored, each 4-byte yuyv data
corresponds to two pixels:
int *yuyv = (int*)Buf;
int yy = *yuyv;
//The first pixel
char y1 = (char)yy;
r = y1; g = y1; b = y1;
// The second pixel
char y2 = (char)(yy >> 16);
r = y2; g = y2; b = y2;
//Keep traversing the yuyv data
yuyv++;
4. For image data in sbggr8, each byte is gray value, that is,
the value is assigned to r.g.b byte by byte:
char* ptr = Buf;
r = *ptr; g = *ptr; b = *ptr;
// Keep traversing the data
ptr++;
5. For image data in NV21, the first 640*480 bytes of the Buf
are the Y values of each pixel, that is, the value is assigned
to r.g.b byte by byte:
char* y = (char*)Buf;
r = y; g = y; b = y;
// Keep traversing the data
y++;

OsScanDecodeBuf

int OsScanDecodeBuf(const unsigned char *DataIn,

int DataInLen,
unsigned char *DataOut,
Prototype int MaxLen,
int Width,
int Height,
int Format);
Function Decode image data which containing the barcode data.

DataIn[Input] Image data.

Parameters DataInLen[Input] Length of the image data.

DataOut[Output] The buffer used to store barcode

data. For one-dimensional code, the

PAX Computer Technology (Shenzhen) Co., Ltd. 276

 Prolin API Programming Guide

buffer size is recommended to be

more than 512 bytes; for
two-dimensional code, the buffer
size is recommended to be more
than 3072 bytes.
MaxLen[Input] The size of the DataOut.
Width[Input] Image width. The value range is from
320 to 1280.
Height[Input] Image height. The value range is
from 320 to 1280.
Format[Input] The format of image data:
CAMERA_PIXEL_FORMAT_YUYV.
>=0 Read the byte length of the barcode
data from the image data.
ERR_SYS_NOT_SUPP
System does not support.
Return ORT
ERR_BAR_DECODE_F
Decoding failed.
AILED
ERR_INVALID_PARAM Invalid parameter.

Instruction The parameters DataInLen, Width and Height conform to the

formula “DataInLen=Width * Height * 2”.

OsCameraDetectMotion

int OsCameraDetectMotion(int threshold,

Prototype int interval,
int timeout);

Function Motion detection, the camera captures images at specified

intervals and checks for differences in two consecutive images.
The threshold of image difference
ranges from 0 to 100. When the
difference between two consecutive
threshold[Input] frames captured by the camera is
not less than the value of this
parameter, the function returns the
Parameters actual difference.
The interval between images
interval[Input] captured by the camera. [unit:
milliseconds]

timeout[Input] Interface blocking timeout in

seconds. The interface will return

PAX Computer Technology (Shenzhen) Co., Ltd. 277

 Prolin API Programming Guide

ERR_TIME_OUT if the interface

blocking has reached timeout and
the image difference has not been
detected to reach the set threshold.
Actual difference value of two
consecutive frames of images
>=0
captured by the camera (ranges
from threshold to 100).
Return
ERR_DEV_NOT_OPEN Camera is not open.
ERR_INVALID_PARAM Invalid parameter.
ERR_TIME_OUT Timeout.
1. Call OsCameraOpen() to open the camera before calling
this function, otherwise ERR_DEV_NOT_OPEN will be
returned, and call OsCameraClose() to close the camera
after the detection is finished.
2. The range of detected difference value is 0~100, so the
parameter threshold must be within this range, otherwise
ERR_INVALID_PARAM will be returned. In the actual
application scenario, the recommended value range is
20~50.
3. The value of the parameter interval that captures the image
Instruction determines the sensitivity of the detection. In the actual
application scenario, the recommended value range is
500~2000 in milliseconds.
4. The unit of the parameter timeout is second. When timeout
is set to 0, this function immediately returns the comparison
difference value after capturing two frames of images.
When timeout is greater than 0, interface blocking works. If
the difference value of two consecutive frames of images is
not less than the threshold parameter, the difference value
will be returned; otherwise, ERR_TIME_OUT will be
returned after blocking time.

PAX Computer Technology (Shenzhen) Co., Ltd. 278

 Prolin API Programming Guide

29Power Management

29.1 Return Code List

Macro Value Description

BATTERY_LEVEL_0 0 Battery level is 0.
BATTERY_LEVEL_1 1 Battery level is 1.
BATTERY_LEVEL_2 2 Battery level is 2.
BATTERY_LEVEL_3 3 Battery level is 3.
BATTERY_LEVEL_4 4 Battery level is 4.
BATTERY_LEVEL_CHARGE 5 Battery is being charged.
BATTERY_LEVEL_COMPLE
6 Battery is fully charged.
TE
BATTERY_LEVEL_ABSENT 7 Battery is absent.

29.2 Data Structure

PAX Computer Technology (Shenzhen) Co., Ltd. 279

 Prolin API Programming Guide

PM_MSG_T: events broadcasted by pm.

PM_MSG_T：

typedef enum {
PM_MSG_NO_EVENT, /* No event.*/
PM_MSG_ENTER_SLEEP, /* Device enters sleep mode.*/
PM_MSG_EXIT_SLEEP, /* Device exits sleep mode.*/
PM_MSG_ENTER_SCREENSAVER, /* Device enters screensaver
mode.*/
PM_MSG_EXIT_SCREENSAVER, /* Device exits screensaver
mode.*/
PM_MSG_ENTER_ POWEROFF, /* Device starts to power off*/
PM_MSG_POWER_ABNORMAL, /* Device power is abnomal*/
PM_MSG_BATTERY_DAMAGE, /* Battery is out of service */
} PM_MSG_T;

PM_REQ_T: action requested by client.

PM_REQ_T：

typedef enum {
PM_FORBID_SLEEP, /* Forbid device from sleeping. */
PM_ALLOW_SLEEP, /* Allow device to sleep.*/
PM_FORBID_SCREENSAVER, /*Forbid device from entering
screensaver mode. */
PM_ALLOW_SCREENSAVER, /* Allow device to enter screensaver
mode.*/
PM_FORBID_ POWEROFF, /*Forbid device from powering off. */
PM_ALLOW_ POWEROFF, /*Allow device to power off.*/
} PM_REQ_T;

POWER_TYPE: the type of power supply.

POWER_TYPE:
typedef enum {
POWER_ADAPTER = 1, /*Supplied by adapter.*/
POWER_USB, /*Supplied by USB external device.*/
POWER_BATTERY, /*Supplied by battery.*/
POWER_WPC /*Supplied by wireless base.*/
} POWER_TYPE;

PAX Computer Technology (Shenzhen) Co., Ltd. 280

 Prolin API Programming Guide

WAKEUP_SOURCE: the wakeup source

WAKEUP_SOURCE:
typedef enum {
WAKEUP_SRC_NONE = 0, /* No wakeup has been done, it has no
wakeup source. */
WAKEUP_SRC_KP, /* Key pressing wakeup */
WAKEUP_SRC_RTC, /* Timer wakeup */
WAKEUP_SRC_BT, /* Bluetooth wakeup */
WAKEUP_SRC_CHC, /* Power wakeup */
WAKEUP_SRC_WIFI, /* WIFI wakeup */
WAKEUP_SRC_MSR, /* MSR wakeup */
WAKEUP_SRC_SMARTCARD0 = 8, /* IC card wakeup */
WAKEUP_SRC_UART = 12, /* serial port wakeup*/
WAKEUP_SRC_ETHER, /* Ethernet wakeup */
WAKEUP_SRC_GENERAL1 = 1000, /* general wakeup 1 */
WAKEUP_SRC_GENERAL2, /* general wakeup 2 */
WAKEUP_SRC_GENERAL3, /* general wakeup 3 */
WAKEUP_SRC_GENERAL4, /* general wakeup 4 */
WAKEUP_SRC_GENERAL5, /* general wakeup 5 */
} WAKEUP_SOURCE;

29.3 OsCheckBattery

Prototype int OsCheckBattery(void);

Function Check the battery level.
Parameters None.
0~5%, low battery and need to be
charged immediately.
Transaction, wireless
BATTERY_LEVEL_0 communications and printing are
not recommended. When the
battery is too low, the system will
Return automatically power off.
BATTERY_LEVEL_1 5%~15%
BATTERY_LEVEL_2 15%~40%
BATTERY_LEVEL_3 40%~70%
BATTERY_LEVEL_4 70%~100%

PAX Computer Technology (Shenzhen) Co., Ltd. 281

 Prolin API Programming Guide

BATTERY_LEVEL_CHA Battery is being charged.

RGE
BATTERY_LEVEL_COM Battery is fully charged; external
PLETE power supply.
BATTERY_LEVEL_ABSE Battery does not exist; external
NT power supply.
System does not support
ERR_SYS_NOT_SUPPO checking battery level. Only
RT terminal without battery can return
this value.
1. When the terminal is being charged with external power
supply, it can detect whether the battery is fully charged or
not but cannot obtain the battery level. The battery level
can be detected only when the device is powered by
built-in battery.
2. It is not recommended to call this function during the
Instruction process of searching RF card, connecting wireless
network or printing, as the returned battery level might
bounce.

3. When BATTERY_LEVEL_0 is returned, wireless module,

printer and RF module may fail to work, the battery should
be charged immediately.

29.4 OsCheckPowerSupply

Prototype int OsCheckPowerSupply(void);

Function Check the type of power supply.

Parameters None.

POWER_BATTERY Powered by built-in battery.

POWER_ADAPTER Powered by power adapter.
Return
POWER_USB Powered by USB device, such as PC.
POWER_WPC Powered by wireless base.
Instruction Only D220 supports powering by wireless base.

PAX Computer Technology (Shenzhen) Co., Ltd. 282

 Prolin API Programming Guide

29.5 OsSysSleep

Prototype int OsSysSleep(void);

Function Get the terminal to enter sleep mode.

Parameters None.

RET_OK Succeeded.

Return ERR_SYS_NOT_SU Device doesn’t support.

PPORT
ERR_DEV_BUSY Device is busy.
1. The device will fail to enter sleep mode and return
ERR_DEV_BUSY in the following situations:
1) OsPmRequest() has been called to forbidd sleeping.
2) POS is being used as USB device
2. During the sleep, CPU will stop and the screen will be
turned off. After waken up by key, the screen will display
the same content as that before sleep and the system will
Instruction continue to run from where it stopped.
3. After Modem dialed successfully, calling OsSysSleep() or
OsSysSleepEx(2) will return ERR_DEV_BUSY, and the
system cannot sleep. After Modem hanged up, the system
can sleep by calling sleep function.
4. After the terminal enters sleep mode, Keypad and
communication module will not be powered off.
5. PX5, PX7, Q30, SP200, IM500, IM700 and IM310 don’t
support this function.

1. It is not recommended to start sleep when using RF card.

Otherwise, after the system wakes up, OsPiccClose() and
OsPiccOpen() must be called before performing other card
functions.
2. It is recommended to disconnect PPP connection by calling
OsWlLogout() before system enters sleep state, and to set
up PPP connection by calling OsWlLogin() after system
wakes up.
3. After system wakes up, OsScanClose() and OsScanOpen()
must be called in advance to process scanning operation.

PAX Computer Technology (Shenzhen) Co., Ltd. 283

 Prolin API Programming Guide

29.6 OsSysSleepEx

Prototype int OsSysSleepEx(int Level);

Function Set terminal power management mode.
Sleep level, value range is [0, 2].
0: System runs normally;
1: Screensaver mode.
CPU works normally; LCD, key backlight,
touch key and touch screen can be woken
up by plastic button and application
Parameters Level[Input] program.
2: System sleeps.
CPU is in standby mode, all modules are
closed, parts of modules can
be awakened by plastic button; and some
of them can be awakened by WiFi or
power button.
RET_OK Succeeded.
ERR_INVALID_PARAM Invalid parameter.
Return ERR_SYS_NOT_SUPPO
Device doesn’t support.
RT
ERR_DEV_BUSY Device is busy.
1. When Level=1, the system will enter screensaver mode. In
one of the following scenarios, it will fail to enter the
screensaver mode and return ERR_DEV_BUSY.
1) OsPmRequest() has been called to forbid screensaver.
2) The system is in PED mode.
2. When Level=2, it is the same as OsSysSleep().
3. The opened handles will not be closed in any sleep level.
4. Neither Level 0 nor Level 1 will change the current working
state of cards and communication modules. While in Lever
Instruction
2, all the modules will be closed except the plastic button,
communication module and the module which has been set
the wake-up source.
5. Normally, the screensaver mode will be activated if there is
no input within the specified interval whose default value is
60 seconds. The interval can be set by
persist.sys.backlighttime (unit: sec).
persist.sys.backlighttime=0 means turning off the
screensaver.
6. PX5, PX7, Q30, SP200 , IM500, IM700 and IM310 don’t

PAX Computer Technology (Shenzhen) Co., Ltd. 284

 Prolin API Programming Guide

support the Lever=2 sleep mode.

29.7 OsSysSleepTime

Prototype int OsSysSleepTime(int Time);

Enter sleep mode and wakeup automatically within specified
Function
Time.
Sleep duration.[Unit: sec]
The valid sleep duration ranges from 60 to
43200 (that is, 12 hours). For Prolin-2.4 and
Prolin-phoenix-2.5: If the sleep duration <128,
Parameter Time[Input] it will be set to 128 automatically. For
Prolin-cygnus-2.6 and higher version:If the
sleep duration <60, it will be set to 60
automatically; if the sleep duration>43200, it
wil be set to 43200 automatically.
RET_OK Suceeded.
Return ERR_SYS_NOT_SUP
Not supported by device.
PORT
1. The timing error of Prolin-2.4 and Prolin-phoenix-2.5 is
±128s; the timing error of Prolin-cygnus-2.6 and higher
version is ±1s.
2. ERR_SYS_NOT_SUPPORT will be returned, if this
function is called by Px5, Px7, Q30, SP200, IM500, IM700
Instruction
or IM310;
3. If OsPmRequest() is called or terminal is connected as a
USB device, calling this function will return
ERR_DEV_BUSY and the terminal cannot enter sleep
mode.

29.8 OsReboot

Prototype int OsReboot(void);

Function Reboot the terminal.

Parameters None.

Return ERR_SYS_BAD System error.

Instruction This function works in blocking mode. If this function is

PAX Computer Technology (Shenzhen) Co., Ltd. 285

 Prolin API Programming Guide

executed successfully, the terminal will reboot directly without

any return value.

29.9 OsPowerOff

Prototype int OsPowerOff(void);

Function Power off the terminal.
Parameters None.
Return ERR_SYS_BAD System error.
This function works in blocking mode. If this function is executed
Instruction successfully, the terminal will be powered off directly without
any return value.

29.10 OsPmGetEvent

Prototype PM_MSG_T OsPmGetEvent(int TimeoutMs);

Function Get the events sent by PM module.
Timeout.[Unit: ms]
The value range of TimeoutMs includes
Parameters 0 and number ranging from 100 to
TimeoutMs [Input]
3600000.
TimeoutMs=0 means to get the event
in nonblocking mode.
ERR_INVALID_PAR
Invalid parameter
Return AM
>=0 Please refer to PM_MSG_T
Each time OsPmGetEvent is called, a power management
Instruction event can be got. It is recommended that the TimeoutMs
parameter should not be more than 1000ms.

1. There must be only one OsPmGetEvent() in a process.

2. Before an event occurs, call OsPmGetEvent(0) to establish a
link between the application process and the daemon
service, after establishment, the subsequent power

PAX Computer Technology (Shenzhen) Co., Ltd. 286

 Prolin API Programming Guide

management events can be sent to the application process.

And OsPmGetEvent() can be called to get event directly
when the power management event occurs. If
OsPmGetEvent() is not called for a long time, the events will
be lost.

29.11 OsPmRequest

Prototype int OsPmRequest(PM_REQ_T ReqType);

Function The client requests device to enter into a specified mode
The corresponding meanings of specified
events please refer to PM_REQ_T
structure.
For example：
Parameters ReqType[input]
PM_FORBID_SLEEP: Forbid the device
from entering sleep mode.
PM_ALLOW_SLEEP: Allow the device to
enter sleep mode.
ERR_INVALID_PARAM Parameter error.
Return
RET_OK Succeeded.
1. The “forbid” and “allow” action don’t have to be used in
pairs.
For example:
Instruction RET_OK will always be returned no matter how many times
PM_FORBID_SLEEP is called.
2. The device will enter sleep mode as long as
PM_ALLOW_SLEEP is called.

29.12 OsWakeupSource

Prototype int OsWakeupSource(void);

Function Get the wakeup source which makes the terminal wake up.
Parameters None
Enumeration values of the wakeup
Return source.
>=0
Please refer to the enumeration
structure WAKEUP_SOURCE for the

PAX Computer Technology (Shenzhen) Co., Ltd. 287

 Prolin API Programming Guide

corresponding wakeup source of each

value.
ERR_SYS_NOT_SU The system does not support.
PPORT
Because different models have different hardware
Instruction configurations, a model may support only one or several
wakeup sources.

29.13 OsCheckPowerStatus

Prototype int OsCheckPowerStatus(int *PowerStatus);

Function Check the power status.
Power status:
Bit0: Battery voltage status, 0-normal;
1-abnormal;
Bit1: Battery charging status, 0-normal;
1-abnormal;
Bit2: Charging IC status, 0-normal;
1-abnormal;
Parameters PowerStatus[Output]
Bit3: Whether the battery is damaged,
0-no, 1-yes;
Bit4: Whether the charging cycle
exceeds the limitation, 0-no, 1-yes;
Bit5: SOH, 0-health, 1-aging seriously;
Bit6~Bit31: Reserved.
RET_OK Succeeded
ERR_SYS_NOT_SU
Return Device does not support.
PPORT
ERR_INVALID_PARA Invalid parameter.
M
1. This function only supports terminals with battery, such as
S920, D190,D195 and terminals with voltmeter (Q80, Q92,
QR68, QR65);
2. Due to the differences in model and hardware, the system
Instruction may not be able to detect all the abnormal types in the
above list.
Model Exception type that support detection
S920 S920 V20: Bit0-Bit5

PAX Computer Technology (Shenzhen) Co., Ltd. 288

 Prolin API Programming Guide

Other S920 with voltmeter: Bit0-Bit2

D190 V06 and higher version: Bit0-Bit1
D190, D195
Other D190 version and D195: Bit0
Q80 Bit0, Bit3-Bit5
Q92 Bit0-Bit5
QR68, QR65 Bit0

In case of abnormal battery damage of Bit3, the system will

periodically broadcast the PM_MSG_BATTERY_DAMAGE event
and stop charging, and the battery voltage is controlled within
3.6V. Please be sure to replace the battery. Other abnormal
events are broadcast with PM_MSG_POWER_ABNORMAL.

29.14 OsCheckBMSMode

int OsCheckBMSMode(int*CurrentMode,
int *Capacity,
Prototype
int *FullCharge,
int *Recharge);
Function Get information about battery management system.

CurrentMode[Output] Current mode of the terminal.

Current battery capacity, it ranges from

Capacity[Output]
0 to 100%.
Parameters
FullCharge[Output] Full charge, it ranges from 0 to 100%.

Recharge[Output] Recharge, it ranges from 0 to 100%.

RET_OK Succeeded
ERR_INVALID_PARA Invalid parameter.
Return M
ERR_SYS_NOT_SU System does not support.
PPORT
Instruction

PAX Computer Technology (Shenzhen) Co., Ltd. 289

 Prolin API Programming Guide

29.15 Get the Power Management Information

PM_MSG_T msg;
while(1) {
msg = OsPmGetEvent(100000);
if (msg > 0) {
switch (msg) {
case PM_MSG_ENTER_SLEEP:
break;
case PM_MSG_EXIT_SLEEP:
break;
/*add other case*/
default:
break;
}
}
}

29.16 Client Sends Request

OsPmRequest(PM_FORBID_SLEEP); /* Forbid system from sleeping.*/

OsPmRequest(PM_ALLOW_SLEEP); /* Allow system to sleep.*/
OsPmRequest(PM_FORBID_SCREENSAVER); /* Forbid screensaver.*/
OsPmRequest(PM_ALLOW_SCREENSAVER); /* Allow screensaver.*/
OsPmRequest(PM_FORBID_POWEROFF); /*Forbid system from powering
off.*/
OsPmRequest(PM_ALLOW_POWEROFF); /*Allow system to power
off.*/

PAX Computer Technology (Shenzhen) Co., Ltd. 290

 Prolin API Programming Guide

Appendix 1 PIN Block Format

Format 0 PIN block

This PIN block is constructed by modulo-2 addition of two 64-bit fields: the plain text
PIN field and the account number field. The formats of these fields are described in
1.1.1 and 1.1.2 respectively.

The format 0 PIN block shall be reversibly enciphered when transmitted.

Plain text PIN field

The plain text PIN field shall be formatted as follows.

Bit

1 5 9 13 17 21 25 29 33 37 41 45 49 53 57 61 64

C N P P P P P P/F P/F P/F P/F P/F P/F P/F F F

where

C = Control field: shall be binary 0000;

N = PIN length: 4-bit binary number with permissible values of 0100(4) to 1100(12);

P = Pin digit: 4-bit field with permissible values of 0000(zero) to 1001(9);

P/F = PIN/Fill digit: designation of these fields is determined by the PIN length field;

F = Fill digit: 4-bit field value 1111(15).

Account number field

The account number field shall be formatted as follows.

Bit

PAX Computer Technology (Shenzhen) Co., Ltd. 291

 Prolin API Programming Guide

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

Wherein,

0 = Pad digit: a 4-bit 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

Wherein,

C = Control field: shall be binary 0001;

PAX Computer Technology (Shenzhen) Co., Ltd. 292

 Prolin API Programming Guide

N = PIN length: 4-bit binary number with permissible values 0100(4) to 1100 (12);

P = PIN digit: 4-bit field 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).

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

PAX Computer Technology (Shenzhen) Co., Ltd. 293

 Prolin API Programming Guide

C N P P P P P/F P/F P/F P/F P/F P/F P/F P/F F F

Wherein,

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;

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 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. 294

 Prolin API Programming Guide

Appendix 2 EPS PINBLOCK Format

String format: “1234”+ISN [6 bytes] +PIN [byte bit];

If PIN is less than 6 bytes, add “0” at the beginning ofPIN;

Convert the above data into BCD code and use TPK to encrypt the BCD code with
DES/TDES algorithm.

PAX Computer Technology (Shenzhen) Co., Ltd. 295

 Prolin API Programming Guide

Appendix 3 Registry

The table below is a registry of functions which mainly begin with “ro.fac.” and
“persist.sys.”. The "ro.fac." are read-only and"persist.sys." can be both read and
written.

System configuration
Description
name
ro.fac.bootver Boot version information.
Hardware version number. Main board- interface
ro.fac.hwver
board.
ro.fac.mach Product model name.
Boardid information, including the product model,
ro.fac.boardid
hardware version number, etc.
ro.fac.conf.ver Version information of configuration files.
ro.fac.pn PN number.
ro.fac.sn SN number.
Prolin_debug_level information, this value is 0 and 1
ro.fac.prolin_debug_level
for release system and debug system, respectively.
Whether there is a network cable port.(0: does not
ro.fac.eth
exist; 1: exist)
Whether there is a main device interface.(0: does
ro.fac.usb.host
not exist; 1: exist)
Whether there is an USB device interface.(0: does
ro.fac.usb.device
not exist; 1: exist)
Whether there is an USB OTG interface.(0: does not
ro.fac.usb.otg
exist; 1: exist)
Whether there is a LED digital tube.(0: does not
ro.fac.leddt
exist; 1: exist)
Key types.(0: have no key; 1: physical button; 2:
ro.fac.keybroad
touch-screen button)
Whether there is a Buzzer module.(0: does not
ro.fac.buzzer
exist; 1: exist)
ro.fac.simsocket The number of SIM card slot.
Whether there is a battery.(0: does not exist; 1:
ro.fac.battery
exist)
Whether there is a coulombmeter. (None means it
ro.fac.coulomb_counter
does not exist by default.)

PAX Computer Technology (Shenzhen) Co., Ltd. 296

 Prolin API Programming Guide

Name of WiFi module.(None means it does not exist

ro.fac.wifi
by default.)
Name of Bluetooth module.(None means it does not
ro.fac.bt
exist by default.)
Wireless module information and parameter
information (optional). Used for multiple wireless
ro.fac.radio
modules; separated. (None means it does not exist
by default.)
Name of Modem module. (None means it does not
ro.fac.modem
exist by default.)
Name of Printer module. (None means it does not
ro.fac.printer
exist by default.)
Name of PCD module. (None means it does not
ro.fac.pcd
exist by default.)
Name of IC card reader. (None means it does not
ro.fac.sci
exist by default.)
Name of MSR reader. (None means it does not exist
ro.fac.msr
by default.)
Name of LCD module. (None means it does not
ro.fac.videocard
exist by default.)
Name of audio card module. (None means it does
ro.fac.audiocard
not exist by default.)
Name of Touch-screen module. (None means it
ro.fac.touchscreen
does not exist by default.)
Supported specification, capacity range and speed
ro.fac.sdhc level of SD card. (None means it does not exist by
default.)
ro.fac.barcode Name of barcode module
ro.fac.camera_number Number of camera(None means it has no camera)
ro.fac.camera_front Name of front camera
ro.fac.camera_back Name of back camera
ro.fac.barcode_cipher_chi Name of cipher chip (Used for camera scanning
p code.)
Name of SM ciper chip(None means it does not
ro.fac.cipher_chip
exist by default.)
PCD antenna parameter 1. (None means PCD does
ro.fac.pcd.param1
not exist.)
PCD antenna parameter 2. (None means PCD does
ro.fac.pcd.param2
not exist.)

PAX Computer Technology (Shenzhen) Co., Ltd. 297

 Prolin API Programming Guide

PCD antenna parameter 3. (None means PCD does

ro.fac.pcd.param3
not exist.)
ro.fac.lcd.rotate LCD clockwise rotation degrees. (0,90,180, 270)
Security level, the value can be 1 or 2. When
updating firmware, the security level of the new
ro.fac.security_level
firmware should be higher than the old one and
Boot.
Security mode, the value can be 0, 1 or 2. 0
represents production state, it only exists in the
process of factory production; 1 represents factory
ro.fac.security_mode
state, it indicates non-authorization scheme; 2
represents security state, it indicates authorization
scheme.
Version information of PCI. (This information is
ro.security_version
available for models certified by PCI)
DHCP is open or not. (true: open; false or none:
persist.sys.eth0.dhcp
closed)
persist.sys.eth0.ip Ethernet ip address.
persist.sys.eth0.mask Ethernet subnet mask.
persist.sys.eth0.gateway Ethernet gateway.
Ethernet network port speed.(eth_auto: automatic
configuration; eth_10mhd: 10M half-duplex;
persist.sys.eth0.speed
eth_10mfd: 10M full-duplex;eth_100mhd: 100M
half-duplex; eth_100mfd: 100M full-duplex)
persist.sys.prolin Prolin system version information.
persist.sys.language System language.
Time interval to enter screensaver mode from
normal mode automatically. (The time interval
ranges from 0 to 7200 sec. It will be set to 60 sec by
default if screensaver time is not more than 30 sec;
persist.sys.backlighttime
it is the set value if more than 30 sec. The system
will automatically enter screensaver mode if there is
no operation for specified time. 0 means closing the
screensaver mode.)
Time interval to enter sleep mode from screensaver
mode automatically. (The valid value ranges from 0
persist.sys.sleeptime
to 60s, and the default value is 0, which means the
auto-enter sleep mode is disabled)
Wait time for user process to deal with events before
persist.sys.sleepwaittime the system enters sleep mode. (The value range is
from 0 to 15s, the default value is 1, which means
the user is notified that system will sleep and is

PAX Computer Technology (Shenzhen) Co., Ltd. 298

 Prolin API Programming Guide

given 1 second to handle events before system

goes to sleep.)
After long pressing the power key or OsReboot() is
called, the system will power off after
persist.sys.delayshutdow persist.sys.delayshutdown seconds. (The
n persist.sys.delayshutdown value ranges from 0~600
seconds, and the default value is 0.) It is invalid
when OsPowerOff() is called.
Setting it to 1 means the screen will display the
shutdown confirmation interface after pressing the
power key for 3 seconds, press “Enter” key to
continue the shutdown or press “Cancel” key to
persist.sys.confirmshutdo cancel the shutdown. Setting it to 0 means the
wn terminal will power off immediately after pressing
power key for 3 seconds.
By default, this value is 0 for Prolin-2.4 system and
Prolin-phoenix-2.5 and 1 for Prolin-cygnus-2.6 and
higher version.
Whether to open the keypad tone. (False means
persist.sys.sound.enable closed; true means open) The setting will take effect
after reboot.
The status of current key tone (0 means off; 1
means open. It is not recommended to modify the
rt.app.key.tone
keyword. Only prolin-peng-2.8 supports this
keyword)
The duty cycle of PWM (valid range is from 1 to 99).
persist.sys.keypad.duty_c It is used to adjust the buzzer volume when pressing
ycle the button, and the setting will take effect after
reboot.
Whether the button backlight is open or not. (0
persist.sys.key.backlight
means closed; 1 means open)
The status of current key backlight (0 means off; 1
means open. It is not recommended to modify the
rt.app.key.backlight
keyword. Only prolin-peng-2.8 supports this
keyword)
LCD brightness. (The valid brightness ranges from 1
persist.sys.lcd.brightness
to 10 and the higher, the brighter.)
LCD brightness in screensaver mode(This value
ranges from 0 to 10, the effect of setting this value is
persist.sys.lcdsaverbright the same as calling OsScrBrightness.This variable
ness only applies to auto-screensaver and
OsSysSleepEx(1), and it will take effect immediately
after setting this value. )
persist.sys.sound.volume Audio/video sound volume. (The valid volume

PAX Computer Technology (Shenzhen) Co., Ltd. 299

 Prolin API Programming Guide

ranges from 0 to 4.)

persist.sys.auto.mount.en
Mount u disk or sd card automatically or not.
able
persist.sys.xcb.enable Open or close XCB service.（0: close; 1: open）
Network port number of XCB service. (It is the
persist.sys.xcb.tcp.port network port number when using network; it is -1
when using other ways.)
USB or COM of XCB service. (When using USB, it is
/dev/ttydev; when using COM port, it is /dev/ttyAMA*
(* means the represented value, refer to
persist.sys.xcb.rs232
[ro.kernel.CONSOLE]: [ttyAMA3, 115200] as it may
vary from model to model); it is null when using
network.)
System sleeps for autowaketime seconds and then
automatically wakes up.
If autowaketime has not been set, it means the
autowake function is disabled, and the system will
not wake up automatically.
If autowaketime is set to less than 0, the system will
not wake up automatically.
persist.sys.autowaketime If the autowaketime is set to be greater than 0 and
less than 128s, then systems will automatically
wake up after 128s;
If the autowaketime is set to be greater than
12*60*60s, which is 12 hours, the system will
automatically wake up after 12 hours.
If application calls OsSysSleep() or OsSysSleepEx()
to enter the sleep state, this variable will not work,
and the system will not wake up automatically.
persist.sys.console.enabl
Open/close console (0: close, 1: open)
e
Enable or disable the function of DHCP when the
persist.sys.wifi.roam.dhcp terminal is in roaming state. (0: disable, 1: enable)
and it is enabled by default.
persist.sys.tm.imei The IMEI value of wireless module
Set time zone. For tz values of various regions,
please refer to standard Linux tz value. For more
persist.sys.timezone.tz
information on how to set time zone, please refer to
“Prolin Application Development Manual”
Enable/disable the function of continuing to print
persist.sys.continue.print
after a shutdown. (0: disable, 1:enable )
persist.sys.autouload.ena Enable/disable USB flash driver auto-downloading

PAX Computer Technology (Shenzhen) Co., Ltd. 300

 Prolin API Programming Guide

ble function at the POS terminal startup.( 0: disable,

1:enable)
Terminal host name(If the host name is not filled, it
means this term does not exist. Developers can use
the internet or Linux standard method to acquire the
hostname. The default hostname is “product
persist.sys.hostname
name-series number”. After this value is being set, it
will not take effect until the terminal is rebooted, and
the display of hostname requires the terminal to
connect to the internet again.)
Acquire wireless module firmware version
persist.sys.wnet.version
information.
Enable/disable the function of starting the terminal
automatically when terminal is being charged. (0:
persist.sys.autostartup.en disable, 1:enable, and the default startup method
able will be used when this value is not filled in. Prolin-2.4
and Prolin-phoenix-2.5 doesn’t support this
configuration.)
When setting it to 1, if PED tampers, XCB service
will be enabled; if POS enters TM, XCB service will
persist.sys.enable.debug also be enabled, and after entering the application,
XCB service will restore to the original status which
is before POS entering TM.
Whether to restart the application automatically after
persist.sys.mainapp.resta MAINAPP abnormally crashes. (1 represents Yes,
rt and the application can be restarted 10 times at
most; 0 represents No)
Whether to restart the main application
rt.sys.mainapp.restart automatically after a normal exit. (1 represents Yes;
0 represents No)
When inputting PIN, mask the specified keys on soft
keypad, and this function has no effect on physical
persist.sys.ped.keypad.m
key. Currently, it only supports passing “cancel” into
ask
QR55, and masking “cancel” key while inputting
PIN.
Switch the soft keypad style of inputting PIN, after
setting the registry value, it will take effect on the
next time the PIN is inputted.
 when it is set to “0”, the default soft keypad will
persist.sys.ped.keypad.ty
be used;
pe
 when it is set to “1”, the 1PIN keypad
customized for Q20 will be used (“displaying on
top and inputting at bottom” soft keypad in
disordered mode);

PAX Computer Technology (Shenzhen) Co., Ltd. 301

 Prolin API Programming Guide

 when it is set to “2”, the 1PIN keypad

customized for D220 will be used;
 When it is set to “3”, the 2PIN keypad
customized for D220 will be used;
 when it is set to “4”, the 2PIN keypad
customized for Q20 will be used;
 When it is set to “5”, the 3PIN keypad
customized for Q20 will be used;
 when it is set to “6”, the 4PIN keypad
customized for Q20 will be used;
 when it is set to “7”, the 5PIN keypad
customized for Q20 will be used;
 when it is set to “8”, the 6PIN keypad
customized for Q20 will be used.
persist.sys.batterylow.offc Record the times of auto shutdown caused by low
nt battery.
persist.sys.reboot.cnt Record the times of calling OsReboot().
persist.sys.powerkey.offc Record the times of shutdown by long pressing on
nt the power key.
Whether to use static DNS server address. It
defaults to “0”, that is, if DHCP is enabled, DNS
server address acquired by DHCP will be used; If it
persist.sys.dns.static set to “1”, OS will ignore the DNS server address
acquired by DHCP and use the static DNS server
address set by users, and DHCP will not modify the
static DNS server address.
Whether to disable XCB to install AIP/AUP. If it is
persist.sys.xcb.installapp. set to “1”, the function of installing AIP/AUP through
lock XCB is disabled; if it is set to “0”, the function of
installing AIP/AUP through XCB is enabled.
Whether to enable the dynamic center display
function of PIN ICON.
 when it is set to “1”, while inputting PIN, the
foreground image which is passed in after
calling OsPedSetPinIconLayout() will be
persist.sys.ped.pin.icon.al
centered and displayed dynamically, and the
ign
background image will not be displayed at the
same time;
 when it is set to “0”, the foreground image will
restore to normal display, and the default value
is “0”.
Set the mode for USB device, and it will take effect
persist.sys.usbd.mode after restart.
 When it is set to “1”, the POSVCOM single

PAX Computer Technology (Shenzhen) Co., Ltd. 302

 Prolin API Programming Guide

channel mode with old Product ID and old

Vender ID will be used, and it’s the default
mode;
 When it is set to “2”, CDC single channel mode
will be used;
 When it is set to “3”, the POSVCOM single
channel mode with new Product ID and old
Vender ID will be used;
 When it is set to “4”, ECM mode will be used,
after the device is connected to the upper
computer, a USB0 virtual network card will be
enumerated at both sides;
 When it is set to “5”, the dual-channel mode will
be used;
 When it is set to “6”, CDC ACM + CDC ECM
mode will be used, and this mode is compatible
with the USB dual-channel mode and has a
virtual network port usb0;
 When it is set to “7”, the POSVCOM
three-channel mode will be used;
 When it is set to “8”, the CDC ACM
three-channel mode will be used.
Whether to restart the terminal regularly.
 When it is set to an integer between 1 and 48,
the set value (Unit: hour) will be used as the
period for restarting the terminal. This feature
will not take effect until the registry is set
successfully and the terminal is restarted. This
value defaults to "0", the function of restarting
persist.sys.ped.reboot.cyc
the terminal regularly will be disabled at this
le
time.
 When it is set to more than 48h, the system will
set the restart period to 48h. When the
continuous running time of the system reaches
the restart period, a countdown prompt interface
will appear in advance of 5s, and then the
terminal will be automatically restarted.
Whether it is forbidden to press the cancel key to
exit the PIN waiting interface when entering PIN.
 The default value is "0", that is, pressing the
persist.sys.ped.pinwait.ret cancel key to exit the pin waiting interface is
ain allowed.
 If the value is set to "1", it is forbidden to press
the cancel key to exit the PIN waiting interface
when entering PIN. After setting this value, it will
take effect when entering the pin waiting

PAX Computer Technology (Shenzhen) Co., Ltd. 303

 Prolin API Programming Guide

interface next time.

persist.sys.tm.cpu CPU information of the terminal.
persist.sys.tm.flash Flash size of the terminal. (For example, "128MB ")
persist.sys.tm.ram Memory size of the terminal. (For example, "64MB ")

PAX Computer Technology (Shenzhen) Co., Ltd. 304

 Prolin API Programming Guide

Appendix 4 Validity of Models and Contents

Allowing for the configuration differences for different models, some OSAL interfaces

may be invalid for certain kinds of model. For the validity of different models and

chapters, please refer to the table below.

Note: Whether there is Wireless module, Modem module or Ethernet module

depends on the model configuration. (Refer to the POS PN number)

Chapters S300 S800 S900 S920 D200 PXX Q80 D220

Thread √ √ √ √ √ √ √ √

System √ √ √ √ √ √ √ √

Function

Encryptio √ √ √ √ √ √ √ √

n and

Decryptio

PED √ √ √ √ √ √ √ √

LCD 240*32 320*240 240*320 240*320, 240*32 800*480 480*80 480*80

0, , rotate , rotate rotate 0, no 0 no 0 no

no
rotate 90°in 90°in 90°in rotatio rotatio rotatio
rotation
90°in clockwis clockwis clockwise n n n

clockwi e e direction

PAX Computer Technology (Shenzhen) Co., Ltd. 305

 Prolin API Programming Guide

se direction direction

directio

Keyboard √ √ √ √ √ √ √ NA

Touch √ NA √ √ NA √ √ √

Screen

Signature √ NA √ √ NA √ √ √

Pad

Printer NA √ √ √ NA NA √ NA

Font √ √ √ √ √ √ √ √

Library

Code √ √ √ √ √ √ √ √

MSR √ √ √ √ √ √ √ √

IC Card √ √ √ √ √ √ √ √

Reader

RF √ √ √ √ √ √ √ √

Reader

Communi PORT PORT_ PORT_ PORT_U PORT PORT_C PORT PORT

PAX Computer Technology (Shenzhen) Co., Ltd. 306

 Prolin API Programming Guide

cation _COM COM1 COM1 SBDEV _COM OM2 _COM _USB

Port 1 1 1 DEV
PORT_ PORT_ PORT_U PORT_U

PORT COM2 USBDE SBHOST PORT SBDEV PORT PORT

_USB V _ _PINP _USB

PORT_ PORT_U
DEV USBD AD HOST
PINPAD PORT_ SBHOST
EV
PORT USBHO PORT
PORT_
_USB ST PORT _USB
USBDE
HOST _USB DEV
V
HOST
PORT
PORT_
_USB
USBHO
HOST
ST

MODEM N/A √ N/A N/A N/A NA √ NA

Network √ √ √ N/A N/A √ √ √

Communi

cation

Network √ √ √ N/A N/A √ √ √

Configura

tion

GPRS/CD N/A √ √ √ N/A √ √ √

MA
(optional)

PAX Computer Technology (Shenzhen) Co., Ltd. 307

 Prolin API Programming Guide

WiFi N/A N/A √ √ √ √ √ √

(optional)

File √ √ √ √ √ √ √ √

System

System √ √ √ √ √ √ √ √

Informati

on

Audio √ √ √ √ N/A √ √ √

Power N/A N/A √ √ √ √ √ √

Managem

ent

Barcode N/A N/A √ N/A N/A NA NA NA

Bluetooth N/A N/A N/A √ √ √ √ √

(optional)

PAX Computer Technology (Shenzhen) Co., Ltd. 308