Prolin API Programming

Guide
V 2.5.3

PAX Computer Technology(Shenzhen)Co.,Ltd.

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

Copyright Statement

Copyright © 2000-2022 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 “pow-hwclock –
2013-04-17 V1.0.5 Prolin Team
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 Timer; Prolin Team

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().

III
 1. Added parameter description of
KeyVarType about 0x02 in
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
2013-11-20 V2.0.0 Prolin Team
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;
2014-04-16 V2.0.4 3. Added a new interface Prolin Team
OsSysSleepEx();

IV
 4. Removed MountFlag’s support to
MS-MOVE in OsMount();
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();
2014-11-26 V2.0.8 Prolin Team
2. Added U disk file format limitation
in OsMount();

V
 3. Added the instruction of
parameter Channel about S920
model in OsPortOpen();
4. Modified the instruction of
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 5. Added a new return value and Prolin Team
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.

VI
 1. Added a new return value
ERR_APP_NOT_EXIST in
OsRunApp();
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

2015-02-06 V2.1.0 ERR_WL_NOREG in OsWlInit() Prolin Team
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.

VII
 1. Revised the V2.1.1 version of this
documentation;
2. Added a return value and
function instruction in condition
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
2015-07-09 V2.1.2 Prolin Team
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
2015-11-24 V2.1.3 PED; Prolin Team
5. Added the SM part in
OsPedWriteKey() function;
6. Added nine functions in the
chapter of PED, including
OsPedGenSM2Pair(),
OsPedWriteSM2Key(),
OsPedSM2Sign(),
OsPedSM2Verify(),
OsPedSM2Recover(),
OsPedSM(), OsPedSM(),

VIII
 OsPedGetMacSM(), and
OsPedGetPinBlockSM4();
7. Added two new return values
ERR_MSR_END_ZEROERR
and
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.

IX
 1. Updated the instruction of
OsSysSleep();
2. Modified the value range of
ConnectTimeout from 0~300 to
0~60 in the table of Variable
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
2016-07-04 V2.1.5 persist.sys.lcdsaverbrightness Prolin Team
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
2016-07-21 V2.1.6 member of ST_WifiApSet structure Prolin Team
in the instruction of OsWifiConnect();
4. Added two new system
configuration parameters
persist.sys.wifi.roam.dhcp
and persist.sys.tm.imei in
Appendix 3 Registry;

X
 5. Updated the instruction of
OsGpsClose();
6. Updated the instruction of
OsWlSwitchPower();
7. In 6.5.6
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,
2017-03-10 V2.1.8 Prolin Team
persist.sys.autostartup.enable,
persist.sys.hostname,
persist.sys.wnet.version and

XI
 persist.sys.confirmshutdown in
Appendix 3 Registry;
2. In Network Configuration
chapter, added two new return
values ERR_ROUTE_EXIST 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();
2017-07-13 V2.1.9 3. Added note of OsSysSleep(); Prolin Team
4. Added ro.fac.coulomb_counter
key in registry table;
5. Modified the function of
OsGetSysVer();

XII
 6. Added a note of OsSysSleep();
7. Modified the instruction of
OsPortRecv();
8. Added persist.sys.enable.debug
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;
2017-11-15 V2.2.1 4. Added persist.sys.sound.enable Prolin Team
in registry table;
5. Modified the description of
persist.sys.delayshutdown in
registry table;
6. Modified the instructions of
OsSysSleep() and
OsSysSleepEx();

XIII
 7. Updated the instruction of
OsPmGetEvent();
8. Added ro.fac.security_level and
ro.fac.security_mode in registry
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
2018-05-23 V2.2.4 Prolin Team
description of parameters DataIn
and Mode in

XIV
 OsPedUpdatePinBlock() and the
description of parameters
InitVector, DataInLen and Mode
in OsPedAes();
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
2018-11-15 V2.2.6 Prolin Team
OsStopPlayAudio();
4. Added macros
RESOLUTION_WIDTH_1024_H
EIGHT_480 and
CAMERA_PIXEL_FORMAT_SB
GGR8 in chapter “Barcode and
Camera”;

XV
 5. Updated the instruction in section
OsCameraCapture();
6. Updated the parameter and
instruction in
OsPedGetPinBlock();
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
2019-03-13 V2.2.9 registry; Prolin Team
2. Added new interface OsLed(),
and list the interface parameter

XVI
 settings related to the model in
the instruction;
3. Updated parameter KeyFlag in
OsPedSetFunctionKey(), and the
instruction of
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 Chen Xiaoyong
2019-09-12 V2.3.4 OsPedCancelPinEntry() and
OsPedEndPinEntry(); Zheng Zhihai

XVII
 2. Updated the parameter
description of
OsPedGetPinBlock();
3. Added keywords
“persist.sys.ped.reboot.cycle”
and
“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 Zhang Mengying
registry; Zheng Zhihai
4. Added section “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”.

XVIII
 1. Update the user configuration
structure in the chapter “RF
Reader”.
2. Modified the description of the Zhang Mengying
2020-05-13 V2.3.9 keyword ro.fac.videocard;
3. Added descriptions of keywords Huang Ruzhen
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.
1. Optimized the structure of the
PED chapter;
2020-11-19 V2.4.1 Yang Yongquan
2. Added APIs AES MKSK and AES
DUKPT.
1. Added caution in chapter LCD;
2020-12-09 V2.4.2 Zhang Mengying
2. Updated chapter Touch Screen.
Updated the return code list in
2021-01-21 V2.4.3 Fang Wei
chapter Barcode and Camera.
1. Added structure member
PCD_USER_ST;
2. Added instruction of Hu Liancong
OsPiccSetUserConfig();
2021-04-27 V2.4.4 Zhang Mengying
3. Modified the return value of
OsBaseConnect(); Wu Haisheng
4. Added a new interface
OsIccTransfer().
Added a new interface
2021-08-06 V2.4.5 Liao Wenxiong
OsPrnRawData().
Added the description of the keyword
2021-08-30 V2.4.6 Zhang Mengying
"persist.sys.tm.pwd".
Modified the interface
2021-11-29 V2.4.7 Li Ling
OsGetBaseInfo and OsOnBase.
Modified the instruction of
2021-11-30 V2.4.8 He Wenliang
OsWlGetSignal.
Modified the instruction of
2021-12-27 V2.4.9 Yang Yongquan
OsPedWriteRsaKey.
Added new interfaces
OsPedCalcAesGcm,
OsPedGenerateEccKeyPair,
2022-02-28 V2.5.0 OsPedWriteEccKey, Huang Ruzhen
OsPedReadEccPublicKey,
OsPedEccSign, OsPedEccVerify and
OsPedEccPointMul.
Modified the instruction of the
2022-03-02 V2.5.1 parameter Mac [Output] of Yang Yongquan
OsPedGetMacAes.

XIX
 1. Modified the instruction of
OsOnBase.
2022-03-18 V2.5.2 Li Ling
2. Added a registry key
persist.sys.switch.tm.app.
Modified the ScrKeyType in the
2022-03-24 V2.5.3 Yang Yongquan
interface OsPedWriteAesKey.

XX
Table of Contents

History of Revisions .................................................................................................... II

Table of Contents .................................................................................................... XXI

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

4.3.1 OsSetTime ..................................................................................... 10

4.3.2 OsGetTime ..................................................................................... 11

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

4.4.1 OsTimerSet .................................................................................... 11

XXI
 4.4.2 OsTimerCheck ............................................................................... 11

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

4.5.1 OsSleep.......................................................................................... 12

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

4.7 Log ........................................................................................................... 12

4.7.1 OsLogSetTag ................................................................................. 12

4.7.2 OsLog ............................................................................................. 13

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

4.8.1 OsGetTickCount ............................................................................. 13

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

4.9.1 OsGetAppInfo................................................................................. 14

4.9.2 OsGetOptInfo ................................................................................. 14

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

4.10.1 OsBeep .......................................................................................... 15

4.11 Key tone ................................................................................................... 15

4.11.1 OsSetKeyTone ............................................................................... 15

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

4.12.1 OsRunApp ...................................................................................... 16

4.12.2 OsGetAppExitCode ........................................................................ 17

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

4.13.1 OsRegSetValue .............................................................................. 17

4.13.2 OsRegGetValue ............................................................................. 18

XXII
4.14 Install and Uninstall Files.......................................................................... 18

4.14.1 OsInstallFile.................................................................................... 18

4.14.2 OsUninstallFile ............................................................................... 20

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

4.15.1 OsFirmwareGetVersion .................................................................. 21

4.15.2 OsFirmwareUpgrade ...................................................................... 21

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

4.16.1 OsVerifySign .................................................................................. 22

4.16.2 OsVerifySignExternal ..................................................................... 23

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

4.17.1 OsGetSysVer ................................................................................. 24

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

4.18.1 OsOnBase ...................................................................................... 24

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

4.19.1 OsSaveCrashReport ...................................................................... 25

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

4.20.1 OsMount ......................................................................................... 26

4.20.2 OsUmount ...................................................................................... 28

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

4.21.1 OsCryptFormat ............................................................................... 29

4.21.2 OsCryptMount ................................................................................ 30

4.21.3 OsCryptUmount.............................................................................. 30

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

4.22.1 OsLed ............................................................................................. 31

4.23 Get Terminal Accumulated Usage Information......................................... 32

4.23.1 OsTerminalConsumeInfo................................................................ 32

4.24 Digital IO .................................................................................................. 33

4.24.1 OsDigitalIOGetStat ......................................................................... 33

4.24.2 OsDigitalIOSetStat ......................................................................... 33

5 Encryption and Decryption.................................................................................. 35

5.1 Return Code List ...................................................................................... 35

5.2 Random Number ...................................................................................... 35

5.2.1 OsGetRandom ............................................................................... 35

5.3 SHA Algorithm .......................................................................................... 36

5.3.1 OsSHA ........................................................................................... 36

5.4 DES Algorithm .......................................................................................... 37

5.4.1 OsDES ........................................................................................... 37

5.5 AES Algorithm .......................................................................................... 37

5.5.1 OsAES............................................................................................ 37

5.6 RSA Algorithm .......................................................................................... 38

5.6.1 OsRSA ........................................................................................... 38

5.6.2 OsRSAKeyGen .............................................................................. 39

6 PED .................................................................................................................... 41

6.1 Return Code List ...................................................................................... 42

XXIV
6.2 Data Definition .......................................................................................... 44

6.2.1 Key Type ........................................................................................ 44

6.2.2 DisplayAttribute of Asterisk............................................................. 45

6.3 Data Structure .......................................................................................... 45

6.3.1 Structure of RSA Key ..................................................................... 45

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

6.4 Basic PED ................................................................................................ 46

6.4.1 OsPedOpen.................................................................................... 46

6.4.2 OsPedGetVer ................................................................................. 46

6.4.3 OsPedEraseKeys ........................................................................... 47

6.4.4 OsPedClose ................................................................................... 47

6.4.5 OsPedInjectKeyBlock ..................................................................... 47

6.5 PIN Input .................................................................................................. 50

6.5.1 OsPedSetInterval ........................................................................... 50

6.5.2 OsPedVerifyPlainPin ...................................................................... 51

6.5.3 OsPedVerifyCipherPin ................................................................... 52

6.5.4 OsPedSetFunctionKey ................................................................... 55

6.5.5 OsPedCancelPinEntry .................................................................... 56

6.5.6 OsPedSetOfflinePin ....................................................................... 56

6.5.7 OsPedEndPinEntry ........................................................................ 57

6.5.8 OsPedPinKeyNotify ........................................................................ 57

6.5.9 OsPedSetAsteriskLayout................................................................ 58

XXV
 6.5.10 OsPedSetPinIconLayout ................................................................ 59

6.5.11 OsPedSetPinBg ............................................................................. 60

6.5.12 OsPedCustomKeypad .................................................................... 62

6.6 MK/SK ...................................................................................................... 63

6.6.1 OsPedWriteKey .............................................................................. 63

6.6.2 OsPedWriteKeyVar ........................................................................ 67

6.6.3 OsPedGetPinBlock ......................................................................... 68

6.6.4 OsPedUpdatePinBlock ................................................................... 70

6.6.5 OsPedGetMac ................................................................................ 71

6.6.6 OsPedDes ...................................................................................... 72

6.6.7 OsPedGetKcv................................................................................. 74

6.6.8 OsPedDeriveKey ............................................................................ 75

6.7 DUKPT ..................................................................................................... 76

6.7.1 OsPedWriteTIK .............................................................................. 76

6.7.2 OsPedGetPinDukpt ........................................................................ 78

6.7.3 OsPedGetMacDukpt ...................................................................... 80

6.7.4 OsPedDesDukpt............................................................................. 81

6.7.5 OsPedGetKsnDukpt ....................................................................... 83

6.7.6 OsPedIncreaseKsnDukpt ............................................................... 83

6.8 RSA .......................................................................................................... 84

6.8.1 OsPedReadRsaKey ....................................................................... 84

6.8.2 OsPedWriteRsaKey ....................................................................... 84

XXVI
 6.8.3 OsPedRsaRecover ......................................................................... 85

6.8.4 OsPedReadCipherRsaKey ............................................................. 86

6.8.5 OsPedWriteCipherRsaKey ............................................................. 86

6.9 AES .......................................................................................................... 87

6.9.1 OsPedWriteAesKey ........................................................................ 87

6.9.2 OsPedAes ...................................................................................... 89

6.9.3 OsPedGetMacAes .......................................................................... 90

6.9.4 OsPedCalcAesGcm ....................................................................... 91

6.10 SM Algorithm ............................................................................................ 92

6.10.1 OsPedGenSM2Pair ........................................................................ 92

6.10.2 OsPedWriteSM2Key ...................................................................... 93

6.10.3 OsPedSM2Sign .............................................................................. 94

6.10.4 OsPedSM2Verify ............................................................................ 95

6.10.5 OsPedSM2Recover ........................................................................ 96

6.10.6 OsPedSM3 ..................................................................................... 97

6.10.7 OsPedSM4 ..................................................................................... 97

6.10.8 OsPedGetMacSM .......................................................................... 98

6.10.9 OsPedGetPinBlockSM4 ................................................................. 99

6.11 DES FIRE............................................................................................... 101

6.11.1 OsPedDFAuthDiver ...................................................................... 101

6.11.2 OsPedDFAuthMerge .................................................................... 102

6.12 RKI ......................................................................................................... 103

XXVII
 6.12.1 OsPedRkiInjectKey ...................................................................... 103

6.13 AES DUKPT ........................................................................................... 103

6.13.1 Key Type Definition ...................................................................... 103

6.13.2 Derivation Constraint .................................................................... 104

6.13.3 OsPedWriteAesTIK ...................................................................... 104

6.13.4 OsPedGetPinAesDukpt ................................................................ 105

6.13.5 OsPedGetMacAesDukpt .............................................................. 107

6.13.6 OsPedCalcAesDukpt .................................................................... 109

6.13.7 OsPedGetKsnAesDukpt ............................................................... 111

6.13.8 OsPedIncreaseKsnAesDukpt ....................................................... 111

6.14 ECC........................................................................................................ 112

6.14.1 OsPedGenerateEccKeyPair ......................................................... 112

6.14.2 OsPedWriteEccKey ...................................................................... 113

6.14.3 OsPedReadEccPublicKey ............................................................ 114

6.14.4 OsPedEccSign ............................................................................. 115

6.14.5 OsPedEccVerify ........................................................................... 117

6.14.6 OsPedEccPointMul ...................................................................... 118

7 LCD .................................................................................................................. 121

7.1 OsScrContrast........................................................................................ 123

7.2 OsScrBrightness .................................................................................... 124

7.3 OsScrGetSize ........................................................................................ 124

8 Keyboard .......................................................................................................... 125

XXVIII
 8.1 OsKbBacklight ........................................................................................ 128

9 Touch Screen ................................................................................................... 129

10 Signature Pad ............................................................................................... 130

11 Printer ........................................................................................................... 131

11.1 Return Code List .................................................................................... 131

11.2 Open and Close ..................................................................................... 132

11.2.1 OsPrnOpen .................................................................................. 132

11.2.2 OsPrnReset .................................................................................. 132

11.2.3 OsPrnClose .................................................................................. 133

11.3 Printer Settings ....................................................................................... 133

11.3.1 OsPrnSetSize ............................................................................... 133

11.3.2 OsPrnSetDirection ........................................................................ 133

11.3.3 OsPrnSetGray .............................................................................. 134

11.4 Type Setting ........................................................................................... 134

11.4.1 OsPrnSetSpace ............................................................................ 134

11.4.2 OsPrnSetReversal ........................................................................ 135

11.4.3 OsPrnSetIndent ............................................................................ 135

11.4.4 OsPrnCheck ................................................................................. 136

11.4.5 OsPrnGetDotLine ......................................................................... 136

11.4.6 OsPrnSetFont............................................................................... 136

11.4.7 OsPrnSelectFontSize ................................................................... 137

11.4.8 OsPrnFeed ................................................................................... 137

XXIX
 11.4.9 OsPrnPrintf ................................................................................... 138

11.4.10 OsPrnRawData ........................................................................... 138

11.4.11 OsPrnPutImage .......................................................................... 139

11.4.12 OsPrnStart .................................................................................. 140

11.4.13 OsPrnClrBuf ................................................................................ 141

11.4.14 OsPrnSetParam .......................................................................... 141

11.5 POSIX .................................................................................................... 141

11.5.1 Open ............................................................................................ 141

11.5.2 Read ............................................................................................. 142

11.5.3 Write ............................................................................................. 142

11.5.4 Close ............................................................................................ 143

12 Font Library................................................................................................... 144

12.1 Data Structure ........................................................................................ 144

12.2 Font Operation ....................................................................................... 145

12.2.1 OsEnumFont ................................................................................ 145

12.2.2 OsOpenFont ................................................................................. 145

12.2.3 OsCloseFont ................................................................................ 146

12.2.4 OsGetFontDot .............................................................................. 146

13 Code ............................................................................................................. 149

13.1 Code Conversion ................................................................................... 149

13.1.1 OsCodeConvert ............................................................................ 149

14 MSR .............................................................................................................. 151

XXX
 14.1 Return Code List .................................................................................... 151

14.2 Data Structure ........................................................................................ 152

14.3 MSR Control Interface ............................................................................ 152

14.3.1 OsMsrOpen .................................................................................. 152

14.3.2 OsMsrClose.................................................................................. 153

14.3.3 OsMsrReset ................................................................................. 153

14.3.4 OsMsrSwiped ............................................................................... 153

14.3.5 OsMsrRead .................................................................................. 154

14.3.6 OsMsrReadJIS ............................................................................. 154

15 IC Card Reader............................................................................................. 156

15.1 Return Code List .................................................................................... 156

15.2 Data Structure ........................................................................................ 157

15.2.1 APDU Request Structure.............................................................. 157

15.2.2 APDU Response Structure ........................................................... 158

15.3 Encapsulated Interfaces ......................................................................... 159

15.3.1 OslccOpen.................................................................................... 159

15.3.2 OsIccDetect .................................................................................. 159

15.3.3 OsIccInit ....................................................................................... 160

15.3.4 OsIccExchange ............................................................................ 162

15.3.5 OsIccTransfer ............................................................................... 162

15.3.6 OsIccClose ................................................................................... 164

16 RF Reader .................................................................................................... 166

XXXI
16.1 Return Code List .................................................................................... 166

16.2 Data Structure ........................................................................................ 167

16.2.1 User Configuration Structure ........................................................ 167

16.3 Encapsulate Interfaces ........................................................................... 169

16.3.1 OsPiccOpen ................................................................................. 169

16.3.2 OsPiccClose ................................................................................. 170

16.3.3 OsPiccResetCarrier ...................................................................... 170

16.3.4 OsPiccPoll .................................................................................... 170

16.3.5 OsPiccAntiSel............................................................................... 171

16.3.6 OsPiccActive ................................................................................ 171

16.3.7 OsPiccTransfer............................................................................. 172

16.3.8 OsPiccRemove ............................................................................. 172

16.3.9 OsMifareAuthority ......................................................................... 173

16.3.10 OsMifareOperate ........................................................................ 173

16.3.11 OsPiccInitFelica .......................................................................... 174

16.3.12 OsPiccIsoCommand ................................................................... 174

16.3.13 OsPiccSetUserConfig ................................................................. 175

16.3.14 OsPiccGetUserConfig ................................................................. 176

16.3.15 OsPiccApplePoll ......................................................................... 176

16.3.16 OsPiccOffCarrier ......................................................................... 177

16.3.17 OsPiccInitIso15693 ..................................................................... 177

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

XXXII
17 Communication Port ..................................................................................... 179

17.1 Data Definition ........................................................................................ 179

17.2 Communication Control .......................................................................... 180

17.2.1 OsPortOpen ................................................................................. 180

17.2.2 OsPortClose ................................................................................. 182

17.2.3 OsPortSend .................................................................................. 182

17.2.4 OsPortRecv .................................................................................. 183

17.2.5 OsPortReset ................................................................................. 184

17.2.6 OsPortCheckTx ............................................................................ 184

17.2.7 OsPortCheckRx............................................................................ 185

17.3 POSIX Interface ..................................................................................... 185

17.3.1 Open ............................................................................................ 186

17.3.2 Read ............................................................................................. 186

17.3.3 Write ............................................................................................. 186

17.3.4 Close ............................................................................................ 187

17.3.5 Query the Buffer Data of Communication Port ............................. 187

17.3.6 Clear the Buffer Data of Communication Port .............................. 187

17.3.7 Set the Configuration Parameters of Communication Port ........... 187

18 MODEM ........................................................................................................ 191

18.1 Return Code List .................................................................................... 191

18.2 Data Structure ........................................................................................ 199

18.3 OsModemOpen ...................................................................................... 203

XXXIII
 18.4 OsModemClose ..................................................................................... 204

18.5 OsModemSwitchPower .......................................................................... 204

18.6 OsModemConnect ................................................................................. 205

18.7 OsModemCheck .................................................................................... 206

18.8 OsModemExCmd ................................................................................... 207

18.9 OsModemHangup .................................................................................. 208

18.10 OsModemSend ................................................................................... 208

18.11 OsModemRecv ................................................................................... 209

18.12 OsPppomLogin ................................................................................... 210

18.13 OsPppomCheck .................................................................................. 212

18.14 OsPppomLogout ................................................................................. 212

19 Network Communication ............................................................................... 214

19.1 TCP Programming ................................................................................. 214

19.2 UDP Programming ................................................................................. 217

20 Network Configuration .................................................................................. 220

20.1 Return Code List .................................................................................... 220

20.2 Data Definition ........................................................................................ 222

20.2.1 Physical Channel List ................................................................... 222

20.2.2 IPv6 Status Value List .................................................................. 223

20.2.3 Data Structure .............................................................................. 223

20.3 IPv4 Network Configuration Interface ..................................................... 225

20.3.1 OsNetAddArp ............................................................................... 225

XXXIV
 20.3.2 OsNetPing .................................................................................... 226

20.3.3 OsNetPingEx ................................................................................ 226

20.3.4 OsNetDns ..................................................................................... 227

20.3.5 OsNetDnsEx................................................................................. 228

20.3.6 OsNetSetConfig ........................................................................... 228

20.3.7 OsNetGetConfig ........................................................................... 230

20.3.8 OsNetStartDhcp ........................................................................... 231

20.3.9 OsNetCheckDhcp ......................................................................... 231

20.3.10 OsNetStopDhcp .......................................................................... 232

20.3.11 OsPppoeLogin ............................................................................ 232

20.3.12 OsPppoeCheck ........................................................................... 233

20.3.13 OsPppoeLogout .......................................................................... 233

20.3.14 OsNetSetRoute ........................................................................... 233

20.3.15 OsNetGetRoute .......................................................................... 234

20.3.16 OsNetSetRouteTable .................................................................. 234

20.3.17 OsNetDelRouteTable .................................................................. 235

20.3.18 OsNetGetRouteTable.................................................................. 236

20.3.19 OsNetNat .................................................................................... 236

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

20.4.1 OsNetSetDns ............................................................................... 237

20.5 IPv6 Network Configuration.................................................................... 238

20.5.1 OsNetPing6 .................................................................................. 238

XXXV
 20.5.2 OsNetSetIPv6Addr ....................................................................... 239

20.5.3 OsNetGetIPv6Addr ....................................................................... 239

20.5.4 OsNetGetRouteAdvertise6 ........................................................... 240

20.5.5 OsNetStartDhcp6 ......................................................................... 241

20.5.6 OsNetCheckDhcp6 ....................................................................... 241

20.5.7 OsNetStopDhcp6 ......................................................................... 242

20.5.8 OsNetSetRouteTable6 ................................................................. 242

20.5.9 OsNetGetRouteTable6 ................................................................. 243

21 GPRS/CDMA ................................................................................................ 244

21.1 Return Code List .................................................................................... 244

21.2 Wireless Module Interface ...................................................................... 245

21.2.1 OsWlLock ..................................................................................... 245

21.2.2 OsWlUnLock ................................................................................ 246

21.2.3 OsWlInit ........................................................................................ 246

21.2.4 OsWlInitEx.................................................................................... 247

21.2.5 OsWlSwitchPower ........................................................................ 248

21.2.6 OsWlSwitchSleep ......................................................................... 249

21.2.7 OsWlGetSignal ............................................................................. 250

21.2.8 OsWlCheck .................................................................................. 251

21.2.9 OsWlLogin .................................................................................... 251

21.2.10 OsWlLoginEx .............................................................................. 254

21.2.11 OsWlLogout ................................................................................ 256

XXXVI
 21.3 Wireless Module Information Settings .................................................... 257

21.3.1 OsWlSelSim ................................................................................. 257

22 WiFi .............................................................................................................. 258

22.1 Return Code List .................................................................................... 258

22.2 Encryption Type List ............................................................................... 259

22.3 Data Structure ........................................................................................ 259

22.4 OsWifiOpen ............................................................................................ 262

22.5 OsWifiClose ........................................................................................... 262

22.6 OsWifiSwitchPower ................................................................................ 263

22.7 OsWifiScan ............................................................................................ 263

22.8 OsWifiConnect ....................................................................................... 264

22.9 OsWifiDisconnect ................................................................................... 265

22.10 OsWifiCheck ....................................................................................... 265

22.11 OsWifiCmd .......................................................................................... 267

22.12 OsWifiWpsConnect ............................................................................. 267

23 GPS .............................................................................................................. 269

23.1 Return Code List .................................................................................... 269

23.2 Data Definition ........................................................................................ 269

23.3 OsGpsOpen ........................................................................................... 270

23.4 OsGpsRead ........................................................................................... 270

23.5 OsGpsClose ........................................................................................... 271

24 Base ............................................................................................................. 272

XXXVII
 24.1 Introduction ............................................................................................ 272

24.2 Macro Definition ..................................................................................... 273

24.3 API ......................................................................................................... 273

24.3.1 OsOnBase .................................................................................... 273

24.3.2 OsBaseOpen ................................................................................ 273

24.3.3 OsBaseCheck .............................................................................. 274

24.3.4 OsBaseClose ............................................................................... 275

24.3.5 OsBaseScan ................................................................................ 275

24.3.6 OsBaseConnect ........................................................................... 276

24.3.7 OsBaseDisconnect ....................................................................... 277

24.3.8 OsCheckPortStatus ...................................................................... 277

24.3.9 OsGetBaseInfo ............................................................................. 278

24.3.10 OsBaseCmd ................................................................................ 279

25 File System ................................................................................................... 280

26 System Information ....................................................................................... 281

27 Audio ............................................................................................................ 284

27.1 Return Code List .................................................................................... 284

27.2 OsRecordOpen ...................................................................................... 284

27.3 OsRecordStart ....................................................................................... 285

27.4 OsRecordStop ........................................................................................ 287

27.5 OsRecordCheck ..................................................................................... 287

27.6 OsRecordClose ...................................................................................... 288

XXXVIII
 27.7 OsPlayWave .......................................................................................... 288

27.8 OsStopPlayWave ................................................................................... 289

27.9 OsPlayAudio .......................................................................................... 290

27.10 OsStopPlayAudio ................................................................................ 291

28 Barcode and Camera .................................................................................... 292

28.1 General Definition .................................................................................. 292

28.2 Data Definition ........................................................................................ 293

28.2.1 Macro Definition of Camera .......................................................... 293

28.2.2 Image Resolution Macro Definition of Photography ..................... 293

28.2.3 Image Data Format Macro Definition of Photography .................. 294

28.2.4 The Attribute Structure of the Photography Parameter ................ 294

28.2.5 Return Code List .......................................................................... 294

28.3 Basic Interface ....................................................................................... 295

28.3.1 OsScanSetParam ......................................................................... 295

28.3.2 OsScanOpen ................................................................................ 296

28.3.3 OsScanRead ................................................................................ 296

28.3.4 OsScanClose ............................................................................... 297

28.3.5 OsCameraOpen ........................................................................... 297

28.3.6 OsCameraClose ........................................................................... 298

28.3.7 OsCameraGetParam .................................................................... 298

28.3.8 OsCameraSetParam .................................................................... 298

28.3.9 OsCameraCapture ....................................................................... 299

XXXIX
 28.3.10 OsScanDecodeBuf ..................................................................... 300

28.3.11 OsCameraDetectMotion.............................................................. 301

29 Power Management ...................................................................................... 303

29.1 Return Code List .................................................................................... 303

29.2 Data Structure ........................................................................................ 303

29.3 OsCheckBattery ..................................................................................... 305

29.4 OsCheckPowerSupply ........................................................................... 306

29.5 OsSysSleep ........................................................................................... 306

29.6 OsSysSleepEx ....................................................................................... 307

29.7 OsSysSleepTime ................................................................................... 309

29.8 OsReboot ............................................................................................... 309

29.9 OsPowerOff............................................................................................ 310

29.10 OsPmGetEvent ................................................................................... 310

29.11 OsPmRequest..................................................................................... 311

29.12 OsWakeupSource ............................................................................... 311

29.13 OsCheckPowerStatus ......................................................................... 312

29.14 OsCheckBMSMode ............................................................................ 313

29.15 Get the Power Management Information ............................................ 314

29.16 Client Sends Request ......................................................................... 314

Appendix 1 PIN Block Format................................................................................. 315

Appendix 2 EPS PINBLOCK Format ...................................................................... 319

Appendix 3 Registry ............................................................................................... 320

XL
Appendix 4 Validity of Models and Contents .......................................................... 328

XLI
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 ......................................... 35

Table 6.1 PED return code list ........................................................................... 42

Table 6.2 Key types ........................................................................................... 44

Table 6.3 Layout attributes of asterisk ............................................................... 45

Table 6.4 Color values of asterisk ..................................................................... 45

Table 11.1 Printer return code list ................................................................... 131

Table 14.1MSR return code list ....................................................................... 151

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

Table 16.1 Return code list.............................................................................. 166

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

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

Table 18.1 Modem return code list .................................................................. 191

Table 18.2 Variable definitions of ST_MODEM_SETUP ................................. 200

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

Table 20.2 Physical channel list ...................................................................... 222

Table 20.3 IPv6 status value list ...................................................................... 223

XLII
Table 21.1 GPRS/CDMA return code list ........................................................ 244

Table 22.1 Return code list.............................................................................. 258

Table 22.2 Encryption type list ........................................................................ 259

Table 27.1 Return code list.............................................................................. 284

Table 28.1 Camera definition list ..................................................................... 293

Table 28.2 Image resolution definition list ....................................................... 293

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

Table 28.4 Return code list.............................................................................. 294

XLIII
 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 [email protected] 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.

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

 Prolin API Programming Guide

System does not

ERR_SYS_NOT_SUPPORT -1015
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

4.3.1 OsSetTime

Prototype int OsSetTime(const ST_TIME *Time);

Function Set system time and date. Prolin system does not contain time zone.

Time[Input] A pointer to ST_TIME structure that contains system

Parameters time. DayOfWeek is ignored in ST_TIME structure; it
can’t be NULL.
RET_OK Succeeded.
Return ERR_NEED_ADMIN Permission denied.
ERR_INVALID_PARAM Invalid parameter.

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

 Prolin API Programming Guide

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

4.3.2 OsGetTime

Prototype void OsGetTime(ST_TIME *Time);

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

Instruction

4.4 Timer

4.4.1 OsTimerSet

int OsTimerSet(ST_TIMER *Timer,

Prototype
unsigned long Ms);
Function Create a timer with a specified timeout value.
Timer[Output] A poiner to ST_TIMER structure.
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 when
Instruction
system enters sleep mode.

4.4.2 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_PARAM Invalid parameter.
Instruction

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

 Prolin API Programming Guide

4.5 Delay

4.5.1 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;
}

4.7 Log

4.7.1 OsLogSetTag

Prototype void OsLogSetTag(const char *Tag);

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

 Prolin API Programming Guide

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.

4.7.2 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 Invalid parameter.
ERR_INVALID_PARAM

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

4.8.1 OsGetTickCount

Prototype unsigned long OsGetTickCount(void);

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

Return >0 Count value.

Instruction

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

 Prolin API Programming Guide

4.9 Get Application Information

4.9.1 OsGetAppInfo

int OsGetAppInfo(ST_APP_INFO AppInfo[],

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

4.9.2 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
Parameters be NULL.
The number of optional system components
InfoCnt [input]
that can be stored in OptInfo array.
>=0 The number of optional system components
information that has been obtained.
ERR_FILE_NOT_ The file path that stores optional system
Return
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.

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

 Prolin API Programming Guide

4.10 Buzzer

4.10.1 OsBeep

void OsBeep(int ToneType,

Prototype
int DurationMs)；
Function Set the frequency and duration of buzzer.
ToneType [Input] Tone type.
The valid ToneType ranges from 1 to 7.
DurationMs [Input] Duration.[unit:ms]
Parameters The valid DurationMs ranges from 10 to 10000.
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
Instruction 3 2020
4 2130
5 2380
6 2700
≥7 2750

4.11 Key tone

4.11.1 OsSetKeyTone

void OsSetKeyTone(int OnOff,

Prototype
int DutyCycle);
Function Set the key tone switch and duty cycle.
OnOff [Input] 0 represents turn off the keytone;
Parameters 1 represents turn on the keytone.
DutyCycle[Input] Keytone duty cycle, the ranges is [1,99].

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

 Prolin API Programming Guide

If DutyCycle <1, or DutyCycle >99, keep the same

DutyCycle.
If DutyCycle=50, the volume is the maximum.
Return None

Instruction

4.12 Run Application

4.12.1 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.
ERR_APP_NOT_EXIS
Sub-application does not exist.
T
ERR_ACCESS_DENY Access denied.
Return
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
Instruction
AppId; the sub-application cannot be the main application;
otherwise, ERR_INVALID_PARAM will be returned.
3. The standard output message and standard error message
of sub-application will be exported to CbOut() and CbErr(),

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

 Prolin API Programming Guide

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).

4.12.2 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

4.13.1 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.”
or “rt.app.” and ending with “\0”.
The valid string length ranges from 0
Parameters 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
Instruction
name begins with “persist.sys” , “rt.sys” or “rt.app.”, such as

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

 Prolin API Programming Guide

“persist.sys.app0.pic”. For more information, refer to

Appendix 3 Registry.
2. OsRegSetValue()supports both the keywords listed in
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.

4.13.2 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 “ ”.

4.14 Install and Uninstall Files

4.14.1 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).
Parameters Name[Input] Pathname of the specified destination.

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

 Prolin API Programming Guide

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)
 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
FILE_TYPE_APP_PARAM; otherwise, it is invalid. Name is
the application name in “MAINAPP” and other terminals, if
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
Instruction 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

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

 Prolin API Programming Guide

execl() fails, or the updater in the FWP package returns an

error code.

4.14.2 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.

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

restart the terminal to complete the uninstallation.

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

 Prolin API Programming Guide

4.15 System Firmware Upgrade

4.15.1 OsFirmwareGetVersion

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

Function Get system firmware version.

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

4.15.2 OsFirmwareUpgrade

Prototype int OsFirmwareUpgrade(const char *FwFileName);

Function Upgrade system firmware.

FwFileName[Input] Firmware filename, in ZIP format.
Parameters
RET_OK Update succeeded.
RR_FILE_NOT_FOUND FwFileName file doesn’t exist.
Return ERR_VERIFY_SIGN_FAIL Signature error.
ERR_SYS_NOT_SUPPOR Incompatible with OS.
T
1. Only the main application has permission to upgrade system
firmware.
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
Instruction 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.

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

 Prolin API Programming Guide

4.16 Verify Signature

Prolin provides signature verification functions.

4.16.1 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.
ERR_VERIFY_SIGN_ Invalid signature.
FAIL
ERR_FILE_NOT_EXIS
Return 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.

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

 Prolin API Programming Guide

4.16.2 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.
FAIL
ERR_FILE_NOT_EXIS
Return The 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 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.

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

 Prolin API Programming Guide

4.17 Get System Version

4.17.1 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.

4.18.1 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_ABSEN Base is absent.
T
Return ERR_SYS_NOT_SU System does not support this function.
PPORT
ERR_TIME_OUT Timeout
ERR_SYS_BAD System error
This function only applies to handsets connected to the base via USB,
Instruction serial ports and Bluetooth.

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

 Prolin API Programming Guide

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(). .

4.19.1 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
Call OsSaveCrashReport (sig) to save the error messages.
For example:
Instruction 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().
 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.

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

 Prolin API Programming Guide

4.20 Mount and Unmount the External File System

4.20.1 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.
Here is a list of flags and their corresponding
meanings. The mount flag can be a flag or a
combination of the following flags.
Parameters MS_DIRSYNC: Update synchronous
directory.
MS_MANDLOCK: Permit mandatory
locking on files in this file system.

MountFlags[In  MS_NOATIME: Do not update the access

put] time of file.

 MS_NODEV: Do not allow to access

device file.

 MS_NODIRATIME: Don't update the

access time of directory.

 MS_NOEXEC: Do not allow programs to

be executed on the mounted file system.

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

 Prolin API Programming Guide

 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
defined in “mount.h”, such as MS_DIRSYNC,
MS_MANDLOCK, etc.
Instruction Sample code
Mount a SD card:
ret = OsMount("/dev/block/mmcblk0p1", "/mnt/sdcard", "vfat", 0,
0);
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);

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

 Prolin API Programming Guide

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.

4.20.2 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.
1. Only the main application has permission to unmount;
Instruction otherwise, it will fail to unmount and return
ERR_NEED_ADMIN.

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

 Prolin API Programming Guide

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.
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

4.21.1 OsCryptFormat

int OsCryptFormat(const char *Dev,

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

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

 Prolin API Programming Guide

4.21.2 OsCryptMount

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

Prototype const char *Target,
const char *FsType);
Function Mount the encrypted file system.
Dev [Input] Device that needs to be mounted, this device is
located at /dev/block/ directory, and the path
length cannot exceed 128 bytes.
Pwd [Input] Password of encrypted file system, it is a visible
string ranging from 6 to 32 bytes.
Parameters
Target [Input] The target file directory, it must be located at
/mnt/ directory, and the path length cannot
exceed 128 bytes.
FsType [Input] The type of format file system, this value can be
“vfat”.
0 Succeeded.
ERR_INVALID_PARAM Invalid parameter
ERR_SYS_NOT_SUPPO System doesn’t support (wrong password or
Return RT encryption format is unsupported)
ERR_DEV_NOT_EXIST Device doesn’t exist
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.
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
Instruction format, 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.

4.21.3 OsCryptUmount

Prototype int OsCryptUmount(const char *Target);

Function Unmount the encrypted file system.

Target [Input] The directory of encrypted SD card that
Parameters needs to be unmounted.
0 Succeeded.
ERR_INVALID_PARAM Invalid parameter
Return
ERR_DEV_BUSY Device is busy.
ERR_ACCESS_DENY Permission denied.

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

 Prolin API Programming Guide

ERR_FILE_NOT_EXIST The file directory doesn’t exist

File related operations such as read/write file system must be stopped
Instruction when calling OsCryptUmount(), otherwise, ERR_DEV_BUSY will be
returned.

4.22 LED

4.22.1 OsLed

int OsLed(int Id,

Prototype unsigned int Color,
const char *dev);
Function Control Led state and color.
Id [Input] Led number.
Color [Input] The color of Led can be set as
followings:
LED_OFF: off
LED_RED: red
LED_GREEN: green
LED_BLUE: blue
LED_YELLOW: yellow
LED_CYAN: cyan
Parameters LED_MAGENTA: magenta
LED_WHITE: white
dev [Input] Device model.
When operating the led light of
remote device, this parameter
needs to be input (such as card
reader: "IM700", "IM500" or
"IM20");
When operating the led light of the
local device, this parameter is
NULL.
0 Succeeded.
ERR_INVALID_PARAM Invalid parameter
Return
ERR_SYS_BAD System error.
ERR_SYS_NOT_SUPPORT System does not support.
IM500
Id = 1: red
IM300
Id = 2: green
Instruction IM310
IM700 Id = 1: blue
QR55 Id = 2: yellow

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

 Prolin API Programming Guide

SP200 Id = 3: green
Id = 4: red
B920 Id = 1: red or green
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

4.23 Get Terminal Accumulated Usage Information

4.23.1 OsTerminalConsumeInfo

int OsTerminalConsumeInfo(const char *Key,

Prototype
int *Value);
Function Get accumulated usage information of each module on terminal.
Key [Input] Device information category.
Parameters
Value [Output] Device usage information
RET_OK Succeeded.
ERR_SYS_NOT_SUPPO System does not support.
Return RT
ERR_INVALID_PARAM Invalid parameter.
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 RF card
Instruction 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.

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

 Prolin API Programming Guide

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
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

4.24.1 OsDigitalIOGetStat

Prototype int OsDigitalIOGetStat(int *value);

Function Get the input status of all digital IO.

Value[Output] The status of each IO is represented by bit,
0 represents suspended or high level, 1
Parameters 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_PARAM Invalid parameter.
Return
ERR_SYS_NOT_SUPPO System does not support.
RT
In the case of a connected handset, if the handset supports digital IO, the
Instruction interface will get the input status of the handset digital IO by default.

4.24.2 OsDigitalIOSetStat

Prototype int OsDigitalIOSetStat(int index, int value);

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

 Prolin API Programming Guide

Function Set the output status of the specified IO.

Index[Input] Specify the sequence number of IO to be
set, and if the IO does not support setting
Parameters (read only), ERR_SYS_NOT_SUPPORT
will be returned.
Value[Input] 0: the corresponding IO output is high level;
1: the corresponding IO output is low level.
RET_OK Succeeded.
ERR_INVALID_PARAM Invalid parameter.
Return
ERR_SYS_NOT_SUPPO System does not support.
RT
In the case of a connected handset, if the handset supports digital IO, the
Instruction interface will get the input status of the handset digital IO by default.

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

 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.

5.2.1 OsGetRandom

void OsGetRandom(unsigned char *Random,

Prototype
int RandomLen);
Function Generate true random number.

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

 Prolin API Programming Guide

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).

5.3.1 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.
DataLen[Inpu Input data length.
Parameters t]

Output SHA value.

The memory space is recommended to be more
than 64 bytes. The corresponding relationship
between Mode value and the valid length of
ShaOut[Outp
ShaOut are listed below:
ut]
 SHA_TYPE_1 20
 SHA_TYPE_224 28
 SHA_TYPE_256 32

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

 Prolin API Programming Guide

 SHA_TYPE_38 48
 SHA_TYPE_512 64
Return None.
Instruction

5.4 DES Algorithm

Prolin supports DES&TDES algorithms.

5.4.1 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[Output] 8-byte output data.
DesKey[Input] DES/TDES key.
Parameters
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.

5.5.1 OsAES

void OsAES(const unsigned char *Input,

Prototype unsigned char *Output,
const unsigned char *AesKey,

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

 Prolin API Programming Guide

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.

5.6.1 OsRSA

int OsRSA(const unsigned char *Modulus,

int ModulusLen,
const unsigned char *Exp,
Prototype
int ExpLen,
const unsigned char *DataIn,
unsigned char *DataOut);
Function Encrypt or decrypt data with RSA algorithm
A pointer that contains RSA
Modulus[Input] modulus (n=p*q). (stored in big
endian)
Parameters ModulusLen[Input] Modulus length[unit:byte].
A pointer that contains RSA
Exp[Input] operation exponent. (stored in big
endian)

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

 Prolin API Programming Guide

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.

5.6.2 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)
Modulus length [unit: byte].
Parameters ModulusLen The modulus is valid only when it is 64, 128,
256 or 512 bytes.
Public key exponent.
PubExp[Input] The valid value can only be
“\x00\x00\x00\x03” or “\x00\x01\x00\x01”.
Return RET_OK Succeeded.

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

 Prolin API Programming Guide

ERR_INVALID_PARA
Invalid Parameters.
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. 40

 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. 41

 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. 42

 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. 43

 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

6.2.1 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. 44

 Prolin API Programming Guide

PED_SM4_TDK 0x35 SM4 Data Key

PED_AES_TLK 0x27 AES Loading Key
PED_AES_TMK 0x28 AES Master Key
PED_AES_TPK 0x23 AES PIN Key
PED_AES_TAK 0x24 AES MAC Key
PED_AES_TDK 0x20 AES Data Key
PED_AES_TIK 0x51 AES Initial Key

6.2.2 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

6.3.1 Structure of RSA Key

ST_RSA_KEY

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

 Prolin API Programming Guide

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;

6.3.2 RSA Key Structure for Verifying the Ciphertext IC Card PIN

ST_RSA_PINKEY
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

6.4.1 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.

6.4.2 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.

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

 Prolin API Programming Guide

RET_OK Succeeded.
Return ERR_DEV_NOT_OPEN PED device is not open.
ERR_INVALID_PARAM Invalid parameter.
Instruction

6.4.3 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

6.4.4 OsPedClose

Prototype void OsPedClose(void);

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

6.4.5 OsPedInjectKeyBlock

int OsPedInjectKeyBlock(uchar *KeyBlock,

Prototype
uint KeyBlkLen);
Write a key in the TR31 data encapsulation format, including
Function TMK, TWK, AES_TMK and AES_TWK and AES_TIK.
1 byte Format: 0x08
SrcKeyType：
 PED_TLK
KeyBlock
Parameters 1 byte  PED_TMK
[Input]  PED_AES_TLK
 PED_AES_TMK
1 byte SrcKeyIdx：

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

 Prolin API Programming Guide

 When SrcKeyType =
PED_TLK,
SrcKeyIdx = 1;
 When SrcKeyType =
PED_TMK,
SrcKeyIdx = [1~100];
 When ucSrcKeyType
= PED_AES_TLK,
Header ucSrcKeyIdx = 1;
 When ucSrcKeyType
= PED_AES_TMK,
ucSrcKeyIdx =
[1~100];
DstKeyIdx:
 When DstKeyType =
PED_TMK,
DstKeyIdx = [1~100];
 When DstKeyType =
PED_TPK or
PED_TAK or
PED_TDK,
DstKeyIdx = [1~100];
 When
DstKeyType=PED_A
ES_TMK,
DstKeyIdx=[1~100];
1 byte  When
DstKeyType=PED_
AES_TPK/PED_AE
S_TAK/PED_AES_
TDK,
DstKeyIdx=[1~100];
 When
DstKeyType=PED_
TIK,
DstKeyIdx=[1~100];
 When
DstKeyType=PED_
AES_TIK,
DstKeyIdx=[1~40].
Key Block ‘B’ TDEA
Version ID(1
byte) ‘D’ AES

ASCII decimal numeric

digits providing key block

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

 Prolin API Programming Guide

Key Block length after encoding.for

Length example, “0080”
(4 bytes)
“P0” – PIN encryption
“B1”-DUKPT TIK
Key Usage “K0”-TMK
(2 bytes) “D0”-TDK
“M0”-TAK
“C1”-TCHDK
TR31
data Algorithm (1 “T” TDEA
byte) “A” AES
Mode of
ignore
Use(1 byte)
Key Version
Number(2 ignore
bytes)
Exportability(
ignore
1 byte)
Number of
Optional
“00”/”01”/”02”
Blocks (2
bytes)
Reserved field
ignore
(2 bytes)
Optional “KS” (2 bytes option id)
Blocks (The + len(2 bytes, hex-ASCII
total length of “18”) + 20 hex-ASCII
all optional characters KSN,
blocks in the (PED_TIK KSN)
key block will or
be a multiple
“IK” (2 bytes option id) +
of the
len (2bytes, hex-ASCII
encryption
“14”) + 16 hex-ASCII
block size
characters
(TDES is 8,
KSN(PED_AES_TIK
AES is16).
Initial Key Identifier)
This may
require or
padding, and “PB” (2 bytes option id) +
if padding is len(2 bytes, hex-ASCII
needed it is “0C”) + hex-ASCII
included in a characters padding

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

 Prolin API Programming Guide

special final
optional block
that is filled
with an
appropriate
number of
padding
characters.)
Encryption Cipher text (2 bytes len +
body key + padding)
TDES is 16 bytes, AES
MAC
is 32 bytes
0 Succeeded
Return
others Failed
The relationship between the types of destination keys that each
source key supports for injection is as follows:
1. When SrcKeyType = TLK, key TLK, TMK or TIK can be
injected;
2. When SrcKeyType = TMK, key TMK, TPK, TAK or TDK can
be injected;
3. When SrcKeyType = AES_TLK, key AES_TLK, AES_TMK
or AES_TIK can be injected;
Instruction
4. When SrcKeyType = AES_TMK, key AES_TMK, AES_TPK,
AES_TAK or AES_TDK can be injected.
The length of the source key and destination key must meet the
following conditions:
1. You cannot use a key with a length of 8 bytes as the source
key;
2. The length of the destination key should be less than or
equal to the length of the source key.

6.5 PIN Input

6.5.1 OsPedSetInterval

Prototype int OsPedSetInterval(unsigned long TpkIntervalMs);

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

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

 Prolin API Programming Guide

Current settings remain

=0xffffffff
unchanged.
RET_OK Succeeded.
Return
ERR_DEV_NOT_OPEN PED device is not open.
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.

6.5.2 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, 4, 6”. “0”
means no PIN is required and can return
Parameters 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
ms. “0” means no timeout, and PED has no
timeout control.

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

 Prolin API Programming Guide

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;

6.5.3 OsPedVerifyCipherPin

int OsPedVerifyCipherPin(int IccSlot,

const ST_RSA_PINKEY
Prototype *RsaPinKey,
const char *ExpPinLen,
int Mode,

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

 Prolin API Programming Guide

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
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,
4, 6”. “0” means no PIN is required and
Parameters 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
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
OsPedVerifyCipherPin(), after a while, call XuiResume() to
resume XUI.

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

 Prolin API Programming Guide

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– gotten from terminal
b
padding bytes 17 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 OsIccExchange() is used to send verification command to card.

handling The process is as follows:
porcess 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;
icc_resp[1] = apdu_r.SWB;

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

 Prolin API Programming Guide

6.5.4 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 ATM
button.
0x03: Press FN button to end the PIN input. This rule
Parameters KeyFlag 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
(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.

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

 Prolin API Programming Guide

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.

6.5.5 OsPedCancelPinEntry

Prototype int OsPedCancelPinEntry(void);

Function Terminate the process of PIN input.

Parameters None.

Return RET_OK Succeeded.

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

6.5.6 OsPedSetOfflinePin

int OsPedSetOfflinePin(uchar Mode,

uchar TpkIdx,
Prototype
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

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

 Prolin API Programming Guide

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

6.5.7 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.

6.5.8 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.

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

 Prolin API Programming Guide

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.

6.5.9 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:
 fontSize = 16: the character size is 16 dots;
 fontSize = 24: the character size is 24 dots;
 fontSize = 32: the character size is 32 dots;
fontSize
Parameters  fontSize = 48: the character size is 48 dots.
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.

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

 Prolin API Programming Guide

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 ().

6.5.10 OsPedSetPinIconLayout

int OsPedSetPinIconLayout(int X,
int Y,
int Interval,
uchar IconNum,
Prototype
char *PinIcon,
int PinIconLen,
char *PinIconBG,
int PinIconBGLen);
Function Set the layout attributes of foreground and background icons.
The initial x coordinate of foreground
X [Input]
and background icons.
Parameters The initial y coordinate of foreground
Y [Input]
and background icons.
Interval [Input] The interval of two adjacent icons.

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

 Prolin API Programming Guide

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
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;
3. Enable/disable the dynamic center display function of the
foreground image by setting the value of
Instruction “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;
 When persist.sys.ped.pin.icon.align=0, the foreground
image will restore to normal display, and the default value is
“0”.

6.5.11 OsPedSetPinBg

Prototype int OsPedSetPinBg(uchar Mode,

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

 Prolin API Programming Guide

const uchar *Bg,

int BgLen);
Set the background of the PIN input interface using Framebuffer
Function
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;
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;
Instruction 4. The image data represents the data which is read from
image file by users and cached into memory, and only “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”.

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

 Prolin API Programming Guide

6.5.12 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
specified path as the PIN input keypad icon, and to set the
canvas backround color as the PIN input keypad
background color.
2. Support replacing parts of keypad icons. The system will
only obtain the icon resource file which corresponds to
Instruction 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.

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

 Prolin API Programming Guide

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 MK/SK

6.6.1 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
Parameters KeyBlock[Input] SrcKeyIdx:
 When SrcKeyType =
PED_TLK,
SrcKeyIdx = 1;
 When SrcKeyType =
1 byte PED_TMK,
SrcKeyIdx = [1~100];
 When
ucSrcKeyType=PED_TPK/PE
D_TAK/PED_TDK,
ucSrcKeyIdx = [1~100];

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

 Prolin API Programming Guide

 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 =
PED_TLK,
DstKeyIdx = 1;
 When DstKeyType =
1 byte 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:
1 byte
0x00: No verification.

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

 Prolin API Programming Guide

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 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
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.

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

 Prolin API Programming Guide

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.
ERR_PED_KEY_IDX_ER
R Key index error.

ERR_PED_KEY_TYPE_E
RR Key type error.

ERR_PED_TAMPERED PED is locked.

Return 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.
Instruction 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.
4. Before writing in PED_TLK, all keys that have been
downloaded must be cleared.

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

 Prolin API Programming Guide

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
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.

6.6.2 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 type
Function to operate with data string and write the result to specified
destination key index in the same key type area.

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

 Prolin API Programming Guide

Key types:
 PED_TMK
KeyType  PED_TPK
 PED_TAK
 PED_TDK
Source key index.The valid range is from 1
Parameters 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.

6.6.3 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
Function within 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.
Parameters
DataIn[Input]  When Mode=0x00, DataIn points to
the16-bit primary account number

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

 Prolin API Programming Guide

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 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,
which is an enumeration set from 0 to 12.
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
ExpPinLen[Input]
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
Mode  0x02 0x02 ISO9564 format 3
 0x03 0x03 HK EPS proprietary
format
Format of PinBlock encrypted with DES-
CBC (3DES-CBC) algorithm:
 0x50 0x50 SIN MCCS proprietary
format

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

 Prolin API Programming Guide

Format of PinBlock encrypted with AES-

ECB algorithm:
 0x10: 0x14 ISO9564 format 4, 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 or 0x14, 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.
2. Call OsPedGetPinBlock() 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, call XuiSuspend() to suspend XUI before calling
OsPedGetPinBlock(), after a while, call XuiResume() to
Instruction 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.

6.6.4 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.

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

 Prolin API Programming Guide

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
[6 Bytes, ASCII code].
 When UpdateFlag is 0 and Mode=0x00, the
first 16 bytes of DataIn is the old PAN, and
Parameters
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.
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.

6.6.5 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.
Parameters KeyIdx
The valid KeyIdx ranges from 1 to 100.

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

 Prolin API Programming Guide

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 ，
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
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-
Mode byte xor result. Then perform DES/TDES
encryption with TAK on the final xor
result.
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_OPEN PED device is not open.
Return
ERR_INVALID_PARAM Invalid parameter.
Others Refer to PED Return Code List .
Instruction

6.6.6 OsPedDes

int OsPedDes(int KeyIdx,

unsigned char * InitVector,
Prototype
const unsigned char *DataIn,
int DataInLen,

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

 Prolin API Programming Guide

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
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.
A pointer to the data that needs to be
DataIn[Input]
calculated.
Length of data that needs to be
Parameters 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

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

 Prolin API Programming Guide

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.

6.6.7 OsPedGetKcv

int OsPedGetKcv(int KeyType,

int KeyIdx,
int KcvMode,
Prototype
int KcvDataLen,
unsigned char *KcvData,
unsigned char *Kcv);
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
Function
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
Parameters
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.
0x00: Calculate the KCV of the key with DES
KcvMode algorithm ;
0x04: Calculate the KCV of SM4 key with SM4
algorithm, and the key types can only be SM4
series keys (KeyType can only be

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

 Prolin API Programming Guide

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 128bytes
KcvDataLen 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.
KcvData[Inpu A pointer to the data that needs to be 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.
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

6.6.8 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 key
Function 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
Parameters
 PED_TPK
 PED_TDK
Index number of source key, for example:
SrcKeyIdx
 TLK can only be 1.

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

 Prolin API Programming Guide

 TMK ranges from 1 to 100.

 TWK ranges from 1 to 100.
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.
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 .
The level of source key type cannot be lower than destination
Instruction
key.

6.7 DUKPT

6.7.1 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 =
Parameters KeyBlock[Input] PED_TLK,
1 byte
SrcKeyIdx = 1;
 When writing in plaintext,
SrcKeyIdx = 0.
DstKeyIdx:
1 byte
DstKeyIdx = [1~100];

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

 Prolin API Programming Guide

Reserved domain. Random

7 bytes
number.
DstKeyType:
1 byte
 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, 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, KcvValue
points to the KCV value.

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

 Prolin API Programming Guide

10
Initialize KSN.
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 .
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.

6.7.2 OsPedGetPinDukpt

int OsPedGetPinDukpt(int GroupIdx,

const unsigned char *DataIn,
const char *ExpPinLen,
Prototype
int Mode,
unsigned long TimeoutMs,
unsigned char *Ksn,

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

 Prolin API Programming Guide

unsigned char *PinBlock);

Scan input PIN and output PIN block which is a result of DUKPT
Function
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
primary account number after shifting card
number.
2. If Mode=0x21, DataIn has no meaning.
DataIn[Input] 3. If Mode=0x22, DataIn points to the 16-bit
primary account number after shifting card
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
Parameters 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.
Return
ERR_DEV_NOT_OPEN PED device is not open.

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

 Prolin API Programming Guide

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.

6.7.3 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.

Parameters 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
Mode 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

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

 Prolin API Programming Guide

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.

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 the
Instruction
request MAC key can calculate MAC for unlimited times.

6.7.4 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.
Parameters GroupIdx DUKPT group index.

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

 Prolin API Programming Guide

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.
Only ECB and CBC encryption is
available, which means Mode can be
0x01 or 0x03. When the length of
DUPKT key is 8 bytes, the standard
DES algorithm is not adopted but
KeyVarType[Inpu the special DES algorithm defined in
t] ANSI9.24-1998 is adopted.
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
InitVector[Input] or decryption; If InitVector is NULL, the
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
Mode
 0x01: ECB encryption
 0x02: CBC decryption

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

 Prolin API Programming Guide

 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 .
If KSN does not increase 1 automatically, a DUKPT group can
perform DES operations for 256 times at most when
Instruction
KeyVarType is 0x00/0x01; a DUKPT group can only do one DES
operation when KeyVarType is 0x02.

6.7.5 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

6.7.6 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.
Return
ERR_DEV_NOT_OPEN PED device is not open.

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

 Prolin API Programming Guide

ERR_INVALID_PARAM Invalid parameter.

Others Refer to PED Return Code List .
Instruction

6.8 RSA

6.8.1 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.

6.8.2 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 .

Instruction 1. The type of RSA key depends on ExponentLen and

ModulusLen in RsaKey. It is a private key if ExponentLen is

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

 Prolin API Programming Guide

equal to ModulusLen (ExponentLen=ModulusLen);

otherwise, it is public key.
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.
3. In the RsaKey parameter, if Modulus and Exponent are less
than 512 bytes, 0x00 is padded with at the left side.

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

2. RSA key can be rewritten at any time.

6.8.3 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 .

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

 Prolin API Programming Guide

Instruction

6.8.4 OsPedReadCipherRsaKey

int OsPedReadCipherRsaKey(int RsaKeyIdx,

Prototype unsigned char
*CipherRsaKey);
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

6.8.5 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

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

 Prolin API Programming Guide

6.9 AES

6.9.1 OsPedWriteAesKey

Prototype intOsPedWriteAesKey(const unsigned char *KeyBlock);

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_AES_TMK
SrcKeyIdx:
 When SrcKeyType =
PED_TLK,
SrcKeyIdx = 1;
1 byte  When SrcKeyType =
PED_AES_TMK,
SrcKeyIdx = [1~100];
 If ucSrcKeyIdx = 0, key will be
written in PED as plaintext.
1 byte DstKeyIdx: [1-100].
KeyBlock[Input 7 bytes Reserved field, random number.
Parameters
]
DstKeyType:
 PED_AES_TMK
1 byte  PED_AES_TPK
 PED_AES_TAK
 PED_AES_TDK
1 byte DstKeyLen: 16/24/32
DstKeyValue:
32 bytes Destination key plaintext or
ciphertext.
KcvMode:
0x00: No verification.
1 byte 0x01: KCV is the first 3 bytes of
ciphertext after encrypting
the 16-byte 0x00 with
AES/ECB algorithm.

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

 Prolin API Programming Guide

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,
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.
Instruction
2. Only when PED_TLK does not exist, plaintext is allowed to
be written and key is allowed to be downloaded.
3. When SrcKeyIdx is valid, DstKeyValue is regarded as the
ciphertext of the key. The system will decrypt DstKeyValue

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

 Prolin API Programming Guide

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.

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

Valid KeyBlock length must be 184 bytes.

6.9.2 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.
Parameters
When Mode=0x06/0x07, the initialization
vector represents a 16-byte temporary
counter which is required for calculation,
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.
DataInLen[Input]
The valid length is not more than 1024
bytes and must be a multiple of 16.

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

 Prolin API Programming Guide

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.
0x00: ECB Decryption
0x01: ECB Encryption
0x02: CBC Decryption
0x03: CBC Encryption
Mode [Input]
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.3 OsPedGetMacAes

int OsPedGetMacAes(uchar KeyIndex,

uchar *DataIn,
Prototype uint DataInLen,
uchar *Mac,
uchar Mode);
Use AES_TAK to perform MAC operation on the algorithm
Function specified by Mode in DataIn, and output the 16-byte MAC result
to Mac.
KeyIndex[Inp AES_TAK index.
ut] It ranges from 1 to 100.
DataIn[Input] Data that needs to do MAC operation.
The length of data, which is less than or equal
DataInLen[In
to 8192 bytes. If the length is not a multiple of
put]
Parameters 16, 0x00 will be padded automatically.
Point to the resulting MAC, which outputs 32
Mac[Output] bytes of data when Mode is 0x05, and 16 bytes
of data when other Modes
DataIn is blocked into 16-byte as BLOCK1，
Mode
BLOCK2，BLOCK3, etc.

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

 Prolin API Programming Guide

0x00: Perform AES encryption on BLOCK1 with

MAC key and bitwise xor the encryption
result with Block2. Then perform AES
encryption on the xor result to get an 16-
byte encrypted result.
0x01: Hypercom Fast Mode. Bitwise xor
BLOCK1 with BLOCK2; use the xor
result to bitwise xor with BLOCK3;
continue in this way, we can get an 16-
byte xor result. Then perform AES
encryption with AES_TAK on the final xor
result.
0x03: CMAC algorithm
0x05: HMAC-HASH256 algorithm
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

6.9.4 OsPedCalcAesGcm

int OsPedCalcAesGcm(uchar KeyIdx,

const uchar *InitVector,
uint InitVectorLen,
const uchar *DataIn,
uint DataLen,
Prototype const uchar *Aad,
uint AadLen,
uchar *DataOut,
uchar *AuthTag,
uint AuthTagLen,
uchar Mode);
Function Use PED_AES_TDK key for AES encryption or decryption.

Index of AES_TDK key, and the value

KeyIdx [Input]
Parameters range is 1~100.
InitVector [Input] Initialization Vector. It cannot be NULL.

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

 Prolin API Programming Guide

InitVectorLen The length of Initialization Vector. It is at

[Input] least 1 byte.
Points to the data to be calculated. It can
DataIn [Input]
be NULL.
The length of data to be calculated, in
DataLen [Input]
bytes. It should be <=2048.
Additional Authentication Data. It can be
Aad [Input]
NULL.
The length of Additional Authentication
AadLen [Input]
Data.
Point to the data that has been
DataOut [Output]
calculated.
Authentication Tag.
 If Mode is 0x00: input the
AuthTag
authentication tag.
[Input/Output]
 If Mode is 0x01: Output the
authentication tag.
AuthTagLen The length of Authentication Tag. It
[Input] should be 4, 8, 12, 13, 14, 15, 16 bytes.
 0x00: GCM Decryption
Mode [Input]  0x01: GCM Encryption
RET_OK Succeeded.
ERR_DEV_NOT_OPEN PED device is not open.
ERR_INVALID_PARAM Invalid parameter.
Return
ERR_PED_DATA_MAC_E
Data MAC check error.
RR
Refer to PED Return Code
Others
List .
Instruction

6.10 SM Algorithm

6.10.1 OsPedGenSM2Pair

Prototype int OsPedGenSM2Pair(uchar *PvtKey,

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

 Prolin API Programming Guide

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.

6.10.2 OsPedWriteSM2Key

int OsPedWriteSM2Key(int KeyIdx,

Prototype int KeyType,
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.
Return ERR_SYS_BAD System error
ERR_PED_KEY_IDX_ERR Key index error
ERR_PED_KEY_TYPE_ER
Key type error
R

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

 Prolin API Programming Guide

Others Refer to PED Return Code List .

Instruction

6.10.3 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.
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,
0x33, 0x34, 0x35, 0x36, 0x37, 0x38,
Parameters 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.
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.

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

 Prolin API Programming Guide

Refer to PED Return Code

Others
List .
Instruction

6.10.4 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.
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,
Parameters 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.
Return ERR_VERIFY_SIGN_FAIL Verification failed.
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

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

 Prolin API Programming Guide

Refer to PED Return Code

Others
List .
Instruction

6.10.5 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.
InputLen[Input] Data length.
For encryption: The maximum length is
(2048-96) bytes,
For decryption: The maximum length is
2048 bytes.
Parameters 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.
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. 96

 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.
Refer to PED Return Code
Others
List .
Instruction

6.10.6 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.
RET_OK Succeeded.
ERR_DEV_NOT_OPEN Device is not open.
Return
ERR_INVALID_PARAM Invalid parameter.
ERR_SYS_BAD System error.
Instruction

6.10.7 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
Parameters is from 1 to 100.
InitVector[Input] 16-byte initialization vector.

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

 Prolin API Programming Guide

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.
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.
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.
ERR_PED_KEY_LEN_ERR Key length error.
Refer to PED Return Code
Others
List.
Instruction

6.10.8 OsPedGetMacSM

int OsPedGetMacSM(int KeyIdx,

uchar *InitVector,
uchar *Input,
Prototype
int InputLen,
uchar *MacOut,
int Mode);
Function Use SM4 algorithm to calculate MAC.

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

 Prolin API Programming Guide

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.
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.
ERR_PED_KEY_LEN_ERR Key length error.
Refer to PED Return Code
Others
List.
Instruction

6.10.9 OsPedGetPinBlockSM4

int OsPedGetPinBlockSM4(int KeyIdx,

Prototype const char *ExpPinLenIn,
uchar *DataIn,

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

 Prolin API Programming Guide

uchar *PinBlockOut,
int Mode,
ulong TimeoutMs);
Within specified TimeoutMs, scan the input PIN on the keyboard
Function
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”.
DataIn[Input] When Mode=0x00, DataIn points to the
16-bit primary account number generated
Parameters
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
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.
Return ERR_PED_NO_KEY Key doesn’t exist.
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.

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

 Prolin API Programming Guide

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.11 DES FIRE

6.11.1 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.
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;
Parameters  When DivType = 0x01, combine
with Uid to diverge key, the
divergent key will be used to
encrypt the session key.
Encryption mode of the session key:
Mode[Input]
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.

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

 Prolin API Programming Guide

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

6.11.2 OsPedDFAuthMerge

int OsPedDFAuthMerge(uchar *EncRndA,

Prototype
int DataLen);
Function Check the cipher-text session key A’ passed from DESFire card.
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

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

 Prolin API Programming Guide

6.12 RKI

6.12.1 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

6.13 AES DUKPT

The DUKPT algorithm defines the process of generating one or more unique keys for
each transaction, without the need for the SCD of the transaction initiator to retain any
information that can determine any keys previously used by the SCD, nor does it
include any keys that have been or will be used.

This key management standard is used in conjunction with the AES to manage
symmetric keys, which can be used to protect messages and other sensitive
information in the financial service environment. The security and reliability of any AES-
based process directly depends on the protection of the key.

6.13.1 Key Type Definition

Macro value description

_2TDEA_ 0x00 2TDEA key
_3TDEA_ 0x01 2TDEA key

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

 Prolin API Programming Guide

_AES128_ 0x02 AES128 key

_AES192_ 0x03 AES192 key
_AES256_ 0x04 AES256 key
_HMAC128_ 0x05 HMAC128 key
_HMAC192_ 0x06 HMAC192 key
_HMAC256_ 0x08 HMAC256 key

6.13.2 Derivation Constraint

The derivation function is used to derive intermediate derived keys from TIK (terminal
initial key), and these intermediate derived keys are used to generate the working key
of the transaction. The strength of the working key must be the same or weaker than
these intermediate derived keys. The corresponding relationship is as follows:

Working Key AES-128 BDK AES-192 BDK AES-256 BDK

2TDEA Working Key Allowed Allowed Allowed
3TDEA Working Key Allowed Allowed Allowed
AES-128 Working Key Allowed Allowed Allowed
AES-192 Working Key Not Allowed Allowed Allowed
AES-256 Working Key Not Allowed Not Allowed Allowed
HMAC-128 Working Key Allowed Allowed Allowed
HMAC-192 Working Key Not Allowed Allowed Allowed
HMAC-256 Working Key Not Allowed Not Allowed Allowed

6.13.3 OsPedWriteAesTIK

Prototype int OsPedWriteAesTIK(const uchar *KeyBlock);

Write an AES DUKPT initial key, and optionally use KCV to verify
Function the correctness of the key.

1 byte Format: 0x03

SrcKeyType, source key type,

1 byte
which is reserved field.
Parameters KeyBlock[Input] SrcKeyIdx, source key index, which
1 byte currently must be 0, that is, only
plaintext writing is supported
DstKeyIdx, AES DUKPT key group
1 byte
index, which ranges from 0 to 40.

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

 Prolin API Programming Guide

7 bytes Reserved field

DstKeyType, destination key type,
1 byte
which can only be PED_AES_TIK
DstKeyLen, key length, which
1 byte
supports keys of 16/24/32 bytes.
32 DstKeyValue, destination key
bytes plaintext
16
Reserved field
bytes
KcvMode, KCV verification mode
 0x00, no verification
 0x05, calculate AES encryption
for 16 bytes of 0x00, and get the
1 byte first 3 bytes of the ciphertext as
KCV
 0x06, calculate AES CMAC
encryption for 16 bytes of 0x00,
and get the first 3 bytes of the
ciphertext as KCV
94
Reserved field
bytes
 When KcvMode = 0x00,
padding with random number
16
bytes  When KcvMode = 0x05/0x06,
KcvValue point to the value of
KCV
12
Initialize KSN
bytes
ERR_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.13.4 OsPedGetPinAesDukpt

int OsPedGetPinAesDukpt(uchar GroupIdx,

const char *DataIn,
Prototype
const char *ExpPinLen,
uchar KeyType,

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

 Prolin API Programming Guide

uchar Mode,
ulong TimeoutMs,
uchar *Ksn,
uchar *PinBlock);
Within the specified time limit, input the PIN on the keypad, and
Function output the PIN block calculated using the PIN key of AES
DUKPT.
AES DUKPT group index, which ranges
GroupIdx [Input]
from 1 to 40.
When Mode=0x20, DataIn points to the 16-
digit main account number generated after
the card number is shifted
When Mode=0x21, it is meaningless
When Mode=0x22, DataIn points to the 16-
DataIn [Input]
digit main account number generated after
the card number is shifted
When Mode=0x23, DataIn is the transaction
serial number ISN, which is 6-bytes ASCII.
When Mode=0x24, DataIn is main account
A string of valid password length that can be
entered, which is an enumerated set of
0~12;
The application enumerates all the allowed
password lengths, and separates each
ExpPinLen [Input] length with a ",". If 4 or 6-digit passwords
Parameters
and press confirm without a password are
allowed, the string should be set to "0," 4,6";
If the length of the enumeration is 0, it
means that you can directly press the enter
key to return without entering any number
When KeyType = 2TDEA_or_3TDEA_, use
TDES algorith to calculate pin block;
KeyType [Input] When KeyType =_AES128,
AES192_or_AES256_, use AES algorith to
calculate pin block, and at the meantime,
Mode can only be 0x24;
Choose the format of PIN block:
 When Mode = 0x20, PIN block format is
ISO9564 Format 0, KSN will not
Mode [Input] automatically add 1;
 When Mode = 0x21, PIN block format is
ISO9564 Format 1, KSN will not
automatically add 1;

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

 Prolin API Programming Guide

 When Mode = 0x22, PIN block format is

ISO9564 Format 3, KSN will not
automatically add 1;
 When Mode = 0x23, PIN block format is
HK EPS Format, KSN will not
automatically add 1;
 When Mode = 0x24, PIN block format is
ISO9564 Format 4, KSN will not
automatically add 1;
The timeout period of entering PIN, which is
in millisecondsn, and the maximum value is
TimeoutMs [Input] 300000.
0 means there is no timeout, and PED does
not do timeout control.

The length is 12 bytes, and it points to the

Ksn [Input]
current KSN.

PinBlock [Input] Point to the generated 8/16-byte PIN block.

RET_OK Succeeded
ERR_DEV_NOT_OPEN Device is not open
Return
ERR_INVALID_PARAM Invalid parameter
Others Refer to PED Return Code List
Calling OsPedGetPinAesDukpt() will operate on the
framebuffer, which may cause resource conflicts. If you find an
interface abnormality in an application that uses XUI, you can
Instruction call XuiSuspend() before calling OsPedGetPinAesDukpt() to
suspend the operation of XUI, and call XuiResume() later to
restore.

6.13.5 OsPedGetMacAesDukpt

int OsPedGetMacAesDukpt(uchar GroupIdx,

const uchar *DataIn,
uint DataInLen,
Prototype uchar KeyType,
uchar Mode,
uchar *Ksn,
uchar *Mac);
Function Calculate the MAC value using the MAC key of AES DUKPT.

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

 Prolin API Programming Guide

AES DUKPT group index, which ranges

GroupIdx [Input]
from 1 to 40.
Point to the MAC data that needs to be
DataIn [Input]
calculated
Data length which is less than or equal to
8192 bytes, it will automatically add "\x00"
DataInLen [Input]
when it cannot be divisible by 8 (DES)/16
(AES)
 When KeyType =_2TDEA_or_3TDEA,
use TDES algorithm to calculate
 When KeyType
=_AES128,_AES192_or_AES256, use
AES algorithm to calculate
KeyType [Input]
 When KeyType
=_HMAC128,_HMAC192
or_HMAC256, only calculation with
HMAC-SHA256(Mode0x25/0x45/0x65)
algorithm is supported
 0x20, 0x21, 0x22, 0x23 and 0x25 are
applicable to request and response
MAC key
Parameters
 0x40, 0x41, 0x42, 0x43 and 0x45 are
applicable to response MAC key
 0x60, 0x61, 0x62, 0x63 and 0x65 are
applicable to request MAC key

The meanings of each mode is as follows:

 0x20, 0x40 and 0x60: according to
ANSI.X9.9 standard, encrypt BLOCK1
with TDES/AES via MAC key, then XOR
Mode [Input]
the encryption result with BLOCK2, and
then encrypt the XOR result with
TDES/AES via MAC key, and then
obtain an encryption result of 8
(TDES)/16 (AES) bytes, KSN will not
automatically add 1
 0x21, 0x41 and 0x61: Hypercom Fast
Mode, perform a bitwise XOR between
BLOCK1 and BLOCK2, and perform a
bitwise XOR between the XOR result
and BLOCK3, and finally obtain an XOR
result of 8 (TDES)/16 (AES) bytes, then
encrypt the result with TDES/AES via

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

 Prolin API Programming Guide

MAC key, KSN will not automatically

add 1
 0x22, 0x42 and 0x62: according to
ANSIX9.19 standard, encrypt BLOCK1
with DES (only take the first 8 bytes of
key) via MAC key, and perform a bitwise
XOR between the encrypted result and
BLOCK2, and then use the MAC key for
DES encryption, then obtain an 8-byte
encryption result, until the last time
encryption with TDES, KSN will not
automatically add 1 (AES algorithm is
not supported)
 0x23, 0x43 and 0x63: CMAC algorithm,
KSN will not automatically add 1
 0x25, 0x45 and 0x65: HMAC-SHA256
algorithm, KSN will not automatically
add 1
Ksn [Output] Point to the obtained 12-byte KSN
When Mode = 0x25, 0x45 or 0x65, output
32-byte MAC, otherwise when KeyType
Mac [Output] =_2TDEA_or_3TDEA, output 8-byte MAC;
When KeyType =_AES128,
_AES192_or_AES256, output 16-byte MAC
RET_OK Succeeded
ERR_DEV_NOT_OPEN Device is not open
Return
ERR_INVALID_PARAM Invalid parameter
Others Refer to PED Return Code List
Mode is represented by hexadecimal numbers, please pay
Instruction attention to the decimal distinction with DesDukpt.

6.13.6 OsPedCalcAesDukpt

int OsPedCalcAesDukpt(uchar GroupIdx,

uchar KeyVarType,
uchar *InitVector,
uint DataInLen,
Prototype const uchar *DataIn,
uchar KeyType,
uchar Mode,
uchar *Ksn,
uchar *DataOut);

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

 Prolin API Programming Guide

Function Encrypt or decrypt input data with DUKPT key.

AES DUKPT group index, which ranges
GroupIdx [input] from 1 to 40.
 0x01, use TDES/AES data key to
calculate, support encryption and
decryption;
 0x04, use response TDES/AES data
key to calculate, only support
KeyVarType [input] encryption, that is, the value of
Modecan only be 0x01 or 0x03
 0x05, use request TDES/AES data key
to calculate, only support decryption,
that is, the value of Modecan only be
0x00 or 0x02
CBC operation initial vector, only valid
when Mode is 2 or 3; if NULL is passed in,
8 or 16 bytes of 0x00 will be used as the
initial vector by default
InitVector [input]  When KeyType =_2TDEA_or_3TDEA,
the intitial vector is 8 bytes
 When KeyType
=_AES128,_AES192_or_AES256, the
Parameters intitial vector is 16 bytes
The length of the data to be encrypted and
decrypted is less than or equal to 8192.
When KeyType = TDEA, DataInLen
DataInLen [input]
should be an integer multiple of 8,
otherwise it should be an integer multiple
of 16.
DataIn [input] Point to the data to be calculated
 When KeyType =_2TDEA_or_3TDEA,
use TDES algorithm to calculate
KeyType [input]  When
KeyType=_AES128,_AES192_or_AE
S256, use AES algorithm to calculate
Encryption/decryption mode:
 0x00: ECB decryption
Mode [input]  0x01: ECB encryption
 0x02: CBC decryption
 0x03: CBC encryption
Ksn [input] Point to the current KSN of 12 bytes
DataOut [input] Point to the calculated data

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

 Prolin API Programming Guide

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.13.7 OsPedGetKsnAesDukpt

int OsPedGetKsnAesDukpt(uchar GroupIdx,

Prototype
uchar *Ksn);
Function Get the current KSN.
AES DUKPT group index, which ranges from
GroupIdx [input]
Parameters 1 to 40.
Ksn [input] Point to the current KSN of 12 bytes
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.13.8 OsPedIncreaseKsnAesDukpt

Prototype int OsPedIncreaseKsnDukpt (uchar GroupIdx);

Function Add the KSN value of the specified AES DUKPT group.
AES DUKPT group index, which ranges from
Parameters GroupIdx [input] 1 to 40.
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

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

 Prolin API Programming Guide

6.14 ECC

6.14.1 OsPedGenerateEccKeyPair

int OsPedGenerateEccKeyPair (uchar EccType,

uchar EccUsage,
uchar EccPrivateKeyIndex,
Prototype
uint EccPublicKeyLen,
uchar *EccPublicKey,
uchar Mode);
Function Generate ECC key pair and output the public key.

EccType [Input] ECC Type:

 0x00 - Curve Brainpool P512r1;
 0x01 - Curve NIST P-521
(secp521r1);
 0x02 - Curve NIST P-256
(secp256r1).

EccUsage [Input] Reserved. The current value is 0.

EccPrivateKeyIndex [1~20] The key index for ECC private

[Input] key.

Parameters EccPublicKeyLen ECC public key length.

[Input]  Mode 0x00: ECC public key
 128 - Curve Brainpool P512r1;
 132 - Curve NIST P-521
(secp521r1);
 64 - Curve NIST P-256
(secp256r1).
 Mode 0x01: (04+ECC public key)
 129 - Curve Brainpool P512r1;
 133 - Curve NIST P-521
(secp521r1);
 65 - Curve NIST P-256
(secp256r1).

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

 Prolin API Programming Guide

EccPublicKey ECC public key.

[Output]

Mode [Input] 0x00/0x01, public key format

RET_OK Succeeded.
ERR_DEV_NOT_OPEN PED device is not open.
Return ERR_INVALID_PARAM Invalid parameter.
ERR_SYS_BAD System error.
Others Refer to PED Return Code List.
Instruction

6.14.2 OsPedWriteEccKey

int OsPedWriteEccKey(uchar EccType,

uchar EccUsage,
uchar EccKeyIndex,
Prototype
uint EccKeyLen,
const uchar *EccKey,
uchar Mode);
Function Write ECC private key or public key.

EccType [Input] ECC TYPE:

 0x00 - Curve Brainpool P512r1;
 0x01 - Curve NIST P-521
(secp521r1);
 0x02 - Curve NIST P-256
(secp256r1).

Parameters EccUsage [Input] Reserved. The current value is 0.

EccKeyIndex [Input] [1~20] The key index for ECC key.

EccKeyLen [Input] ECC private key length:

 64 - Curve Brainpool P512r1;
 66 - Curve NIST P-521
(secp521r1);

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

 Prolin API Programming Guide

 32 - Curve NIST P-256

(secp256r1).

ECC public key length:

Mode 0x00: ECC public key

 128 - Curve Brainpool P512r1;
 132 - Curve NIST P-521
(secp521r1);
 64 - Curve NIST P-256
(secp256r1).

Mode 0x01: (04+ECC public key)

 129 - Curve Brainpool P512r1;
 133 - Curve NIST P-521
(secp521r1);
 65 - Curve NIST P-256
(secp256r1).

EccKey [Input] ECC public key or private key

Mode [Input] 0x00/0x01, public key format

RET_OK Succeeded.
ERR_DEV_NOT_OPEN PED device is not open.
Return ERR_INVALID_PARAM Invalid parameter.
ERR_SYS_BAD System error.
Others Refer to PED Return Code List.
Instruction

6.14.3 OsPedReadEccPublicKey

int OsPedReadEccKey(uchar EccType,

uchar EccPublicKeyIndex,
Prototype uint EccPublicKeyLen,
uchar *EccPublicKey,
uchar Mode);
Function Read ECC public key.

Parameters EccType [Input] ECC TYPE:

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

 Prolin API Programming Guide

 0x00 - Curve Brainpool P512r1;

 0x01 - Curve NIST P-521
(secp521r1);
 0x02 - Curve NIST P-256
(secp256r1).

EccPublicKeyIndex [1~20] The key index for ECC public

[Input] key.

EccPublicKeyLen ECC public key length.

[Input]  Mode 0x00: ECC public key
 128 - Curve Brainpool P512r1;
 132 - Curve NIST P-521
(secp521r1);
 64 - Curve NIST P-256
(secp256r1).
 Mode 0x01: (04+ECC public key)
 129 - Curve Brainpool P512r1;
 133 - Curve NIST P-521
(secp521r1);
 65 - Curve NIST P-256
(secp256r1).

EccPublicKey ECC public key.

[Output]

Mode [Input] 0x00/0x01, public key format.

RET_OK Succeeded.
ERR_DEV_NOT_OPEN PED device is not open.
Return ERR_INVALID_PARAM Invalid parameter.
ERR_SYS_BAD System error.
Others Refer to PED Return Code List.
Instruction

6.14.4 OsPedEccSign

Prototype int OsPedEccSign(uchar EccType,

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

 Prolin API Programming Guide

uchar EccPrivateKeyIndex,
uint DataLen,
const uchar *Data,
uint *SignLen,
uchar *Sign,
uchar Mode);
Function ECC sign.

EccType [Input] ECC TYPE:

 0x00 - Curve Brainpool P512r1;
 0x01 - Curve NIST P-521
(secp521r1);
 0x02 - Curve NIST P-256
(secp256r1).

EccPrivateKeyIndex [1~20] The key index for ECC private

[Input] key.

DataLen [Input] Length of data to be signed, and it can

be 2048 bytes at most.

Data [Input] Data to be signed

Parameters
SignLen Input: The Sign size
[Input/Output]
Output: The Sign length

The Sign size must be greater than or

equal to the Sign length, otherwise an
error will be returned.

Sign [Output] Signature information.

 Mode 0x00: Signature information.

Signature information length:

 128 - Curve Brainpool P512r1;
 132 - Curve NIST P-521
(secp521r1);

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

 Prolin API Programming Guide

 64 - Curve NIST P-256

(secp256r1).
 Mode 0x01: ASN.1 encoded
signature information

Mode [Input] 0x00/0x01, format of signature

information

RET_OK Succeeded.
ERR_DEV_NOT_OPEN PED device is not open.
Return ERR_INVALID_PARAM Invalid parameter.
ERR_SYS_BAD System error.
Others Refer to PED Return Code List.
This interface directly signs the input data and does not
calculate the hash value. If you need to sign the hash value of
Instruction the data, the caller needs to calculate the hash value first and
then pass in the hash value.

6.14.5 OsPedEccVerify

int OsPedEccVerify(uchar EccType,

uchar EccPublicKeyIndex,
uint DataLen,
Prototype const uchar *Data,
uint SignLen,
const uchar *Sign,
uchar Mode);
Function ECC verify.

EccType [Input] ECC TYPE:

 0x00 - Curve Brainpool P512r1;
 0x01 - Curve NIST P-521
(secp521r1);
Parameters  0x02 - Curve NIST P-256
(secp256r1).

EccPublicKeyIndex [1~20] The key index for ECC public

[Input] key.

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

 Prolin API Programming Guide

DataLen [Input] Input data length and it can be 2048

bytes at most.

Data [Input] Input data.

SignLen [Input] The Sign length.

Sign [Input] Signature information:

 Mode 0x00: Signature information

Signature information length:

 128 - Curve Brainpool P512r1;
 132 - Curve NIST P-521
(secp521r1);
 64 - Curve NIST P-256
(secp256r1).
 Mode 0x01: ASN.1 encoded
signature information

Mode [Input] 0x00/0x01, format of signature

information

RET_OK Succeeded.
ERR_DEV_NOT_OPEN PED device is not open.
ERR_INVALID_PARAM Invalid parameter.
Return
ERR_SYS_BAD System error.
ERR_VERIFY_SIGN_FAIL Verification failed.
Others Refer to PED Return Code List.
The interface directly verifies the input data, and does not
Instruction calculate the hash value of the input data.

6.14.6 OsPedEccPointMul

int OsPedEccPointMul(uchar EccType,

uchar EccPrivateKeyIndex,
Prototype
uint EccPeerPublicKeyLen,
const uchar * EccPeerPublicKey,

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

 Prolin API Programming Guide

uchar *EccSharedKey,
uchar Mode);
Function Generate ECC shared key.

EccType [Input] ECC TYPE:

 0x00 - Curve Brainpool P512r1;
 0x01 - Curve NIST P-521
(secp521r1);
 0x02 - Curve NIST P-256
(secp256r1).

EccPrivateKeyIndex [1~20] The key index for ECC private

[Input] key.

EccPeerPublicKeyLe ECC peer public key length:

n [Input]
Mode 0x00: ECC public key
 128 - Curve Brainpool P512r1;
 132 - Curve NIST P-521
(secp521r1);
 64 - Curve NIST P-256
Parameters (secp256r1).

Mode 0x01: (04+ECC public key)

 129 - Curve Brainpool P512r1;
 133 - Curve NIST P-521
(secp521r1);
 65 - Curve NIST P-256
(secp256r1).

EccPeerPublicKey ECC peer public key

[Input]

EccSharedKey Output the shared key

[Output]
Mode 0x00: the shared key

Mode 0x01: (04+ the shared key)

same length as PeerPubKeyLen.

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

 Prolin API Programming Guide

Mode [Input] 0x00/0x01, key format.

RET_OK Succeeded.
ERR_DEV_NOT_OPEN PED device is not open.
Return ERR_INVALID_PARAM Invalid parameter.
ERR_SYS_BAD System error.
Others Refer to PED Return Code List.
Instruction

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

 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. 121

 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. 122

 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);
}

When a single static screen is displayed for a long time, the

following problems may occur:

 There will be afterimages when switching other screens;

 It will destroy the characteristics of the LCD liquid crystal,
resulting in the polarization of the liquid crystal and the
appearance of bright stripes;

It is recommended to avoid displaying a single static screen for a

long time.

7.1 OsScrContrast

Prototype void OsScrContrast(int Contrast);

Function Set LCD contrast.
Contrast level. The value range is [0~7].
Parameters Contrast 0: darkest
7: brightest

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

 Prolin API Programming Guide

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].
0: turn off the backlight
Parameters Brightness 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. 124

 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”

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

 Prolin API Programming Guide

KEYF1 59 The first key from left to right

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)

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

 Prolin API Programming Guide

realx = ev0[i].value;
else if (ev0[i].type == 3 && ev0[i].code == 1)
realy = ev0[i].value;
else if (ev0[i].type == 1) {
if (ev0[i].code == 158) {
//if key esc then exit
return 0;
}
}
else if (ev0[i].type == 0 && ev0[i].code == 0 && ev0[i].value == 0) {
realx = 0, realy = 0;
}
printf("event(%d): type: %d; code: %3d; value: %3d; realx: %3d;
realy: %3d\n", i,
ev0[i].type, ev0[i].code, ev0[i].value, realx, realy);
}
return 1;
}

int main(void) {
int done = 1;
printf("sizeof(struct input_event) = %d\n", sizeof(struct input_event));
keypad_fd = open("/dev/keypad", O_RDWR);
if ( keypad_fd < 0 )
return -1;
while ( done ) {
printf("begin handel_event0...\n");
done = handle_event0();
printf("end handel_event0...\n");
}
if ( keypad_fd > 0 ) {
close(keypad_fd);
keypad_fd = -1;
}
return 0;
}

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

 Prolin API Programming Guide

8.1 OsKbBacklight

Prototype void OsKbBacklight(int OnOff);

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. 128

 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”.

Always keeping the RF module enabled may affect the operating experience of the
touch screen, such as the touch screen does not respond, reports random points, or
abnormal signatures. It is recommended that the RF module is turned off when
operating the actual functions of the touch screen.

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

 Prolin API Programming Guide

10 Signature Pad

For more details, please refer to the “Prolin XUI Programming Guide”.

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

 Prolin API Programming Guide

11 Printer

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. 131

 Prolin API Programming Guide

11.2 Open and Close

This part includes three functions: opening, resetting and closing printer.

11.2.1 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.

11.2.2 OsPrnReset

Prototype void OsPrnReset(void);

Function Reset printer parameters and clear printing buffer.
Parameters None.

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

 Prolin API Programming Guide

Return None.
Instruction

Font library settings will be restored to default font status (only

support English).

11.2.3 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

11.3.1 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.

11.3.2 OsPrnSetDirection

Prototype int OsPrnSetDirection(unsigned char Mode);

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

 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.

11.3.3 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

11.4.1 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.

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

 Prolin API Programming Guide

1. After a successful call of this function, the settings will

remain valid until OsPrnSetSpace() is called again or
OsPrnReset( ) is called.
2. The default character space is 0 pixel.
Instruction 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.

11.4.2 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.

11.4.3 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 corresponds to the
Instruction bottom page margin.

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

 Prolin API Programming Guide

11.4.4 OsPrnCheck

Prototype int OsPrnCheck(void);

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

11.4.5 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.

11.4.6 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().

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

 Prolin API Programming Guide

11.4.7 OsPrnSelectFontSize

void OsPrnSelectFontSize(int SingleCodeWidth,

int SingleCodeHeight,
Prototype
int MultiCodeWidth,
int MultiCodeHeight);
Function Set font size.
Width control of single code font. (For non-
SingleCodeWi 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
Instruction is (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.

11.4.8 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.

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

 Prolin API Programming Guide

Return None.
Instruction 1. This function applies to both physical and virtual printer.

This is a one-time action which will become invalid once

implemented.

11.4.9 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.

11.4.10 OsPrnRawData

Prototype int OsPrnRawData (const char *data, int len);

Function Print the typeset data directly.

data[Input] A pointer to string that needs to be printed.
Paramete
rs len[Input] The length of the pointer to string that
needs to be printed.
RET_OK Succeeded.
ERR_INVALID_PARAM Invalid parameter.
Return ERR_DEV_NOT_OPEN Failed to open the device.
ERR_PRN_PAPEROUT Out of paper.
ERR_PRN_OVERHEAT Printer is overheating.

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

 Prolin API Programming Guide

ERR_PRN_OVERVOLTAGE Voltage is too high.

ERR_PRN_BUSY Printer is busy.
1. OsPrnRawData() will begin printing task and will not return until the task is
completed.
2. After completing printing task, OsPrnRawData() will return the printer status
in return value. Therefore, it is not necessary to check printer status.
3. The range of parameter len is (0, 240002]. When len is greater than 240002, the
excess part will not be printed.
Instructio 4. The function is supported only on the Prolin-peng-2.8 and Prolin-albatross-2.9
n platforms.
5. When the breakpoint continuation function is turned on through the keyword
persist.sys.continue.print, and if the printer interrupts printing due to lack of
paper or high temperature during printing, the function can be called again to
continue printing from the breakpoint after adding paper or waiting for the
temperature to drop. Continuing typing from breakpoints after restarting
printers is not supported.
6. The data format can be found in the section “Write”.

11.4.11 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.)

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.

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

 Prolin API Programming Guide

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.

11.4.12 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
1. OsPrnStart() will begin printing task and will not return until
the task is completed.
2. After completing printing task, OsPrnStart() will return the
Instruction 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.

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

 Prolin API Programming Guide

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.

11.4.13 OsPrnClrBuf

Prototype void OsPrnClrBuf(void);

Function Clear print buffer.

Parameters None

Return None
Instruction

11.4.14 OsPrnSetParam

Prototype int OsPrnSetParam(unsigned int cmd);

Function Set whethere to pre-feed printing paper.
cmd [Input] 1: No pre-feeding printing paper
Parameters 2: Pre-feeding printing paper
RET_OK Succeeded
Return
ERR_INVALID_PARAM Invalid parameter
1. This setting only affect the pre-feeding printing paper function, and
Instruction 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.

11.5.1 Open

Open physical printer.

The device name is “/dev/printer”.

int handle = open(“/dev/printer”, O_RDWR).

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

 Prolin API Programming Guide

11.5.2 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]
}

11.5.3 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
001 Default gray level
010 Reserved
011 Two-layer thermal printing A
100 Two-layer thermal printing B
101 Reserved
110 Reserved

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

 Prolin API Programming Guide

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.

11.5.4 Close

Close file handles of printer.

close (handle);

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

 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. 144

 Prolin API Programming Guide

}FT_DOT;

12.2 Font Operation

12.2.1 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);

12.2.2 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

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

 Prolin API Programming Guide

Dot-matrix data needs to be cached after the fonts were opened.

Instruction It is recommended to wait 3 seconds before calling
OsGetFontDot().

12.2.3 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.

12.2.4 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. 146

 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. 147

 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. 148

 Prolin API Programming Guide

13 Code

Prolin uses UTF-8 as the default code and provides interfaces to converse code.

13.1 Code Conversion

13.1.1 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”.
Parameters InBuf [Input]
“Unicode” should end with“\0\0’’.
Target encoding string that has been
OutBuf [Output]
converted.
LenOut [Input] Size of OutBuf array.

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

 Prolin API Programming Guide

It should be at least 1.5 times of the InBuf

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. 150

 Prolin API Programming Guide

14 MSR

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

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

 Prolin API Programming Guide

The corresponding magnetic track in

ERR_MSR_NO_TRACK_ER
-2710 the magnetic card has not been
R
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

14.3.1 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

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

 Prolin API Programming Guide

OsMsrOpen() shall be called to open the device; otherwise, the

Instruction 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.

14.3.2 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.

14.3.3 OsMsrReset

Prototype void OsMsrReset(void);

Soft reset magnetic stripe reader and clear the obtained
Function magnetic card data.
Parameters None.
Return None.
Instruction

14.3.4 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

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

 Prolin API Programming Guide

1. OsMsrSwiped() will return immediately no matter whether

there is a card-swiping action or not.
Instruction
2. OsMsrOpen(), OsMsrRead() or OsMsrReset() can clear the
swiped status of magnetic card.

14.3.5 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.

14.3.6 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
Return RET_OK Succeeded.

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

 Prolin API Programming Guide

ERR_MSR_NOT_SWIP
No card is swiped.
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. 155

 Prolin API Programming Guide

15 IC 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. 156

 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

15.2.1 APDU Request Structure

ST_ APDU_REQ

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

 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.

15.2.2 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 */
unsigned char SWB; /* status word 2 of ICC */

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

 Prolin API Programming Guide

}ST_ APDU_RSP;

15.3 Encapsulated Interfaces

15.3.1 OslccOpen

Prototype int OsIccOpen(int Slot);

Function Open IC card reader.

Slot IC card channel number:
 ICC_USER_SLOT User card
 ICC_SAM1_SLOT SAM card
slot 1
 ICC_SAM2_SLOT SAM card
Parameters slot 2
 ICC_SAM3_SLOT SAM card
slot 3
 ICC_SAM4_SLOT SAM card
slot 4
RET_OK Succeeded.
Return ERR_DEV_NOT_EXIST Device does not exist.
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.

15.3.2 OsIccDetect

Prototype int OsIccDetect(int Slot);

Function Test whether there is a card in specified slot.

Slot IC card channel number:
Parameters
 ICC_USER_SLOT User card

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

 Prolin API Programming Guide

 ICC_SAM1_SLOT SAM card

slot 1
 ICC_SAM2_SLOT SAM card
slot 2
 ICC_SAM3_SLOT SAM card
slot 3
 ICC_SAM4_SLOT SAM
card slot 4
RET_OK Card is inserted.
Return Others Please refer to IC Card Return Code
List.
1. OsIccDetect () will return immediately no matter whether there is a
card in slot or not.
Instruction 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.

15.3.3 OsIccInit

int OsIccInit(int Slot,

Prototype unsigned long Option,
unsigned char *Atr);
Function Initialize IC card device.

Slot IC card channel number:

 ICC_USER_SLOT User card
 ICC_SAM1_SLOT SAM card
slot 1
 ICC_SAM2_SLOT SAM card
slot 2
 ICC_SAM3_SLOT SAM card
Parameters slot 3
 ICC_SAM4_SLOT SAM
card slot 4.
Option (Bit 0~1) Card voltage options:
00 - 5V, 01 - 1.8V,
10 - 3V
(Bit 2)Support PPS protocol:

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

 Prolin API Programming Guide

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).
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).
Atr [Output] 1. Answer To Reset (ATR). The card
will return response data of 34
bytes at most.
2. Contents: Length of ATR (1 byte)
and ATR.
RET_OK Succeeded.
Return Others Please refer to IC Card Return Code
List.
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.
Instruction 3. Some terminals can only work with one SAM card at a time. If several
cards need to be operated at the same time, initialize cards one by
one: (OsIccInit ( )) - > operation (OsIccExchange()) - > close
(OsIccClose( )).

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

 Prolin API Programming Guide

Most SAM cards only support ISO7816, so the “Option” should be

set to 0x20 instead of 0x00.

15.3.4 OsIccExchange

int OsIccExchange(int Slot,

int CtrlFlag,
Prototype
constST_APDU_REQ *ApduReq,
ST_APDU_RSP *ApduRsp);
Function Interact with IC card using commands.

Slot IC card channel number:

 ICC_USER_SLOT User card
 ICC_SAM1_SLOT SAM card
slot 1
 ICC_SAM2_SLOT SAM card
slot 2
 ICC_SAM3_SLOT SAM card
slot 3
 ICC_SAM4_SLOT SAM
card slot 4
CtrlFlag 1. Bit0: Whether to send "GET
Parameters RESPONSE" command
automatically under T=0 protocol.
1 Yes
0 No
2. Bit1~Bit31: Reserved
ApduReq [Input] A pointer to APDU request structure
ST_APDU_REQ : terminal request
message.
ApduRsp [Output] A pointer to APDU response structure
ST_APDU_RSP :card response
message.
RET_OK Succeeded.
Return Others Please refer to IC Card Return Code
List.
Instruction

15.3.5 OsIccTransfer

Prototype int OsIccTransfer(int Slot,

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

 Prolin API Programming Guide

int CtrlFlag, const unsigned char,

*pucTxBuff,
int iTxLen,
unsigned char *pucRxBuff,
int *piRxLen);
According to the half-duplex communication protocol specified in
Function ISO14443-4 to achieve transparent transmission/reception function.
Slot IC card channel number:
 ICC_USER_SLOT User card
 ICC_SAM1_SLOT SAM card
slot 1
 ICC_SAM2_SLOT SAM card
slot 2
 ICC_SAM3_SLOT SAM card
slot 3
 ICC_SAM4_SLOT SAM
card slot 4
CtrlFlag 1. Bit0: Whether to send "GET
RESPONSE" command
Parameters automatically under T=0 protocol.
1 Yes
0 No
2. Bit1~Bit31: Reserved
pucTxBuff [Input] Data buffer to be transmitted.
iTxLen [Input] Length of the data to be transmitted,
[unit:byte]
pucRxBuff [Output] Buffer for receiving card response data
piRxLen [Output] Length of received card data,
[unit:byte]

RET_OK Succeeded.
Return Others Please refer to IC Card Return Code
List.
The following is an example of how the terminal sends the
standard APDU commands and extended APDU commands
supported by the card to the IC card:
unsigned char ucpSrc[4096] = {0};
Instruction unsigned int iTxNum = 0;
unsigned char ucpDes[4096] = {0};
unsigned int ipRxNum = 0;
unsigned int Lc = 0;/*the length of send data*/

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

 Prolin API Programming Guide

unsigned int Le = 0;/*the expect data which receive from

card*/
1. the standard APDU:
memset(ucpSrc, 0x00, sizeof(ucpSrc));
iTxNum = 0;
memcpy(ucpSrc,"\x00\xA4\x04\x00",4);
iTxNum += 4;
Lc = 0x0C;
ucpSrc[iTxNum ++] = Lc;
memcpy(ucpSrc+iTxNum,"\xd2\x76\x00\x01\x35\x4b\x4
1\x53\x4d\x30\x31\x00", Lc);
iTxNum += Lc;
Le = 0x0;
ucpSrc[iTxNum ++] = Le;
OsIccTransfer(0, 1, ucpSrc, iTxNum, ucpDes, &
ipRxNum);

2. the extended APDU:

Lc = 0x00;
memset(ucpSrc, 0x00, sizeof(ucpSrc));
iTxNum = 0;
memcpy(ucpSrc,"\x00\xb2\x01\x3c",4);// The specific
card may have different instructions.
iTxNum += 4;
Le = 65536;
ucpSrc[iTxNum ++] = 0x00;// The extended APDU
needs to be spliced like this.
ucpSrc[iTxNum ++] = (unsigned char)( Le & 0xFF);
ucpSrc[iTxNum ++] = (unsigned char)( Le >> 8 & 0xFF);
OsIccTransfer(0, 1, ucpSrc, iTxNum, ucpDes, &
ipRxNum);

15.3.6 OsIccClose

Prototype int OsIccClose(int Slot);

Function Close IC card device.

Slot IC card channel number:

 ICC_USER_SLOT User card
Parameters  ICC_SAM1_SLOT SAM card
slot 1
 ICC_SAM2_SLOT SAM card
slot 2

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

 Prolin API Programming Guide

 ICC_SAM3_SLOT SAM card

slot 3
 ICC_SAM4_SLOT SAM
card slot 4
RET_OK Succeeded.
Return Others Please refer to IC Card Return Code
List.
Instruction

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

 Prolin API Programming Guide

16 RF 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.

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

 Prolin API Programming Guide

Configuration file does

PCD_ERR_PARAMFILE_FLAG -2911
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
PCD_CHIP_ABNORMAL -2952
does 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.

16.2.1 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.*/

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

 Prolin API Programming Guide

unsigned char check_cancel_key_w; /*respond to write permission of

the cancel key*/
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

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

 Prolin API Programming Guide

os_picc_transfer_rxlen_set_v
al is invalid */
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 configure_technology_type_w; /* Set whether the
configure_technology_type_v
al parameter can be written：
1—allowed, other values--not
allowed */
unsigned char configure_technology_type_val; /* Configure the modulation
technology type of the data
sent by OsPiccTransfer()*/
unsigned char reserved[34]; /* Reserved byte, for future use.
sizeof(PCD_USER_ST)= 76*/
} PCD_USER_ST;

16.3 Encapsulate Interfaces

16.3.1 OsPiccOpen

Prototype int OsPiccOpen(void);

Function Power on PCD module and make it prepared for work.
Parameters None.
0 Succeeded.
Others Fail to open device. (Details refer to
Return Code List.)

Return ERR_BATTERY_V Battery voltage is too low.

OLTAGE_TOO_LO
W
ERR_BATTERY_A Battery is absent.
BSENT

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

 Prolin API Programming Guide

1. D200 and S920 POS models must be powered by battery to

operate RF module; otherwise, ERR_BATTERY_ABSENT
Instruction will be returned.
2. When the battery voltage is 0,
ERR_BATTERY_VOLTAGE_TOO_LOW is returned.

16.3.2 OsPiccClose

Prototype int OsPiccClose(void);

Function Power off PCD module.
Parameters None.
0 Succeeded.
Return Others Failed.(Details refer to Return Code
List.)
Instruction

16.3.3 OsPiccResetCarrier

Prototype int OsPiccResetCarrier(void);

Function Reset the carrier wave.
Parameters None.
0 Succeeded.
Return Others Failed. (Details refer to Return Code
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.

16.3.4 OsPiccPoll

int OsPiccPoll( char *pcPiccType,

Prototype
unsigned char *pucATQx );
Function Poll cards, only support the roll polling of A card and B card.
pcPiccType[Output] Card type:
 “A” - card A
 “B” - card B
Parameters
pucATQx [Output] Response data:
The valid length of A card is 2 bytes.
The valid length of B card is 12 bytes.
Return 0 Succeeded.

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

 Prolin API Programming Guide

Others Failed. (Details refer to 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.

16.3.5 OsPiccAntiSel

int OsPiccAntiSel( const char pcPiccType,

unsigned char *pucUID,
Prototype
const unsigned char ucATQ0,
unsigned char *pucSAK );
Function Do anti-collision and selection operations for cards.
pcPiccType[Input] Card type:
 “A” - card A
 “B” - card B
pucUID[Output] Unique identifier of card:
 Card A-- 4, 7 or 10 bytes.
 Card B—4 bytes.
Parameters
ucATQ0[Input] The parameter is unused.
pucSAK[Output] Response data to card selection.
SAK is the response data to the last
selected command of card A. This
parameter is ignored by card B.
The valid length is 1 byte.
0 Succeeded.
Return Others Failed. (Details refer to Return Code
List.)
The value of pucSAK can be used to differentiate card A and
Instruction Mifare card.

16.3.6 OsPiccActive

int OsPiccActive( const char pcPiccType,

Prototype
unsigned char *pucRATS );
Function Activate card.
pcPiccType[Input] Card type:
 “A”– A card
Parameters  “B”– B card
pucRATS[Output] Response data to card activation:

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

 Prolin API Programming Guide

 For A card, pucRATS is the response

data to ATS command.
 For B card, PucRATS is the
response data to ATTRIB command.

0 Succeeded.
Return Others Fail to activate card. (Details refer to
Return Code List.)
Instruction

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”.

16.3.7 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

16.3.8 OsPiccRemove

Prototype int OsPiccRemove(void );

Function Remove card in accordance with EMV mode.
Parameters None.
Return 0 Succeeded.

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

 Prolin API Programming Guide

Others Failed. (Refer to Return Code List.)

Instruction

16.3.9 OsMifareAuthority

int OsMifareAuthority(unsigned char *uid,

unsigned char blk_no,
Prototype
unsigned chargroup,
unsigned char *psw);
Function VerifyMifare card.
uid [Input] Card ID.
The valid length is 4 bytes.
blk_no[Input] Block number.
Parameters
group [Input] Password types: “A”/“B”.
psw[Input] Authentication password.
The valid length is 6 bytes.
0 Succeeded.
Return
Others Failed. (Refer to Return Code List.)
Instruction

16.3.10 OsMifareOperate

int OsMifareOperate(unsigned charucOpCode,

unsigned charucSrcBlkNo,
Prototype
unsigned char*pucVal,
unsigned char ucDesBlkNo );
Read or write a specific block of Mifare card; Increase, decrease
Function or backup the data in specified block of Mifare card, and update
it into another specified data block.
ucOpCode [Input]  “r”or“R”:read;
 “w”or“W”: write;
 “+”: increase;
 “-“: decrease;
 “>”: transfer/backup.
Parameters
ucSrcBlkNo[Input] Specify the block number that will be
accessed.
pucVal[Input/Output]  For reading operation, pucVal
outputs block contents. The buffer
size of pucVal is 16 bytes.

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

 Prolin API Programming Guide

 For writing operation, pucVal

inputs block contents. The buffer
size of pucVal is 16 bytes.
 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.
ucUpdateBlkNo [Input] Specify the block number which is
used to write in the operation result.
(When reading or writing block,
ucUpdateBlkNo is a NULL pointer.)
0 Succeeded.
Return
Others Failed. (Refer to Return Code List.)
Instruction

16.3.11 OsPiccInitFelica

int OsPiccInitFelica(unsigned char ucSpeed,

Prototype
unsigned char ucModInvert );
Function Initialize the configuration of FeliCa card.
ucSpeed[Input] Set transmission rate of interaction with
card:
 1: 424Kbp
Parameters  Others: 212Kbps
ucModInvert[Input] Set modulation mode of FeliCa.
 1: positive modulation output;
 Others: reverse modulation output.
Return 0 Succeeded.
Instruction

16.3.12 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.
cid Specify logical channel number of card.
Parameters
[Input]

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

 Prolin API Programming Guide

The valid value of cid ranges from 0 to 14,

the value is set to 0 currently.
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.)
Instruction

16.3.13 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.)
The parameter configure_technology_type_val of
pcd_user_config is used to configure the modulation mode of
the data sent by OsPiccTransfer. After calling OsPiccOpen(),
call OsPiccSetUserConfig() to set this parameter, and the
configure_technology_type_val parameter is defined as follows:
 0x03 means Type A short frame modulation mode;
 0x04 means Type A standard frame modulation mode,
without CRC check byte at the end of the frame;
 0x05 means Type B modulation mode;
 0x06 represents Type A standard frame modulation mode,
with 2 bytes of CRC check byte at the end of the frame.
Instruction
Demo code:
PCD_USER_ST pcd_user;
OsPiccOpen();
memset(&pcd_user,0x00,sizeof(PCD_USER_ST));
pcd_user.configure_technology_type_w = 1;
pcd_user.configure_technology_type_val = 0x03;
pcd_user.protocol_layer_fwt_set_w = 1;
pcd_user.protocol_layer_fwt_set_val = 9;
ret = OsPiccSetUserConfig(&pcd_user);/* Set the timeout time
(FWT)according to actual needs*/

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

 Prolin API Programming Guide

txbuf[0] = 0x52; /*wupa Short frame modulation mode */

txln = 1;
ret = OsPiccTransfer(txbuf, txln, rxbuf, &rxln);

16.3.14 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

16.3.15 OsPiccApplePoll

int OsPiccApplePoll(char *pcPiccType,

Prototype unsigned char *pucATQx,
unsigned char *pucSendData);
Detect cards, including the roll polling of type A card, type B card
Function
and type V card.
pcPiccType[Output] Card types:
 A – type A card
 B – type B card
 V – type V card
pucATQx [Output] Response data of the detected card:
 The response data length of type A
card is 2 bytes.
Parameters  The response data length of type B
card is 12 bytes.
 The response data length of type V
card is 2 bytes.
pucSendData[Input] When the first byte is 0x01, enter a fixed
four-byte length:
 "\x01\x00\x00\x00" represents
Terminal in VAS App OR Payment
Mode.

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

 Prolin API Programming Guide

 "\x01\x00\x00\x01" represents
Terminal in VAS App AND Payment
Mode.
 "\x01\x00\x00\x02", represents
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.

16.3.16 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.

16.3.17 OsPiccInitIso15693

Prototype int OsPiccInitIso15693(unsigned char ucDataCodeMode);

Function Initialize the ISO15693 card.
ucDataCodeMode[I The transmission rate that used to
nput] interact with the card:
Parameters
 0: 26.48 kbits/s
 Other values: reserved
Return 0 Succeeded.

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

 Prolin API Programming Guide

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. 178

 Prolin API Programming Guide

17 Communication 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
PORT_USBDEV 11
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. 179

 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

17.2.1 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. 180

 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;

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

 Prolin API Programming Guide

 Select a connection mode among COM, USB and Network in

TM.

17.2.2 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.

17.2.3 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. 182

 Prolin API Programming Guide

17.2.4 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. 183

 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.

17.2.5 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

17.2.6 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
ERR_INVALID_PARAM Invalid parameter.

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

 Prolin API Programming Guide

Instruction

17.2.7 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
Device node Serial port Applicable models
module
/dev/ttyAMA0 Modem Modem S800
/dev/ttyAMA1 Wireless Wireless S800/S900

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

 Prolin API Programming Guide

S800/S900/S300/D2
/dev/ttyAMA2 PORT_COM1 COM1
00
/dev/ttyAMA3 PORT_PINPAD Pinpad S800
/dev/ttyAMA3 PORT_COM2 COM2 PX5/PX7
S800/S900/S300/D2
/dev/ttyhost PORT_USBHOST USB
00/S920//PX5/PX7
S800/S900/S300/D2
/dev/ttydev PORT_USBDEV USB
00/S920//PX5/PX7

Specific operations of serial port are as follows:

17.3.1 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”);
}

17.3.2 Read

Read data from communication port.

Sample code:
charbuff [1024];
int Len = 1024;
int readByte = read (fd, buff, Len);

17.3.3 Write

Write data to communication port. (Send)

Sample code:
charbuffer [1024];
int Length = 1024;
int nByte;
nByte = write (fd, buffer, Length);

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

 Prolin API Programming Guide

17.3.4 Close

Close communication port.

close(fd);

17.3.5 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);

17.3.6 Clear the Buffer Data of Communication Port

Sample code:

/* clear the buffer data*/

tcflush(fd, TCIOFLUSH);

17.3.7 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;
}

/* Initialize configuration messages*/

bzero (&newtio, sizeof (newtio));
newtio.c_cflag |= CLOCAL | CREAD;
newtio.c_cflag &= ~CSIZE;

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

 Prolin API Programming Guide

/* 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;
}

/* Set baud rate*/

switch (nSpeed)
{
case 1200:

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

 Prolin API Programming Guide

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;
}
/* set stop bits */
if (nStop == 1)
newtio.c_cflag &= ~CSTOPB;
else if (nStop == 2)

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

 Prolin API Programming Guide

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. 190

 Prolin API Programming Guide

18 MODEM

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. 191

 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. 192

 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. 193

 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. 194

 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. 195

 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.

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

 Prolin API Programming Guide

Calling connection fails

-3180 to set the threshhold of
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.

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

 Prolin API Programming Guide

Daemon fails to create

-3198
thread.
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 pre-
-3206
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.

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

 Prolin API Programming Guide

If no or error
implementation of
OsModemConnect(),
-3218
then implement
OsPppomLogin()
orOsPppomCheck().
Modem or ModemPPP is
-3219 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];

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

 Prolin API Programming Guide

int ConnectTimeout;

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.

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

 Prolin API Programming Guide

 Detect whether the parallel

telephone is occupied (used in
TRUE
Caller dialing or none-manually-
DetectLineVolta answering mode).
ge 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*/

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

 Prolin API Programming Guide

“9600”/*9600 bps */
“12000”/*12000 bps*/
“14400”/*14400 bps */
“19200”/*19200 bps */
“24000”/*24000 bps */
“26400”/*26400 bps */
“28800”/*28800 bps */
“31200”/*31200 bps */
“33600”/*33600 bps */
“48000”/*48000 bps */
“56000”/*56000 bps */
For null string "\ 0"，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 */

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

 Prolin API Programming Guide

“2400”/*2400 bps*/
“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.

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

 Prolin API Programming Guide

1. This function must be called successfully to open Modem

device; otherwise, other related functions will not work.
Instruction
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.

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

 Prolin API Programming Guide

18.6 OsModemConnect

int OsModemConnect(const ST_MODEM_SETUP *Setup,

Prototype
const unsigned char *TelNo);
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
Instruction
called.

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

 Prolin API Programming Guide

2. Telephone icon is controlled by modem driver. It shows

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 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
Return Receive buffer is not empty
VE_DATA
(Have received remote data).
MODEM_SEND_POOL_FU
Send buffer is full.
LL
ERR_MDM_BYPASS_BUS
Parallel line is busy.
Y

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

 Prolin API Programming Guide

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.
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
Return Command is too long.
G
Does not support the
ERR_MDM_CMD_NOT_SUPP command. (command that
ORT doesn’t begin with
AT,S3,S7,WT=)

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

 Prolin API Programming Guide

ERR_DEV_NOT_OPEN Device is not open.

1. The function needs to be called before OsModemConnect();
it is only valid during the current calling process of
OsModemConnect().
2. While executing this function, the current dialing or
Instruction
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.

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

 Prolin API Programming Guide

SendBuf[Input] Send buffer.

Parameters Length of packets which will be sent.[unit:
SendLen
bytes]
RET_OK Succeeded.
ERR_NOT_CONNECT Not connected.
ERR_MDM_TXOVER Send buffer is full.
Return 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.

Instruction 1. The maximum length of received packet is 2048 bytes each

time. As there are 5 additional control characters when

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

 Prolin API Programming Guide

called in synchronous communication, the maximum length

of received and sent data are both 2053 bytes.
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
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.
Parameter Password.
s The valid string length is not more than 50
bytes.
Password[Input] For the 96169 background of China Telecom,
any user name with at least one character
can be entered.
It can’t be NULL.
Authentication algorithms.
Auth
The supported authentication algorithms are:

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

 Prolin API Programming Guide

PPP_ALG_PA 0x00 PAP

P 0000 Authentication
01 Algorithm
PPP_ALG_CH 0x00 CHAP
AP 0000 Authentication
02 Algorithm
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).
Instructio 2. TimeOutMs=0 means no wait time and will return
immediately.
n
3. Call OsPppomCheck() to check the link status.
4. The login time varies according to the settings of
ST_MODEM_SETUP.The maximum asynchronous baud
rate supported by S800 modem chip is 33600. Dialing-up

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

 Prolin API Programming Guide

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
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.

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

 Prolin API Programming Guide

Return RET_OK Succeeded.

Instruction

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

 Prolin API Programming Guide

19 Network 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)
{
struct sockaddr_in stSockAddr;
int SocketFD = socket(PF_INET, SOCK_STREAM, IPPROTO_TCP);

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

 Prolin API Programming Guide

if(-1 == SocketFD)
{
perror("cannot create socket");
exit(EXIT_FAILURE);
}
memset(&stSockAddr, 0, sizeof(stSockAddr));
stSockAddr.sin_family = AF_INET;
stSockAddr.sin_port = htons(1100);
stSockAddr.sin_addr.s_addr = INADDR_ANY;
if(-1 == bind(SocketFD,(struct sockaddr *)&stSockAddr,
sizeof(stSockAddr)))
{
perror("error bind failed");
close(SocketFD);
exit(EXIT_FAILURE);
}
if(-1 == listen(SocketFD, 10))
{
perror("error listen failed");
close(SocketFD);
exit(EXIT_FAILURE);
}

for(;;)
{
int ConnectFD = accept(SocketFD, NULL, NULL);
if(0 > ConnectFD)
{
perror("error accept failed");
close(SocketFD);
exit(EXIT_FAILURE);
}
/* perform read-write operations ... read(ConnectFD,buff,size)*/
if (-1 == shutdown(ConnectFD, SHUT_RDWR))
{
perror("cannot shutdown socket");
close(ConnectFD);
exit(EXIT_FAILURE);
}

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

 Prolin API Programming Guide

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)
{
perror("error: first parameter is not a valid address family");
close(SocketFD);
exit(EXIT_FAILURE);

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

 Prolin API Programming Guide

}
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>
#include <netinet/in.h>
#include <unistd.h> /* for close()socket */
#include <stdlib.h>

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

 Prolin API Programming Guide

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>
#include <sys/socket.h>
#include <sys/types.h>
#include <netinet/in.h>

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

 Prolin API Programming Guide

#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. 219

 Prolin API Programming Guide

20 Network 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

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

 Prolin API Programming Guide

has no corresponding
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 maximum value (default
-3329
ED
value：64).

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

 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 in
NET_DOING 1 process (such as PPP
login, DHCP).

20.2 Data Definition

20.2.1 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. 222

 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”.

20.2.2 IPv6 Status Value List

Table 20.3 IPv6 status value list

Macro Value Description

IP6_STATELESS_ADDR_AUTOCO 0 Stateless address auto-
NFIG configuration.
IP6_DHCP6_STATEFULL_ADDR_C 1 DHCPv6 statefull address
ONFIG configuration.
IP6_DHCP6_STATELESS_ADDR_C 2 DHCPv6 stateless address
ONFIG configuration.

20.2.3 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*/

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

 Prolin API Programming Guide

char GlobalAddr[8][64]; /*Global address of IPv6,at most 8

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{

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

 Prolin API Programming Guide

char DestAddr[16];/* dest addr*/

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.

20.3.1 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

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

 Prolin API Programming Guide

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.

20.3.2 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.

20.3.3 OsNetPingEx

int OsNetPingEx(const char *Addr,

Prototype int TimeOutMs,
int Size);
Function Ping a specific IP address to check the status of the network connection.
Addr[Input] IP address of the target device.
The format is “XXX.XXX.XXX.XXX”. The value
range of XXX is 0~255, e.g.: “192.168.0.3”.
Parameters TimeOutMs [Input] Timeout[unit:ms]
The valid timeout ranges from 3000 to 3600000.
Size [Input] The size of the data

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

 Prolin API Programming Guide

The valid data size is not more than 1024 bytes.

>0 Succeeded, the time it takes to ping.
ERR_NET_IF The network link cannot be used (not
Return established or disconnected).
ERR_INVALID_PARAM Invalid parameter.
ERR_TIME_OUT Timeout.
1. The communication is performed with default route.
Instruction
2. Call OsNetGetRoute() to query the current route.

20.3.4 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 value
Parameters Addr[Output] 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. 227

 Prolin API Programming Guide

2. Call OsNetGetRoute() to query the current route.

20.3.5 OsNetDnsEx

int OsNetDnsEx(const char *Name,

Prototype struct DnsAddrInfo *Addr,
int TimeOutMs);
IP address of the corresponding domain name resolution, which will be
Function saved in structure DnsAddrInfo.
Name[Input] Domain name, for example:
[www.sina.com.cn].
The valid Name is not more than 255
characters and it can’t be NULL.
Parameters
Addr[Output] Store the IP address mapped by the domain
name.
TimeOutMs [Input] Timeout[unit：ms]the valid value ranges from
1000 to 3,600,000.
RET_OK Success
ERR_NET_IF Network link cannot be used (not
established or disconnected).
ERR_INVALID_PARAM Invalid parameter
ERR_TIME_OUT Timeout
Return ERR_NET_DNS Domain name resolution failed, and
corresponding domain name may not
exist.
ERR_NET_SERVER_BAD IP server exception.
ERR_NET_NODNServer The domain name server is not
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 resolution;
Instruction 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().

20.3.6 OsNetSetConfig

int OsNetSetConfig(int NetLink,

const char *Addr,
Prototype const char *Mask,
const char *Gateway,
const char *DNSServer);

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

 Prolin API Programming Guide

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.
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
Instruction successfully.

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

 Prolin API Programming Guide

2. The function only checks the validity of Addr, Mask and

Gateway’s formats without checking the matching relation
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.

20.3.7 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
ranges from 0 to 255, e.g.: “192.168.0.3” and it
can be NULL.
POS terminal mask code.
Parameters 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
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.
Return RET_OK Succeeded.

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

 Prolin API Programming Guide

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.

20.3.8 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.

Please close all the connections before starting DHCP; otherwise,

these connections may fail to communicate.

20.3.9 OsNetCheckDhcp

Prototype int OsNetCheckDhcp(int NetLink);

Function Check DHCP status.
Parameters NetLink Physical channel:

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

 Prolin API Programming Guide

 NET_LINK_ETH: Ethernet;
 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

20.3.10 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.

20.3.11 OsPppoeLogin

int OsPppoeLogin(const char *Name,

Prototype const char *Password,
int TimeOutMs);
Function PPPoE link login.
User name.
Parameters Name[Input]
The valid length ranges from 0 to 50 bytes.

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

 Prolin API Programming Guide

It can’t be NULL. If there is no user name, a null

string “” can be used instead.
Password.
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.

20.3.12 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

20.3.13 OsPppoeLogout

Prototype void OsPppoeLogout(void);

Function Disconnect the PPPoE link.
Parameters None.
Return None.
Instruction

20.3.14 OsNetSetRoute

Prototype int OsNetSetRoute(int NetLink);

Function Set system default route.
Physical channel, please refer to Physical
Parameters NetLink
channel list

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

 Prolin API Programming Guide

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.

20.3.15 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.
Instruction 2. The last used link is logged out, as any link that has been
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.

20.3.16 OsNetSetRouteTable

int OsNetSetRouteTable(int NetLink,

const char *DestAddr,
Prototype
const char *GenMask,
const char *GateWay)；
Function Add IPv4 static address to the route table.
NetLink Physical channel, please refer to Physical
channel list.
Parameters DestAddr Destination network address
GenMask Mask address of destination network

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

 Prolin API Programming Guide

GateWay Gateway address

RET_OK Success
ERR_INVALID_PARA Invalid parameter
M
ERR_NET_SERVER_B IP server exception
Return AD
ERR_NET_SERVER_B IP server busy
USY
ERR_ROUTE_EXIST Route already exists
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
Instruction OsNetSetRouteTable() add the static route to the 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.

20.3.17 OsNetDelRouteTable

int OsNetDelRouteTable(int NetLink,

Prototype const char *DestAddr,
const char *GenMask);
Function Delete the specified IPv4 address from the router.
NetLink Physical channel, please refer to Physical
channel list.
Parameters DestAddr Destination network address
GenMask Mask of destination address
RET_OK Success
ERR_INVALID_PARAM Invalid parameter
ERR_NET_SERVER_BA IP server exception
D
Return
ERR_NET_SERVER_BU IP server busy
SY
ERR_ROUTE_NONEXIS Route doesn’t exist
T
When application calls this function to delete a certain route, system will
only check the validity of each parameter, application also needs to
Instruction ensure that the current communication will not be affected after the
specified route has been deleted.

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

 Prolin API Programming Guide

20.3.18 OsNetGetRouteTable

int OsNetGetRouteTable(int NetLink,

Prototype
struct IPv4RouteTable *RouteTable)；
Function Acquire the specified IPv4 route.
NetLink Physical channel, please refer to Physical
channel list.
Parameters
RouteTable Structure that is used to receive the IPv4
route table information: IPv4RouteTable.
RET_OK Success
ERR_INVALID_PARA Invalid parameter
M
ERR_NET_SERVER_B IP server exception.
AD
Return ERR_NET_SERVER_B IP server is busy
USY
ERR_SYS_BAD System error
ERR_MEM_FAULT Memory error
ERR_NET_SESS_BR Connection error
OKEN
Application can call OsNetGetRouteTable() to acquire the route
Instruction information of IPv4 address.

20.3.19 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

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

 Prolin API Programming Guide

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 configuration of the
Instruction 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.

20.4 IPv4/IPv6 Network Configuration Interface

The following interfaces apply to both IPv4 and IPv6 network environment.

20.4.1 OsNetSetDns

Prototype int OsNetSetDns(const char *Dns);

Function Set DNS address.

Parameters Dns[Input] DNS address.

RET_OK Succeeded.
Return
ERR_INVALID_PARAM Invalid parameter.
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.
Instruction 3. DNS is stored in /etc/resolv.conf, through which 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

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

 Prolin API Programming Guide

“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.

20.5.1 OsNetPing6

int OsNetPing6(const char *DestAddr,

const char *SrcAddr,
Prototype
int TimeOutMs,
int size);
Send request message ICMPv6 ECHO_REQUEST to the specified
Function network host.
DestAddr[input] IPv6 address of the target network host.
E.g.: “2015:10::5”.
SrcAddr[input] Source IPv6 address. E.g.: “2015:10::6”.
SrcAddr is the default address allocated by the
Parameters system when it is NULL.
TimeOutMs Timeout[unit: ms]
The valid timeout ranges from 3,000 to 3,600,000.
size The load size of the request message.
The valid size is not more than 1,500 bytes.
>=0 Succeeded. Time spent by ping(unit: ms).
ERR_NET_IF The link is not established or is
disconnected.
ERR_INVALID_PARAM Invalid parameter.
ERR_TIME_OUT Timeout.
ERR_NET_ICMPV6_PKT SIZE is greater than the minimum MTU.
Return _TOOBIG
ERR_NET_ICMPV6_UNR Target is unreachable.
EACH
ERR_NET_ICMPV6_TIME TTL exceeds the maximum value (TTL
_EXCEED default value is 64).
ERR_NET_ICMPV6_PAR Protocol parameter error. Cannot process
AMPROB the middle route or destination node.
For example:
Instruction int ret;
ret=OsNetPing6("2015:10::5","2015:10::6",9000,56).

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

 Prolin API Programming Guide

20.5.2 OsNetSetIPv6Addr

int OsNetSetIPv6Addr(int NetLink,

Prototype const char *Addr,
int PrefixLength);
Function Set static IPV6 address.
NetLink Physical channel:
 NET_LINK_ETH: Ethernet.
Addr IPv6 address.
[Input] E.g.: “2015:30::10”.
Parameters
PrefixLength Length of the IPv6 address prefix.
[Input] The valid length ranges from 1 to 128 bits.
The PrefixLength will be set to 64 by default if it is
0.
RET_OK Succeeded.
ERR_NET_IF The link is not established or is
disconnected.
Return ERR_NET_DHCP6_DUPLI The setting address is in conflict with a
CATE_ADDR certain node address in local area 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 powered down.
Instruction
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.

20.5.3 OsNetGetIPv6Addr

int OsNetGetIPv6Addr(int NetLink,

Prototype
struct IPv6Info *AddrInfo);
Function Get IPv6 and DNS address of specified physical channel.
NetLink Physical channel:
 NET_LINK_ETH: Ethernet.
Parameters
AddrInfo Output classified IPv6 and DNS address, IPv6Info
[Output] structure.

RET_OK Succeeded.
Return ERR_NET_IF The link is not established or is
disconnected.

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

 Prolin API Programming Guide

ERR_INVALID_PARAM Invalid parameter.

For example：
Instruction struct IPv6Info AddrInfo;
ret = OsNetGetIPv6Addr(NET_LINK_ETH,&AddrInfo);

20.5.4 OsNetGetRouteAdvertise6

int OsNetGetRouteAdvertise6(int NetLink,

Prototype int TimeOutMs,
int *RouteMode);
Function Get the working mode of router within specified time.
NetLink Physical channel:
NET_LINK_ETH: Ethernet.
TimeOutMs Waiting time for router to respond. (Unit: ms)
[Input] The valid timeout ranges from 1,000 to 5,000.
If the value <1,000, it will be set to 1,000; If the
value> 5,000, it will be set to 5,000.
Parameters RouteMode Working modes of router:
[Output] 1. IP6_STATELESS_ADDR_AUTOCONFIG:
Stateless address auto-configuration.
2.IP6_DHCP6_STATEFULL_ADDR_CONFIG:
DHCPv6 stateful address configuration.
3.IP6_DHCP6_STATELESS_ADDR_CONFIG:
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.
For example：
int ret,route_mode;
Instruction ret=OsNetGetRouteAdvertise6(NET_LINK_ETH,3000,&
route_mode);
if(ret == RET_OK)
{
switch (route_mode)
{
Case IP6_STATELESS_ADDR_AUTOCONFIG:
break; /*do not need to call DHCPv6*/

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

 Prolin API Programming Guide

Case IP6_DHCP6_STATEFULL_ADDR_CONFIG :
ret=OsNetStartDhcp6(NET_LINK_ETH,IP6_DHCP6_ST
ATEFULL_ADDR_CONFIG);
if(ret != RET_OK)
{……};
break;
Case IP6_DHCP6_STATELESS_ADDR_CONFIG:
ret=OsNetStartDhcp6(NET_LINK_ETH,IP6_DHCP6_ST
ATELESS_ADDR_CONFIG);
if(ret != RET_OK)
{……};
break;
}
}
……

20.5.5 OsNetStartDhcp6

int OsNetStartDhcp6(int NetLink,

Prototype
int state);
Start DHCPv6 function to get the dynamically assigned IPv6 address and
Function DNS address.
NetLink Physical channel:
 NET_LINK_ETH: Ethernet.
state IP6_DHCP6_STATEFULL_ADDR_CONFIG:
Parameters
[Input] DHCPv6 stateful address configuration.
IP6_DHCP6_STATELESS_ADDR_CONFIG:
DHCPv6 stateless address configuration.
RET_OK Succeeded.
NET_DOING Repetitive execution.
ERR_NET_IF The link cannot be used (not established or
Return disconnected).
ERR_INVALID_PARAM Invalid parameter (AddrInfo is NULL).

1. DHCPv6 stateful address configuration mode can get the IPv6

address and DNS information.
Instruction 2. DHCPv6 stateless address mode can only get DNS information.
3. OsNetGetRouteAdvertise6() shall be called first to select the type of
DHCPv6.

20.5.6 OsNetCheckDhcp6

Prototype int OsNetCheckDhcp6(int NetLink);

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

 Prolin API Programming Guide

Function Get the current working status of DHCPv6.

NetLink Physical channel:
Parameters
 NET_LINK_ETH: Ethernet.
RET_OK Succeeded.
ERR_NET_IF The link cannot be used (not established
properly or disconnected)
NET_DOING In process of assigning IPv6 and DNS
address.
ERR_NET_DHCP_START OsNetStartDhcp6() is not executed.
ERR_NET_DHCP6_SOLI DHCPv6 server has no respon
CITE
Return ERR_NET_DHCP6_REQ DHCPv6 server has not responded correctly
UEST to REQUEST command.
ERR_NET_DHCP6_INFO DHCPv6 server has not responded correctly
RMATION to INFORMATION REQUEST command.
ERR_NET_DHCP6_VALI Only DHCPv6 stateful mode can be
D_LIFE returned: the valid life time has been
expired, and the IPv6 address, for which
previously applied has been released.
ERR_NET_DHCP6_NOA DHCPv6 server has no available address to
DDRSAVAIL assign.
1. DHCPv6 stateful mode can get the IPv6 and DNS address.
Instruction
2. DHCPv6 stateless working mode can only get DNS address.

20.5.7 OsNetStopDhcp6

Prototype int OsNetStopDhcp6(int NetLink);

Function Stop DHCPv6 server from running.

NetLink Physical channel:
Parameters
 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 not be
Instruction renewed, and address will be invalid after restarting.

20.5.8 OsNetSetRouteTable6

int OsNetSetRouteTable6(int NetLink,

const char *DestAddr,
Prototype
int DestAddrPrefixLength,
const char *NextHop);
Function Set IPv6 static routing table

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

 Prolin API Programming Guide

NetLink Physical link:

 NET_LINK_ETH Ethernet
DestAddr[Input] Destination address:
E.g. : “2001:20::”; “::”.
Parameters DestAddrPrefixLengt The length of prefix destination address, ranging
h from 0 to 128.
[Input]
NextHop[Input] Gateway address:
E.g.: “fe80:9::23”; “::”.
RET_OK Succeeded
ERR_NET_IF The link is not established or is
Return disconnected.
ERR_INVALID_PARAM Invalid parameter
For example:
int ret;
ret=OsNetSetRouteTable6(NET_LINK_ETH,"2016::",128,"fe80:99::
Instruction 99");
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.

20.5.9 OsNetGetRouteTable6

int OsNetGetRouteTable6(int NetLink,

Prototype struct IPv6RouteTable
*RoutingTable);
Function Get the information of specified routing table.
NetLink Physical link:
Parameters  NET_LINK_ETH Ethernet
RoutingTable[Output] IPv6RouteTable structure
RET_OK Succeeded
ERR_NET_IF The link is not established or is
Return disconnected.
ERR_INVALID_PARAM Invalid parameter
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. 243

 Prolin API Programming Guide

21 GPRS/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. 244

 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

21.2.1 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.

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

 Prolin API Programming Guide

1. This function must be called to open the wireless module

first before calling OsWlInit(), OsWlPowerSwitch(),
OsWlLogin() or OsWlLogout().
2. OsWlUnLock() shall be called to close wireless module after
finishing the operation.
Instruction 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.

21.2.2 OsWlUnLock

Prototype void OsWlUnLock(void);

Release the usage rights of wireless device and disconnect from
Function Prolin wireless service.
Parameters None.
Return None.
Instruction

21.2.3 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.
Return ERR_WL_NEEDPIN SIM card needs PIN.
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.

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

 Prolin API Programming Guide

ERR_WL_NOSIM No SIM card.

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.

21.2.4 OsWlInitEx

intOsWlInitEx(constchar*SimPin,
intTimeOutMs,
Prototype char*CmeString,
int Size);

Function Initialize wireless device.

SimPin[Input] A pointer to SIM card PIN.
The valid string length is less than 50
bytes.
It can be NULL, which means it doesn’t need
any password.
TimeOutMs[Input] Timed out time,[unit:ms];
Parameters Valid range is from 25000 to 100000;
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_READ GPRS and CSD dialup service are ready.
Y

Return ERR_DEV_NOT_OPEN Device/ module is not open.

ERR_DEV_NOT_EXIST Wireless device/ module does not exist.
ERR_NO_PORT There’s no physics serial port for terminal.
ERR_WL_NEEDPIN SIM card needs PIN.

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

 Prolin API Programming Guide

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 PIN error.
ERR_WL_NOSIM There’s no SIM card.
ERR_WL_PPP_ONLINE PPP online.
ERR_WL_NOREG Could not register to the network.
ERR_INVALID_PARAM Invalid parameter.
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 by unstable module;
Instruction 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.

21.2.5 OsWlSwitchPower

Prototype int OsWlSwitchPower(int OnOff);

Function Power on /off wireless module.
The state of wireless device:
Parameters OnOff[Input]  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().
Instruction 2. Unless it is a special occasion, it is not recommended to call
this function. Because after calling this function to power off
the wirelss module,the wireless network needs to be

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

 Prolin API Programming Guide

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.

21.2.6 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.
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.

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

 Prolin API Programming Guide

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.

21.2.7 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. For Prolin2.8 and Prolin2.9 systems, the signal values are
directly obtained from the module through AT instructions no
matter whether wireless links are established or not;
3. For Prolin2.4, Prolin2.5, Prolin2.6, Prolin2.7 and Prolin2.10
systems, the signal value is directly obtained from the
module through AT instructions when no wireless link is
Instruction established;
After calling OsWlLogin () to establish a wireless link, the
module is in the data exchange mode and cannot obtain
real-time signals. Calling OsWlGetSignal() at this time will
obtain a signal value , which is cached at the beginning of
OsWlLogin;
4. This function shall not be called until OsWlInit() returns
RET_OK.

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

 Prolin API Programming Guide

21.2.8 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

21.2.9 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.
APN[Input] The valid length is from 0 to 50 characters.
Parameters When it is NULL, the protocol stack will
directly login PPP after the application dialing
up.
Name[Input] User name.

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

 Prolin API Programming Guide

The valid string length ranges from 0 to 50

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.
If timeout <0, it will be automatically set to 0.

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

 Prolin API Programming Guide

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.
RET_OK The link is established 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 network
environment. In general, if the login duration is over 60
Instruction 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.
7. When the return value is PPP_LOGOUTING, OsWlCheck()
can be called to check the logout status. The system has

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

 Prolin API Programming Guide

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. .

21.2.10 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.
User name.
Parameters 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.

Auth Authentication algorithm.

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

 Prolin API Programming Guide

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
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.
ReserParam Reserved parameter, used for extension.

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

 Prolin API Programming Guide

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.

21.2.11 OsWlLogout

Prototype int OsWlLogout(void);

Function Log out wireless network and disconnect wireless link.
Parameters None

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

 Prolin API Programming Guide

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

21.3.1 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. 257

 Prolin API Programming Guide

22 WiFi

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. 258

 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. 259

 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. 260

 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. 261

 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. 262

 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 the

Aps[Output]
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. 263

 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 when

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

 Prolin API Programming Guide

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. 265

 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. 266

 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. 267

 Prolin API Programming Guide

WpsPin [Input/Output] 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 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_SUPPORT WiFi module is not supported by
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. 268

 Prolin API Programming Guide

23 GPS

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. 269

 Prolin API Programming Guide

23.3 OsGpsOpen

int OsGpsOpen(int Mode,

Prototype const char *Attr);

Function Open and initialize GPS module.

Mode Positioning mode:
GPS_MODE: normal GPS positioning mode.
AGPS_MODE: AGPS positioning mode.

Parameters Attr[Input] Positioning parameter.

When Mode is GPS_MODE, Attr will be
ignored.
When Mode is AGPS_MODE, it needs to
pass in AGPS server address.
RET_OK Succeeded.
ERR_DEV_NOT_EXIST Device does not exist.
ERR_INVALID_PARAM Invalid parameter.

Return ERR_SYS_NOT_SUPP System does not support.

ORT
ERR_DEV_NOT_OPEN GPS module is not open.
ERR_GPS_POWER_O GPS module is being powered on.
NING
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.

Parameters Location GPS location structure, GPS_LOCATION.

GPS_NAVIGATING GPS is navigating.
RET_OK Succeeded.
Return ERR_INVALID_PARAM Invalid parameter.
ERR_DEV_NOT_EXIST Device does not exist.
ERR_DEV_NOT_OPEN GPS module is not open.
1. Only when RET_OK is returned, can GPS location
Instruction information be read correctly.

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

 Prolin API Programming Guide

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.
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. 271

 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. 272

 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

24.3.1 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_ABSEN Base is absent.
T
Return ERR_SYS_NOT_SU System does not support this function.
PPORT
ERR_TIME_OUT Timeout
ERR_SYS_BAD System error
This function only applies to handsets connected to the base via USB or
Instruction serial ports.

24.3.2 OsBaseOpen

Prototype int OsBaseOpen(void);

Function Open the communication mode on the handset.

Parameters None

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

 Prolin API Programming Guide

RET_OK Succeeded
ERR_SYS_NOT_SUPPOR System does not support this function.
T
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
Others Return values of the Bluetooth 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.

24.3.3 OsBaseCheck

Prototype int OsBaseCheck(void);

Function Check the base state.

Parameters None
BASE_STATE_CONNECT Bluetooth is connected but base is not
ED open.
BASE_STATE_CONNECTI Connecting
NG
RET_OK Base is open.
ERR_DEV_NOT_OPEN Base is not open.
Return ERR_SYS_NOT_SUPPOR System does not support this function.
T
ERR_SYS_BAD System error.
ERR_TIME_OUT Timeout
ERR_NOT_CONNECT Bluetooth has not connected.
Others Return values of the Bluetooth module
Call this function in the Bluetooth base, the Bluetooth connecting state
and base state will be returned.
Enumeration as follow:
Instruction enum {
BASE_STATE_OPENED = 0, /* Base is open */
BASE_STATE_CONNECTING, /* Connecting*/

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

 Prolin API Programming Guide

BASE_STATE_CONNECTED, /* Bluetooth is connected but

base is not open. */
};

24.3.4 OsBaseClose

Prototype int OsBaseClose(void);

Function Close the communication mode on the handset.

Parameters None
RET_OK Succeeded
Return ERR_SYS_NOT_SUPP System does not support this function.
ORT
Instruction

24.3.5 OsBaseScan

int OsBaseScan(ST_HandsetLinkInfo *links,

Prototype int n,
int timeout);

Function Scan the Bluetooth base information.

links Address of the incoming base information
structure

Parameters n Number of the incoming structure arrays, the

maximum value is 32.
timeout Timeout period, [unit: second]
>=0 The number of the scanned base information.
0 indicates no base has been scanned.
ERR_SYS_NOT_SUPP System does not support this function.
ORT
ERR_SYS_BAD System error
ERR_TIME_OUT Timeout
Return
ERR_INVALID_PARAM Invalid parameter.
ERR_MEM_FAULT Memory application failed.
ERR_DEV_BUSY Device is busy.
ERR_LIB_NOT_FOUND Bluetooth library cannot be found.
Others Return values of the Bluetooth module

Instruction

Sample code

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

 Prolin API Programming Guide

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.

24.3.6 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.
BASE_STATE_CONNE Connecting
CTING
ERR_SYS_NOT_SUPP System does not support this function.
ORT
ERR_SYS_BAD System error
Return
ERR_TIME_OUT Timeout
ERR_INVALID_PARAM Invalid parameter.
ERR_DEV_BUSY Device is busy.
ERR_LIB_NOT_FOUND Bluetooth library cannot be found.
Others Return values of the Bluetooth module
This function is non-blocking. When BASE_STATE_CONNECTING is
Instruction returned, application can check the connecting state by calling
OsBaseCheck().

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

 Prolin API Programming Guide

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.

24.3.7 OsBaseDisconnect

Prototype int OsBaseDisconnect(void);

Function Disconnect the Bluetooth base connection.

Parameters None
RET_OK Succeeded.
ERR_SYS_NOT_SUPP System does not support this function.
ORT
Return ERR_SYS_BAD System error
ERR_TIME_OUT Timeout
ERR_DEV_BUSY Device is busy.
Instruction Only the process which has opened the base can close the base.

24.3.8 OsCheckPortStatus

Prototype int OsCheckPortStatus(int Channel);

Function Check if a physical connection exists at the specified communication port.

Channel[Input] PORT_BASE_DEV: usbdev module of
base
PORT_BASE_ETH0: Ethernet module of
Parameters base
PORT_BASE_WLAN0: WIFI module of
base

Return RET_OK Succeeded.

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

 Prolin API Programming Guide

ERR_NOT_CONNECT It is not connected.

ERR_INVALID_PARAM Invalid parameter
ERR_SYS_NOT_SUPPORT System does not support this 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.

24.3.9 OsGetBaseInfo

int OsGetBaseInfo(const char *Key,

Prototype
char *Value);
Function Get the contents of the registry key specified by the base.
Key [Input] Registry key name, ending with“\0”.
Value [Output] Registry key value.
Parameters
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 registry key, refer to Appendix
3 Registry.
3. Additional system configurations supported by the base are
as follows:
Instruction System configuration name Description
Whether there is a number
ro.fac.digital_io IO(None means it does not
exist by default.)
Whether com1 port that
ro.fac.com1 corresponds to
PORT_BASE_A port exists,

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

 Prolin API Programming Guide

(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.)

24.3.10 OsBaseCmd

int OsBaseCmd(int cmd,

Prototype void *inparm,
void *outparm);
Function Send commands to base.
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. 279

 Prolin API Programming Guide

25 File System

Prolin file system adopts standard ANSI.C file operation API.

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

 Prolin API Programming Guide

26 System 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)
{
int ret, signo;

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

 Prolin API Programming Guide

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. 282

 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. 283

 Prolin API Programming Guide

27 Audio

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.

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

 Prolin API Programming Guide

ERR_DEV_NOT_EXI
Device does not exist.
ST
Return
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.
Return RET_OK Succeseded.

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

 Prolin API Programming Guide

ERR_ACCESS_DENY Access denied.

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 to
Instruction 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. 286

 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. 287

 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；

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

 Prolin API Programming Guide

c) If DurationMs=0, the actual length of the audio data will

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.

Return ERR_SYS_BAD System error.

ERR_DEV_NOT_OP
Audio device is not open.
EN

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

 Prolin API Programming Guide

ERR_SYS_NOT_SU
System does not support this feature.
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;

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

 Prolin API Programming Guide

fd = open(FILENAME, O_RDONLY);
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. 291

 Prolin API Programming Guide

28 Barcode 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. 292

 Prolin API Programming Guide

28.2 Data Definition

28.2.1 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 the back supplementary
OPEN_BACK_ADDBRILAMP 10
light.
Close the back supplementary
CLOSE_BACK_ADDBRILAMP 11
light.
OPEN_BACK_POSITIONLAMP 12 Open the back positioning light.
CLOSE_BACK_POSITIONLAMP 13 Close the back positioning light.
Open the front supplementary
OPEN_FRONT_ADDBRILAMP 20
light.
Close the front supplementary
CLOSE_FRONT_ADDBRILAMP 21
light.
Open the front positioning
OPEN_FRONT_POSITIONLAMP 22
light.
Close the front positioning
CLOSE_FRONT_POSITIONLAMP 23
light.
OPEN_SCAN_LEDLIGHT 24 Open the scanning LED
CLOSE_SCAN_LEDLIGHT 25 Close the scanning LED

28.2.2 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. 293

 Prolin API Programming Guide

28.2.3 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.

28.2.4 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;

28.2.5 Return Code List

Table 28.4 Return code list

Macro Value Description

ERR_BAR_CAMER_INIT_FAILE Failed to initialize camera.
-3601
D
ERR_BAR_DECODE_INIT_FAIL Failed to initialize the
-3602
ED decoding library
ERR_BAR_SRECODE_INIT_FAI Failed to initialize srcode.
-3603
LED
ERR_BAR_NOT_ENOUGH_BU Output buffer is not enough.
-3604
FFER

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

 Prolin API Programming Guide

ERR_BAR_READ_CAMERA_B Failed to read the data in

-3605
UFFE_FAILED camera buffer.
ERR_BAR_DECODE_FAILED -3606 Failed to decode.
ERR_BAR_CAMER_STREAMO Camera failed to turn on
-3607
N_FAILED cellular data
ERR_BAR_CAMER_STREAMO Camera failed to turn off
-3608
FF_FAILED cellular data
ERR_BAR_CAMER_FRAME_F Failed to get camera frame
-3609
AILED data
ERR_BAR_CAMER_SETPARA Camera failed to set
-3610
M_FAILED parameters

28.3 Basic Interface

28.3.1 OsScanSetParam

Prototype int OsScanSetParam(unsigned int Param);

Open/Close the supplementary light, positioning light or scanning LED
Function of camera.
Param  OPEN_BACK_ADDBRILAMP: Open the back
[Input] 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.
Parameters  CLOSE_FRONT_ADDBRILAMP: Close the front
supplementary light.
 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_PARA Invalid parameter.
Return M
ERR_DEV_NOT_O Device is not open.
PEN

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

 Prolin API Programming Guide

1. QR55 has front supplementary light; D190/D195/D220/Q92 hs back

supplementary light; IM10/IM20 has scanning LED.
2. This function should be called after OsScanOpen() succeeds.
Instruction
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.

28.3.2 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.

28.3.3 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.
Parameters Len[Input] Buffer length.
Timeout of barcode reading.[unit:ms]
TimeoutMs[Inpu The valid timeout value ranges from 1500ms
t] to 36000ms. Any timeout value that is less
than 1500ms will be set to 1500ms; while
more than 36000ms, it will be set to 36000ms.

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

 Prolin API Programming Guide

There may be an error less than 1 second

between the actual timeout and the set value.
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

28.3.4 OsScanClose

Prototype void OsScanClose(void);

Function Close scanning device.
Parameters None.

Return None.
Instruction

28.3.5 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 same
Instruction camera device, if this function is called after OsScanOpen (),
ERR_DEV_BUSY will be returned, and vice versa.

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

 Prolin API Programming Guide

28.3.6 OsCameraClose

Prototype void OsCameraClose(void);

Function Close camera device.
Parameters None.

Return None.
Instruction

28.3.7 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

28.3.8 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
Instruction CameraAttribute structure. For example, the value of
CurrentResolution must be supported by camera. Before setting
camera parameter, it is recommended to call

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

 Prolin API Programming Guide

OsCameraGetParam() to obtain all the resolution types

supported by system.

28.3.9 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
Instruction 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
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:

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

 Prolin API Programming Guide

unsigned short tmp_pixel = ((unsigned short)Buf[0] << 8) |

Buf[1];
r = (tmp_pixel >> 8) & 0xF8;
g = (tmp_pixel >> 3) & 0xFC;
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++;

28.3.10 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.
Parameters DataIn[Input] Image data.

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

 Prolin API Programming Guide

DataInLen[Input] Length of the image data.

The buffer used to store barcode
data. For one-dimensional code, the
buffer size is recommended to be
DataOut[Output] 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”.

28.3.11 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
Parameters threshold[Input] frames captured by the camera is not
less than the value of this parameter,
the function returns the actual
difference.

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

 Prolin API Programming Guide

The interval between images

interval[Input] captured by the camera. [unit:
milliseconds]
Interface blocking timeout in
seconds. The interface will return
ERR_TIME_OUT if the interface
timeout[Input]
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. 302

 Prolin API Programming Guide

29 Power 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_COMPLETE 6 Battery is fully charged.
BATTERY_LEVEL_ABSENT 7 Battery is absent.

29.2 Data Structure

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

 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;

WAKEUP_SOURCE: the wakeup source

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

 Prolin API Programming Guide

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
automatically power off.
Return BATTERY_LEVEL_1 5%~15%
BATTERY_LEVEL_2 15%~40%
BATTERY_LEVEL_3 40%~70%
BATTERY_LEVEL_4 70%~100%
BATTERY_LEVEL_CHA Battery is being charged.
RGE

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

 Prolin API Programming Guide

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 checking
ERR_SYS_NOT_SUPPO
battery level. Only terminal without
RT
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.

29.5 OsSysSleep

Prototype int OsSysSleep(void);

Function Get the terminal to enter sleep mode.

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

 Prolin API Programming Guide

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.

29.6 OsSysSleepEx

Prototype int OsSysSleepEx(int Level);

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

 Prolin API Programming Guide

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
Parameters Level[Input] up by plastic button and application
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
support the Lever=2 sleep mode.

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

 Prolin API Programming Guide

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, it
Parameter Time[Input] 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.

This function works in blocking mode. If this function is
Instruction executed successfully, the terminal will reboot directly without
any return value.

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

 Prolin API Programming Guide

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 management
events can be sent to the application process. And
OsPmGetEvent() can be called to get event directly when the

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

 Prolin API Programming Guide

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

ReqType[input] The corresponding meanings of specified
events please refer to PM_REQ_T structure.
For example：
Parameters 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
source.
>=0 Please refer to the enumeration
structure WAKEUP_SOURCE for the
Return
corresponding wakeup source of each
value.
ERR_SYS_NOT_SU The system does not support.
PPORT

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

 Prolin API Programming Guide

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
may not be able to detect all the abnormal types in the above
list.
Instruction Model Exception type that support detection
S920 V20: Bit0-Bit5
S920
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

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

 Prolin API Programming Guide

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. 313

 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. 314

 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. 315

 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. 316

 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. 317

 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. 318

 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. 319

 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.
ro.fac.hwver Hardware version number. Main board- interface 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.
ro.fac.prolin_debug_le Prolin_debug_level information, this value is 0 and 1 for
vel release system and debug system, respectively.
Whether there is a network cable port.(0: does not exist;
ro.fac.eth
1: exist)
Whether there is a main device interface.(0: does not
ro.fac.usb.host
exist; 1: exist)
Whether there is an USB device interface.(0: does not
ro.fac.usb.device
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 exist; 1:
ro.fac.leddt
exist)
Key types.(0: have no key; 1: physical button; 2: touch-
ro.fac.keybroad
screen button)
Whether there is a Buzzer module.(0: does not exist; 1:
ro.fac.buzzer
exist)
ro.fac.simsocket The number of SIM card slot.
ro.fac.battery Whether there is a battery.(0: does not exist; 1: exist)
ro.fac.coulomb_count Whether there is a coulombmeter. (None means it does
er not exist by default.)
Name of WiFi module.(None means it does not exist by
ro.fac.wifi
default.)

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

 Prolin API Programming Guide

Name of Bluetooth module.(None means it does not exist

ro.fac.bt
by default.)
Wireless module information and parameter information
ro.fac.radio (optional). Used for multiple wireless modules;
separated. (None means it does not exist by default.)
Name of Modem module. (None means it does not exist
ro.fac.modem
by default.)
Name of Printer module. (None means it does not exist
ro.fac.printer
by default.)
Name of PCD module. (None means it does not exist by
ro.fac.pcd
default.)
Name of IC card reader. (None means it does not exist
ro.fac.sci
by default.)
Name of MSR reader. (None means it does not exist by
ro.fac.msr
default.)
Name of LCD module. (None means it does not exist by
ro.fac.videocard
default.)
Name of audio card module. (None means it does not
ro.fac.audiocard
exist by default.)
Name of Touch-screen module. (None means it does not
ro.fac.touchscreen
exist by default.)
Supported specification, capacity range and speed level
ro.fac.sdhc
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
Name of cipher chip (Used for camera scanning code.)
_chip
Name of SM ciper chip(None means it does not exist by
ro.fac.cipher_chip
default.)
PCD antenna parameter 1. (None means PCD does not
ro.fac.pcd.param1
exist.)
PCD antenna parameter 2. (None means PCD does not
ro.fac.pcd.param2
exist.)
PCD antenna parameter 3. (None means PCD does not
ro.fac.pcd.param3
exist.)
ro.fac.lcd.rotate LCD clockwise rotation degrees. (0,90,180, 270)

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

 Prolin API Programming Guide

Security level, the value can be 1 or 2. When updating

ro.fac.security_level firmware, the security level of the new 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
ro.fac.security_mode production; 1 represents factory state, it indicates non-
authorization scheme; 2 represents security state, it
indicates authorization scheme.
Version information of PCI. (This information is available
ro.security_version
for models certified by PCI)
persist.sys.eth0.dhcp DHCP is open or not. (true: open; false or none: closed)
persist.sys.eth0.ip Ethernet ip address.
persist.sys.eth0.mask Ethernet subnet mask.
persist.sys.eth0.gatew
Ethernet gateway.
ay
Ethernet network port speed.(eth_auto: automatic
configuration; eth_10mhd: 10M half-duplex; eth_10mfd:
persist.sys.eth0.speed
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
persist.sys.backlightti
time is not more than 30 sec; it is the set value if more
me
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 to
persist.sys.sleeptime
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 the
system enters sleep mode. (The value range is from 0 to
persist.sys.sleepwaitti
15s, the default value is 1, which means the user is
me
notified that system will sleep and is given 1 second to
handle events before system goes to sleep.)
After long pressing the power key or OsReboot() is
persist.sys.delayshutd called, the system will power off after
own persist.sys.delayshutdown seconds. (The
persist.sys.delayshutdown value ranges from 0~600

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

 Prolin API Programming Guide

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 cancel the shutdown. Setting it to
persist.sys.confirmsh 0 means the terminal will power off immediately after
utdown 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.
persist.sys.sound.ena Whether to open the keypad tone. (False means closed;
ble true means open) The setting will take effect after reboot.
The status of current key tone (0 means off; 1 means
rt.app.key.tone open. It is not recommended to modify the keyword. Only
prolin-peng-2.8 supports this keyword)
The duty cycle of PWM (valid range is from 1 to 99). It is
persist.sys.keypad.dut
used to adjust the buzzer volume when pressing the
y_cycle
button, and the setting will take effect after reboot.
persist.sys.key.backli Whether the button backlight is open or not. (0 means
ght closed; 1 means open)
The status of current key backlight (0 means off; 1 means
rt.app.key.backlight open. It is not recommended to modify the keyword. Only
prolin-peng-2.8 supports this keyword)
persist.sys.lcd.brightn LCD brightness. (The valid brightness ranges from 1 to
ess 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 the same
persist.sys.lcdsaverbri
as calling OsScrBrightness.This variable only applies to
ghtness
auto-screensaver and OsSysSleepEx(1), and it will take
effect immediately after setting this value. )
persist.sys.sound.volu Audio/video sound volume. (The valid volume ranges
me from 0 to 4.)
persist.sys.auto.moun
Mount u disk or sd card automatically or not.
t.enable
persist.sys.xcb.enable Open or close XCB service.（0: close; 1: open）
Network port number of XCB service. (It is the network
persist.sys.xcb.tcp.po
port number when using network; it is -1 when using
rt
other ways.)
USB or COM of XCB service. (When using USB, it is
persist.sys.xcb.rs232 /dev/ttydev; when using COM port, it is /dev/ttyAMA* (*
means the represented value, refer to

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

 Prolin API Programming Guide

[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.autowaketi If the autowaketime is set to be greater than 0 and less
me 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.en
Open/close console (0: close, 1: open)
able
Enable or disable the function of DHCP when the
persist.sys.wifi.roam.d
terminal is in roaming state. (0: disable, 1: enable) and it
hcp
is enabled by default.
persist.sys.tm.imei The IMEI value of wireless module
Set time zone. For tz values of various regions, please
persist.sys.timezone.t refer to standard Linux tz value. For more information on
z how to set time zone, please refer to “Prolin Application
Development Manual”
persist.sys.continue.p Enable/disable the function of continuing to print after a
rint shutdown. (0: disable, 1:enable )
Enable/disable USB flash driver auto-downloading
persist.sys.autouload.
function at the POS terminal startup.( 0: disable,
enable
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 name-
persist.sys.hostname
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.)
persist.sys.wnet.versi
Acquire wireless module firmware version information.
on

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

 Prolin API Programming Guide

Enable/disable the function of starting the terminal

automatically when terminal is being charged. (0:
persist.sys.autostartu
disable, 1:enable, and the default startup method will be
p.enable
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 also be
persist.sys.enable.deb
enabled, and after entering the application, XCB service
ug
will restore to the original status which is before POS
entering TM.
Whether to restart the application automatically after
persist.sys.mainapp.re MAINAPP abnormally crashes. (1 represents Yes, and
start the application can be restarted 10 times at most; 0
represents No)
Whether to restart the main application automatically
rt.sys.mainapp.restart
after a normal exit. (1 represents Yes; 0 represents No)
When inputting PIN, mask the specified keys on soft
persist.sys.ped.keypa keypad, and this function has no effect on physical key.
d.mask Currently, it only supports passing “cancel” into 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 be
used;
 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);
 when it is set to “2”, the 1PIN keypad customized for
D220 will be used;
persist.sys.ped.keypa  When it is set to “3”, the 2PIN keypad customized for
d.type 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. Record the times of auto shutdown caused by low
offcnt battery.

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

 Prolin API Programming Guide

persist.sys.reboot.cnt Record the times of calling OsReboot().

persist.sys.powerkey. Record the times of shutdown by long pressing on the
offcnt 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 set to “1”, OS will
persist.sys.dns.static
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 set to
persist.sys.xcb.install “1”, the function of installing AIP/AUP through XCB is
app.lock 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
persist.sys.ped.pin.ico
OsPedSetPinIconLayout() will be centered and
n.align
displayed dynamically, and the 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 after
restart.
 When it is set to “1”, the POSVCOM single 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;
persist.sys.usbd.mode  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;

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

 Prolin API Programming Guide

 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
persist.sys.ped.reboot function of restarting the terminal regularly will be
.cycle disabled at this 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 cancel
persist.sys.ped.pinwai key to exit the pin waiting interface is allowed.
t.retain  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 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 ")
persist.sys.tm.pwd The password ciphertext to enter the TM menu of
"System Configuration". For detailed instructions, please
refer to the section "Change TM Password over
Application Layer" in Prolin Application Development
Manual.
persist.sys.switch.tm. Whether to enter the TM interface by pressing the key.
app  When it is set to “1”, you cannot enter the TM
interface by pressing any key.
 When it is set to “0”, the interface between TM and
USER APP can be switched.

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

 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 direction

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

 Prolin API Programming Guide

se e e

directio direction direction

Keyboard √ √ √ √ √ √ √ NA

Touch √ NA √ √ NA √ √ √

Screen

Signature √ NA √ √ NA √ √ √

Pad

Printer NA √ √ √ NA NA √ NA

Font √ √ √ √ √ √ √ √

Library

Code √ √ √ √ √ √ √ √

MSR √ √ √ √ √ √ √ √

IC Card √ √ √ √ √ √ √ √

Reader

RF √ √ √ √ √ √ √ √

Reader

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

 Prolin API Programming Guide

Communi PORT PORT_ PORT_ PORT_U PORT PORT_C PORT PORT

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

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

 Prolin API Programming Guide

GPRS/CD N/A √ √ √ N/A √ √ √

MA
(optional)

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. 331