Cover

1

Synway Voice Board

Programmer's Manual

Version 5.3.1.2

Synway Information Engineering Co., Ltd

www.synway.net


Contents

Contents. i

Copyright Declaration. xliii

SynCTI Driver Software License Agreement xliv

Revision History. xlv

Preface. xlvii

1 Basic Knowledge on Synway Board Programming. 1

1.1 Board Classification (CTI Series) 1

1.2 Board Classification (REC Series) 3

1.3 SynCTI Supported CODECs. 4

1.3.1 Transcoding Functions. 4

1.3.2 Board Supported CODECs. 5

1.4 SynCTI Supported OS. 8

1.5 SynCTI Driver Architecture (CTI Series) 8

1.6 SynCTI Driver Architecture (REC Series) 10

1.7 Software Tool for SynCTI 11

1.7.1 System Configuration Tool - ShCtiConfig.exe. 11

1.7.2 Tone Analyzer Tool - ShTA.exe. 11

1.7.3 SS7 Server Configuration Program - SS7Cfg.exe. 12

1.7.4 SS7 Server - SS7monitor.exe. 12

1.7.5 MSU Decoder Tool - MsuDecode.exe. 12

1.8 Basic Concepts. 12

1.8.1 Channel (CTI Series) 12

1.8.2 Channel (REC Series) 12

1.8.3 Logical Channel Number 13

1.8.4 Digital Trunk. 13

1.8.4.1 Frame Synchronization over Digital Trunk. 14

1.8.4.2 Clock for Digital Trunk. 14

1.8.4.3 Digital Trunk Configuration. 14

1.8.4.4 Signaling Time Slot on Digital Trunk. 14

1.8.4.5 Digital Trunk Number 14

1.8.4.6 Setting Voice CODEC on B-Channel 15

1.8.5 User Authorization Code for Board. 15

1.8.6 Change in Analog Phone Line Voltage. 15

1.8.7 Ringing Current on Analog Phone Line. 18

1.8.8 Flash Signal on Analog Phone Line. 18

1.8.9 Caller ID on Analog Phone Line. 18

1.9 System Clock Configuration. 19

1.10 Voice Processing. 20

1.10.1 Voice Playing (CTI Series) 20

1.10.1.1 Setting Volume and Direction. 21

1.10.1.1.1 CTI Series. 21

1.10.1.1.2 REC Series. 21

1.10.1.2 Setting Termination Condition. 21

1.10.1.3 Preload File Mode. 22

1.10.1.4 Single File Mode. 23

1.10.1.5 File List Mode. 23

1.10.1.6 Single Buffer Mode. 24

1.10.1.7 Buffer List Mode. 24

1.10.1.8 Pingpong Buffer Mode. 24

1.10.1.9 Common Termination Function. 25

1.10.1.10 Acquiring Information on Voice Playing. 25

1.10.2 Voice Recording. 25

1.10.2.1 Setting Recording Signal Source. 25

1.10.2.2 Setting Termination Condition. 25

1.10.2.3 Setting Prerecord Feature. 26

1.10.2.4 Setting Tail-Truncation Feature. 26

1.10.2.5 Setting AGC Feature. 26

1.10.2.6 Acquiring Information on Voice Recording. 27

1.10.2.7 Brief Introduction of Recording Functions. 28

1.10.2.7.1 File Mode. 28

1.10.2.7.2 Buffer Mode. 28

1.10.2.7.3 Pingpong Buffer Mode. 28

1.10.3 DTMF Detector 29

1.10.3.1 DTMF Filter 30

1.10.3.2 DTMF Pulse-width Filter 31

1.10.3.3 WaitDtmf 31

1.10.3.4 Callback Programming. 32

1.10.3.5 Dial Pulse Detection. 32

1.10.4 DTMF Generator (CTI Series) 32

1.10.5 Tone Detector 33

1.10.5.1 FFT. 35

1.10.5.2 Noise Filter 36

1.10.5.3 Call Progress Tone Detector (SHT Series Only) 36

1.10.5.3.1 Dial Tone Detector 38

1.10.5.3.2 Ringback Tone Detector 39

1.10.5.3.3 Busy Tone Detector 39

1.10.5.3.3.1 General Features. 39

1.10.5.3.3.2 Back-to-back Busy Tone Detection. 40

1.10.5.3.4 User-defined Tone Detector 41

1.10.5.4 Fax Progress Tone Detector (CTI Series) 42

1.10.5.5 Simplified Busy Tone Detector 42

1.10.5.6 AMD (Answering Machine Detector) 44

1.10.5.7 Enhanced Tone Detector 44

1.10.6 Tone Generator (CTI Series) 46

1.10.6.1 Configuring Tone Generator 47

1.10.6.2 Tone Generation. 47

1.10.7 Echo Canceller (CTI Series) 47

1.10.8 Barge-in Detector 48

1.10.9 TDM Capability. 49

1.10.10 Distributed Teleconferencing System (CTI Series) 51

1.10.10.1 Basic Concepts. 51

1.10.10.2 Managing Conference Room.. 53

1.10.10.3 Managing Conference Channel 53

1.10.10.4 Playing Background Music to Conference Room.. 53

1.10.10.5 Recording Voice in Conference Room.. 54

1.11 FSK Transceiver (CTI Series) 54

1.11.1 FSK Transmitter 55

1.11.2 FSK Receiver 55

1.12 Fax (CTI Series) 55

1.12.1 Setting Number of Fax Channels. 55

1.12.2 Supported Fax Rate. 57

1.12.3 Supported Fax File Format 57

1.12.4 Setting Faxing Parameters. 58

1.12.5 Acquiring Information on Faxing. 58

1.12.6 Fax Transmission. 58

1.12.7 Fax Reception. 59

1.13 On-board Audio Power Amplifier 59

1.14 Application Programming Based on Synway Board. 60

1.14.1 Setting Event Output Mode. 60

1.14.1.1 Programming Example in Event Polling Mode. 61

1.14.1.2 Programming Example in Event Callback Mode. 62

1.14.2 Data Structure of Output Event 64

1.14.2.1 MESSAGE_INFO.. 64

1.14.2.2 SSM_EVENT. 71

1.14.3 Event Filter 73

1.14.4 Self-defined Event 73

1.14.5 SynCTI Programming Guide. 73

1.14.5.1 MS VC/C++. 73

1.14.5.2 VB. 73

1.14.5.3 C++ BUILDER.. 75

1.14.5.4 Delphi 75

1.14.5.5 PB6.5. 75

1.14.5.6 Other Programming Environments. 76

1.14.5.7 Linux. 76

1.14.5.8 Use of Character String. 76

1.14.6 Demo Program (CTI Series) 77

1.14.7 Demo Program (REC Series) 77

1.14.8 Driver-provided Timer 78

1.14.9 Driver-provided Debugging Feature. 78

1.15 SHT Series (CTI Series) 79

1.15.1 Brief Introduction of SHT Series. 79

1.15.2 Operation Principle of SHT Series. 80

1.15.3 Analog Trunk Channel 82

1.15.3.1 Generating Flash Signal on Analog Line. 82

1.15.3.2 Detecting Polarity Reversal Signal 82

1.15.3.3 Analog Trunk Channel State Machine. 83

1.15.3.4 Remote Pickup Detector (SHT Series Only) 86

1.15.3.4.1 Ordinary Remote Pickup Detector 87

1.15.3.4.2 Enhanced Remote Pickup Detector 89

1.15.4 Station Channel 90

1.15.4.1 State Machine. 90

1.15.4.2 Pickup/hangup Detection. 90

1.15.4.3 Flash Signal Detection. 91

1.15.4.4 Sending Ringing Signals to Phone. 91

1.15.4.5 Generating Polarity Reversal Signal on Phone Line. 91

1.15.4.6 Auto-transmission of Dial Tones upon Pickup Detected. 92

1.15.5 Composite Module. 92

1.15.6 Magnet Channel 92

1.15.6.1 Overview. 92

1.15.6.2 State Machine. 93

1.15.7 EM Module. 93

1.15.8 Non-module Channel 94

1.16 SHD Series (CTI Series) 94

1.16.1 Brief Introduction of SHD Series. 94

1.16.2 Operation Principle of SHD Series. 95

1.16.3 Number-receiving Rule for Incoming Call 98

1.16.4 SS7 Programming. 99

1.16.4.1 OPC & DPC.. 99

1.16.4.2 Time Slot Allocation. 99

1.16.4.3 Setting Spare Address Codes. 101

1.16.4.4 Configuration Instance for SS7 Server 101

1.16.4.5 TUP Programming and Application. 102

1.16.4.5.1 TUP Channel State Machine. 102

1.16.4.5.2 Channel Blocked and Unblocked. 109

1.16.4.5.2.1 Basic Concepts. 109

1.16.4.5.2.2 Usage. 109

1.16.4.5.2.3 Blocking Ways. 109

1.16.4.5.2.4 Function List 109

1.16.4.5.3 Circuit Resetting. 110

1.16.4.5.4 ‘Caller Holding’ Feature. 110

1.16.4.5.5 TUP Configuration. 110

1.16.4.6 ISUP Programming and Application. 111

1.16.4.6.1 ISUP Configuration. 111

1.16.4.6.2 ISUP Channel State Machine. 113

1.16.4.6.3 ISUP Channel Serving as Tandem Exchange. 119

1.16.4.6.4 SynCTI-provided ISUP State Machine Unused. 120

1.16.4.7 Advanced SS7 Programming. 121

1.16.4.7.1 MTP3 Service. 121

1.16.4.7.2 Client Software Programming Interface on SS7 Server 121

1.16.4.7.3 Virtual Circuit Programming Interface on SS7 Server 121

1.16.4.7.4 SCCP Programming Interface. 122

1.16.5 ISDN Programming. 122

1.16.5.1 Basic Concepts. 122

1.16.5.1.1 Network-side Mode and User-side Mode. 122

1.16.5.1.2 TEI Value. 122

1.16.5.1.3 Representation of Channel Identification Information. 122

1.16.5.1.4 Terminating Office Mode vs. Tandem Exchange Mode. 123

1.16.5.1.5 ISDN Number and ISDN Address. 123

1.16.5.2 ISDN Channel State Machine. 124

1.16.5.3 ISDN Configuration. 129

1.16.5.4 Advanced ISDN Programming Interface. 130

1.16.6 SS1 Programming. 131

1.16.6.1 Choice of Signaling Protocols. 131

1.16.6.2 Setting Call Progressing Parameters. 131

1.16.6.3 Setting Operation Mode for Channels in State Machine. 131

1.16.6.4 China SS1 State Machine. 131

1.16.6.4.1 Number Hold-up Feature. 131

1.16.6.4.2 Connection to Dialogic SS1 Channel 131

1.16.6.4.3 China SS1 State Machine. 132

1.16.6.4.4 Debugging Information Output during Outgoing Call 137

1.16.6.5 Line Side State Machine. 137

1.16.6.6 Advanced SS1 Programming Interface. 139

1.16.6.7 SS1 Configuration. 139

1.16.7 Connection to Channel Bank. 140

1.17 SHV Series (CTI Series) 141

1.17.1 Brief Introduction of SHV Series. 141

1.17.2 Operation Principle of SHV Series. 141

1.17.3 List of Voice-alteration Functions. 141

1.18 SHN Series (CTI Series) 142

1.18.1 Brief Introduction of SHN Series. 142

1.18.2 Operation Principle of SHN-32A-CT/PCI 142

1.18.3 Operation Principle of SHN B Series. 144

1.18.4 SIP Channel Programming. 144

1.18.4.1 Basic Concepts. 144

1.18.4.2 SIP Channel State Machine. 146

1.18.4.3 SIP Channel Configuration. 149

1.18.5 Special Parameters and Structure for VoIP Resource Boards. 150

1.18.5.1 RTP Transmit and Receive Modes for VoIP Resource Boards. 150

1.18.5.2 Special Structure for VoIP Resource Boards. 151

1.19 DST Series (REC Series) 151

1.19.1 Brief Introduction of DST Series. 151

1.19.2 DST Series Supported PBX Models. 152

1.19.3 Operation Principle of DST Series. 152

1.19.4 DST Board Configuration. 155

1.19.5 Voice Operation on DST Series. 156

1.19.6 Programming Guide for DST Series. 156

1.19.6.1 D-channel Signaling Messages. 156

1.20 ATP Series (REC Series) 157

1.20.1 Brief Introduction of ATP Series. 157

1.20.2 Operation Principle of ATP Series. 158

1.20.3 Analog Trunk Recording Channel State Machine. 160

1.20.4 Detection of Off-hook/On-hook State. 161

1.21 DTP Series (REC Series) 161

1.21.1 Brief Introduction of DTP Series. 161

1.21.2 Operation Principle of DTP Series. 162

1.21.3 Concerned Terms. 163

1.21.4 Voice Processing on DTP Series Boards. 164

1.21.4.1 DTMF Detection. 164

1.21.4.2 Voice Recording. 164

1.21.5 Driver-provided State Machine. 165

1.21.5.1 Universal State Machine Model for Digital Trunk Recording Channel 165

1.21.5.2 Acquisition of Call Information. 166

1.21.6 Application and Configuration Instance for DTP Series. 167

1.21.6.1 System Using SS1/ISDN PRI 167

1.21.6.2 System Using SS7. 167

2 SynCTI API Function Description. 169

2.1 System Functions. 169

2.1.1 Driver Platform Initialization Functions. 169

2.1.1.1 SsmStartCti 169

2.1.1.2 SsmCloseCti 170

2.1.2 Setting API Functions and Event Output Mode. 170

2.1.2.1 SsmSetLogEnable. 170

2.1.2.2 SsmSetLogAttribute. 171

2.1.2.3 SsmSetApiLogRange. 172

2.1.2.4 SsmGetLogAttribute. 173

2.1.3 Timer Functions. 174

2.1.3.1 SsmStartTimer 174

2.1.3.2 SsmStopTimer 175

2.1.3.3 StartTimer 175

2.1.3.4 ElapseTime. 176

2.1.4 Functions to Get System Error Messages. 176

2.1.4.1 SsmGetLastErrCode. 176

2.1.4.2 SsmGetLastErrMsg. 177

2.1.4.3 SsmGetLastErrMsgA. 177

2.1.4.4 fBmp_GetErrMsg. 178

2.1.5 Functions to Obtain Board Information. 178

2.1.5.1 Obtaining Installed Board Information. 178

2.1.5.1.1 SsmGetMaxCfgBoard. 178

2.1.5.1.2 SsmGetMaxUsableBoard. 179

2.1.5.1.3 GetTotalPciBoard. 179

2.1.5.1.4 ReloadPciBoardInfo. 180

2.1.5.2 Obtaining Board Authorization Code. 180

2.1.5.2.1 SsmGetAccreditId. 180

2.1.5.2.2 SsmGetAccreditIdEx. 180

2.1.5.3 Obtaining Board Model 181

2.1.5.3.1 SsmGetBoardModel 181

2.1.5.3.2 GetPciBoardModel 184

2.1.5.3.3 SsmGetBoardName. 186

2.1.5.4 Obtaining Board Serial Number 189

2.1.5.4.1 SsmGetPciSerialNo. 189

2.1.5.4.2 GetPciBoardSerialNo. 190

2.1.5.5 Obtaining Version Information. 190

2.1.5.5.1 SsmGetDllVersion. 190

2.1.6 Funtions to Obtain Channel Attributes. 191

2.1.6.1 SsmGetMaxCh. 191

2.1.6.2 SsmGetChType. 192

2.1.6.3 SsmGetChHdInfo. 192

2.1.6.4 SsmGetAppChId. 193

2.1.7 Functions to Set Channel Attributes. 193

2.1.7.1 SsmSetFlag. 193

2.1.7.2 SsmGetFlag. 195

2.2 Functions for Event-mode Programming. 196

2.2.1 Obtaining Events. 196

2.2.1.1 SsmWaitForEvent 197

2.2.1.2 SsmWaitForEventA. 197

2.2.1.3 SsmGetEvent 197

2.2.1.4 SsmGetEventA. 197

2.2.1.5 SsmGetInterEventType. 198

2.2.1.6 SsmSetInterEventType. 199

2.2.2 Filtering Output Events. 199

2.2.2.1 SsmSetEvent 199

2.2.3 Getting Programming Mode. 204

2.2.3.1 SsmGetEventMode. 204

2.2.4 Outputting Application’s Self-defined Events by Driver 204

2.2.4.1 SsmPutUserEvent 204

2.2.4.2 SsmPutUserEventA. 205

2.3 Call State Machine Functions. 206

2.3.1 Outgoing Call Functions (CTI Series) 206

2.3.1.1 Searching for Idle Channel 206

2.3.1.1.1 SsmSearchIdleCallOutCh. 206

2.3.1.2 Starting Outgoing Call 207

2.3.1.2.1 SsmAutoDial 207

2.3.1.2.2 SsmAutoDialEx. 207

2.3.1.2.3 SsmAppendPhoNum.. 210

2.3.1.2.4 SsmChkAutoDial 211

2.3.1.2.5 SsmGetAutoDialFailureReason. 212

2.3.1.2.6 SsmSetTxCallerId. 214

2.3.1.2.7 SsmGetTxCallerId. 215

2.3.1.2.8 SsmSetTxOriginalCallerID.. 216

2.3.1.2.9 SsmSetTxRedirectingNum.. 217

2.3.1.2.10 SsmSetWaitAutoDialAnswerTime. 217

2.3.1.2.11 SsmSetWaitAutoDialAnswerTimeEx. 218

2.3.1.2.12 SsmGetWaitAutoDialAnswerTime. 219

2.3.1.2.13 SsmGetKB. 219

2.3.1.3 SS1 Channel Functions. 220

2.3.1.3.1 SsmSetKA. 220

2.3.1.3.2 SsmSetKD.. 221

2.3.2 Incoming Call Functions. 222

2.3.2.1 Obtaining Calling Party Information. 222

2.3.2.1.1 SsmChkOpCallerId. 222

2.3.2.1.2 SsmGetCallerId. 222

2.3.2.1.3 SsmGetCallerIdA. 222

2.3.2.1.4 SsmGetCallerIdEx. 223

2.3.2.1.5 SsmGetCallerName. 224

2.3.2.1.6 SsmClearCallerId. 224

2.3.2.1.7 SsmClearCallerIdEx. 224

2.3.2.1.8 SsmGetKA. 225

2.3.2.1.9 SsmGetKD.. 226

2.3.2.2 Obtaining Called Party Information. 226

2.3.2.2.1 SsmGetPhoNumStr 226

2.3.2.2.2 SsmGetPhoNumStrA. 226

2.3.2.2.3 SsmGetPhoNumLen. 227

2.3.2.3 Obtaining 1st Called Party Number Information. 228

2.3.2.3.1 SsmGet1stPhoNumLen. 228

2.3.2.3.2 SsmGet1stPhoNumStr 228

2.3.2.3.3 SsmGet1stPhoNumStrA. 228

2.3.2.4 Setting Parameters for Incoming Call Progress. 229

2.3.2.4.1 SsmEnableAutoSendKB. 229

2.3.2.4.2 SsmGetAutoSendKBFlag. 230

2.3.2.4.3 SsmSetKB. 230

2.3.3 Channel State Transition Events. 232

2.3.3.1 SsmGetChState. 232

2.3.3.2 SsmGetChStateKeepTime. 235

2.3.4 Obtaining Pending Reason. 235

2.3.4.1 SsmGetPendingReason. 235

2.3.5 Channel Pickup Functions (CTI Series) 238

2.3.5.1 SsmPickup. 238

2.3.5.2 SsmPickupANX. 238

2.3.6 Channel Hangup Functions (CTI Series) 239

2.3.6.1 SsmHangup. 239

2.3.6.2 SsmHangupEx. 240

2.3.7 Setting Channel’s Call Direction. 241

2.3.7.1 SsmSetAutoCallDirection. 241

2.3.7.2 SsmGetAutoCallDirection. 242

2.3.8 Obtaining Release Reason. 242

2.3.8.1 SsmGetReleaseReason. 242

2.3.9 TUP Channel Functions. 243

2.3.9.1 SsmSetCalleeHoldFlag. 243

2.3.9.2 SsmGetTupFlag. 244

2.3.9.3 SsmSetTupParameter 245

2.3.9.4 SsmGetTupParameter 245

2.3.10 ISUP Channel Functions. 246

2.3.10.1 SsmSetISUPCAT. 246

2.3.10.2 SsmSetIsupParameter 247

2.3.10.3 SsmGetIsupParameter 248

2.3.10.4 SsmSetIsupFlag. 249

2.3.10.5 SsmGetIsupFlag. 250

2.3.10.6 SsmGetIsupUPPara. 251

2.3.10.7 SsmSetIsupUPPara. 251

2.3.10.8 SsmSendIsupMsg. 252

2.3.10.9 SsmGetRedirectionInfReason. 253

2.3.10.10 SsmGetRedirectionInfNum.. 254

2.3.10.11 SsmIsHaveCpg. 254

2.3.10.12 SsmGetCpg. 254

2.3.10.13 SsmIsupGetUsr 255

2.3.10.14 SsmIsupSendUsr 255

2.3.11 ISDN Channel Function. 256

2.3.11.1 Setting Parameters for Setup Message. 256

2.3.11.1.1 SsmISDNSetDialSubAddr 256

2.3.11.1.2 SsmISDNSetDialSubAddrEx. 256

2.3.11.1.3 SsmISDNSetTxSubAddr 257

2.3.11.1.4 SsmISDNSetTxSubAddrEx. 257

2.3.11.1.5 SsmISDNSetCallerIdPresent 258

2.3.11.2 Obtaining Incoming Call Information. 258

2.3.11.2.1 Obtaining Subaddress Information. 258

2.3.11.2.1.1 SsmISDNGetSubAddr 258

2.3.11.2.1.2 SsmISDNGetCallerSubAddr 259

2.3.11.2.2 Obtaining User-defined Calling Party Number 259

2.3.11.2.2.1 SsmGetUserCallerId. 259

2.3.11.3 Setting Hangup Reason. 260

2.3.11.3.1 SsmISDNSetHangupRzn. 260

2.3.11.4 Other Functions. 261

2.3.11.4.1 SsmISDNGetDisplayMsg. 261

2.3.11.4.2 SsmISDNGetTxCallerSubAddr 261

2.3.11.4.3 SsmSetNumType. 262

2.3.11.4.4 SsmGetNumType. 262

2.3.11.4.5 SsmSetCharge. 263

2.4 Tone Generator Functions (CTI Series) 264

2.4.1 Setting Parameters for Tone Generator 264

2.4.1.1 SsmSetTxTonePara. 264

2.4.1.2 SsmQueryOpSendTone. 265

2.4.1.3 SsmGetTxTonePara. 265

2.4.2 Sending Tones. 266

2.4.2.1 SsmSendTone. 266

2.4.2.2 SsmSendToneEx. 266

2.4.2.3 SsmStopSendTone. 266

2.4.2.4 SsmChkSendTone. 267

2.5 Tone Detector Functions. 268

2.5.1 Commonly Used Tone Detector Functions. 268

2.5.1.1 Setting Working Status. 268

2.5.1.1.1 SsmStartToneAnalyze. 268

2.5.1.1.2 SsmCloseToneAnalyze. 268

2.5.1.1.3 SsmQueryOpToneAnalyze. 269

2.5.1.2 Obtaining Detected Result 269

2.5.1.2.1 SsmGetToneAnalyzeResult 269

2.5.1.3 Clearing Detected Result 270

2.5.1.3.1 SsmClearToneAnalyzeResult 270

2.5.2 FFT Functions. 271

2.5.2.1 Setting Parameters. 271

2.5.2.1.1 SsmSetPeakFrqDetectBW.. 271

2.5.2.2 Obtaining Parameters. 271

2.5.2.2.1 SsmQueryOpPeakFrqDetect 271

2.5.2.2.2 SsmGetPeakFrqDetectBW.. 272

2.5.2.3 Obtaining Detected Result 272

2.5.2.3.1 SsmGetPeakFrq. 272

2.5.2.3.2 SsmGetPeakFrqEnergy. 273

2.5.2.3.3 SsmGetOverallEnergy. 273

2.5.2.3.4 SsmGetOverallEnergyAllCh. 274

2.5.3 Setting Parameters for Noise Filter 274

2.5.3.1 SsmSetMinVocDtrEnergy. 274

2.5.3.2 SsmGetMinVocDtrEnergy. 275

2.5.4 Call Progress Tone Detector Functions. 275

2.5.4.1 Setting Working Status of 2nd Call Progress Tone Detector 275

2.5.4.1.1 SsmStart2ndToneAnalyzer 275

2.5.4.1.2 SsmGet2ndToneAnalyzerState. 276

2.5.4.2 Obtaining Result of 2nd Call Progress Tone Detector 277

2.5.4.2.1 SsmGet2ndToneAnalyzeResult 277

2.5.4.2.2 SsmClear2ndToneAnalyzeResult 277

2.5.4.3 Setting Parameters for Frequency Detector 278

2.5.4.3.1 SsmSetTonePara. 278

2.5.4.3.2 SsmSet2ndTonePara. 278

2.5.4.3.3 SsmGetTonePara. 279

2.5.4.3.4 SsmGet2ndTonePara. 279

2.5.4.4 Setting Parameters for Dial Tone Detector 280

2.5.4.4.1 SsmSetIsDialToneDtrTime. 280

2.5.4.4.2 SsmSet2ndIsDialToneDtrTime. 280

2.5.4.4.3 SsmGetIsDialToneDtrTime. 280

2.5.4.4.4 SsmGet2ndIsDialToneDtrTime. 281

2.5.4.5 Setting Parameters for Ringback Tone Detector 281

2.5.4.5.1 SsmSetRingEchoTonePara. 281

2.5.4.5.2 SsmSet2ndRingEchoTonePara. 281

2.5.4.5.3 SsmGetRingEchoToneTime. 282

2.5.4.5.4 SsmGetRingEchoTonePara. 282

2.5.4.5.5 SsmGet2ndRingEchoTonePara. 283

2.5.4.6 Setting Parameters for Busy Tone Detector 283

2.5.4.6.1 SsmSetBusyTonePeriodEx. 283

2.5.4.6.2 SsmSetBusyTonePeriod. 283

2.5.4.6.3 SsmSet2ndBusyTonePeriod. 283

2.5.4.6.4 SsmSetIsBusyToneDtrCnt 284

2.5.4.6.5 SsmSet2ndIsBusyToneDtrCnt 284

2.5.4.6.6 SsmGetBusyTonePeriodEx. 285

2.5.4.6.7 SsmGetBusyTonePeriod. 285

2.5.4.6.8 SsmGet2ndBusyTonePeriod. 285

2.5.4.6.9 SsmGetIsBusyToneDtrCnt 286

2.5.4.6.10 SsmGet2ndIsBusyToneDtrCnt 286

2.5.4.7 Obtaining Detected result 287

2.5.4.7.1 SsmGetBusyToneLen. 287

2.5.4.7.2 SsmGet2ndBusyToneLen. 287

2.5.4.7.3 SsmGetBusyAMDToneCount 287

2.5.4.7.4 SsmGet2ndBusyAMDToneCount 287

2.5.4.8 Obtaining Result Gained by Using Back-to-Back Busy Tone Detection. 288

2.5.4.8.1 SsmGetBusyToneEx. 288

2.5.5 Fax Progress Tone Detector Functions. 289

2.5.5.1 Setting Working Parameters. 289

2.5.5.1.1 SsmSetVoiceFxPara. 289

2.5.5.1.2 SsmGetVoiceFxPara. 289

2.5.5.2 Obtaining Detected Result 290

2.5.5.2.1 SsmGetVocFxFlag. 290

2.5.6 AMD Function. 291

2.5.6.1 Obtaining and Clearing Result Gained by AMD.. 291

2.5.6.1.1 SsmGetAMDResult 291

2.5.6.1.2 SsmClearAMDResult 291

2.5.6.1.3 SsmControlAMD.. 292

2.6 DTMF Detector Functions. 292

2.6.1 Starting/Stopping DTMF Detector 293

2.6.1.1 SsmEnableRxDtmf 293

2.6.2 Setting Callback Functions. 293

2.6.2.1 SsmSetRxDtmfHandler 293

2.6.3 Obtaining DTMF Digits. 294

2.6.3.1 SsmClearRxDtmfBuf 294

2.6.3.2 SsmGetDtmfStr 295

2.6.3.3 SsmGetDtmfStrA. 295

2.6.3.4 SsmGetRxDtmfLen. 295

2.6.3.5 SsmGet1stDtmf 296

2.6.3.6 SsmGet1stDtmfClr 296

2.6.3.7 SsmGetLastDtmf 296

2.6.4 Using WaitDtmf 297

2.6.4.1 SsmSetWaitDtmf 297

2.6.4.2 SsmSetWaitDtmfEx. 297

2.6.4.3 SsmSetWaitDtmfExA. 297

2.6.4.4 SsmCancelWaitDtmf 298

2.6.4.5 SsmChkWaitDtmf 299

2.7 DTMF Generator Functions (CTI Series) 299

2.7.1 Setting Parameters for DTMF Generator 299

2.7.1.1 SsmSetTxDtmfPara. 299

2.7.1.2 SsmQueryTxDtmf 300

2.7.1.3 SsmGetTxDtmfPara. 300

2.7.2 Setting Working Status of DTMF Generator 301

2.7.2.1 SsmTxDtmf 301

2.7.2.2 SsmStopTxDtmf 302

2.7.2.3 SsmChkTxDtmf 302

2.8 Barge-in Detector Functions. 303

2.8.1 Setting Parameters for Barge-in Detector 303

2.8.1.1 SsmSetBargeInSens. 303

2.8.1.2 SsmSetIsBargeInDtrmTime. 303

2.8.1.3 SsmSetVoiceEnergyMinValue. 304

2.8.1.4 SsmSetNoSoundDtrmTime. 305

2.8.1.5 SsmGetBargeInSens. 305

2.8.1.6 SsmGetIsBargeInDtrmTime. 306

2.8.1.7 SsmGetVoiceEnergyMinValue. 306

2.8.1.8 SsmGetNoSoundDtrmTime. 306

2.8.2 Obtaining Detected Result of Barge-in Detector 307

2.8.2.1 SsmDetectBargeIn. 307

2.8.2.2 SsmDetectNoSound. 307

2.8.2.3 SsmGetNoSoundTime. 308

2.9 Voice Playing Functions. 308

2.9.1 Setting Playing Data’s Destination. 308

2.9.1.1 SsmSetPlayDest 308

2.9.2 Setting Playing Volume. 309

2.9.2.1 SsmSetPlayVolume. 309

2.9.2.2 SsmSetPlayGain. 309

2.9.3 Setting Termination Condition of Voice Playing. 310

2.9.3.1 SsmSetDtmfStopPlay. 310

2.9.3.2 SsmSetDTMFStopPlayCharSet 311

2.9.3.3 SsmGetDtmfStopPlayFlag. 311

2.9.3.4 SsmGetDTMFStopPlayCharSet 312

2.9.3.5 SsmSetBargeinStopPlay. 312

2.9.3.6 SsmGetBargeinStopPlayFlag. 313

2.9.3.7 SsmSetHangupStopPlayFlag. 313

2.9.4 Functions for Playing in Single File Mode. 314

2.9.4.1 SsmPlayFile. 314

2.9.4.2 SsmStopPlayFile. 316

2.9.4.3 SsmPausePlay. 316

2.9.4.4 SsmRestartPlay. 317

2.9.4.5 SsmFastFwdPlay. 317

2.9.4.6 SsmFastBwdPlay. 318

2.9.4.7 SsmSetPlayTime. 318

2.9.4.8 SsmSetPlayPrct 319

2.9.4.9 SsmGetDataBytesToPlay. 319

2.9.4.10 SsmGetDataBytesPlayed. 320

2.9.4.11 SsmGetPlayedTimeEx. 320

2.9.4.12 SsmGetPlayingFileInfo. 321

2.9.5 Functions for Playing in File List Mode. 321

2.9.5.1 SsmClearFileList 321

2.9.5.2 SsmAddToFileList 322

2.9.5.3 SsmPlayFileList 323

2.9.5.4 SsmStopPlayFileList 324

2.9.6 Functions for Playing in Single Buffer Mode. 324

2.9.6.1 SsmPlayMem.. 324

2.9.6.2 SsmStopPlayMem.. 325

2.9.6.3 SsmSetStopPlayOffset 326

2.9.6.4 SsmGetPlayOffset 326

2.9.7 Functions for Playing in Buffer List Mode. 327

2.9.7.1 SsmAddToPlayMemList 327

2.9.7.2 SsmClearPlayMemList 328

2.9.7.3 SsmPlayMemList 328

2.9.7.4 SsmStopPlayMemList 329

2.9.8 Preload Voice Data Playing Functions (CTI Series) 330

2.9.8.1 Preload Voice Information Initialization Functions. 330

2.9.8.1.1 SsmSetMaxIdxSeg. 330

2.9.8.1.2 SsmGetTotalIndexSeg. 330

2.9.8.1.3 SsmLoadIndexData. 331

2.9.8.1.4 SsmFreeIndexData. 332

2.9.8.1.5 SsmLoadChIndexData. 333

2.9.8.1.6 SsmFreeChIndexData. 333

2.9.8.2 Functions to Play Preload Voice Segments. 334

2.9.8.2.1 SsmPlayIndexString. 334

2.9.8.2.2 SsmPlayIndexList 334

2.9.8.2.3 SsmStopPlayIndex. 335

2.9.9 Functions for Playing in Pingpong Buffer Mode(CTI Series) 336

2.9.9.1 SsmPlayMemBlock. 336

2.9.9.2 SsmStopPlayMemBlock. 339

2.9.10 General Functions to Stop Voice Playing. 339

2.9.10.1 SsmStopPlay. 339

2.9.11 Obtaining Relative Information about Voice Playing. 340

2.9.11.1 SsmQueryPlayFormat 340

2.9.11.2 SsmGetPlayType. 340

2.9.11.3 SsmCheckPlay. 341

2.9.11.4 SsmGetPlayedPercentage. 342

2.9.11.5 SsmGetPlayedTime. 342

2.10 Voice Recording Functions. 343

2.10.1 Setting Recording Parameters. 343

2.10.1.1 Setting Signal Source and Its Volume. 343

2.10.1.1.1 SsmSetRecVolume. 343

2.10.1.1.2 SsmSetRecMixer 344

2.10.1.1.3 SsmQueryOpRecMixer 344

2.10.1.1.4 SsmGetRecMixerState. 345

2.10.1.1.5 DTRSetMixerVolum.. 346

2.10.1.1.6 DTRGetMixerVolume. 346

2.10.1.1.7 SsmSetRecBack. 347

2.10.1.1.8 SsmSetNoModuleChBusRec. 348

2.10.1.2 Setting Termination Condition of Voice Recording. 348

2.10.1.2.1 SsmSetDTMFStopRecCharSet 348

2.10.1.2.2 SsmGetDTMFStopRecCharSet 349

2.10.1.2.3 SsmSetHangupStopRecFlag. 350

2.10.1.3 Setting Prerecord Feature (REC Series) 350

2.10.1.3.1 SsmSetPrerecord. 350

2.10.1.3.2 SsmGetPrerecordState. 351

2.10.1.4 Setting Tail-truncation Feature. 352

2.10.1.4.1 SsmSetTruncateTail 352

2.10.1.4.2 SsmGetTruncateTailTime. 353

2.10.1.5 Setting AGC Feature. 353

2.10.1.5.1 SsmSetRecAGC.. 353

2.10.1.5.2 SsmGetRecAGCSwitch. 354

2.10.2 Obtaining Recording Operation Information. 354

2.10.2.1 SsmQueryRecFormat 354

2.10.2.2 SsmGetRecType. 355

2.10.2.3 SsmGetRecTime. 356

2.10.2.4 SsmCheckRecord. 356

2.10.3 Functions for Recording in File Mode. 357

2.10.3.1 SsmRecToFile. 357

2.10.3.2 SsmRecToFileA. 357

2.10.3.3 SsmRecToFileB. 357

2.10.3.4 SsmRecToFileEx. 357

2.10.3.5 SpyRecToFile. 357

2.10.3.6 SsmStopRecToFile. 361

2.10.3.7 SpyStopRecToFile. 361

2.10.3.8 SsmPauseRecToFile. 362

2.10.3.9 SsmRestartRecToFile. 362

2.10.3.10 SsmChkRecToFile. 363

2.10.3.11 SsmGetDataBytesToRecord. 363

2.10.4 Functions for Recording in Buffer Mode. 364

2.10.4.1 SsmRecToMem.. 364

2.10.4.2 SsmStopRecToMem.. 365

2.10.4.3 SsmGetRecOffset 365

2.10.5 Functions for Recording in Pingpong Buffer Mode (CTI Series) 366

2.10.5.1 SsmRecordMemBlock. 366

2.10.5.2 SsmStopRecordMemBlock. 368

2.11 TDM Functions. 369

2.11.1 Functions for Two-way Connection (CTI Series) 369

2.11.1.1 Establishing Two-way Connection. 369

2.11.1.1.1 SsmTalkWith. 369

2.11.1.1.2 SsmTalkWithEx. 369

2.11.1.2 Tearing off Two-way Connection. 370

2.11.1.2.1 SsmStopTalkWith. 370

2.11.2 Functions for One-way Connection. 371

2.11.2.1 Establishing One-way Connection. 371

2.11.2.1.1 SsmListenTo. 371

2.11.2.1.2 SsmListenToEx. 371

2.11.2.1.3 SsmLinkFrom.. 371

2.11.2.1.4 SsmLinkFromEx. 371

2.11.2.1.5 SsmLinkFromAllCh. 371

2.11.2.2 Tearing off One-way Connection. 374

2.11.2.2.1 SsmStopListenTo. 374

2.11.2.2.2 SsmStopLinkFrom.. 374

2.11.2.2.3 SsmUnLinkFromAllCh. 374

2.11.3 Obtaining Bus Information. 375

2.11.3.1 SsmGetChBusInfo. 375

2.11.4 Advanced Functions for Bus Operation (CTI Series) 376

2.11.4.1 Forcibly Tearing off All Bus Connections to Channel 376

2.11.4.1.1 SsmClearChBusLink. 376

2.11.4.2 One-way Connection from Channel to Bus Time Slot 376

2.11.4.2.1 SsmLinkToBus. 376

2.11.4.2.2 SsmUnLinkToBus. 377

2.11.4.3 One-way Connection from Bus Time Slot to Channel 378

2.11.4.3.1 SsmLinkFromBus. 378

2.11.4.3.2 SsmLinkFromBusEx. 378

2.11.4.3.3 SsmUnLinkFromBus. 379

2.11.4.3.4 SsmListenToPlay. 379

2.11.4.3.5 SsmUnListenToPlay. 380

2.12 On-board Audio Power Amplifier Functions. 380

2.12.1 SsmQueryOpPowerAmp. 380

2.12.2 SsmSetPowerAmpVlm.. 381

2.12.3 SetVolume. 381

2.13 On-board Speaker Functions. 381

2.13.1 SsmSetLine0OutTo. 381

2.14 Echo Canceller Functions (CTI Series) 382

2.14.1 Setting Operating Status of Echo Canceller 382

2.14.1.1 SsmQueryOpEchoCanceller 382

2.14.1.2 SsmSetEchoCanceller 383

2.14.1.3 SsmGetEchoCancellerState. 383

2.14.2 Setting Parameters of Echo Canceller 384

2.14.2.1 SsmSetEchoCancelDelaySize. 384

2.14.2.2 SsmGetEchoCancelDelaySize. 384

2.15 Teleconferencing Functions (CTI Series) 385

2.15.1 Initializing Conference Room.. 385

2.15.1.1 SsmCreateConfGroup. 385

2.15.1.2 SsmFreeConfGroup. 386

2.15.2 Setting Conference Member’s Behavior 386

2.15.2.1 SsmJoinConfGroup. 386

2.15.2.2 SsmExitConfGroup. 387

2.15.2.3 SsmSetListenVlmInConf 388

2.15.2.4 SsmSetContactInConf 388

2.15.3 Obtaining Conference Room Information. 389

2.15.3.1 SsmGetConfCfgInfo. 389

2.15.3.2 SsmGetTotalConfGroup. 389

2.15.3.3 SsmGetConfGrpCfgInfo. 390

2.15.3.4 SsmGetConfGrpInfo. 390

2.15.3.5 SsmGetConfGrpId. 391

2.15.3.6 SsmValidateGrpId. 391

2.15.4 Obtaining Conference Member Information. 392

2.15.4.1 SsmGetConfGrpMmbrId. 392

2.15.4.2 SsmGetConfGrpMmbrInfo. 392

2.15.4.3 SsmGetConfChInfo. 393

2.16 FSK Transceiver Functions (CTI Series) 394

2.16.1 FSK Transmitter 394

2.16.1.1 SsmSetFskPara. 394

2.16.1.2 SsmGetFskPara. 394

2.16.1.3 SsmTransFskData. 395

2.16.1.4 SsmStartSendFSK. 395

2.16.1.5 SsmCheckSendFsk. 396

2.16.1.6 SsmStopSendFsk. 397

2.16.2 FSK Receiver 397

2.16.2.1 SsmStartRcvFSK. 397

2.16.2.2 SsmStartRcvFSK_II 399

2.16.2.3 SsmStartRcvFSK_III 400

2.16.2.4 SsmCheckRcvFSK. 402

2.16.2.5 SsmStopRcvFSK. 403

2.16.2.6 SsmClearRcvFSKBuf 403

2.16.2.7 SsmGetRcvFSK. 404

2.17 Voltage Detector Functions. 405

2.17.1 Ignoring Result of Voltage Detector 405

2.17.1.1 SsmSetIgnoreLineVoltage. 405

2.17.1.2 SsmGetIgnoreLineVoltage. 405

2.17.2 Setting Threshold Voltage to Detect Pickup and Hangup Behaviors. 406

2.17.2.1 SsmSetDtrmLineVoltage. 406

2.17.2.2 SsmGetDtrmLineVoltage. 406

2.17.3 Obtaining Result of Voltage Detector 407

2.17.3.1 SsmGetLineVoltage. 407

2.17.4 Polarity Reversal Detector Functions. 408

2.17.4.1 SsmQueryOpPolarRvrs. 408

2.17.4.2 SsmGetPolarRvrsCount 408

2.17.5 Ringing Current Detector Functions. 409

2.17.5.1 SsmGetRingCount 409

2.17.5.2 SsmGetCallBackRingCount 409

2.17.5.3 SsmClearRingCount 410

2.17.5.4 SsmGetRingFlag. 410

2.18 Digital Trunk Functions. 411

2.18.1 SsmGetMaxPcm.. 411

2.18.2 SsmGetPcmInfo. 411

2.18.3 SsmGetPcmLinkStatus. 412

2.18.4 SsmPcmTsToCh. 414

2.18.5 SsmChToPcmTs. 415

2.18.6 SsmSetPcmClockMode. 415

2.18.7 SsmGetInboundLinkSet 416

2.18.8 SsmGetCbChStatus. 416

2.18.9 SsmSetPcmPowerDown. 417

2.19 Functions for SHT Series Boards (CTI Series) 417

2.19.1 Setting Operating Mode of Composite Module. 417

2.19.1.1 SsmSetUnimoduleState. 417

2.19.2 Functions for Analog Trunk Channel 418

2.19.2.1 Generating Flash Signal on Analog Phone Line. 418

2.19.2.1.1 SsmTxFlash. 418

2.19.2.1.2 SsmSetTxFlashCharTime. 419

2.19.2.1.3 SsmGetTxFlashCharTime. 419

2.19.2.1.4 SsmChkTxFlash. 420

2.19.2.1.5 SsmTxFlashEx. 420

2.19.2.2 Forced Transition of Channel State. 421

2.19.2.2.1 SsmSetChState. 421

2.19.2.3 Detecting Remote Pick-up During Outgoing Call 422

2.19.2.3.1 SsmStartPickupAnalyze. 422

2.19.2.3.2 SsmSetCalleeHookDetectP. 422

2.19.2.3.3 SsmGetPickup. 423

2.19.2.4 Checking Pickup Status. 423

2.19.2.4.1 SsmCheckActualPickup. 423

2.19.2.5 Checking Analog-trunk-to-recording Channel 424

2.19.2.5.1 SsmGetIsAnalogToRec. 424

2.19.3 Functions for Station Channel 425

2.19.3.1 Sending Ringing Signals to Phone. 425

2.19.3.1.1 SsmStartRing. 425

2.19.3.1.2 SsmStartRingWithCIDStr 425

2.19.3.1.3 fPcm_ConvertFskCID.. 426

2.19.3.1.4 SsmStopRing. 426

2.19.3.1.5 SsmCheckSendRing. 427

2.19.3.1.6 SsmSetRingPeriod. 428

2.19.3.2 Auto Sending Dial Tone upon Detection of Phone Pickup. 428

2.19.3.2.1 SsmSetASDT. 428

2.19.3.2.2 SsmGetASDT. 429

2.19.3.3 Detecting Flash Signal 429

2.19.3.3.1 SsmSetLocalFlashTime. 429

2.19.3.3.2 SsmGetFlashCount 430

2.19.3.3.3 SsmClearFlashCount 430

2.19.3.4 Pickup/Hangup Detection. 431

2.19.3.4.1 SsmGetHookState. 431

2.19.3.5 Generating Polarity Reversal Signals on Phone Line. 432

2.19.3.5.1 SsmSetPolarState. 432

2.19.3.5.2 SsmGetPolarState. 432

2.19.4 Remote Pickup Detector Functions (SHT Series Only) 433

2.19.4.1 Functions for Ordinary Remote Pickup Detector 433

2.19.4.1.1 Setting Parameters. 433

2.19.4.1.1.1 SsmSetVoiceOnDetermineTime. 433

2.19.4.1.2 Obtaining Parameters. 434

2.19.4.1.2.1 SsmGetVoiceOnDetermineTime. 434

2.20 Advanced Programming API for SHD Series (CTI Series) 434

2.20.1 Channel Blocking Control (CTI Series) 434

2.20.1.1 Functions for Blocking Local End. 434

2.20.1.1.1 Blocking Single Channel 434

2.20.1.1.1.1 SsmBlockLocalCh. 434

2.20.1.1.1.2 SsmUnblockLocalCh. 435

2.20.1.1.1.3 SsmQueryLocalChBlockState. 436

2.20.1.1.2 Blocking Whole Digital Trunk. 436

2.20.1.1.2.1 SsmBlockLocalPCM.. 436

2.20.1.1.2.2 SsmUnblockLocalPCM.. 437

2.20.1.1.2.3 SsmQueryLocalPCMBlockState. 437

2.20.1.2 Functions for Blocking Remote End. 438

2.20.1.2.1 Blocking Single Channel 438

2.20.1.2.1.1 SsmQueryOpBlockRemoteCh. 438

2.20.1.2.1.2 SsmBlockRemoteCh. 439

2.20.1.2.1.3 SsmUnblockRemoteCh. 439

2.20.1.2.1.4 SsmGetRemoteChBlockStatus. 440

2.20.1.2.2 Blocking Whole Digital Trunk. 441

2.20.1.2.2.1 SsmBlockRemotePCM.. 441

2.20.1.2.2.2 SsmUnblockRemotePCM.. 442

2.20.1.2.2.3 SsmGetRemotePCMBlockStatus. 443

2.20.2 SS7-MTP3 Based API 444

2.20.2.1 SsmSendSs7Msu. 444

2.20.2.2 SsmGetSs7Msu. 444

2.20.2.3 SsmGetMtp3State. 445

2.20.2.4 SsmGetMtp3StateEx. 445

2.20.2.5 SsmGetMtp2Status. 446

2.20.2.6 SsmSendSs7MsuEx. 447

2.20.2.7 SsmGetMaxSs7link. 447

2.20.2.8 SsmGetSs7Mtp2Msu. 447

2.20.2.9 SsmSendSs7Mtp2Msu. 448

2.20.3 Advanced Functions for ISDN.. 449

2.20.3.1 SsmGetIsdnMsu. 449

2.20.3.2 SsmSendIsdnMsu. 449

2.20.3.3 SsmCheckIsdnMsu. 450

2.20.3.4 SsmISDNGetStatus. 450

2.20.3.5 SsmGetUserInfo. 451

2.20.3.6 SsmISDNGetProgressMsg. 452

2.20.4 Advanced Functions for China SS1. 452

2.20.4.1 Controlling ABCD Signaling Codes. 452

2.20.4.1.1 SsmGetCAS. 452

2.20.4.1.2 SsmSendCAS. 453

2.20.4.1.3 SsmGetSendingCAS. 453

2.20.4.1.4 SsmSetSendCASFlag. 454

2.20.4.1.5 SsmGetSendCASFlag. 455

2.20.4.2 Controlling R2 Signal Transceiver 455

2.20.4.2.1 SsmSetRxR2Mode. 455

2.20.4.2.2 SsmGetR2. 456

2.20.4.2.3 SsmSendR2. 456

2.20.4.2.4 SsmSendR2Ex. 457

2.20.4.2.5 SsmStopSendR2. 458

2.20.4.2.6 SsmGetSendingR2. 458

2.21 Functions for SHV Series Boards (CTI Series) 459

2.21.1 SsmGetMaxVCh. 459

2.21.2 SsmGetMaxFreeVCh. 459

2.21.3 SsmBindVCh. 460

2.21.4 SsmUnBindVCh. 461

2.21.5 SsmSetVoiceEffect 461

2.21.6 SsmGetVoiceEffect 462

2.22 Functions for SHN Series Boards (CTI Series) 462

2.22.1 Setting Special Programming Interfaces for SIP Channel 462

2.22.1.1 SsmIpGetSessionCodecType. 462

2.22.1.2 SsmIpSetForwardNum.. 463

2.22.1.3 SsmIpInitiateTransfer 463

2.22.1.4 SsmIpGetMessageField. 464

2.22.1.5 SsmSipBoardRegister 465

2.22.1.6 SsmSipChRegister 465

2.22.1.7 SsmSipMultiChRegister 466

2.22.1.8 SsmSipSetTxUserName. 467

2.22.1.9 SsmSetIpFlag. 468

2.22.1.10 SsmSipGetReferStatus. 468

2.22.1.11 SsmSipGetBoardRegStatus. 469

2.22.1.12 SsmSipGetChRegStatus. 469

2.22.2 Setting Special API functions for VoIP Resource Boards. 470

2.22.2.1 SsmLockMediaCh. 470

2.22.2.2 SsmGetMediaChParam.. 471

2.22.2.3 SsmOpenMediaCh. 471

2.22.2.4 SsmCloseMediaCh. 472

2.22.2.5 SsmUnlockMediaCh. 472

2.22.2.6 SsmUpdateMediaCh. 473

2.22.3 Setting Special API functions for NAT Traversal 473

2.22.3.1 SsmIPGetStunPublicIP. 473

2.23 Functions for ATP Series Recording Boards (REC Series) 474

2.23.1 Input Gain Control of Microphone Channel 474

2.23.1.1 SsmQueryOpMicGain. 474

2.23.1.2 SsmSetMicGain. 474

2.23.1.3 SsmGetMicGain. 475

2.23.2 MF detector functions. 476

2.23.2.1 SsmClearRxMFBuf 476

2.23.2.2 SsmGetMFStr 476

2.24 Functions for DTP Series Boards (REC Series) 477

2.24.1 State Machine Programming Mode Based Functions. 477

2.24.1.1 Obtaining Basic Information. 477

2.24.1.1.1 SpyGetMaxCic. 477

2.24.1.1.2 SpyChToCic. 477

2.24.1.2 Obtaining Call Progress Information. 478

2.24.1.2.1 SpyGetState. 478

2.24.1.3 Obtaining Call Direction. 479

2.24.1.3.1 SpyGetCallInCh. 479

2.24.1.3.2 SpyGetCallOutCh. 479

2.24.1.4 Obtaining Calling and Called Party Numbers. 480

2.24.1.4.1 SpyGetCallerId. 480

2.24.1.4.2 SpyGetCalleeId. 480

2.24.1.5 Obtaining Hangup Information. 480

2.24.1.5.1 SpyGetHangupInfo. 480

2.24.1.6 Obtaining Calling and Called Party Number Types. 481

2.24.1.6.1 SpyGetCallerType. 481

2.24.1.6.2 SpyGetCalleeType. 481

2.24.1.7 Obtaining Digital Trunk State. 482

2.24.1.7.1 SpyGetLinkStatus. 482

2.24.1.8 Obtaining Original Signaling Messages from SS7 Call State Machine. 482

2.24.1.8.1 SsmGetSs7SpyMsu. 482

2.24.1.9 Obtaining Connection Number 483

2.24.1.9.1 SpyGetConId. 483

2.25 Functions for DST Series Recording Boards (REC Series) 484

2.25.1 SsmGetDstChSNRofUplink. 484

2.25.2 SsmGetDstChSNRofDownlink. 484

2.25.3 SsmGetDstChVoltageState. 485

2.26 Functions for PCM1280E Recording Board (REC Series) 485

2.26.1 SsmGetPcm32LineState. 485

2.27 CODEC Transcoding Functions. 486

2.27.1 fPcm_Mp3ConvertALaw. 486

2.27.2 fPcm_Mp3ConvertULaw. 486

2.27.3 fPcm_AdpcmToAlaw. 487

2.27.4 fPcm_AdpcmToGsm.. 487

2.27.5 fPcm_AdpcmToMp3. 487

2.27.6 fPcm_AlawToUlaw. 488

2.27.7 fPcm_UlawToAlaw. 488

2.27.8 fPcm_MemAdpcmToALAW... 489

2.27.9 fPcm_MemAdpcmToULAW... 489

2.27.10 fPcm_ALawConvertPcm16. 490

2.27.11 fPcm_ALawConvertPcm16_16K. 490

2.27.12 fPcm_ALawConvertPcm8. 490

2.27.13 fPCM_AlawConvertGC8. 490

2.27.14 fPcm_ALawConvertMp3. 490

2.27.15 fPcm_ULawConvertMp3. 491

2.27.16 fPcm_ALawToVox. 492

2.27.17 fPcm_MemAlawToPcm8. 492

2.27.18 fPcm_MemAlawToPcm16. 492

2.27.19 fPcm_MemAlawToPcm16_16K. 493

2.27.20 fPcm_MemGSMToPcm16. 494

2.27.21 fPcm_MemGSMToPcm8. 494

2.27.22 fPcm_MemGSMToUlaw. 495

2.27.23 fPcm_Pcm16ConvertALaw. 495

2.27.24 fPcm_Pcm16_16KconvertALaw. 496

2.27.25 fPcm_MemPcm8ToAlaw. 497

2.27.26 fPcm_MemAlawToUlaw. 497

2.27.27 fPcm_MemUlawtoAlaw. 497

2.27.28 fPcm_MemPcm16ToAlaw. 498

2.27.29 fPcm_MemPcm16_16KtoAlaw. 498

2.27.30 fPcm_GC8Convert 499

2.27.31 fPcm_Vox6KTo8K. 499

2.27.32 fPcm_Vox8KTo6K. 499

2.27.33 fPcm_ULawConvertGSM.. 500

2.27.34 fPCM_Pcm16ConvertG729A. 500

2.27.35 fPcm_Pcm8ConvertGSM.. 501

2.27.36 fPcm_GSMToMp3. 502

2.27.37 fPcm_G729AConvert 502

2.27.38 fPCM_MemULawToG729A. 503

2.27.39 fPcm_MemMp3ToPcm16. 504

2.27.40 fPcm_MemG729AToPcm8. 504

2.27.41 fPcm_MemG729AToPcm16. 504

2.27.42 fPcm_GetLastErrMsg. 505

2.27.43 fPcm_Close. 506

2.28 Faxing Functions (CTI Series) 506

2.28.1 Setting Faxing Parameters. 506

2.28.1.1 SsmFaxSetMaxSpeed. 506

2.28.1.2 SsmFaxSetID.. 507

2.28.2 Transmitting Fax. 507

2.28.2.1 SsmFaxStartSend. 507

2.28.2.2 SsmFaxStartSendEx. 507

2.28.2.3 SsmFaxSendMultiFile. 508

2.28.2.4 SsmFaxSendMultiFileEx. 508

2.28.2.5 SsmFaxAppendSend. 509

2.28.3 Receiving Fax. 510

2.28.3.1 SsmFaxStartReceive. 510

2.28.4 Stopping Faxing. 511

2.28.4.1 SsmFaxStop. 511

2.28.5 Obtaining Faxing Information. 511

2.28.5.1 SsmFaxGetSpeed. 511

2.28.5.2 SsmFaxCheckEnd. 512

2.28.5.3 SsmFaxGetDcnTag. 513

2.28.5.4 SsmFaxGetChStateMsg. 513

2.28.5.5 SsmFaxGetPages. 514

2.28.5.6 SsmFaxGetFailReason. 514

2.28.5.7 SsmFaxGetID.. 515

2.28.5.8 SsmFaxGetMode. 516

2.28.5.9 SsmFaxGetAllBytes. 516

2.28.5.10 SsmFaxGetSendBytes. 517

2.28.5.11 SsmFaxGetRcvBytes. 517

2.28.6 Relatvie Operations on .tif File. 518

2.28.6.1 fBmp_ValidateFaxFile. 518

2.28.6.2 fBmp_SetHeaderFormat 518

2.28.6.3 fBmp_AddTxtToTif 519

2.28.6.4 fBmp_AddTxtToTif_Big. 520

2.28.6.5 fBmp_UniteTif 521

2.28.6.6 fBmp_CutTifHeader 521

2.28.6.7 fBmp_GetFileAllPage. 522

3 SynCTI Driver Configuration. 523

3.1 System Configuration File ShConfig.ini 523

3.1.1 Essential Configuration Items. 523

3.1.1.1 Setting Total Number of Boards. 523

3.1.1.1.1 TotalBoards. 523

3.1.1.1.2 WhoSupplySysClock. 523

3.1.1.2 Setting Channel Number 524

3.1.1.2.1 TotalAppCh. 524

3.1.1.2.2 AppCh. 524

3.1.1.3 Setting Board Information. 524

3.1.1.3.1 BoardModel 524

3.1.1.3.2 BoardSerialNumber 524

3.1.1.4 SHD/DTP Series. 525

3.1.1.4.1 Setting Board Reset Feature. 525

3.1.1.4.1.1 ResetBoardOnClose. 525

3.1.1.4.2 Setting Parameters of Digital Trunk. 525

3.1.1.4.2.1 PcmNumber 525

3.1.1.4.2.2 PcmSSx. 525

3.1.1.4.2.3 PcmClockMode. 525

3.1.1.4.2.4 PcmLinkType. 525

3.1.1.4.2.5 IsdnAutoBuildLink. 525

3.1.1.4.2.6 CRC-4. 525

3.1.1.4.2.7 Loopback. 527

3.1.1.4.2.8 SpySyncAndCCS. 527

3.1.1.4.3 Setting Logical PCM Number 529

3.1.1.4.3.1 TotalPcm.. 529

3.1.1.4.3.2 Pcm.. 529

3.1.1.4.3.3 2PcmIn1Line. 530

3.1.1.4.4 Setting SpyPCM Number (DTP Series) 530

3.1.1.4.4.1 TotalSpyPcm.. 530

3.1.1.4.4.2 SpyPcm.. 530

3.1.1.4.4.3 SpyT1TransE1Line. 531

3.1.1.4.5 Setting SpyCIC Number (DTP Series) 532

3.1.1.4.5.1 TotalAppSpyCIC.. 532

3.1.1.4.5.2 AppSpyCIC.. 532

3.1.1.4.6 Essential Configuration Items for SS7 (DTP Series) 532

3.1.1.4.6.1 TotalSpyLinkSet 532

3.1.1.4.6.2 SpyLinkSet 532

3.1.1.4.6.3 TotalSpyLinkPcm.. 532

3.1.1.4.6.4 SpyLinkPcm.. 533

3.1.1.4.6.5 SpyCICPcm.. 533

3.1.1.4.6.6 SpySpCodeLen. 533

3.1.1.4.6.7 SpyIsupCICPcm.. 533

3.1.1.4.7 Essential Configuration Items for SS7 (SHD Series) 534

3.1.1.4.7.1 Setting Digital Trunk Using ISUP Protocol 534

3.1.1.4.7.1.1 TotalIsupPcm.. 534

3.1.1.4.7.1.2 IsupPcm.. 534

3.1.1.4.8 Essential Configuration Items for ISDN (SHD Series) 535

3.1.1.4.8.1 Setting Operating Mode. 535

3.1.1.4.8.1.1 UseISDNMode. 535

3.1.1.4.8.2 Setting Digital Trunk Using ISDN Signaling (User Side) 535

3.1.1.4.8.2.1 TotalUserLinker 535

3.1.1.4.8.2.2 UserPcmLink. 535

3.1.1.4.8.2.3 UserSendEstablish. 535

3.1.1.4.8.2.4 UserTEIValue. 535

3.1.1.4.8.3 Setting Digital Trunk Using ISDN Signaling (Network Side) 536

3.1.1.4.8.3.1 TotalNetLinker 536

3.1.1.4.8.3.2 NetPcmLink. 536

3.1.1.4.8.3.3 NetSendEstablish. 536

3.1.1.4.8.3.4 NetTEIValue. 536

3.1.1.4.9 Essential Configuration Items for China SS1 (SHD Series) 537

3.1.1.4.9.1 ProtocolType. 537

3.1.1.5 SHN Series. 537

3.1.1.5.1 Common Configuration Items for SHN Series. 537

3.1.1.5.1.1 LocalSipIp. 537

3.1.1.5.1.2 LocalSipPort 538

3.1.1.5.2 Essential Configuration Items for SHN A Series. 538

3.1.1.5.2.1 Setting Protocol Type. 538

3.1.1.5.2.1.1 ProtocolType. 538

3.1.1.5.2.2 Essential Configuration Items for SIP. 538

3.1.1.5.2.2.1 RTPRange. 538

3.1.1.5.2.2.2 AudioCodecList 538

3.1.1.5.2.2.3 SendDtmfType. 539

3.1.1.5.3 Essential Configuration Items for SHN B Series. 539

3.1.1.5.3.1 Essential Configuration Items for SIP. 539

3.1.1.5.3.1.1 BoardIP. 539

3.1.1.5.3.1.2 SubMask. 539

3.1.1.5.3.1.3 Gateway. 539

3.1.1.5.3.1.4 DNS. 539

3.1.1.5.3.1.5 AudioCodecList 539

3.1.1.5.3.1.6 RTPRange. 539

3.1.1.5.3.1.7 SendSipMsg. 539

3.1.1.5.3.1.8 SendDtmfType. 540

3.1.1.6 Essential Configuration Items for DST Series (REC Series only) 540

3.1.1.6.1 PBXType. 540

3.1.1.6.2 PhoneType. 541

3.1.1.6.3 ldr531. 541

3.1.1.6.4 DstRecRawData. 541

3.1.1.6.5 SetAnalogCtrlEnable. 541

3.1.1.6.6 AnalogCtrl 541

3.1.1.6.7 SetVoxChSelectEnable. 542

3.1.1.6.8 VoxChSelect 543

3.1.1.6.9 SetFilterSwitchEnable. 543

3.1.1.6.10 FilterSwitch. 543

3.1.1.6.11 SetVoltageReferenceEnable. 543

3.1.1.6.12 VoltageReference. 544

3.1.2 Common Configuration Items. 544

3.1.2.1 Setting Protocol for SHD/DTP Series Board. 544

3.1.2.1.1 CardType. 544

3.1.2.2 Setting Events Thrown out by Driver 544

3.1.2.2.1 DefaultEventOutput 544

3.1.2.2.2 OvrlEnrgEventOut 545

3.1.2.3 Setting Data Structure of Event 545

3.1.2.3.1 EventInterfaceType. 545

3.1.2.4 Setting Depth of Internal Event Queue. 545

3.1.2.4.1 MaxEventPerChannel 545

3.1.2.4.2 MaxUserEventSize. 546

3.1.2.5 Setting General Parameters for State Machine. 546

3.1.2.5.1 MaxWaitAutoDialAnswerTime. 546

3.1.2.5.2 RingToPending. 546

3.1.2.5.3 AutoClearCallerIdBufOnHangup. 547

3.1.2.5.4 AutomaticAisGeneration. 547

3.1.2.5.5 AutomaticRaiGereration. 547

3.1.2.5.6 IgnoreBlockInGra. 548

3.1.2.5.7 AllowTimeoutInSpyISDN. 548

3.1.2.6 Setting Voice CODECs on Digital Lines. 548

3.1.2.6.1 DefaultVoiceFormat 548

3.1.2.7 Setting Tone Detector 549

3.1.2.7.1 Setting Start/stop of Tone Detector on Digital Voice Board. 549

3.1.2.7.1.1 DefaultToneCheckState. 549

3.1.2.7.2 Setting Parameters of Noise Filter 549

3.1.2.7.2.1 MinimumVoiceDetermineEnergy. 549

3.1.2.7.3 Setting Parameters of DTMF Pulse-width Filter 549

3.1.2.7.3.1 ToneHighFilterPoint 549

3.1.2.7.3.2 ToneLowFilterPoint 549

3.1.2.7.4 Setting 1st Call Progress Tone Detector 550

3.1.2.7.4.1 Setting Parameters of Frequency Detector 550

3.1.2.7.4.1.1 TonePara. 550

3.1.2.7.4.2 Setting Parameters of Dial Tone Detector 550

3.1.2.7.4.2.1 IsDialToneDetermineTime. 550

3.1.2.7.4.3 Setting Parameters of Echo Tone Detector 550

3.1.2.7.4.3.1 RingEchoTonePara. 550

3.1.2.7.4.4 Setting Parameters of Busy Tone Detector 551

3.1.2.7.4.4.1 BusyTonePeriod. 551

3.1.2.7.4.4.2 IsBusyToneDetermineCount 551

3.1.2.7.4.5 Setting Parameters for Kewl Start 551

3.1.2.7.4.5.1 EnableKewlStart 551

3.1.2.7.4.5.2 KSVoltageThreshold. 551

3.1.2.7.4.5.3 KSKeepTime. 551

3.1.2.7.4.6 Setting Parameters of User-defined Tone Detector 552

3.1.2.7.4.6.1 AppointedToneAnalyzerSwitch. 552

3.1.2.7.4.6.2 IsAppointedToneDetermineTime. 552

3.1.2.7.4.6.3 AppointedTonePara. 552

3.1.2.7.4.6.4 IsAppointedToneDetermineCount 552

3.1.2.7.5 Setting 2nd Call Progress Tone Detector 553

3.1.2.7.5.1 Setting Operating Status. 553

3.1.2.7.5.1.1 Enable2ndToneAnalyzer 553

3.1.2.7.5.1.2 Check2ndToneOnAutoDial 553

3.1.2.7.5.2 Setting Parameters of Frequency Detector 553

3.1.2.7.5.2.1 2ndTonePara. 553

3.1.2.7.5.3 Setting Parameters of Dial Tone Detector 553

3.1.2.7.5.3.1 2ndIsDialToneDetermineTime. 553

3.1.2.7.5.4 Setting Parameters of Echo Tone Detector 554

3.1.2.7.5.4.1 2ndRingEchoTonePara. 554

3.1.2.7.5.5 Setting Parameters of Busy Tone Detector 554

3.1.2.7.5.5.1 2ndBusyTonePeriod. 554

3.1.2.7.5.5.2 2ndIsBusyToneDetermineCount 554

3.1.2.7.5.5.3 MaxBsTnOffTime. 554

3.1.2.7.5.6 Setting Parameters of User-defined Tone Detector 555

3.1.2.7.5.6.1 2ndAppointedToneAnalyzerSwitch. 555

3.1.2.7.5.6.2 2ndIsAppointedToneDetermineTime. 555

3.1.2.7.5.6.3 2ndAppointedTonePara. 555

3.1.2.7.5.6.4 2ndIsAppointedToneDetermineCount 555

3.1.2.7.6 Setting Fax Progress Tone Detector 556

3.1.2.7.6.1 VoiceFreqF1Para. 556

3.1.2.7.6.2 VoiceFreqF2Para. 556

3.1.2.7.7 Setting Simplified Busy Tone Detector 556

3.1.2.7.7.1 Setting Operating Status. 556

3.1.2.7.7.1.1 ToneAnalyzeAtRcvFsk. 556

3.1.2.7.7.2 Setting Parameters of Noise Filter 556

3.1.2.7.7.2.1 TAARFDetermineEnergy. 556

3.1.2.7.8 Setting Way to Detect Ringback Tones. 557

3.1.2.7.8.1 Setting Way to Detect Ringback Tones. 557

3.1.2.7.8.1.1 IsEchoQuickDetect 557

3.1.2.7.8.2 Sets Allowance Error in Detecting Echo Tone at On State. 557

3.1.2.7.8.2.1 EchoOnTolerance. 557

3.1.2.7.8.3 Setting Allowance Error in Detecting Echo Tone at Off State. 557

3.1.2.7.8.3.1 EchoOffTolerance. 557

3.1.2.7.9 Setting CCIR Tone Detector 557

3.1.2.7.9.1 CCIREnableDetector 557

3.1.2.8 Setting Answering Machine Detector 558

3.1.2.8.1 EnableAMD.. 558

3.1.2.8.2 AMDNoSoundAfterDialTime. 558

3.1.2.8.3 AMDNoSoundTime. 558

3.1.2.8.4 AMDTimeOut 559

3.1.2.8.5 AMDToneCount 559

3.1.2.8.6 AMDTOn. 559

3.1.2.8.7 AMDTOff 559

3.1.2.8.8 AMDTimeA. 559

3.1.2.8.9 AMDTimeB. 560

3.1.2.8.10 AMDTimeC.. 560

3.1.2.8.11 AMDTimeD.. 560

3.1.2.8.12 AMDSilentEnergy. 560

3.1.2.9 Setting Enhanced Tone Detector 560

3.1.2.9.1 ToneDetectorMode. 560

3.1.2.9.2 VoiceOffDetermineTime. 561

3.1.2.9.3 MaxToneDetectorItem.. 561

3.1.2.9.4 ToneDetectorItem.. 561

3.1.2.10 Setting Tone Generator(CTI Series) 565

3.1.2.10.1 DefaultSendToneFrequence. 565

3.1.2.10.2 DefaultSendToneVolume. 565

3.1.2.11 Setting Teleconferencing Parameters (CTI Series) 565

3.1.2.11.1 ClearInVoiceOnRxDtmf 565

3.1.2.11.2 ClearInVoiceOnRx450Hz. 566

3.1.2.11.3 ConfMaxGroup. 566

3.1.2.11.4 ConfDefaultMaxGroupMember 566

3.1.2.11.5 ConfDefaultMaxGroupSpeaker 566

3.1.2.11.6 ConfDefaultMaxGroupSpeaking. 566

3.1.2.11.7 ConfJoinedbyEnergy. 567

3.1.2.11.8 ConfMaxListener 567

3.1.2.11.9 ConfDefaultMaxSilenceTime. 567

3.1.2.11.10 BackgroundVoicePriority. 567

3.1.2.11.11 PlayVoiceIsListen. 568

3.1.2.12 Setting Voice Playing Operation. 568

3.1.2.12.1 Setting Termination Condition of Voice Playing. 568

3.1.2.12.1.1 DefaultDtmfStopPlay. 568

3.1.2.12.1.2 DtmfStopPlayCharSet 568

3.1.2.12.1.3 HangupStopPlay. 568

3.1.2.12.1.4 DefaultBargeInStopPlay. 569

3.1.2.12.2 Setting Internal Playback Buffer 569

3.1.2.12.2.1 PlayBufSize. 569

3.1.2.12.3 Setting Parameters of Voice Playing in File List Mode. 569

3.1.2.12.3.1 MaxPlayFileList 569

3.1.2.12.4 Setting Parameters of Voice Playing in Preload File Mode. 570

3.1.2.12.4.1 MaxPlayIndexList 570

3.1.2.12.5 Setting Parameters of Voice Playing in Buffer List Mode. 570

3.1.2.12.5.1 MaxPlayMemList 570

3.1.2.12.6 Setting Parameters of Voice Playing in Single File Mode. 570

3.1.2.12.6.1 FastPlayTime. 570

3.1.2.12.7 Setting Volume of Voice Playing. 570

3.1.2.12.7.1 DefaultPlayVolume. 570

3.1.2.12.8 Setting Encoding Format of Voice Playing. 571

3.1.2.12.8.1 DefaultPlayFormat 571

3.1.2.12.9 Setting Other Parameters of Voice Playing. 571

3.1.2.12.9.1 DefaultPausePlayOnRxDtmf 571

3.1.2.12.9.2 PlayFilterFlag. 572

3.1.2.13 Setting Recording Operation. 572

3.1.2.13.1 Setting Termination Condition of Voice Recording. 572

3.1.2.13.1.1 DtmfStopRecCharSet 572

3.1.2.13.1.2 HangupStopRec. 572

3.1.2.13.2 Setting Recording Signal Sources. 573

3.1.2.13.2.1 DefaultRecordVolume. 573

3.1.2.13.2.2 DefaultRecordMixerVolume. 573

3.1.2.13.3 Setting Tail-Truncation Feature for File Recording. 573

3.1.2.13.3.1 TruncateTailOnRecordToFile. 573

3.1.2.13.4 Setting Encoding Format of Voice Recording. 574

3.1.2.13.4.1 DefaultRecordFormat 574

3.1.2.13.5 Setting Internal Recording Buffer 574

3.1.2.13.5.1 RecordBufSize. 574

3.1.2.13.6 Setting WAV Format for Recording. 574

3.1.2.13.6.1 RecAsWavFormat 574

3.1.2.13.6.2 Mp3IsOnlyRead. 575

3.1.2.13.7 Setting AGC Parameters. 575

3.1.2.13.7.1 AGCMAXGAIN. 575

3.1.2.13.7.2 AGCMINGAIN. 575

3.1.2.13.7.3 AGCMAXGAINUPLINK. 575

3.1.2.13.7.4 AGCMINGAINUPLINK. 575

3.1.2.13.7.5 AGCMAXGAINDOWNLINK. 575

3.1.2.13.7.6 AGCMINGAINDOWNLINK. 575

3.1.2.13.7.7 AGCMAXLEVEL. 576

3.1.2.13.7.8 AGCMINLEVEL. 576

3.1.2.13.7.9 AGCMAXLEVELUPLINK. 576

3.1.2.13.7.10 AGCMINLEVELUPLINK. 576

3.1.2.13.7.11 AGCMAXLEVELDOWNLINK. 576

3.1.2.13.7.12 AGCMINLEVELDOWNLINK. 576

3.1.2.13.7.13 AGCDOWNRATIO.. 577

3.1.2.13.7.14 AGCUPRATIO.. 577

3.1.2.13.7.15 AGCDOWNRATIOUPLINK. 577

3.1.2.13.7.16 AGCUPRATIOUPLINK. 577

3.1.2.13.7.17 AGCDOWNRATIODOWNLINK. 577

3.1.2.13.7.18 AGCUPRATIODOWNLINK. 577

3.1.2.13.7.19 AGCKEEPTIME. 577

3.1.2.13.7.20 OpenRecEnAndPlayEnOnIdle. 578

3.1.2.13.7.21 AutoRecAgcSwitch. 578

3.1.2.13.8 Setting Other Parameters. 579

3.1.2.13.8.1 RecEliDTDurTalking. 579

3.1.2.13.9 Setting Bit Rate for MP3 Recording. 579

3.1.2.13.9.1 Mp3EncodingBitRate. 579

3.1.2.14 Setting Parameters Required for Both Recording and Playing Operations. 579

3.1.2.14.1 Setting Minimum Size of Pingpong Buffer Area. 579

3.1.2.14.1.1 RecordAndPlayUseAsIP. 579

3.1.2.14.2 Setting Software-based GSM Format 579

3.1.2.14.2.1 GsmCodecEnable. 579

3.1.2.15 Setting DTMF Detector 580

3.1.2.15.1 Starting/Stopping DTMF Detector 580

3.1.2.15.1.1 AlwaysEnableRxDtmf 580

3.1.2.15.1.2 RcvDtmfOnIdle. 580

3.1.2.15.2 Setting Buffer Size for DTMF Detector 580

3.1.2.15.2.1 RxDtmfBufSize. 580

3.1.2.15.3 Setting Parameters of DTMF Filter 581

3.1.2.15.3.1 DualAndAllFreqEnScale. 581

3.1.2.15.3.2 HighAndLowFreqEnScale. 581

3.1.2.15.3.3 DtmfEnergy. 582

3.1.2.15.4 Setting Parameters of DTMF Pulse-width Filter 582

3.1.2.15.4.1 ReceiveDtmfSensitive. 582

3.1.2.15.4.2 OmitABCD.. 582

3.1.2.15.4.3 DtrmOnDtmfHighLevel 583

3.1.2.16 Setting DTMF Generator (CTI Series) 583

3.1.2.16.1 Setting Size of Transmission Buffer Area. 583

3.1.2.16.1.1 TxDtmfBufSize. 583

3.1.2.16.2 Setting Parameters for DTMF Generator 584

3.1.2.16.2.1 TxDtmfTimePara. 584

3.1.2.16.2.2 DefaultTxDelayTime. 584

3.1.2.17 Setting Echo Canceller (CTI Series) 584

3.1.2.17.1 Setting Operating Status. 584

3.1.2.17.1.1 EnableEchoCancellor 584

3.1.2.17.2 Setting Parameters. 585

3.1.2.17.2.1 EchoCancelDelaySize. 585

3.1.2.18 Setting Barge-in Detector (CTI Series) 585

3.1.2.18.1 Setting Way to Start Barge-in Detector 585

3.1.2.18.1.1 AlwaysDetectBargeIn. 585

3.1.2.18.2 Setting Parameters for Barge-in Detector 585

3.1.2.18.2.1 VoiceEnergyMinValue. 585

3.1.2.18.2.2 BargeInSensitive. 586

3.1.2.18.2.3 BargeInDtrmTime. 586

3.1.2.18.2.4 IsNoSoundDtrmTime. 586

3.1.2.18.2.5 DefaultDtmfIsSound. 587

3.1.2.19 Setting TDM Connection. 587

3.1.2.19.1 InVoiceToBus. 587

3.1.2.19.2 LinkFromStopPlayAndTone. 587

3.1.2.19.3 DefaultSpeakVolume. 588

3.1.2.19.4 EnableCommonTimeSlot 588

3.1.2.20 Setting Caller ID Detector for Analog Phone Line (SHT＋ATP Series) 588

3.1.2.20.1 Setting Operating Mode of Caller ID Detector 588

3.1.2.20.1.1 CallerIdStyle. 588

3.1.2.20.2 Setting Parameters for FSK Mode. 589

3.1.2.20.2.1 CloseCallerIdOnReceived. 589

3.1.2.20.2.2 FSKCallerIdDtrmTime. 589

3.1.2.20.2.3 FilterInvalidCID.. 589

3.1.2.20.2.4 FSKMinGate. 590

3.1.2.20.2.5 FskNoPhase. 590

3.1.2.20.3 Setting Parameters for DTMF Mode. 590

3.1.2.20.3.1 DtmfCallerIDStyleLength. 590

3.1.2.20.3.2 DtmfCallerIDInterTimeOut 590

3.1.2.21 Setting Ringing Current Signal Detector (SHT+ATP Series) 591

3.1.2.21.1 RingDetectFilterPara. 591

3.1.2.21.2 CallBackRingDetectFilterPara. 591

3.1.2.21.3 RingEndDtrTime. 592

3.1.2.21.4 AlwaysToRingingOnRingCntX. 592

3.1.2.21.5 ChToRingingOnRingCnt 592

3.1.2.22 Setting FSK Transceiver (CTI Series) 593

3.1.2.22.1 Setting Parameters for FSK Transceiver 593

3.1.2.22.1.1 FreqBit0. 593

3.1.2.22.1.2 FreqBit1. 593

3.1.2.22.1.3 Baudrate. 593

3.1.2.22.1.4 MdlAmp. 593

3.1.2.23 Setting FSK Transceiver (CTI Series) 594

3.1.2.23.1 FskMarkSignal 594

3.1.2.23.2 FskFrameMode. 594

3.1.2.23.3 FskEchoCancelDelay. 594

3.1.2.24 Setting Parameters for Fax Channel 595

3.1.2.24.1 MaxSpeed. 595

3.1.2.24.2 RcvDisTime. 595

3.1.2.24.3 ResendForRTN. 595

3.1.2.24.4 ResetRcvForRTN. 595

3.1.2.24.5 KeepPageForRTN. 595

3.1.2.24.6 PercentageForRTN. 596

3.1.2.25 Setting Voltage Detector 596

3.1.2.25.1 Ignoring Detected Result of Voltage Detector 596

3.1.2.25.1.1 IgnoreLineVoltage. 596

3.1.2.25.2 Setting Voltage Threshold for Ring Detection. 596

3.1.2.25.2.1 JudgeLineVoltage. 596

3.1.2.25.3 Setting Judgement on Pickup/Hangup. 597

3.1.2.25.3.1 IsHangupDtrmVoltage. 597

3.1.2.25.3.2 LineOncnt 597

3.1.2.25.4 Setting Off-line Detection. 597

3.1.2.25.4.1 OffLineSet 597

3.1.2.25.4.2 OffLineDetermineTime. 597

3.1.2.25.5 Setting Effect of Polarity Reversal Signal 598

3.1.2.25.5.1 DisablePolarReverse. 598

3.1.2.25.6 Setting Threshold Voltage to Ignore Interfering Signal 598

3.1.2.25.6.1 PolarIgnore. 598

3.1.2.26 Setting Speaker of USB Recording/voice Box. 598

3.1.2.26.1 USBLine0Output 598

3.1.2.27 Common Configuration Item for SHT Series (CTI Series) 599

3.1.2.27.1 Special Configuration Item for Analog Trunk Channel 599

3.1.2.27.1.1 Setting Analog Trunk Channel to Be Recording Channel 599

3.1.2.27.1.1.1 SetAnalogChToRecCh. 599

3.1.2.27.1.2 Setting Parameters for Outgoing Call 599

3.1.2.27.1.2.1 MaxWaitDialToneTime. 599

3.1.2.27.2 Setting Flash Signal and Duration. 600

3.1.2.27.2.1 DefaultTxFlashChar 600

3.1.2.27.2.2 DefaultTxFlashTime. 600

3.1.2.27.2.3 Remote Pickup Detector 600

3.1.2.27.2.3.1 Setting Parameters for Ordinary Remote Pickup Detector 600

3.1.2.27.2.3.1.1 WaitAfterDialTime. 600

3.1.2.27.2.3.1.2 MaxWaitVocAfterEcho. 600

3.1.2.27.2.3.1.3 VoiceOnDetermineTime. 601

3.1.2.27.2.3.1.4 EchoNoVoiceToTalking. 601

3.1.2.27.2.3.2 Setting Parameters for Enhanced Remote Pickup Detector 601

3.1.2.27.2.3.2.1 RelativeEngyHookDetect 601

3.1.2.27.2.3.2.2 HookEngyConfigMulti 601

3.1.2.27.2.3.2.3 HookValidEngyCnt 602

3.1.2.27.3 Special Configuration Item for Station Channel 602

3.1.2.27.3.1 AutoSendDialTone. 602

3.1.2.27.3.2 StopSendDialToneOnDtmf 603

3.1.2.27.3.3 MaxLocalFlashTime. 603

3.1.2.27.3.4 UserOnHookFilterTime. 603

3.1.2.27.3.5 UserChGenerateRingMode. 604

3.1.2.27.3.6 UserSendPolar 604

3.1.2.27.4 Special Configuration Item for Fax Channel 604

3.1.2.27.4.1 MaxFaxChannel 604

3.1.2.27.4.2 DSP3WORKMODE. 604

3.1.2.27.5 Special Configuration Item for Composite Module. 605

3.1.2.27.5.1 UnimoduleState. 605

3.1.2.27.6 Special Configuration Item for Non-module channel 605

3.1.2.27.6.1 NoModuleChBusRec. 605

3.1.2.27.7 Magnet Channel 606

3.1.2.27.7.1 IsMagnetModule. 606

3.1.2.28 Common Configuration Item for SHD Series (CTI Series) 606

3.1.2.28.1 Setting Number-receiving Rule for Incoming Call 606

3.1.2.28.1.1 DefaultRcvPhoNumLen. 606

3.1.2.28.1.2 DefaultRcvCallerID.. 606

3.1.2.28.1.3 RcvPhoNumCfgLen. 606

3.1.2.28.1.4 MaxPhoNumRule. 607

3.1.2.28.1.5 Rule. 607

3.1.2.28.1.6 MfcLenCtrlPos. 608

3.1.2.28.1.7 MfcLengthTable. 608

3.1.2.28.1.8 CallerIdEnTable. 608

3.1.2.28.2 Setting ‘Auto-answer of Incoming Call’ Feature. 609

3.1.2.28.2.1 AutoSendKB. 609

3.1.2.28.2.2 AutoSendACM.. 609

3.1.2.28.2.3 UserSideAutoSendAck. 609

3.1.2.28.2.4 NetSideAutoSendAck. 609

3.1.2.28.3 Setting Calling Party Number for Outgoing Call 610

3.1.2.28.3.1 TxCallerId. 610

3.1.2.28.3.2 CalloutCallerId. 610

3.1.2.28.3.3 SetSTSignal 610

3.1.2.28.4 Connecting to Channel Bank. 610

3.1.2.28.4.1 UsageMode. 610

3.1.2.28.4.2 CBProtocolType. 611

3.1.2.28.4.3 CBChannelType. 611

3.1.2.28.5 Setting Board Operating Mode. 612

3.1.2.28.5.1 RunAsSpy. 612

3.1.2.28.6 Advanced Setting for SS1. 612

3.1.2.28.6.1 Selecting Country. 612

3.1.2.28.6.1.1 mfcr2_Protocol 612

3.1.2.28.6.2 Setting R2 Parameters for SS1 Connection. 613

3.1.2.28.6.2.1 tonesgroupA. 613

3.1.2.28.6.2.2 tonesgroupB. 614

3.1.2.28.6.2.3 Tonesendofinfo. 614

3.1.2.28.6.2.4 Tonesanswer 614

3.1.2.28.6.2.5 Tonesrepeatrequest 614

3.1.2.28.6.3 Setting Basic Parameters for SS1 Connection. 615

3.1.2.28.6.3.1 TxCas_CD.. 615

3.1.2.28.6.3.2 RxCASFilterTime. 615

3.1.2.28.6.3.3 MaxWaitMfcTime. 615

3.1.2.28.6.3.4 RxR2FilterTime. 616

3.1.2.28.6.3.5 LSRingTimeout 616

3.1.2.28.6.4 Setting Operating Mode of SS1 Channel State Machine. 616

3.1.2.28.6.4.1 EnableAutoCall 616

3.1.2.28.6.4.2 AutoCallInTimeSlot 616

3.1.2.28.6.5 Setting Parameters for China SS1 State Machine. 617

3.1.2.28.6.5.1 MfcKB. 617

3.1.2.28.6.5.2 MaxWaitSetKBTime. 617

3.1.2.28.6.5.3 MaxWaitKDTime. 617

3.1.2.28.6.5.4 PcmSyncMask. 617

3.1.2.28.6.5.5 PhoNumHoldup. 617

3.1.2.28.6.5.6 A1ToA3pWaitTime. 617

3.1.2.28.6.5.7 A3pTime. 618

3.1.2.28.6.5.8 Setting Parameters in State Machine for Outgoing Call 618

3.1.2.28.6.5.8.1 MaxWaitOccupyAckTime. 618

3.1.2.28.6.5.8.2 MfcKD.. 618

3.1.2.28.6.5.8.3 MfcKA. 619

3.1.2.28.6.5.8.4 MaxWaitKBTime. 619

3.1.2.28.6.5.9 Connecting with Dialogic SS1 Channel 619

3.1.2.28.6.5.9.1 ToRingingDelayTime. 619

3.1.2.28.6.5.9.2 RepeatPhoNumOn1stR2bwdIsA5. 619

3.1.2.28.6.5.10 Setting Remote Blocked at Application’s Exit 620

3.1.2.28.6.5.10.1 IsBlockSS1In. 620

3.1.2.28.6.5.11 Outputting Debugging Information. 620

3.1.2.28.6.5.11.1 MfcR2ToRxCallerIdBuf 620

3.1.2.28.6.6 Setting Parameters for LineSide Protocol 620

3.1.2.28.6.6.1 LSWaitPickup. 620

3.1.2.28.6.6.2 Ss1SendIdleState. 620

3.1.2.28.7 Advanced Setting for SS7. 621

3.1.2.28.7.1 Setting TS16 Property. 621

3.1.2.28.7.1.1 UseTS16AsCircuit 621

3.1.2.28.7.1.2 Ss7SignalingTS. 621

3.1.2.28.7.2 Setting Corresponding Characters for Spare Address Codes. 622

3.1.2.28.7.2.1 AddressSignal 622

3.1.2.28.7.3 Setting IP Address of SS7 Server 623

3.1.2.28.7.3.1 Ss7ServerIP. 623

3.1.2.28.7.3.2 SecondServerIP. 623

3.1.2.28.7.4 Setting IP Address of Local PC.. 623

3.1.2.28.7.4.1 LocalIP. 623

3.1.2.28.7.5 SS7 Server Outputting Data on Voice Time Slot 623

3.1.2.28.7.5.1 LoadShp_a3AsSIU. 623

3.1.2.28.7.6 Setting SS7 Circuit for Digital Trunk. 624

3.1.2.28.7.6.1 Ss7CircuitMap[pcm] 624

3.1.2.28.7.7 Advanced Configuration Item for TUP. 624

3.1.2.28.7.7.1 Setting Range Field in Circuit Group Message. 624

3.1.2.28.7.7.1.1 SendGRMRange. 624

3.1.2.28.7.7.1.2 HangupRingSendCBK. 625

3.1.2.28.7.7.2 Incoming Call: Customizing ACM Message. 625

3.1.2.28.7.7.2.1 DefaultACM.. 625

3.1.2.28.7.7.3 Incoming Call: Customizing GRQ Message. 625

3.1.2.28.7.7.3.1 ReqTypeIndicators. 625

3.1.2.28.7.7.4 Outgoing Call: Customizing IAI/IAM Message. 626

3.1.2.28.7.7.4.1 ConnectReqMsg. 626

3.1.2.28.7.7.4.2 CalloutIAM_CAT. 626

3.1.2.28.7.7.4.3 CalloutIAM_MsgPntr 627

3.1.2.28.7.7.4.4 CallingIndicatorBit 628

3.1.2.28.7.7.4.5 OriginalCalleeAddrInd. 628

3.1.2.28.7.7.4.6 CallerAddrInd. 629

3.1.2.28.7.7.5 Outgoing Call: Setting Way to Reply with GRQ Message. 629

3.1.2.28.7.7.5.1 AutoSendGSM.. 629

3.1.2.28.7.7.6 Not Using SynCTI-provided TUP State Machine. 629

3.1.2.28.7.7.6.1 AutoHandleTup. 629

3.1.2.28.7.7.7 Outputting Debugging Information. 630

3.1.2.28.7.7.7.1 DebugViewTupCallProc. 630

3.1.2.28.7.8 Advanced Configuration Item for ISUP. 630

3.1.2.28.7.8.1 Incoming Call: Customizing Message Type Used by Local End to Reply Incoming Call 630

3.1.2.28.7.8.1.1 DefaultCalledPickupMsg. 630

3.1.2.28.7.8.2 Incoming Call: Customizing Backward Call Indicator 630

3.1.2.28.7.8.2.1 DefaultBackwardCallInd. 630

3.1.2.28.7.8.3 Incoming Call: Customizing REL Message. 631

3.1.2.28.7.8.3.1 DefaultHangupRELInd. 631

3.1.2.28.7.8.3.2 DefaultCauseInd. 632

3.1.2.28.7.8.4 Incoming Call: Setting Other Parameters. 633

3.1.2.28.7.8.4.1 SaveRGNTo1stPhoNumStr 633

3.1.2.28.7.8.5 Outgoing Call: Customizing IAM Message. 633

3.1.2.28.7.8.5.1 DefaultNatureOfConnectionInd. 633

3.1.2.28.7.8.5.2 DefaultIAM_ForwardCallInd. 633

3.1.2.28.7.8.5.3 DefaultIAM_CAT. 633

3.1.2.28.7.8.5.4 DefaultIAM_TransmissionMediumRequirment 633

3.1.2.28.7.8.5.5 DefaultIAM_CalleeParam.. 634

3.1.2.28.7.8.5.6 DefaultIAM_CallerParam.. 634

3.1.2.28.7.8.5.7 DefaultIAM_OriginalCalleeParam.. 635

3.1.2.28.7.8.5.8 DefaultIAM_RedirectingNumber 635

3.1.2.28.7.8.5.9 bSubscriberSI 636

3.1.2.28.7.8.5.10 SubscriberSI 636

3.1.2.28.7.8.5.11 bOptionalFCI 636

3.1.2.28.7.8.5.12 OptionalFCI 636

3.1.2.28.7.8.5.13 Usr2UsrInfo. 637

3.1.2.28.7.8.5.14 LocationNumber 637

3.1.2.28.7.8.6 Outgoing Call: Setting Way to Reply with INF Message. 637

3.1.2.28.7.8.6.1 AutoSendINF. 637

3.1.2.28.7.8.7 Not Using SynCTI-provided ISUP State Machine. 637

3.1.2.28.7.8.7.1 AutoHandleIsup. 637

3.1.2.28.7.8.7.2 CircuitReset 638

3.1.2.28.7.9 Advanced Configuration Item for SCCP. 638

3.1.2.28.7.9.1 AutoHandleSccp. 638

3.1.2.28.7.10 Setting Way to Output SS7 MSU. 638

3.1.2.28.7.10.1 GetMsuOnAutoHandle. 638

3.1.2.28.7.11 Setting Way to Handle SS7 MTP2 MSU. 638

3.1.2.28.7.11.1 AppHandleMtp2Msu. 638

3.1.2.28.8 Advanced Setting for ISDN. 639

3.1.2.28.8.1 Setting ISDN Processing Mode. 639

3.1.2.28.8.1.1 AutoHandleIsdn. 639

3.1.2.28.8.2 Setting Parameters for User-side/Network-side Digital Trunk. 639

3.1.2.28.8.2.1 UserCrcMode. 639

3.1.2.28.8.2.2 NetCrcMode. 639

3.1.2.28.8.2.3 UserChIdentify. 639

3.1.2.28.8.2.4 NetChIdentify. 639

3.1.2.28.8.2.5 UserVoiceFormat 640

3.1.2.28.8.2.6 NetVoiceFormat 640

3.1.2.28.8.2.7 UserRestarTime. 640

3.1.2.28.8.2.8 NetRestarTime. 640

3.1.2.28.8.2.9 UserEstablishTime. 640

3.1.2.28.8.2.10 NetEstablishTime. 641

3.1.2.28.8.3 Setting Parameters for Outgoing Call 641

3.1.2.28.8.3.1 UserCalledNoSet 641

3.1.2.28.8.3.2 NetCalledNoSet 641

3.1.2.28.8.3.3 UserCallingNoSet 641

3.1.2.28.8.3.4 NetCallingNoSet 641

3.1.2.28.8.3.5 UserNumIsFull 642

3.1.2.28.8.3.6 NetNumIsFull 642

3.1.2.28.8.3.7 UserChPreference. 642

3.1.2.28.8.3.8 NetChPreference. 642

3.1.2.28.8.3.9 UserHighLayerCompatible. 642

3.1.2.28.8.3.10 NetHighLayerCompatible. 642

3.1.2.28.8.3.11 UserLowLayerCompatible. 643

3.1.2.28.8.3.12 NetLowLayerCompatible. 643

3.1.2.28.8.3.13 UserDialTime. 643

3.1.2.28.8.3.14 NetDialTime. 643

3.1.2.28.8.3.15 TransferCapability. 643

3.1.2.28.8.3.16 PresentNumber 644

3.1.2.28.8.3.17 UserT303. 644

3.1.2.28.8.3.18 NetT303. 644

3.1.2.28.8.3.19 UserT304. 644

3.1.2.28.8.3.20 NetT304. 644

3.1.2.28.8.3.21 UserWaitAfterCallProceeding. 644

3.1.2.28.8.3.22 UserTxCallingPartyNum.. 645

3.1.2.28.8.3.23 NetTxCallingPartyNum.. 645

3.1.2.28.8.3.24 NetWaitAfterCallProceeding. 645

3.1.2.28.8.4 Setting Parameters for Incoming Call 645

3.1.2.28.8.4.1 UserSideDefaultAckTimer 645

3.1.2.28.8.4.2 UserSideDefaultAck. 645

3.1.2.28.8.4.3 NetSideDefaultAckTimer 645

3.1.2.28.8.4.4 NetSideDefaultAck. 646

3.1.2.28.8.4.5 UserIsReceivePhoNum.. 646

3.1.2.28.8.4.6 NetIsReceivePhoNum.. 646

3.1.2.28.8.4.7 UserIsSendChIdentify. 646

3.1.2.28.8.4.8 NetIsSendChIdentify. 647

3.1.2.28.8.4.9 UserT302. 647

3.1.2.28.8.4.10 NetT302. 647

3.1.2.28.8.4.11 UserT313. 647

3.1.2.28.8.4.12 ProgressExt 647

3.1.2.28.8.5 Setting Timers. 648

3.1.2.28.8.5.1 UserT305. 648

3.1.2.28.8.5.2 NetT305. 648

3.1.2.28.8.5.3 NetT306. 648

3.1.2.28.8.5.4 UserT308. 648

3.1.2.28.8.5.5 NetT308. 649

3.1.2.28.8.6 Setting Other Parameters. 649

3.1.2.28.8.6.1 WaitHangupTime. 649

3.1.2.28.8.6.2 UserStatusReason. 649

3.1.2.28.8.6.3 NetStatusReason. 649

3.1.2.28.8.6.4 EnAutoAlert02. 649

3.1.2.28.8.6.5 EnAutoAlert03. 650

3.1.2.28.9 Setting Way to Use DSP Chip. 650

3.1.2.28.9.1 LoadFskBin. 650

3.1.2.29 Common Configuration Item for SHN Series (CTI Series) 650

3.1.2.29.1 Advanced General Settings for SHN Series. 650

3.1.2.29.1.1 EnableSIPStun. 650

3.1.2.29.1.2 SIPStunServerIP. 651

3.1.2.29.1.3 LogLevel 651

3.1.2.29.1.4 LogFile. 651

3.1.2.29.1.5 EventThreadNum.. 651

3.1.2.29.1.6 SipCallCheckInterval 651

3.1.2.29.1.7 SendOptionsOutCallIP. 651

3.1.2.29.1.8 SendOptionsOutCallInterval 651

3.1.2.29.1.9 HeartInterval 651

3.1.2.29.1.10 SipTransportProtocol 652

3.1.2.29.1.11 UserName. 652

3.1.2.29.1.12 RegPassword. 652

3.1.2.29.1.13 Domain. 652

3.1.2.29.1.14 RegRealm.. 652

3.1.2.29.1.15 RegExpires. 652

3.1.2.29.1.16 RegStartCh. 652

3.1.2.29.1.17 RegEndCh. 653

3.1.2.29.1.18 SipTotalMultiRegNum.. 653

3.1.2.29.2 SHN A Series. 655

3.1.2.29.2.1 Advanced Setting for SHN A Series. 655

3.1.2.29.2.1.1 Setting RTP Traversal through NAT and SIP Server 655

3.1.2.29.2.1.1.1 EnableRTPStun. 655

3.1.2.29.2.1.1.2 StunServerIP. 655

3.1.2.29.2.1.1.3 Register 655

3.1.2.29.2.1.1.4 UserName. 655

3.1.2.29.2.1.1.5 RegPassword. 655

3.1.2.29.2.1.1.6 Domain. 655

3.1.2.29.2.1.1.7 RegExpires. 655

3.1.2.29.2.1.1.8 RegRealm.. 655

3.1.2.29.3 SHN B Series. 656

3.1.2.29.3.1 Advanced Setting for SHN B Series. 656

3.1.2.29.3.1.1 Setting RTP Traversal through NAT and SIP Server 656

3.1.2.29.3.1.1.1 EnableRTPStun. 656

3.1.2.29.3.1.1.2 StunServerIP. 656

3.1.2.29.3.1.1.3 Register 656

3.1.2.29.3.1.1.4 UserName. 656

3.1.2.29.3.1.1.5 RegPassword. 656

3.1.2.29.3.1.1.6 Domain. 657

3.1.2.29.3.1.1.7 RegExpires. 657

3.1.2.29.3.1.1.8 RegRealm.. 657

3.1.2.29.3.1.2 Setting RTP Payload. 657

3.1.2.29.3.1.2.1 SizeG711A. 657

3.1.2.29.3.1.2.2 SizeG711U. 657

3.1.2.29.3.1.2.3 SizeG729. 658

3.1.2.30 Common Configuration Items for DST Series (REC Series) 658

3.1.2.30.1 SupplyBoardClockLine. 658

3.1.2.30.2 DEventUpdates. 658

3.1.2.31 Common Configuration Items for ATP Series (REC Series) 658

3.1.2.31.1 Setting Input Signal Gain. 658

3.1.2.31.1.1 MicGain. 658

3.1.2.31.2 Setting Idle Channel’s Capability of Energy Detection. 659

3.1.2.31.2.1 EnableIdleChTA. 659

3.1.2.31.3 Acquiring More Recording Formats. 659

3.1.2.31.3.1 DspCoder 659

3.1.2.31.4 Setting Prerecord Feature. 660

3.1.2.31.4.1 PrerecordEnable. 660

3.1.2.31.4.2 PrerecordMode. 660

3.1.2.31.4.3 PrerecordInsertTime. 660

3.1.2.31.4.4 PrerecordCodec. 661

3.1.2.31.5 Detecting Dial Pulse. 661

3.1.2.31.5.1 EnablePulseKeyDetect 661

3.1.2.31.6 Setting Maximum Duration of Flash Signal 661

3.1.2.31.6.1 MaxRecChFlashFilterTime. 661

3.1.2.31.7 Setting Guard Time for Clearing Ringing Signal Counter 661

3.1.2.31.7.1 RecChClearRingDelayTime. 661

3.1.2.31.8 Setting Soft-switch Feature. 662

3.1.2.31.8.1 BusPlayListen. 662

3.1.2.31.9 Setting MF detector 662

3.1.2.31.9.1 MFDualAndAllFreqEnScale. 662

3.1.2.31.9.2 MFFreqOffset 662

3.1.2.31.9.3 DTMFFreqOffset 662

3.1.2.32 Common Configuration Items for DTP Series (REC Series) 663

3.1.2.32.1 Saving Monitoring Message to File. 663

3.1.2.32.2 Setting Signaling Message Output by SS7 State Machine. 663

3.1.2.32.2.1 bOpenSpySS7Msu. 663

3.1.2.32.3 Supporting CorNet Protocol for ISDN Monitoring. 663

3.1.2.32.3.1 ISDNProtocolType. 663

3.1.3 Advanced Configuration Items. 663

3.1.3.1 Multi-program Support 663

3.1.3.1.1 MultiCardMultiProcess. 663

3.1.3.2 Outputting API Debugging Information. 664

3.1.3.2.1 ApiLogEnable. 664

3.1.3.2.2 ApiLogSetEventRange. 664

3.1.3.2.3 ApiLogSetChRange. 664

3.1.3.2.4 ApiLogCreateMode. 665

3.1.3.2.5 Mask_SsmGetNoSoundTime. 665

3.1.3.2.6 Mask_SsmGetChStateKeepTime. 665

3.1.3.2.7 Mask_SsmGetPlayedTime. 665

3.1.3.2.8 Mask_SsmGetPlayedPercentage. 665

3.1.3.2.9 Mask_SsmGetPlayOffset 665

3.1.3.2.10 Mask_SsmGetRecTime. 665

3.1.3.2.11 Mask_SsmGetRecOffset 666

3.1.3.3 Setting ISDN Connection Log. 666

3.1.3.3.1 IsdnLogEnable. 666

3.1.3.3.2 DecodeIsdnMsg. 666

3.1.3.3.3 IsdnDebugLog. 667

3.1.3.4 Setting SS1 Connection Log. 667

3.1.3.4.1 Ss1LogEnable. 667

3.1.3.4.2 Ss1LogCreateMode. 667

3.1.3.5 Setting SS1 Monitoring Log. 667

3.1.3.5.1 SpySs1LogEnable. 667

3.1.3.5.2 SpySs1CreateMode. 668

3.1.3.6 Setting SS7 Monitoring Log. 668

3.1.3.6.1 SpySs7LogEnable. 668

3.1.3.7 Setting ISDN Monitoring Log. 668

3.1.3.7.1 SpyIsdnLogEnable. 668

3.1.3.8 Setting PCM Link Information Monitoring Log. 668

3.1.3.8.1 PcmLinkInfoLogEnable. 668

3.1.3.9 Setting Control Information for Log Creating. 669

3.1.3.9.1 LogCreatePeriod. 669

3.1.3.9.2 LogMaxKeep. 669

3.1.3.9.3 LogMaxPeriod. 670

3.1.3.9.4 LogFilePath. 670

3.1.3.9.5 LogOverWrite. 671

3.1.3.9.6 CreateDumpWhenCrash. 671

3.2 Preload Voice Configuration File ShIndex.ini (CTI Series) 672

3.2.1 [System] Section. 672

3.2.1.1 MaxIndexSeg. 672

3.2.2 [SegNo=x] Section. 672

3.2.2.1 FileName. 672

3.2.2.2 Alias. 672

3.2.2.3 CodecFormat 672

3.2.2.4 StartOffset 673

3.2.2.5 Length. 673

4 SS7 (CTI Series) 674

4.1 Basic Concepts. 674

4.1.1 OPC & DPC.. 674

4.1.2 Associated Mode & Quasi-associated Mode. 674

4.1.3 Signaling Link & Signaling Link Set 675

4.2 SS7 Application System Based on Synway Board. 675

4.3 SS7 Server Configuration. 676

4.3.1 Setting Signaling Point Code. 679

4.3.1.1 OPC.. 679

4.3.1.2 SpCodeLen. 680

4.3.2 Setting IP Address. 680

4.3.2.1 ServerIP. 680

4.3.2.2 SecondServerIP. 680

4.3.2.3 Port 680

4.3.3 Setting Operating Mode and Parameters for MTP3 Layer 680

4.3.3.1 ConfigMtp3AsSTP. 680

4.3.3.2 SendSNT. 680

4.3.3.3 SubServicefield. 681

4.3.4 Setting Client Information. 681

4.3.4.1 MaxSs7Client 681

4.3.4.2 IP. 681

4.3.5 Setting Physical Position of Signaling Link. 682

4.3.5.1 MaxSs7Pcm.. 682

4.3.5.2 Ss7PcmLink. 682

4.3.6 Setting Signaling Link Set 682

4.3.6.1 MaxLinkSet 682

4.3.6.2 LinkSet 682

4.3.7 Setting DPC.. 683

4.3.7.1 MaxDPC.. 683

4.3.7.2 DPC.. 683

4.3.8 Setting DPC for User Layer Messages. 684

4.3.8.1 MaxUP_DPC.. 684

4.3.8.2 UP_DPC.. 684

4.3.9 Setting Route to Distribute TUP/ISUP Messages. 684

4.3.9.1 UP_DPC.. 684

4.3.9.2 CIC_PCM.. 684

4.3.9.3 DPC.. 685

4.3.10 Setting Way to Start SS7 Server 685

4.3.10.1 ConfigAsGateway. 685

4.3.11 Setting Display Ability of SS7 Server 686

4.3.11.1 RcvMsuListMaxItem.. 686

4.3.11.2 TxMsuListMaxItem.. 686

4.3.12 Special Configuration Item for Linux SS7 Server 686

4.3.12.1 ShowMSU. 686

4.3.12.2 ShowStatus. 686

4.3.12.3 ShowSNT. 687

4.3.12.4 ShowSNM.. 687

4.3.12.5 AutoTranslate. 687

4.3.13 One Ss7Monitor Supporting Multiple Clients. 687

4.4 Application and Configuration Instance for SS7 Server 688

4.4.1 Single OPC/Single DPC.. 688

4.4.1.1 Single-PC-Single-Board System.. 688

4.4.1.2 Single-PC-Multi-Board System.. 689

4.4.1.3 Multi-PC System.. 690

4.4.1.4 Multi-PC System with Separate SS7 Server 691

4.4.2 Single OPC/Multiple DPC.. 692

4.4.3 SS7 Application System with Multiple OPC.. 693

4.4.4 High-reliability Application System.. 694

4.4.5 Supplying SS7 Service for Third-party Board. 696

4.4.6 Application System in Quasi-associated Mode. 698

Appendix 1 ISDN Release Cause Information Element 700

Appendix 2 ISUP Parameters. 703


Copyright Declaration

This manual is provided by Synway Information Engineering Co., Ltd (hereinafter referred to as ‘Synway’) as the support file for the Synway board driver software ( ‘SynCTI’ ). Both the software and this manual are copyrighted and protected by the laws of the People's Republic of China.

All rights reserved; no part of this manual may be extracted, modified, copied, reproduced or transmitted in any form or by any means, electronic or mechanical, without prior written permission from Synway. By using this manual, you agree to the following Software License Agreement.

Synway reserves the right to revise this manual without prior note. Please contact Synway for the latest version of this manual before placing an order.

Synway has made every effort to ensure the accuracy of this manual but does not guarantee the absence of errors. Moreover, Synway assumes no responsibility in obtaining permission and authorization of any third party patent, copyright or product involved in relation to the use of this manual.

Note: Windows, Windows 2000, Windows XP and etc. mentioned in this book are registered trademarks of Microsoft Corporation, and Dialogic is of Intel Corporation.


SynCTI Driver Software License Agreement

1. Synway Information Engineering Co., Ltd (hereinafter referred to as ‘Synway’) owns the copyright of ‘this software and its accessories, relative files and archives’ (hereinafter referred to as ‘this product’). No organization, enterprise, agency or individual may use this product without our authorization.

2. We authorize those who achieve the following two requirements to use this product for free:

A. Using this product with hardware products purchased from Synway through a legitimate marketing channel;

B. Promising not to transmit the whole or part of this product to any third party without prior permission from Synway.

3. Any organization, enterprise, agency or individual, except as otherwise subject to the second article of this license agreement, must obtain the written permission from Synway before using this product.

4. The authorized organizations, enterprises or individuals have no right to transfer the authorization.

5. The use of this product indicates that you have fully understood and accepted all terms in this license.


Revision History

Version | Date | Comments
Version 2.0 | 2001-12 | Initial publication
Version 3.0.0.0 | 2003-07 | Significant revision
Version 4.7.3.0 | 2006-12 | Significant revision
Version 4.8.0.0 | 2007-07 | Significant revision
Version 4.8.0.1 | 2007-08 | No modification
Version 4.9.0.0 | 2007-10 | Significant revision
Version 5.0.0.0 | 2007-12 | Significant revision
Version 5.0.1.0 | 2008-04 | Significant revision
Version 5.0.2.0 | 2008-08 | Significant revision
Version 5.0.3.0 | 2009-01 | Significant revision
Version 5.0.4.0 | 2009-05 | Significant revision
Version 5.0.5.0 | 2009-07 | Significant revision
Version 5.1.0.0 | 2009-11 | Significant revision
Version 5.1.1.0 | 2009-12 | Significant revision
Version 5.2.0.0 | 2010-06 | Significant revision
Version 5.2.0.1 | 2010-08 | Significant revision
Version 5.2.0.2 | 2010-08 | Significant revision
Version 5.2.0.3 | 2010-10 | Significant revision
Version 5.3.0.0 | 2010-12 | Significant revision
Version 5.3.0.1 | 2011-01 | Significant revision
Version 5.3.0.2 | 2011-03 | Significant revision
Version 5.3.0.3 | 2011-04 | Significant revision
Version 5.3.0.4 | 2011-04 | Significant revision
Version 5.3.1.0 | 2011-07 | Significant revision
Version 5.3.1.1 | 2011-10 | Significant revision
Version 5.3.1.2 | 2011-12 | Significant revision

Note: Only major revisions to this manual itself recorded herein. For detailed information about the documentation modification undergone with the upgrade of the SynCTI Driver Program, refer to the corresponding version of SynCTI Upgrade Manual.


Preface

Thank you for choosing the Synway boards. SynCTI is a unified driver program for the Synway boards. This manual, as the biggest help file for SynCTI, aims at those software engineers dedicated to API development and application. It can also be provided as a reference book for the salesmen as well as the installation and maintenance technicians who are using products from Synway to set up the CTI application system.

We offer the SynCTI - a unified driver program and development platform – to serve as the link between the Synway board hardware and software. SynCTI provides a unified API interface for its various board models so that the application system based on certain model can be easily extended to different environments.

This document consists of four chapters.

Chapter 1 introduces the fundamental knowledge about programming for voice boards, covering the structure, classification, system set-up of the Synway boards and the SynCTI driver program, the operation procedure and the precaution on it. Readers will get to know what the board can do and how to enable all board features via API functions after they read through this chapter. We suggest those who are in the first use of our products to read this chapter carefully before programming. You can surely skip over the content in no relation with your application. For example, if your application is for processing analog phone lines, you can ignore the words about digital trunks.

Chapter 2 elaborates the SynCTI’s API functions, driver-generated events and relative data structures.

Chapter 3 describes all configuration items in detail for the SynCTI driver program and classifies them by function. Each function has the necessary configuration items as well as the advanced ones which are generally used to meet requirements from a few of particular environments and users.

Chapter 4 tells you how to configure and use the SS7 system.

Although Synway has scrupulously checked through this manual, but cannot guarantee the absence of errors and omissions. We sincerely apologize for any consequent inconvenience brought to you and will be very grateful if you kindly give your advice regarding amendments to this book.


1 Basic Knowledge on Synway Board Programming


1.1 Board Classification (CTI Series)

The Synway boards are divided into two categories: the CTI Series and the REC Series. The former serves as one party of a call in communication while the latter is the call-recording board mainly used for high-impedance recording in parallel. Both drivers for the CTI Series and the REC Series are contained in SynCTI.

The CTI Series includes four subseries:

SubSeries Name | Description
SHT | Use modular structure and analog lines.
SHD | Use digital trunks (E1/T1/J1).
SHV | Voice-alteration boards
SHN | VoIP boards

Below is a detailed list of board models in each subseries:

SubSeries | Bus | Board Model | Comments
SHT | USB | SHT-2A/USB | Referred to as ‘USB Voice Box’ for short
 |  | SHT-4A/USB
 |  | SHT-2B/USB
 |  | SHT-4B/USB
 | PCI | SHT-8A/PCI |
 |  | SHT-16A-CT/PCI |
 |  | SHT-120A-CT/PCI | Production stopped
 |  | SHT-8B/PCI |
 |  | SHT-8B/PCI/FAX |
 |  | SHT-16B-CT/PCI |
 |  | SHT-16B-CT/PCI/FAX |
 |  | SHT-16B-CT/PCI/MP3 |
 |  | SHT-8C/PCI/FAX |
 |  | SHT-8C/PCI/EC |
 |  | SHT-16C-CT/PCI/FAX |
 |  | SHT-16C-CT/PCI/EC |
 | cPCI | SHT-120A-CT/cPCI | Production stopped
 |  | SHT-16B-CT/cPCI |
 |  | SHT-16B-CT/cPCI/FAX |
 |  | SHT-16B-CT/cPCI/MP3 |
SHD | PCI | SHD-30A-CT/PCI/SS1 | SS1 support
 |  | SHD-30A-CT/PCI/ISDN | SS1, ISDN support
 |  | SHD-30A-CT/PCI/SS7 | SS1, ISDN, SS7 support
 |  | SHD-60A-CT/PCI/SS1 | SS1 support
 |  | SHD-60A-CT/PCI/ISDN | SS1, ISDN support
 |  | SHD-60A-CT/PCI/SS7 | SS1, ISDN, SS7 support
 |  | SHD-120A-CT/PCI/SS1 | SS1 support
 |  | SHD-120A-CT/PCI/ISDN | SS1, ISDN support
 |  | SHD-120A-CT/PCI/SS7 | SS1, ISDN, SS7 support
 |  | SHD-30B-CT/PCI/SS7/FAX | SS1, ISDN, SS7 support
 |  | SHD-60B-CT/PCI/SS7/FAX | SS1, ISDN, SS7 support
 |  | SHD-30C-CT/PCI | E1: SS1, ISDN, SS7 support; T1: ISDN support
 |  | SHD-30C-CT/PCI/FAX | E1: SS1, ISDN, SS7 support; T1: ISDN support
 |  | SHD-60C-CT/PCI | E1: SS1, ISDN, SS7 support; T1: ISDN support
 |  | SHD-60C-CT/PCI/FAX | E1: SS1, ISDN, SS7 support; T1: ISDN support
 |  | SHD-120D-CT/PCI | E1: SS1, ISDN, SS7 support; T1: ISDN support
 |  | SHD-120D-CT/PCI/EC | E1: SS1, ISDN, SS7 support; T1: ISDN support
 |  | SHD-120D-CT/PCI/CAS | SS1 support
 |  | SHD-240D-CT/PCI | E1: SS1, ISDN, SS7 support; T1: ISDN support
 |  | SHD-240D-CT/PCI/EC | E1: SS1, ISDN, SS7 support; T1: ISDN support
 |  | SHD-240D-CT/PCI/CAS | SS1 support
 |  | SHD-30E-CT/PCI(ssw) | SS1 support; E1: SS1, ISDN, SS7 support; T1: ISDN support
 |  | SHD-30E-CT/PCI/FAX(ssw) | SS1 support; E1: SS1, ISDN, SS7 support; T1: ISDN support
 |  | SHD-30E-CT/PCI/EC(ssw) | SS1 support; E1: SS1, ISDN, SS7 support; T1: ISDN support
 |  | SHD-60E-CT/PCI(ssw) | SS1 support; E1: SS1, ISDN, SS7 support; T1: ISDN support
 |  | SHD-60E-CT/PCI/FAX(ssw) | SS1 support; E1: SS1, ISDN, SS7 support; T1: ISDN support
 |  | SHD-60E-CT/PCI/EC(ssw) | SS1 support; E1: SS1, ISDN, SS7 support; T1: ISDN support
 |  | SHD-120E-CT/PCI(ssw) | SS1 support; E1: SS1, ISDN, SS7 support; T1: ISDN support
 |  | SHD-120E-CT/PCI/FAX(ssw) | SS1 support; E1: SS1, ISDN, SS7 support; T1: ISDN support
 |  | SHD-120E-CT/PCI/EC(ssw) | SS1 support; E1: SS1, ISDN, SS7 support; T1: ISDN support
 |  | SHD-240E-CT/PCI(ssw) | SS1 support; E1: SS1, ISDN, SS7 support; T1: ISDN support
 |  | SHD-240E-CT/PCI/FAX(ssw) | SS1 support; E1: SS1, ISDN, SS7 support; T1: ISDN support
 |  | SHD-240E-CT/PCI/EC(ssw) | SS1 support; E1: SS1, ISDN, SS7 support; T1: ISDN support
 | PCIe | SHD-30E-CT/PCIe | E1: SS1, ISDN, SS7 support; T1: ISDN support
 |  | SHD-30E-CT/PCIe/FAX | E1: SS1, ISDN, SS7 support; T1: ISDN support
 |  | SHD-30E-CT/PCIe/EC | E1: SS1, ISDN, SS7 support; T1: ISDN support
 |  | SHD-60E-CT/PCIe | E1: SS1, ISDN, SS7 support; T1: ISDN support
 |  | SHD-60E-CT/PCIe/FAX | E1: SS1, ISDN, SS7 support; T1: ISDN support
 |  | SHD-60E-CT/PCIe/EC | E1: SS1, ISDN, SS7 support; T1: ISDN support
 |  | SHD-120E-CT/PCIe | E1: SS1, ISDN, SS7 support; T1: ISDN support
 |  | SHD-120E-CT/PCIe/FAX | E1: SS1, ISDN, SS7 support; T1: ISDN support
 |  | SHD-120E-CT/PCIe/EC | E1: SS1, ISDN, SS7 support; T1: ISDN support
 |  | SHD-240E-CT/PCIe | E1: SS1, ISDN, SS7 support; T1: ISDN support
 |  | SHD-240E-CT/PCIe/FAX | E1: SS1, ISDN, SS7 support; T1: ISDN support
 |  | SHD-240E-CT/PCIe/EC | E1: SS1, ISDN, SS7 support; T1: ISDN support
 | cPCI | SHD-30A-CT/cPCI/SS7 | SS1, ISDN, SS7 support
 |  | SHD-60A-CT/cPCI/SS7 | SS1, ISDN, SS7 support
 |  | SHD-120A-CT/cPCI/SS7 | SS1, ISDN, SS7 support
 |  | SHD-240A-CT/cPCI | SS7 support
 |  | SHD-480A-CT/cPCI | SS7 support
 |  | SHD-30B-CT/cPCI/SS7/FAX | SS1, ISDN, SS7 support
 |  | SHD-60B-CT/cPCI/SS7/FAX | SS1, ISDN, SS7 support
 |  | SHD-240S-CT/cPCI | SS7 support
 |  | SHD-480S-CT/cPCI | SS7 support
SHV | PCI | SHV-120A-CT/PCI |
 |  | SHV-240A-CT/PCI |
 |  | SHV-240A-CT/cPCI |
SHN | PCI | SHN-32A-CT/PCI | SIP support
 |  | SHN-8B-CT/PCI+ | SIP support
 |  | SHN-16B-CT/PCI+ | SIP support
 |  | SHN-32B-CT/PCI+ | SIP support
 |  | SHN-60B-CT/PCI+ | SIP support
 |  | SHN-120B-CT/PCI+ | SIP support


1.2 Board Classification (REC Series)

The Synway boards are divided into two categories: the CTI Series and the REC Series. The former serves as one party of a call in communication while the latter is the call-recording board mainly used for high-impedance recording in parallel. Both drivers for the CTI Series and the REC Series are contained in SynCTI.

The REC Series includes four subseries:

SubSeries Name | Description
ATP | Use modular structure, applicable to high-impedance parallel recording of analog phone lines or other analog voice signals.
DTP | Support SS1/ISDN/SS7, applicable to high-impedance parallel recording of digital trunks simultaneously over signaling links and voice channels.
DST | Applicable to high-impedance parallel recording of digital phone lines (2B+D).
SHF | Decode the fax data recorded into voice files and obtain the actual fax image, generally used as accessories for the REC Series boards.

Below is a detailed list of board models in each subseries:

SubSeries | Bus | Board Model | Comments
ATP | USB | SHT-2A/USB | Referred to as ‘USB Recording Box’ for short
 |  | SHT-4A/USB
 |  | SHT-2B/USB
 |  | SHT-4B/USB
 | PCI | SHT-8A/PCI |
 |  | SHT-8B/PCI |
 |  | SHT-16A-CT/PCI |
 |  | SHT-16B-CT/PCI |
 |  | SHT-16B-CT/PCI/MP3 | Hardware-based MP3 encoding support
 |  | ATP-24A/PCI |
 |  | ATP-24A/PCI+ | Hardware-based GSM or G.729A encoding support
 | PCIe | ATP-24A/PCIe |
 |  | ATP-24A/PCIe+ | Hardware-based GSM or G.729A encoding support
 | cPCI | SHT-16B-CT/cPCI |
 |  | SHT-16B-CT/cPCI/MP3 | Hardware-based MP3 encoding support
DTP | PCI | SHD-30A-CT/PCI/FJ | With on-board high-impedance input circuit
 |  | SHD-60A-CT/PCI/FJ | With on-board high-impedance input circuit
 |  | SHD-30B-CT/PCI/FJ | With on-board high-impedance input circuit
 |  | SHD-60B-CT/PCI/FJ | With on-board high-impedance input circuit
 |  | DTP-30C/PCI | With on-board high-impedance input circuit
 |  | DTP-30C/PCI+ | With on-board high-impedance input circuit
 |  | DTP-60C/PCI | With on-board high-impedance input circuit
 |  | DTP-60C/PCI+ | With on-board high-impedance input circuit
 |  | DTP-120C/PCI | With on-board high-impedance input circuit
 |  | DTP-120C/PCI+ | With on-board high-impedance input circuit
 | PCIe | DTP-30C/PCIe | With on-board high-impedance input circuit
 |  | DTP-30C/PCIe+ | With on-board high-impedance input circuit
 |  | DTP-60C/PCIe | With on-board high-impedance input circuit
 |  | DTP-60C/PCIe+ | With on-board high-impedance input circuit
 |  | DTP-120C/PCIe | With on-board high-impedance input circuit
 |  | DTP-120C/PCIe+ | With on-board high-impedance input circuit
DST | PCI | SHR-16DA-CT/PCI | PCI-X bus support
 |  | SHR-24DA-CT/PCI | PCI-X bus support
 |  | DST-24B/PCI |
 |  | DST-24B/PCI(SSW) |
 |  | DST-24B/PCI+ | Hardware-based GSM, MP3 or G.729A encoding support
 |  | DST-24B/PCI+(SSW) | Hardware-based GSM, MP3 or G.729A encoding support
 | PCIe | DST-24B/PCIe |
 |  | DST-24B/PCIe+ | Hardware-based GSM, MP3 or G.729A encoding support


1.3 SynCTI Supported CODECs

The following table displays all voice CODECs supported by the Synway boards and their characteristics.

CODEC | Abbreviation | Sampling Rate | bps | bytes/frame | bytes/sec | CODEC Engine | Coding Value
Unsigned 8-bit PCM | PCM8 | 8000 Hz | 64 Kbps | 1 | 8000 | Host CPU | 1
16-bit linear PCM | PCM16 | 8000 Hz | 128 Kbps | 2 | 16000 | Host CPU | -2
A-law | A-law | 8000 Hz | 64 Kbps | 1 | 8000 | On-board DSP | 6
μ-law | μ-law | 8000 Hz | 64 Kbps | 1 | 8000 | On-board DSP | 7
IMA ADPCM | IMA ADPCM | 8000 Hz | 32 Kbps | 256 | 4055 | On-board DSP | 17
VOX | VOX | 8000 Hz | 32 Kbps | 256 | 4000 | On-board DSP | 23
MP3 | MP3 | 8000 Hz | 8 Kbps | 72 | 1000 | On-board DSP Host CPU | 85
GSM 6.10 | GSM | 8000 Hz | 13 Kbps | 65 | 1625 | Host CPU | 49
G.729A | G.729A | 8000 Hz | 8 Kbps | 10 | 1000 | On-board DSP | 131

Note:

(1) If the board is marked by ‘/MP3’ in the model, it uses on-board DSP chips as the CODEC engine; otherwise it uses host CPU.

(2) VOX refers to the ’ADPCM’ format used by Dialogic.

(3) Due to historical reasons, the coding value 65411 which ever represented G.729A is still valid in early versions and backward compatible. For G.729A recording in new versions, we suggest you use the coding value 131.


1.3.1 Transcoding Functions

ShPcmHandle.dll provides a number of transcoding functions which can be used without the need to initialize the SynCTI driver program first via the call of SsmStartCti . However, after the call of these functions, it is required to invoke fPcm_Close to release resources. See below for details.

Functions | Description
fPcm_Mp3ConvertALaw | Transcodes MP3 files which are recorded by the Synway board to A-law files.
fPcm_Mp3ConvertULaw | Transcodes MP3 files to μ-law files.
fPcm_AdpcmToAlaw | Transcodes IMA ADPCM files which are recorded by the Synway board to A-law files.
fPcm_AdpcmToGsm | Transcodes IMA ADPCM files to GSM 6.10 files.
fPcm_AdpcmToMp3 | Transcodes IMA ADPCM files to MP3 files.
fPcm_AlawToUlaw | Transcodes A-Law files recorded by the Synway board to µ-Law files.
fPcm_UlawToAlaw | Transcodes µ-Law files recorded by the Synway board to A-Law files.
fPcm_MemAdpcmToALAW | Transcodes the IMA ADPCM data which are recorded by the Synway board and saved in the buffer to A-law format.
fPcm_MemAdpcmToULAW | Transcodes the IMA ADPCM data which are recorded by the Synway board and saved in the buffer to μ-law format.
fPcm_AlawConvertPcm16 | Transcodes A-law files to 16-bit linear PCM format.
fPcm_ALawConvertPcm8 | Transcodes A-law files to unsigned 8-bit PCM format.
fPCM_AlawConvertGC8 | Transcodes A-law files to G.729A files.
fPcm_ALawConvertMp3 | Transcodes A-law files to MP3 files.
fPcm_ULawConvertMp3 | Transcodes µ-Law files to MP3 files.
fPcm_ALawToVox | Transcodes A-Law files to vox files.
fPcm_MemAlawToPcm8 | Transcodes A-law data saved in the buffer to unsigned 8-bit PCM format.
fPcm_MemAlawToPcm16 fPcm_MemMp3ToPcm16 | Transcodes A-law/MP3 data saved in the buffer to unsigned 16-bit PCM format.
fPcm_MemGSMToPcm16 | Transcodes GSM data saved in the buffer to 16-bit PCM format.
fPcm_MemGSMToPcm8 | Transcodes GSM data saved in the buffer to unsigned 8-bit PCM format.
fPcm_MemGSMToUlaw | Transcodes GSM data saved in the buffer to μ-law format.
fPcm_Pcm16ConvertALaw | Transcodes 16-bit linear PCM files to A-law files.
fPcm_MemPcm8ToAlaw | Transcodes unsigned 8-bit PCM data saved in the buffer to A-law format.
fPcm_MemAlawToUlaw | Transcodes A-Law data saved in the buffer to μ-law format.
fPcm_MemUlawtoAlaw | Transcodes μ-Law data saved in the buffer to A-Law format.
fPcm_MemPcm16ToAlaw | Transcodes unsigned 16-bit PCM data saved in the buffer to A-law format.
fPcm_GC8Convert | Tanscodes G.729A files to other formats.
fPcm_Vox6kTo8k fPcm_Vox8KTo6K | Enable the sampling rate of VOX files to convert between 6K and 8K.
fPcm_ULawConvertGSM | Transcodes µ-Law files to GSM files.
fPCM_Pcm16ConvertG729A | Transcodes 16-bit linear PCM files to G.729A files.
fPcm_Pcm8ConvertGSM | Transcodes 8-bit PCM files to GSM files.
fPcm_GSMToMp3 | Transcodes GSM files to MP3 files.
fPcm_G729AConvert | Tanscodes G.729A files to other formats.
fPCM_MemULawToG729A | Tanscodes μ-Law data saved in the buffer to G.729A format.


1.3.2 Board Supported CODECs

All CODECs supported by the Synway boards in voice playback and recording operation are shown as follows:

Sieries

Board Model

PCM8

PCM16

A-law

μ-law

IMA

ADPCM

VOX

MP3

GSM

G.729A

DEC

COD

DEC

COD

DEC

COD

DEC

COD

DEC

COD

DEC

COD

DEC

COD

DEC

COD

DEC

COD

SHT

SHT-2A/USB

☆

☆

☆

☆

Ö

Ö

Ö

Ö

－

－

Ö

Ö

★

★

★

★

★

－

SHT-4A/USB

☆

☆

☆

☆

Ö

Ö

Ö

Ö

－

－

Ö

Ö

★

★

★

★

★

－

SHT-2B/USB

☆

☆

☆

☆

Ö

Ö

Ö

Ö

－

－

Ö

Ö

★

★

★

★

★

－

SHT-4B/USB

☆

☆

☆

☆

Ö

Ö

Ö

Ö

－

－

Ö

Ö

★

★

★

★

★

－

SHT-8A/PCI

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

SHT-16A-CT/PCI

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

SHT-120A-CT/PCI

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

SHT-8B/PCI

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

SHT-8B/PCI/FAX

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

SHT-16B-CT/PCI

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

SHT-16B-CT/PCI/FAX

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

Ö

Ö

★

－

SHT-16B-CT/PCI/MP3

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

Ö

★

★

★

－

SHT-8C/PCI/FAX

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

SHT-8C/PCI/EC

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

SHT-16C-CT/PCI/FAX

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

SHT-16C-CT/PCI/EC

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

SHT-120A-CT/cPCI

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

SHT-16B-CT/cPCI

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

SHT-16B-CT/cPCI/FAX

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

SHT-16B-CT/cPCI/MP3

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

Ö

★

★

★

－

SHD

SHD-30A-CT/PCI/SS1

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

SHD-30A-CT/PCI/ISDN

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

SHD-30A-CT/PCI/SS7

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

SHD-60A-CT/PCI/SS1

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

SHD-60A-CT/PCI/ISDN

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

SHD-60A-CT/PCI/SS7

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

SHD-120A-CT/PCI/SS1

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

SHD-120A-CT/PCI/ISDN

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

SHD-120A-CT/PCI/SS7

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

SHD-30B-CT/PCI/SS7/FAX

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

SHD-60B-CT/PCI/SS7/FAX

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

SHD-30C-CT/PCI

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

SHD-30C-CT/PCI/FAX

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

SHD-60C-CT/PCI

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

SHD-60C-CT/PCI/FAX

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

SHD-120D-CT/PCI

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

SHD-120D-CT/PCI/EC

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

SHD-120D-CT/PCI/CAS

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

SHD-240D-CT/PCI

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

SHD-240D-CT/PCI/EC

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

SHD-240D-CT/PCI/CAS

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

SHD-30E-CT/PCI(ssw)

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

SHD-30E-CT/PCI/FAX(ssw)

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

SHD-30E-CT/PCI/EC(ssw)

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

SHD-60E-CT/PCI(ssw)

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

SHD-60E-CT/PCI/FAX(ssw)

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

SHD-60E-CT/PCI/EC(ssw)

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

SHD-120E-CT/PCI(ssw)

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

SHD-120E-CT/PCI/FAX(ssw)

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

SHD-120E-CT/PCI/EC(ssw)

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

SHD-240E-CT/PCI(ssw)

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

SHD-240E-CT/PCI/FAX(ssw)

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

SHD-240E-CT/PCI/EC(ssw)

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

SHD-30E-CT/PCIe

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

SHD-30E-CT/PCIe/FAX

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

SHD-30E-CT/PCIe/EC

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

SHD-60E-CT/PCIe

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

SHD-60E-CT/PCIe/FAX

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

SHD-60E-CT/PCIe/EC

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

SHD-120E-CT/PCIe

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

SHD-120E-CT/PCIe/FAX

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

SHD-120E-CT/PCIe/EC

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

SHD-240E-CT/PCIe

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

SHD-240E-CT/PCIe/FAX

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

SHD-240E-CT/PCIe/EC

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

SHD-30A-CT/cPCI/SS7

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

SHD-60A-CT/cPCI/SS7

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

SHD-120A-CT/cPCI/SS7

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

SHD-240A-CT/cPCI

☆

☆

☆

☆

Ö

Ö

Ö

Ö

－

－

Ö

Ö

★

★

★

★

★

－

SHD-480A-CT/cPCI

☆

☆

☆

☆

Ö

Ö

Ö

Ö

－

－

Ö

Ö

★

★

★

★

★

－

SHD-30B-CT/cPCI/SS7/FAX

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

SHD-60B-CT/cPCI/SS7/FAX

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

SHD-240S-CT/cPCI

☆

☆

☆

☆

Ö

Ö

Ö

Ö

－

－

Ö

Ö

★

★

★

★

★

－

SHD-480S-CT/cPCI

☆

☆

☆

☆

Ö

Ö

Ö

Ö

－

－

Ö

Ö

★

★

★

★

★

－

SHN

SHN-32A-CT/PCI

☆

☆

☆

☆

Ö

Ö

Ö

Ö

－

－

☆

－

★

★

★

★

★

－

SHN-8B-CT/PCI+

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

SHN-16B-CT/PCI+

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

SHN-32B-CT/PCI+

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

SHN-60B-CT/PCI+

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

SHN-120B-CT/PCI+

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

ATP

SHT-2A/USB

☆

☆

☆

☆

Ö

Ö

Ö

Ö

－

－

Ö

Ö

★

★

★

★

★

－

SHT-4A/USB

☆

☆

☆

☆

Ö

Ö

Ö

Ö

－

－

Ö

Ö

★

★

★

★

★

－

SHT-2B/USB

☆

☆

☆

☆

Ö

Ö

Ö

Ö

－

－

Ö

Ö

★

★

★

★

★

－

SHT-4B/USB

☆

☆

☆

☆

Ö

Ö

Ö

Ö

－

－

Ö

Ö

★

★

★

★

★

－

SHT-8A/PCI

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

SHT-16A-CT/PCI

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

ATP-24A/PCI

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

ATP-24A/PCI+

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

Ö

★

Ö

★

Ö

ATP-24A/PCIe

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

ATP-24A/PCIe+

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

Ö

★

Ö

★

Ö

SHT-8B/PCI

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

SHT-16B-CT/PCI

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

SHT-16B-CT/PCI/MP3

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

Ö

★

★

★

－

SHT-16B-CT/cPCI

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

SHT-16B-CT/cPCI/MP3

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

Ö

★

★

★

－

DTP

SHD-30A-CT/PCI/FJ

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

SHD-60A-CT/PCI/FJ

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

SHD-30B-CT/PCI/FJ

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

Ö

★

Ö

SHD-60B-CT/PCI/FJ

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

Ö

★

Ö

DTP-30C/PCI

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

DTP-30C/PCI+

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

Ö

★

Ö

★

Ö

DTP-60C/PCI

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

DTP-60C/PCI+

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

Ö

★

Ö

★

Ö

DTP-120C/PCI

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

DTP-120C/PCI+

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

Ö

★

Ö

★

Ö

DTP-30C/PCIe

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

DTP-30C/PCIe+

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

Ö

★

Ö

★

Ö

DTP-60C/PCIe

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

DTP-60C/PCIe+

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

Ö

★

Ö

★

Ö

DTP-120C/PCIe

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

DTP-120C/PCIe+

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

Ö

★

Ö

★

Ö

DST

SHR-16DA-CT/PCI

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

Ö

SHR-24DA-CT/PCI

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

Ö

DST-24B/PCI

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

DST-24B/PCI(SSW)

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

DST-24B/PCI+

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

Ö

★

Ö

★

Ö

DST-24B/PCI+(SSW)

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

Ö

★

Ö

★

Ö

DST-24B/PCIe

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

★

★

★

★

－

DST-24B/PCIe+

☆

☆

☆

☆

Ö

Ö

Ö

Ö

Ö

Ö

☆

－

★

Ö

★

Ö

★

Ö

Legend: COD: Coder DEC: Decoder

Ö: Hardware-based －: Unsupported

☆: Software-based, enabled via software algorithm by the driver ★: Software-based, enabled via the external ACM program

Note: For more information about the DTP series boards, refer to the section Voice Recording .


1.4 SynCTI Supported OS

The SynCTI driver program supports two mainstream operating systems: WINDOWS and LINUX. See below for details.

· WINDOWS: Windows 5.0 and above versions all supported, either 32-bit or 64-bit, includes Windows 2000, Windows XP, Windows 2003 server, Vista, Windows 2008 server, Win7.

· LINUX: includes CentOS, Debian, FC4, FC6, FC7, Gentoo, Red Hat A4 U4, Red Hat AS3, RH9.0, Suse, Tribox2.0, Ubuntu

Note: The board with Compact PCI bus must run in Windows 2000 or above.


1.5 SynCTI Driver Architecture (CTI Series)

It is the SynCTI driver architecture in Windows shown below:

The following table describes each component in the figure above:

Components | Description
Applications | User applications
ShPcmHandle.dll | Provides API functions for the application; enables conversion between various audio formats
ShInitPci.dll | Provides interfaces for the application; helps users obtain basic information about the board
ShIndex.ini | Configuration file of the form where lists voice files used for memory playback by index
ISDNUser.dll | ISDN message processing modules. Via interface functions, analyze and process the commands and data transferred from A3 according to the ISDN protocol, and then pass the results back to A3
ShCtiConfig.exe | Automatic configuration program
ShConfig.ini | System configuration file which corresponds to ShCtiConfig.exe. Refer to ShConfigAdvanced.ini under the driver installation directory for detailed information
Shp_A3.dll | Provides API functions for the application; helps achieve all functions of the board
ShdUSB.dll ShdPci.dll | Transfer data, states and commands between the A3 layer and the SYS
ShdUSBWdm.sys ShdcPCI.sys ShdPCI.sys | Constitute the SYS layer. Used to add or remove hardware, communicate with the DSP program. These three files respectively process USB, cPCI and PCI interfaces
SS7Monitor.exe | SS7 server
SS7Cfg.exe | SS7 configuration program
SS7Server.ini | Configuration file for SS7 server
SS7Server.dll | SS7 server scheduling module. Enables transmission of SS7 signaling, route control, etc
MTP3.dll | Constitutes the MTP3 layer in SS7 server
MmfServer.dll | Stand-alone version of SS7 server. Communicates with SS7Server.dll and MmfClient.dll via transmission of signaling and data
MmfClient.dll | Stand-alone version of SS7 client. Communicates with MmfServer.dll and the A3 layer via transmission of signaling and data
TcpServer.dll TcpClient.dll | Network versions of SS7 server and client. Communicate with each other via data transmission according to the TCP/IP protocol
USB Box, cPCI Board, PCI Board | Voice boards respectively with USB, cPCI and PCI interfaces
SynSip.dll | SIP signaling processing component
H323Dll.dll | H.323 signaling adaptation layer
SynH323.dll | H.323 signaling processing component

It is the SynCTI driver architecture in Linux shown below:

Note: Each component in the figure above functions as same as that correspondingly represented in the driver architecture in Windows.


1.6 SynCTI Driver Architecture (REC Series)

It is the SynCTI driver architecture in Windows shown below:

It is the SynCTI driver architecture in Linux shown below:

Note: Each component in the driver architecture for the REC Series functions as same as the corresponding one for the CTI Series.


1.7 Software Tool for SynCTI


1.7.1 System Configuration Tool - ShCtiConfig.exe

ShCtiConfig.exe is a software tool for visual configuration of the ShConfig.INI file. It supports configuration of common parameters for all board models from Synway. Upon the completion of driver (SynCTI) installation, what you need to do, if you don’t want to edit the configuration file manually, is simply running ShCtiConfig.exe to set parameters. The configuration program can automatically read information about board model, serial number, etc. from the board firmware, calculate such basic elements as quantity of channels, provide corresponding control buttons and write the default value of each configuration item into ShConfig.INI.

ShCtiConfig.exe is mainly for:

Ø visual configuration of common parameters used by PCI boards.

Ø visual configuration of common parameters used by USB voice boxes.

Ø visual configuration of common parameters used by cPCI boards and handling of hot-swap management.


1.7.2 Tone Analyzer Tool - ShTA.exe

Failure in call and detection of remote hangup, etc. over analog trunks while using the SHT and ATP Series boards always result from the mismatch in parameters between the on-board call-processing tone detector and the PBX. While some small PBXes use different tone frequency, tone cycle from those adopted by Central Office Terminal (COT), the tone detector on the Synway board is compliant with the COT standard. Therefore, it is essential to set correct parameters for tone frequency, duty ratio of dial tone, ringback (echo) tone, busy tone, etc. ShTA.exe can be used in such case to detect and analyze the call-processing tone parameters on the PBX side to obtain accurate settings.

For detailed information about the use of ShTA.exe, refer to Tone Analyzer Tool User Manual, i.e. the file ShTA_UserManual_en.chm (English) or ShTA_UserManual_cn.chm (Chinese) under the SynCTI driver installation directory.


1.7.3 SS7 Server Configuration Program - SS7Cfg.exe

SS7Cfg.exe is a software tool for setting Ss7server.ini (the configuration file of the SS7 Server). For more information about the use of SS7Cfg.exe, refer to SS7 Server Configuration Program User Manual, i.e. the file SS7Cfg_UserManual.chm (English) or SS7Cfg_UserManual_cn.chm (Chinese) under the SynCTI driver installation directory.


1.7.4 SS7 Server - SS7monitor.exe

Ss7Monitor.exe supports the SS7 MTP3 protocol, can distribute signaling messages and monitor the system. The application must run the SS7 server first if it requires SS7 signaling.


1.7.5 MSU Decoder Tool - MsuDecode.exe

MsuDecode.exe is a software tool for decoding the messages (MSU) contained in the log file of the SS7 server. A log file with the ‘.msu’ extension can be generated based on customer requirements to save necessary messages in binary system during the runtime of Ss7Monitor.exe. This MSU Decoder Tool can translate binary messages into the intelligible ‘.txt’ document for direct, easy reading. For detailed information about the use of MsuDecode.exe, refer to MSU Decoder Tool User Manual, i.e. the file MsuDecode_UserManual.chm (English) or MsuDecode_UserManual_ch.chm (Chinese) under the SynCTI driver installation directory.


1.8 Basic Concepts


1.8.1 Channel (CTI Series)

It is an on-board physical circuit entity with the capability of completed voice processing for a call, classified as follows according to supported interfaces and signaling.

Board Series | Module / Protocol | Channel Type | Type Code
SHT | Analog trunk module | Analog trunk channel | 0
 | Station module | Station channel | 2
 | Recording module | Recording channel | 3
 | Microphone module | Recording channel | 3
 | Magnet module | Magnet channel | 10
 | none | Non-module channel | 20
 | fax channel | Fax channel | 5
SHD | SS1 | SS1 channel | 4
 | ISDN (User-side) | ISDN channel (User-side) | 7
 | ISDN (Network-side) | ISDN channel (Network-side) | 8
 | SS7-TUP protocol | TUP channel | 6
 | SS7-ISUP protocol | ISUP channel | 11
 | Fax channel | Fax channel | 5
SHV |  | Voice-alteration channel | 14
SHN | SIP | SIP channel | 16

Note: Type code is available via the function SsmGetChType .


1.8.2 Channel (REC Series)

It is an on-board physical circuit entity with the capability of completed voice processing for a call, classified as follows according to supported interfaces and signaling.

Board Series | Module / Protocol | Channel Type | Type Code
ATP | Recording module | Analog trunk recording channel | 3
 | Microphone module | Microphone recording channel | 3
DST |  | Digital call recording channel | 12
DTP | SS1 | SS1 recording channel | 4
 | ISDN | ISDN recording channel | 7 or 8
 | SS7-TUP | TUP recording channel | 6
 | SS7-ISUP | ISUP recording channel | 11

Note: Type code is available via the function SsmGetChType .


1.8.3 Logical Channel Number

Each channel has two numbers in the driver: the physical number and the logical number.

Physical number (referred to as ‘BCh’ for short) indicates the channel number marked on the board, which is automatically allocated by the driver. Suppose N is the total number of on-board channels and M represents the total number of fax channels, the physical channel number range is:

Board Series | Physical Channel Number Range
SHT | ‘/FAX’ unmarked in the model: 0~N-1 ‘/FAX’ marked in the model: For voice channel, 0~N-M-1; for fax channel, N-M~N-1
SHD | 0~N-1
SHV | 0~N-1
SHN | 0~N-1
ATP | 0~N-1
DTP | CIC number：0~N-1 Channel number：0~N * 2 - 1
DST | 0~N-1

Logical number is the unified number given to each channel in the application system. The configuration item TotalAppCh is used to set the total number of channels in the system. Note that the parameter ‘ch’ used by most functions in this driver refers to the logical number of a channel.

Each logical channel number maps a physical number, determined by the configuration item AppCh .

Note: The channel number mentioned in this manual is the logical number except as otherwise specified.


1.8.4 Digital Trunk

A trunk is a line which links user terminal devices (e.g. user PBXes, key telephone systems, call centers, etc.) to PBX systems in the PTN (Public Telephone Network). The digital trunk serves as a digital subscriber line to the telecommunication network, usually made up of a pair of coaxial cables or twisted pair cables from the SPC exchange, one cable for transmission and the other for reception. If the trunk carries signals at 2.048Mbps (referred to as ‘2M cable’ for short), the interface between it and the user terminal device is called E1 interface; if it carries signals at 1.544Mbps, the interface is called T1 interface.

The digital trunk uses TDM technology, consisting of multiple time slots (referred to as ‘TS’ for short), each of which transmits data at 64Kbps. An E1 trunk has 32 time slots while a T1 trunk has 24.

As to the E1 trunk, TS 0 is used for frame synchronization. Hence there are only 31 effective time slots, among which TS 16 usually transfers signaling and multiframe synchronization information, called D-channel, and the rest 30 time slots are used for transmitting voice data, called B-channel.

In this manual, each pair of E1/T1 lines is called a digital trunk.


1.8.4.1 Frame Synchronization over Digital Trunk

As TS 0 over the digital trunk usually carries frame synchronization information, it cannot be used as a voice time slot. Both the SHD and DTP Series boards are equipped with a frame-synchronization indicator at each port of digital trunks, tracing the frame synchronization at the link layer: Light on indicates the smooth in frame synchronization; light off or flash hints the failure.

In the use of CAS, multiframe synchronization information is also transmitted through TS 0.

When the frame synchronization status changes over the digital trunk, the application will immediately receive the E_CHG_PcmLinkStatus event from the driver, or it can call SsmGetPcmLinkStatus at any time to obtain the current state of digital trunks.


1.8.4.2 Clock for Digital Trunk

Each digital trunk requires a clock for normal operation. See the section ‘ System Clock Configuration ’ in this chapter for more information.


1.8.4.3 Digital Trunk Configuration

Each physical digital trunk on the local end must be consistent in configuration with that from the remote PBXes to ensure good operation.

Setting of digital trunks is based on the board and carried out in the [BoardId=x] section, involving the following configuration items.

[BoardId=x]

……

PcmNumber=M // Set the total number of on-board digital trunks

PcmSSx[0]=1 // Set Digital Trunk 0 on the board: select the signaling mode

PcmClockMode[0]=j // Select the operating mode of the clock

PcmLinkType[0]=k // Select the type of the physical line

…….


1.8.4.4 Signaling Time Slot on Digital Trunk

The signaling time slot on the digital trunk functions variously depending on the protocol type as shown in the table below.

Protocol Type | Signaling Time Slot
SS1 | TS 16 is used for transmitting the ABCD signaling code.
ISDN PRI | TS 16 is used for transmitting signaling information.
SS7 | TS 16 is generally used as a signaling link. You can also make other time slots serve as signaling links by modifying two configuration items UseTS16AsCircuit and Ss7SignalingTS . For more information, see ‘ Time Slot Allocation ’ in this chapter.


1.8.4.5 Digital Trunk Number

Each digital trunk has two numbers: the physical number and the logical number.

Physical PCM number refers to the on-board digital trunk number, always beginning with 0 and ending with the total number of on-board digital trunks minus 1. Logical number is given on a unified basis to all digital trunks on multiple boards in the same application system. At the time when the application has only one board in it, the physical number of a digital trunk is the same as the logical.

The mapping relationship between the physical number and the logical can be designated via configuration items TotalPcm and Pcm .

Note: The ‘PCM number’ mentioned in this manual indicates the logical digital trunk number except as otherwise specified.


1.8.4.6 Setting Voice CODEC on B-Channel

The configuration item DefaultVoiceFormat is used for setting the voice CODEC on the digital subscriber line.


1.8.5 User Authorization Code for Board

The Synway board is designed with an encrypted authorization code identification circuit so that no one except the manufacturer is able to modify the code. This feature, offering the same effect as installing a dongle in the user software, enables users to bind the application program with a particular board. By using the authorization code, your board from Synway becomes a customized, exclusive model. Below tells some merits in the use of this code to protect the user software.

  • Simple operation: When Synway writes the authorization code applied for by users ahead of time into its supplied product, the user software only need check the code to see if it is valid, requiring neither algorithm for calculation nor resettings performed after each installation, unlike using the Series number for software protection which involves complex encrypted calculation as well as a sequence of settings based on the Series number at each installation.
  • High reliability: Software protection by the Series number goes invalid once the encrypted algorithm leaks out. By comparison, as long as you have applied for an authorization code, you are assured in technology that no one except the manufacturer can rewrite the code, which therefore eliminates the possibility to run your software on the voice boards from various channels other than Synway or those provided for other customers by Synway, even if the code is open to the public.

The function SsmGetAccreditId or SsmGetAccreditIdEx can be used to obtain the user authorization code for the board.


1.8.6 Change in Analog Phone Line Voltage

The DC voltage on analog phone lines is -48V, provided by PBXes. Each channel on the Synway SHT/ATP Series boards has a voltage detector for examining the operating voltage on the analog trunk. The following figure is a typical model for phone connection.

If Analog Phone B performs the following operations,

（1） At the time t1, B picks up.

（2） At t2, B completes dialing; the PBX rings A up and sends ringback (echo) tones to B.

（3） At t3, A picks up; both parties start a call with each other.

（4） At t4, the call ends up; A hangs up and the PBX starts sending busy tones to B.

（5） At t5, B hangs up.

（6） At t6, B is disconnected from the PBX.

（7） At t7, B is reconnected with the PBX.

its line voltage changes as follows provided the PBX doesn't support the polarity reversal feature.

In the figure above,

Va: the line voltage at the time when the phone is on-hook, usually being -48V.

Vb: the line voltage at the time when the phone is off-hook, usually being around -15V for the Synway board.

Vc: the line voltage at the time when the phone line is disconnected, theoretically being 0V.

The voltage detector judges the state of lines and phones by analyzing the relationship between the actual line voltage (assumed as Vin) and Va, Vb, Vc. The judging criterion may be described as follows.

² Off-hook: If Vc<Vin<Vb and keeps for toffhook.

² On-hook: If Vb≤Vin and keeps for tonhook.

² Off-line: If Vin≤Vc and keeps for toff.

The configuration items or functions in the SynCTI driver used for setting the above parameters are listed in the following table.

Parameter Name | Related Configuration Items or Functions
Vc | Configuration item: OffLineSet
toff | Configuration item: OffLineDetermineTime
Vb | Configuration item: IsHangupDtrmVoltage Function: SsmSetDtrmLineVoltage
toffhook | Configuration item: LineOncnt
tonhook | Configuration item: MaxRecChFlashFilterTime

The line voltage of Analog Phone B changes as follows provided the PBX supports the polarity reversal feature.

We can see from the above figure that in case the PBX supports the polarity reversal feature, it changes the polarity of the line voltage at the calling party once the called party picks up or hangs up. In such way, the PBX passes the on-hook/off-hook information to the calling party. Over analog lines, it is the most accurate way to judge whether the called party has picked up by the polarity reversal signal of the line voltage. Remember that this feature doesn’t work without the support of PBXes.

Both the Synway SHT and ATP Series boards are designed with voltage detectors. Every time when the line voltage changes and the variation range goes beyond the preset value of 5V which can be set via the function call of SsmSetEvent , the driver will send the E_CHG_LineVoltage event to the application. Also the application can obtain the line voltage through the function SsmGetLineVoltage .

The voltage detector can:

Ø Monitor the line connection between the local end and the PBX.

The analog trunk recording channel on the ATP Series supports the off-line detection feature. When the line voltage gets lower than the set value of the configuration item OffLineSet and keeps for a period of time longer than the set value of the configuration item OffLineDetermineTime , the driver will conclude that the off-line fault occurs and transfer the channel state to ‘off-line’.

Ø Judge the pickup and hangup behaviors on the line.

The recording channel on the ATP Series determines whether the phone has picked up or hung up according to the variation of the line voltage (absolute value) between Va and Vb.

In default, the analog recording channel judges the on-hook/off-hook phone state by the output value of the voltage detector. However, you can let the driver ignore the result from the voltage detector by modifying settings of the function SsmSetIgnoreLineVoltage or the configuration item IgnoreLineVoltage so as to keep the recording channel in the off-hook state.

When using the microphone recording module, as there is no feed voltage on the line, you should set the configuration item IgnoreLineVoltage to 1 and keep the recording channel always in the ‘off-hook’ state.

Ø Detects the polarity reversal signal.

The PBX provides the feed voltage, usually with negative polarity, for the analog line, and can pass some information to phones by changing the voltage polarity (e.g. change -Vb to Vb).

The polarity reversal signal for the analog phone line can be used to accurately judge the called party’s pickup and hangup behavior in cooperation with the PBX. Both the ATP Series analog trunk recording channel and the SHT Series analog trunk channel support the polarity reversal detection. Every time when a channel detects the polarity reversal, the driver will send the event E_CHG_PolarRvrsCount to the application. Also the application can obtain information on polarity reversal via the function SsmGetPolarRvrsCount .

Under some circumstances, the interfering signals on the PBX or the line become so large that they will be mistaken by the driver for the polarity reversal signals. To eliminate such error, set the configuration item PolarIgnore to ignore large interferring signals.

When the analog trunk channel detects the polarity reversal signal, it is determined by the setting of the configuration item DisablePolarReverse whether to transfer the channel state or not.


1.8.7 Ringing Current on Analog Phone Line

When the PBX calls the phone through an analog line, it will send the ringing current to the phone and make the phone to ring. This current signal usually goes periodically, involving 1 sec on and 4 sec off.

Both the ATP Series analog trunk recording channel and the SHT Series analog trunk channel are designed with the ringing current detector. The configuration item RingDetectFilterPara is used to set the minimum durations of the ringing current respectively at on and off states. The configuration item RingEndDtrTime is used to set the maximum durations of the ringing current at on and off states. Once the PWL of the ringing current changes, the driver will send the E_CHG_RingFlag event to the application.

Every time when the driver detects a complete circle of ringing current, it will send the E_CHG_RingCount event to the application. When the count reaches the specified value N, the channel state will turn to ‘ringing’ from ‘idle’. N can be set via the configuration item AlwaysToRingingOnRingCntX or ChToRingingOnRingCnt , its value in practice calculated by the following ways.

(1) If not specified in the configuration item ChToRingingOnRingCnt or set via the function SsmSetFlag which takes the parameter F_ChToRingingOnRingCnt, it is subject to the set value of the configuration item AlwaysToRingingOnRingCntX .

(2) If not designated in the configuration item AlwaysToRingingOnRingCntX , it is determined by the driver and N is 2.

Also the application can invoke the function SsmGetRingCount to obtain the count of ringing current signals.

The driver will automatically clear the count when:

the channel state transfers from ‘ringing’ to ‘idle’;

the channel state transfers from ‘ringing’ to ‘off-hook’ and keeps ‘off-hook’ for a period of time longer than the set value of the configuration item RecChClearRingDelayTime.

Also the application can clear the count via the function call of SsmClearRingCount.


1.8.8 Flash Signal on Analog Phone Line

The flash signal is a short temporary on-hook pulse generated by a rapid clap on the hook switch of the analog phone during a call, generally used for such operations as transferring the call to an extension with the help of the PBX. You should do the clap as swift as possible lest the PBX mistakes the flash signal for the on-hook signal.


1.8.9 Caller ID on Analog Phone Line

The Caller ID service is a business provided with extra fee charged by corporations on telecommunications, which usually requires an application submitted ahead of time. There are two modes for the PBX to transmit the calling party number to the phone.

² FSK (Frequency-shift Keying) Mode: The Caller ID, i.e. the calling party number, is transmitted by the PBX somewhen between the first ring and the second of the phone.

² DTMF (Dual-tone Multi-frequency) Mode: Most PBXes transmit the Caller ID before sending the first ring to the phone. However, a few PBXes send somewhen between the first ring and the second.

In general, the PBX involved in the local area network provides the Caller ID in FSK mode while the small-sized PBX in DTMF mode. Note that the application program should pick up the phone after the second ring to ensure a complete reception of the Caller ID. When the analog trunk channel state comes into ‘ringing’ can be set in the configuration file.

Both the Synway SHT and ATP Series boards are designed with the Caller ID detector for examining the FSK or DTMF Caller ID. The operation principle is shown below:

There are 2 buffers in the driver for each channel to save the Caller ID information: Caller ID Buffer and Extended Caller ID Buffer. The latter holds the original data of the FSK Caller ID, including the calling party number, date, name of the calling party, etc. The driver processes the original information as follows:

² Separates the calling party number and saves it to Caller ID Buffer;

² Separates the name of the calling party and saves it to Caller Name Buffer

The functions, events and configuration items related to the Caller ID detector are listed in the following table.

 | Name | Description
Configuration Item | CallerIdStyle | Sets the operating mode of the Caller ID detector (FSK/DTMF), i.e. set the switch k1 in the figure above
 | CloseCallerIdOnReceived FSKCallerIdDtrmTime FilterInvalidCID | Set parameters for the Caller ID detector running in FSK mode
 | DtmfCallerIDStyleLength DtmfCallerIDInterTimeout | Set parameters for the Caller ID detector running in DTMF mode
Function | SsmSetFlag (with the parameter F_CALLERIDSTYLE) | Sets the operating mode of the Caller ID detector
 | SsmGetCallerId SsmGetCallerIdEx SsmGetCallerIdA | Obtain the calling party number
 | SsmGetCallerName | Obtains the name of the calling party
 | SsmClearCallerId SsmClearCallerIdEx | Empty the buffer in the driver which holds the calling party number
Event | E_CHG_CIDExBuf | While the Caller ID detector is working in FSK mode, every time the driver receives a calling party number, it sends this event to the application


1.9 System Clock Configuration

Each Synway board requires a clock for normal operation. Take the following cases into consideration when setting the clock signal source for the application system based on the Synway board.

u In the case of board connection over CT Bus:

² The clock signal source solely provided by one of the boards is called Master Clock. As a result, the board that offers the master clock is called Master Board, others called Slave Board. The signal clock source acquired by the slave board from the master board is called Slave Clock.

² If the application system involves at least one SHD board, it is required to choose one SHD board as the master board; if no SHD boards but the DST or DTP used in the system, you should select one DST or DTP board as the master board.

² If a SHD board serves as the master board, only one digital trunk on it can supply the master clock while others must work in the Slave Clock mode.

² The clock signal from the SHD or DTP boards must keep consistent with that from PTN; otherwise it may result in noise or high signal error rate during the call.

u In the case of board connection not through CT Bus, the board must be set to Master Board.

u In the case of connection to third-party boards over CT Bus, if the third-party board is set to Master Board, all Synway boards should be set to Slave Board.

The master clock derives from two ways: Line-synchronization and Free-run. Line-synchronization is to pick up at the local end the input signal from the remote PBX as the master clock, applicable to the SHD, DTP and DST Series boards, to ensure the on-board master clock synchronous with the clock signal at the remote PBX. Free-run is to generate the clock signal by the on-board clock oscillation circuit, applicable to the SHT and ATP Series. When setting up a testing system by using the SHD boards and linking it to a real application system, you should choose ‘Free-run’ for the master clock of the master board.

The SHV Series boards can’t serve as the master board, so they must work in the Slave Clock mode.

Configuration items and functions in relation to the clock signal are listed in the following table.

 | Name | Description
Configuration Item | WhoSupplySysClock | Sets the clock mode for the board (Master Board/Slave Board)
 | PcmClockMode | Sets the clock mode for digital trunks on the SHD and DTP Series boards
Function | SsmSetPcmClockMode | Sets the clock mode for digital trunks on the SHD and DTP Series boards. Identical in function with the configuration item PcmClockMode


1.10 Voice Processing


1.10.1 Voice Playing (CTI Series)

There are 6 modes for voice playing as shown in the following figure.

In the four voice playing modes – Preload File Mode, Single File Mode, File List Mode and Buffer List Mode, the driver will first read the source data into the internal Playback Buffer after the voice-playing operation starts. The buffer size is designated by the configuration item PlayBufSize , with a default value of 32K bytes.


1.10.1.1 Setting Volume and Direction


1.10.1.1.1 CTI Series

For detailed information about the volume and the direction to play data, refer to relative content in this chapter.

² SHD Series: See the section Operation Principle of SHD Series in this chapter.

² SHT Series: See the section Operation Principle of SHT Series in this chapter.

² SHN Series: See the section Operation Principle of SHN Series in this chapter.


1.10.1.1.2 REC Series

For detailed information about the volume and the direction to play data, refer to relative content in this chapter.

² ATP Series: See the section Operation Principle of ATP Series in this chapter.

² DST Series: See the section Operation Principle of DST Series in this chapter.

² DTP Series: See the section Operation Principle of DTP Series in this chapter.


1.10.1.2 Setting Termination Condition

After the start of voice playing, other than the occasion where the task stops naturally by itself or is terminated by the driver through function calls, the driver will automatically end it once the channel detects some events triggered by particular conditions, simplifying compilation of the application program. The ‘particular conditions’ mentioned here include:

l The DTMF Detector detects DTMF digits in the incoming signals.

Related functions and configuration items are listed below.

Function Name | Description | Related Configuration Item
SsmSetDtmfStopPlay | Sets whether to stop voice playing as the DTMF Detector detects DTMF digits. | DtmfStopPlayCharSet
SsmSetDTMFStopPlayCharSet | Sets the DTMF digits which stop voice playing.
SsmGetDtmfStopPlayFlag | Obtains the flag which tells if voice playing ends as the DTMF Detector detects DTMF digits. |
SsmGetDTMFStopPlayCharSet | Obtains the DTMF digits that stop voice playing. |

Note: In case that the DTMF detector detects DTMF in the incoming signals, if the configuration item DefaultPausePlayOnRxDtmf is set to 1, the driver will intermit voice playing to ensure the accuracy of the DTMF detector, and automatically resume playing when DTMF signals totally disappear.

l The Barge-in detector detects voice activities on the line.

Function Name | Description | Related Configuration Item
SsmSetBargeinStopPlay | Sets whether to stop voice playing as the Barge-in Detector detects voice activities on the line. | DefaultBargeInStopPlay
SsmGetBargeinStopPlayFlag | Obtains the flag which tells if voice playing ends as the Barge-in Detector detects voice activities on the line. |

l Call state machine detects remote hangup.

Function Name | Description | Related Configuration Item
SsmSetHangupStopPlayFlag | Sets whether to stop voice playing as the driver state machine detects remote hangup. | HangupStopPlay

l The application program invokes the function that takes data off bus.

For particular information about characteristic features of some models in the SHD Series, refer to the section Operation Principle of SHD Series in this chapter.


1.10.1.3 Preload File Mode

The use of IVR and so forth requires the application program to play some voice segments, such as the speech prompt, date, time, number, etc. To improve the running efficiency of the application system and to reduce the times that the application visits HD, the SynCTI driver provides Preload File Mode for voice playing, whose operation principle is: Record some commonly used voice segments, e.g. ‘0’, ‘1’, ‘2’, ……, ‘9’, ‘ten’, ‘hundred’, ‘thousand’, ‘ten thousand’, to one or multiple files and define a number and an alias for each of them ahead of time. Then the driver will automatically preload those segments to the memory once the function for driver initialization SsmStartCti is invoked, which offers great facility to play such successive segments as ‘125’. Playing in Preload File Mode enables the driver to make seamless connection of voice segments and creates much more excellent effect than playing a number of single files in sequence.

The driver supports up to 65536 preload voice segments.

You can preload voice segments by compiling the configuration file ShIndex.ini, the detailed information on which can be found in Preload Voice Configuration File ShIndex.ini (CTI Series) in Section 3.2.

Also the application program is able to preload voice segments dynamically via function calls. See the table below for relative functions.

l Functions for loading and unloading voice segments

Function Name | Description
SsmSetMaxIdxSeg | Sets the total number of preload voice segments.
SsmGetTotalIndexSeg | Obtains the total number of preload voice segments.
SsmLoadIndexData | Loads the specified voice segments to the memory.
SsmFreeIndexData | Unloads the preload voice segments from the memory.

l Specific functions for playing preload voice segments

Function Name | Description
SsmPlayIndexList | Plays one or multiple specified preload voice segments in sequence.
SsmPlayIndexString | Plays one or multiple specified preload voice segments in sequence.
SsmStopPlayIndex | Stops playing preload voice segments.


1.10.1.4 Single File Mode

This mode is used for playing a single voice file, including the WAV file, the MP3 file and the non-header file (without file header, in need of extra designation of CODEC).

Related functions and configuration items are listed in the table below.

Function/Event Name | Description
SsmPlayFile | Starts playing a single file.
SsmStopPlayFile | Stops playing a single file.
SsmPausePlay | Suspends playing a single file.
SsmRestartPlay | Resumes file playing which is paused by the function call of SsmPausePlay.
SsmFastFwdPlay | Continues file playing after 1 sec. of fast forward.
SsmFastBwdPlay | Continues file playing after 1 sec. of fast backward.
SsmSetPlayTime | Continues file playing from the position specified by time.
SsmSetPlayPrct | Continues file playing from the position specified by percentage.
SsmGetDataBytesToPlay | Queries the amount of unplayed voice data bytes.
SsmGetDataBytesPlayed | Queries the amount of played voice data bytes.
SsmGetPlayingFileInfo | Obtains information on the voice file being played.
SsmGetPlayedTimeEx | Obtains the duration of voice playing from the first byte of the file to the current position.
E_PROC_PlayFile | An event which tells the playing progress in Single File Mode.


1.10.1.5 File List Mode

In this mode, the application first consecutively submits multiple voice files with the same CODEC. Then the driver automatically plays those files according to the submitting sequence, making seamless connection of files.

The function SsmAddToFileList is used to submit necessary files to be played to the driver. The maximum amount of submitted files is determined by the configuration item MaxPlayFileList .

Once the application invokes the function SsmPlayFileList , the driver starts a task of playing multiple files from the 1st one. Every time when a file is completely played, the driver will send the event E_PROC_PlayFileList to the application and go to the next file. After all files are played, the driver automatically closes all of them, terminates the play task and launches the E_PROC_PlayEnd to the application.

Related functions and output events are shown in the table below.

Function/Event Name | Description
SsmAddToFileList | Submits a file to be played to the driver.
SsmPlayFileList | Starts voice playing in File List Mode.
SsmClearFileList | Closes and clears all voice files submitted to the driver.
SsmStopPlayFileList | Stops voice playing in File List Mode.
E_PROC_PlayFileList | An event thrown out by the driver when a voice file is completely played


1.10.1.6 Single Buffer Mode

In this mode, the application allocates a buffer for itself, writes voice data into the buffer and then submits a play task to the driver. The driver launches an event to the application upon completing the play of all data in the buffer and ends the play task.

Related functions and output events are displayed in the table below.

Function/Event Name | Description
SsmPlayMem | Starts voice playing in Single Buffer Mode.
SsmSetStopPlayOffset | Resets the position in the buffer where the play stops.
SsmStopPlayMem | Stops voice playing in Single Buffer Mode.
SsmGetPlayOffset | Obtains the pointer to data being played in the driver during voice playing in Single Buffer Mode.
E_PROC_PlayMem | An event which tells the playing progress in Single Buffer Mode


1.10.1.7 Buffer List Mode

In this mode, the application program submits ahead of time a group of voice data blocks respectively in multiple buffers. Then the driver plays them consecutively according to the set sequence, making seamless connection of voice data blocks. Note that those blocks are managed by the application itself.

Relative functions are shown below:

Function Name | Description
SsmAddToPlayMemList | Submits a buffer to the driver.
SsmClearPlayMemList | Clears all buffers submitted to the driver.
SsmPlayMemList | Starts voice playing in Buffer List Mode.
SsmStopPlayMemList | Stops voice playing in Buffer List Mode.


1.10.1.8 Pingpong Buffer Mode

This mode uses double buffers. Its operation principle is: Before the start of voice playing, the application prepares one (or two) buffer full of voice data to be played, and then invokes the function SsmPlayMemBlock once (or consecutively twice) to submit the buffer to the driver. When the driver receives the play command, it will perform voice playing in Pingpong Buffer Mode, that is, upon a complete play of voice data in the first buffer, the driver will automatically play those in the second and meanwhile invoke the callback function from the application to pass an end-of-play message to the application. After that, the application will fill data into the next buffer and restart such process.

Compared with Single Buffer Mode, Pingpong Buffer Mode has the following characteristics.

l The minimum buffer size can be set to 192 bytes;

l Support for callback programming.

Since neither Windows nor Linux is a true real-time operating system, there is bound to be some delay in transmitting voice data from the application buffer to the on-board voice decoder. Besides, due to the indirect transmission of voice data, first from the application program (User Mode) to the device driver (Kernel Mode), then from the device driver to the board, the delay in time is not invariable but changes depending on how busy the application is. A relatively effective way to shorten the delay time is to reduce the buffer size and enhance the priority for the application to update voice data at the same time. The driver’s thread priority is quite high, and in this case all related source codes in the callback function can acquire the priority as high as that of the driver. From the above we can see that the use of Pingpong Buffer Mode can minimize this kind of delay, so it is applicable to those occasions that demand high real-time capability in voice playing.

Related functions are shown below:

Function Name | Description
SsmPlayMemBlock | Submits a buffer to the driver and starts voice playing in Pingpong Buffer Mode.
SsmStopPlayMemBlock | Stops voice playing in Pingpong Buffer Mode.


1.10.1.9 Common Termination Function

The function SsmStopPlay can be used to stop any kind of play tasks.


1.10.1.10 Acquiring Information on Voice Playing

The following functions can be called to obtain relative information about voice playing.

Function Name | Description
SsmQueryPlayFormat | Queries if the channel supports the specified playing format.
SsmGetPlayType | Queries the mode of voice playing performed currently on the channel.
SsmCheckPlay | Queries various situations during voice playing.
SsmGetPlayedPercentage | Obtains the percentage of the played data to the entire.
SsmGetPlayedTime | Obtains the duration of voice playing.


1.10.2 Voice Recording


1.10.2.1 Setting Recording Signal Source

The recording signal source varies on the board model. Refer to the operation principle of corresponding board Series for details.


1.10.2.2 Setting Termination Condition

After the start of voice recording, other than the occasion where the task stops naturally by itself or is terminated by the application through function calls, the driver will automatically end it once the channel detects some events triggered by particular conditions, simplifying compilation of the application program. The ‘particular conditions’ mentioned here include:

(1) The DTMF Detector detects DTMF digits in the incoming signals.

Related functions and configuration items are listed below.

Function Name | Description | Related Configuration Item
SsmSetDTMFStopRecCharSet | Sets whether to stop voice recording as the DTMF Detector detects DTMF digits. | DtmfStopRecCharSet

(2) Call state machine detects remote hangup.

Related functions and configuration items are listed below.

Function Name | Description | Related Configuration Item
SsmSetHangupStopRecFlag | Sets whether to stop voice recording as the driver state machine detects remote hangup. | HangupStopRec


1.10.2.3 Setting Prerecord Feature

Prerecord is a process that the driver starts a prerecord task according to reset parameters and stores the recorded data in its internal buffers; thus, when the application invokes functions to record data into a file, it can copy the recorded data in the buffer from the driver to this file before the start of normal recording. This feature helps prevent loss of the foremost part of voice data during File Mode recording caused by delay in application response and the like.

As to the buffer for prerecord data, the size can be set via the configuration item RecordBufSize .

Related functions and configuration items are listed below.

Function Name | Description | Related Configuration Item
SsmSetPrerecord | Sets the prerecord feature. | PrerecordEnable PrerecordMode PrerecordInsertTime PrerecordCodec
SsmGetPrerecordState | Obtains the prerecord settings. |


1.10.2.4 Setting Tail-Truncation Feature

When the application stops recording data into files, the driver will automatically truncate the last section of the recorded voice data. This feature is applicable to some particular occasions, for example, in case the driver’s detection of DTMF signals stops the File Mode recording and the application doesn’t like those DTMF digits shown in the file.

This feature only supports File Mode recording and requires cooperation with the settings ‘automatic stop of voice recording upon detection of DTMF’.

Related functions and configuration items are listed below.

Function Name | Description | Related Configuration Item
SsmSetTruncateTail | Sets the parameters for the tail-truncation feature | TruncateTailOnRecordToFile
SsmGetTruncateTailTime | Obtains the preset parameters for the tail-truncation feature. |


1.10.2.5 Setting AGC Feature

If the AGC (Automatic Gain Control) feature is enabled, the driver will automatically adjust the input signal amplitude, increasing that of small signals and decreasing that of large signals.

The function SsmSetRecAGC is used to enable or disable the AGC feature, whose parameters can be set via the following configuration items.

² AGCMAXGAIN

² AGCMINGAIN

² AGCMAXLEVEL

² AGCMINLEVEL

² AGCDOWNRATIO

² AGCUPRATIO

² AGCKEEPTIME

For DST-24B/PCI, DST-24B/PCI+, DST-24B/PCIe, DST-24B/PCIe+ boards, the parameters for AGC module can be set both uplink and downlink via the following configuration items:

² AGCMAXGAINUPLINK

² AGCMINGAINUPLINK

² AGCMAXLEVELUPLINK

² AGCMINLEVELUPLINK

² AGCDOWNRATIOUPLINK

² AGCUPRATIOUPLINK

² AGCMAXGAINDOWNLINK

² AGCMINGAINDOWNLINK

² AGCMAXLEVELDOWNLINK

² AGCMINLEVELDOWNLINK

² AGCDOWNRATIODOWNLINK

² AGCUPRATIODOWNLINK

Note:

l The AGC operation principle for the Synway voice board is to adjust the gain of amplifiers in AGC circuits according to the voltage level of originally input signals so as to control the output signal level within an expected range. By setting AGC parameters, we can provide various AGC effects to satisfy different application environments and different users. Our AGC parameters may be divided into three categories: first, AGCMAXGAIN (AGCMAXGAINUPLINK, AGCMAXGAINDOWNLINK) and AGCMINGAIN (AGCMINGAINUPLINK, AGCMINGAINDOWNLINK), used to control the range of DSP gain increase and decrease; second, AGCMAXLEVEL (AGCMAXLEVELUPLINK, AGCMAXLEVELDOWNLINK) and AGCMINLEVEL (AGCMINLEVELUPLINK, AGCMINLEVELDOWNLINK), used to set the expected value of the AGC output voltage level; third, AGCDOWNRATIO (AGCDOWNRATIOUPLINK,AGCDOWNRATIODOWNLINK), AGCUPRATIO (AGCUPRATIOUPLINK, AGCUPRATIODOWNLINK) and AGCKEEPTIME , used to control the speed of AGC gain decrease/increase.

l Our default AGC settings are suitable for most application environments. If you are required to reset the parameters for AGC in particular cases, please do it under the instruction of our technicians.

l Because the driver will automatically disable the AGC feature when the channel state transfers to S_CALL_STANDBY, although the application can still perform recording on the channel, the data recorded afterwards are obviously not endued with the AGC feature. If the application would like to recover the AGC feature in this case, it is necessary to set the configuration item OpenRecEnAndPlayEnOnIdle .


1.10.2.6 Acquiring Information on Voice Recording

Related functions are shown below.

Function Name | Description
SsmQueryRecFormat | Queries if the channel supports the specified recording format.
SsmGetRecType | Queries the mode of voice recording performed currently on the channel.
SsmGetRecTime | Obtains the duration of voice recording.
SsmCheckRecord | Queries various situations during voice recording.


1.10.2.7 Brief Introduction of Recording Functions

The driver will allocate in itself a recording buffer for each channel. The buffer size can be set via the configuration RecordBufSize item, with a default value of 32768 bytes.

There are 3 categories of recording functions respectively for 3 recording modes: File Mode, Buffer Mode and Pingpong Buffer Mode.


1.10.2.7.1 File Mode

Related functions are shown below.

Function Name | Description
SsmRecToFile SsmRecToFileA SsmRecToFileEx | Start voice recording in File Mode.
SsmStopRecToFile | Stops voice recording in File Mode.
SsmPauseRecToFile | Suspends voice recording in File Mode.
SsmRestartRecToFile | Resumes voice recording in File Mode.
SsmChkRecToFile | Queries various situations during voice recording in File Mode.
SsmGetDataBytesToRecord | Obtains the amount of unrecorded voice data bytes.


1.10.2.7.2 Buffer Mode

In this mode, the application program first calls the function SsmRecToMem to submit a buffer to the driver. Then the driver writes the recorded data into this buffer and throws out progress messages according to the set conditions.

Related functions are shown below.

Function Name | Description
SsmRecToMem | Starts voice recording in Buffer Mode.
SsmStopRecToMem | Stops voice recording in Buffer Mode.
SsmGetRecOffset | During voice recording in Buffer Mode, obtains the pointer to the position in the driver buffer where the recorded data are written.


1.10.2.7.3 Pingpong Buffer Mode

This mode uses double buffers. Its operation principle is: Before the start of voice recording, the application prepares one (or two) recording buffer, and then invokes the function SsmRecordMemBlock once (or consecutively twice) to submit the buffer to the driver. After the application calls SsmRecordMemBlock for the first time, the driver will start voice recording in Pingpong Buffer Mode and write the recorded data into the buffer. When one buffer is full, the driver will automatically shift to another and meanwhile invoke the callback function from the application to pass an end-of-record message to the application. Via this callback function, the application can call SsmRecordMemBlock to submit a new buffer and do subsequent processing of the recorded data.

Compared with Buffer Mode, Pingpong Buffer Mode has the following characteristics.

l The minimum buffer size can be set to 192 bytes.

l Support for the callback operation mode.

Since neither Windows nor Linux is a true real-time operating system, there is bound to be some delay in transmitting recorded data from the board to the application buffer. Besides, as voice data need to be passed from the device driver (Kernel Mode) to the application program (User Mode), involving the switch from Kernel Mode to User Mode, the delay in time is not invariable but changes depending on how busy the application is. A relatively effective way to shorten the delay time is to reduce the buffer size and enhance the priority for the application to process voice data at the same time. The driver’s thread priority is quite high, and in this case all related source codes in the callback function can acquire the priority as high as that of the driver. From the above we can see that the use of Pingpong Buffer Mode can minimize this kind of delay, so it is applicable to those occasions that require high real-time capability in voice recording.

Related functions are shown below:

Function Name | Description
SsmRecordMemBlock | Submits a buffer to the driver and starts voice recording in Pingpong Buffer Mode.
SsmStopRecordMemBlock | Stops voice recording in Pingpong Buffer Mode.


1.10.3 DTMF Detector

All Synway boards provide an independent DTMF detector for each channel on them.

The following figure shows the operation principle of the DTMF detector.

The switch K1 is controlled by the configuration item AlwaysEnableRxDtmf , the driver and the application together. When AlwaysEnableRxDtmf is set to 1, K1 is switched on; when AlwaysEnableRxDtmf is set to 0, it is the driver that determines the state of K1 based on channel state transition: switch on K1 as the channel turns to the talking state; switch off K1 as the channel leaves the talking state followed by call disconnection. Also the application can invoke the function SsmEnableRxDtmf to control the state of K1.

When a station channel stays in the idle state, the DTMF detector is disabled under the automatic control of the driver, which however can be enabled via the configuration item RcvDtmfOnIdle .

FFT (Fast Fourier Transform) figured above indicates FFT signal processing provided to transform input voice signals from the time domain to the frequency domain.

The DTMF filter examines the frequency of input signals to see if there are DTMF digits and outputs its judgement by voltage level.

The pulse-width filter is used for eliminating the pulse width of DTMF signals so as to avoid the effect of interlarded DTMF signals on the examining result. The detected DTMF digits are output via the switch K2 while being passed to the callback function.

The switch K2 is automatically controlled by the driver to determine the outgoing route of DTMF signals. Usually the driver puts K2 at the 1-3 position, stores the detected DTMF digits to the buffer RcvBuffer, and meanwhile sends the event E_CHG_RcvDTMF to the application program.

RcvBuffer holds the detected DTMF, whose size can be specified via the configuration item RxDtmfBufSize . The following functions helps access RcvBuffer.

Function Name | Description
SsmClearRxDtmfBuf | Empty the buffer in the driver which stores DTMF digits, i.e. the DTMF detector buffer.
SsmGetDtmfStr SsmGetDtmfStrA | Obtains the DTMF digits saved in the DTMF detector buffer.
SsmGetRxDtmfLen | Obtains the number of DTMF digits saved in the DTMF detector buffer.
SsmGet1stDtmf SsmGet1stDtmfClr | Obtains the first DTMF digit received by the DTMF detector buffer.
SsmGetLastDtmf | Obtains the last DTMF digit received by the DTMF detector buffer.

When the application invokes the function SsmSetWaitDtmf to start a task of WaitDtmf, K2 will automatically switch to the 1-2 position and the detected DTMF digits be sent to the WaitDtmf component for subsequent processing. Note that none of the detected DTMF digits will enter RcvBuffer after the task of WaitDtmf is started, however, the DTMF digits which already exist in RcvBuffer will be copied to the buffer.


1.10.3.1 DTMF Filter

The DTMF filter examines the frequency of input signals to see if there are DTMF digits involved, and prevents the mistaking of voice signals for DTMF.

The corresponding relationship between DTMF digits and the frequency is shown in the following table.

 | 1209Hz | 1336Hz | 1477Hz | 1633Hz
697Hz | 1 | 2 | 3 | A
770Hz | 4 | 5 | 6 | B
852Hz | 7 | 8 | 9 | C
941Hz | * | 0 | # | D

The following configuration items and functions help ensure the DTMF filter to make accurate judgements.

Configuration Item or Function | Description
Configuration item: DualAndAllFreqEnScale Function: SsmSetFlag (with the parameter F_DualAndAllFreqEnScale) | Sets the threshold value in percentage for the rate of DTMF in-band energy to overall energy. The DTMF filter calculates the percentage of DTMF in-band energy to overall energy in real time and compares it with a set threshold value. Only if the percentage is greater than the threshold value will the DTMF filter conclude that the on-line signals are DTMF and output the judgement by voltage level (High voltage level means detection of DTMF signals while low level implies nondetection).
DtmfEnergy | Sets the absolute value of DTMF in-band energy. Only if the DTMF in-band energy is greater than the set value of this configuration item will the driver confirm that those detected are DTMF signals.
Configuration item: HighAndLowFreqEnScale Function: SsmSetFlag (with the parameter F_HighAndLowFreqEnScale) | Sets the proportion of the high-frequency DTMF energy to the low-frequency. Only if the proportion is greater than the set value of this configuration item will the driver confirm that those detected are DTMF signals.


1.10.3.2 DTMF Pulse-width Filter

The figure below shows the operation principle of the DTMF pulse-width filter.

In the figure above, Ton and Toff represent the minimum DTMF signal durations respectively at on and off states (voltage level). In practice, after the voltage level of the input DTMF signal transforms from low to high, only if the signal stays at on or off state for more than Ton /Toff will the driver conclude that it is a real DTMF digit that goes through the line, write this digit into a buffer and send the event E_CHG_RcvDTMF to the application program at the same time.

Ton and Toff are set via the configuration item ReceiveDtmfSensitive or the function SsmSetFlag (with the parameter F_RCVDTMFSENS).

The configuration item OmitABCD is used to determine on whether to discard the received A, B, C or D digit. If this item is set to RESERVED, the A, B, C or D will be sent to the subsequent processing component with other digits, otherwise be discarded.

The configuration item DtrmOnDtmfHighLevel is used to determine the time for the driver to output the DTMF digit. In the use of the high-level output setting, the driver will immediately detect the output of DTMF digits when the signal last at on state for more than Ton (i.e. at the time t1 in the figure above); in the use of low-level output setting, the driver can detect the output of DTMF digits only when the signal transforms from on to off state and keeps at off state for more than Toff (i.e. at the time t3 in the figure above).


1.10.3.3 WaitDtmf

WaitDtmf is a task of receiving particular DTMF digits submitted to the driver by the application. It is started when the application invokes the function SsmSetWaitDtmf . The DTMF digits detected afterwards by the DTMF detector will not enter RcvBuffer but come directly into the WaitDtmf component. Then the driver determines on whether to terminate this task according to preset conditions: it will send the event E_PROC_WaitDTMF to the application and end this WaitDtmf task once the termination condition is satisfied.

Related functions are listed below.

Function/Event Name | Description
SsmSetWaitDtmf SsmSetWaitDtmfEx SsmSetWaitDtmfExA | Start the WaitDtmf task.
SsmCancelWaitDtmf | Cancel the WaitDtmf task.
SsmChkWaitDtmf | Queries the WaitDtmf task progress.
E_PROC_WaitDTMF | Reports the WaitDtmf task progress.


1.10.3.4 Callback Programming

The Callback component is used to process the application’s callback function. Provided the application has configured a callback function by calling the function SsmSetRxDtmfHandler , the driver will invoke this callback function when it detects DTMF digits.


1.10.3.5 Dial Pulse Detection

The DTMF detector for the analog trunk recording channel is able to detect the dial pulse provided the configuration item EnablePulseKeyDetect is properly reset.


1.10.4 DTMF Generator (CTI Series)

The DTMF generator can produce standard DTMF digits on the line, including ‘0’, ‘1’, ‘2’, ‘3’, ‘4’, ‘5’, ‘6’, ‘7’, ‘8’, ‘9’, ‘*’, ‘#’, ‘A’, ‘B’, ‘C’, ‘D’.

The following figure shows the operation principle of the DTMF generator.

The Synway board prepares an independent DTMF generator and a TxDtmfBuffer for each channel.

The size of TxDtmfBuffer can be designated via the configuration item TxDtmfBufSize , with a default value of 50 characters.

The DTMF generator is able to create DTMF digits which in frequency and amplitude completely meet the country criteria for DTMF dialing. Below is a typical DTMF signal produced by the DTMF generator.

As shown above, Ton and Toff are used to describe the waveform of a DTMF digit: Ton indicates the signal duration at on state while Toff represents the signal duration at off state. Both of them can be set via the configuration item TxDtmfTimePara or the function SsmSetTxDtmfPara . The function SsmGetTxDtmfPara is for obtaining the Ton and Toff settings.

The signal amplitude A can be set via the function SsmSetFlag (with the parameter F_TXDTMFAMP). The default value is 0X8976, among which the 16 higher bits set the amplitude of low frequency and the 16 lower bits set the amplitude of high frequency. The conversion between Amplitude A and DB is Y=20*lg(X/16), among which Y is the DB value and X is the set value. Take the default value 0X8976 for example. According to the conversion formula, the low-frequency DB value is 18.65=20*lg(137/16) and the high-frequency DB value is 17.35=20*lg(118/16).

After the application invokes the function SsmTxDtmf , the diver will store the DTMF digits to be transmitted in TxDtmfBuffer and start a task to transmit DTMF at the same time. Every time when the DTMF generator finishes transmitting a digit, it will automatically take the next one out of TxDtmfBuffer for transmission. As TxDtmfBuffer gets empty, which indicates termination of the task, the driver will send the event E_PROC_SendDTMF to the application.

You can use the function SsmStopTxDtmf to stop transmission at any time and the function SsmChkTxDtmf to query the task progress.


1.10.5 Tone Detector

Each channel on the Synway board has an independent tone detector which is mainly for:

· Call progress tone detection on the analog line.

· Fax tone detection.

· Other special applications, such as tone detection on the digital trunk channel in the automatic call testing system.

Tip: Skip this section if your system does not involve such applications mentioned above. Otherwise, if your system contains analog trunk channels or analog trunk recording channels, read through this section carefully as it is quite essential to your system’s compatibility.

The figure below shows the operation principle of the tone detector and the event outputs concerned.

The switch K1, which can be set via the function SsmStartToneAnalyze / SsmCloseToneAnalyze , controls the operation of the tone detector as well as the remote pickup detector. It is under an automatic control of the driver based on channel state transition and switched on after system initialization. Refer to the section on channel state machine for details.

K2 is automatically controlled by the DSP program: it is switched off when starting the on-channel FSK receiver, and switched on otherwise.

K6 determines the use of the enhanced tone detector. It can be set by the configuration item ToneDetectorMode . By default, K6 is connected with A, using the 1st and 2nd call progress tone detectors as well as the fax progress tone detector for detection. When K6 is connected with B, the enhanced tone detector is used for detection.

The tone detector is made up of the following components.

· FFT

FFT indicates FFT signal processing provided to transform input voice signals from the time domain to the frequency domain. The processing results are sent to the subsequent component for analysis and calculation. Also the overall energy of on-line voice signals is calculated in this component. Since FFT calculation is performed in DSP chips, no host resource needs to be used.

· Noise Filter

Used for eliminating noises on the line.

· Call Progress Tone Detector

It is used to examine if there are call progress tones, whether single tones or dual tones, on the line. Each tone detector has 2 call progress tone detectors independent to each other. The switch K4, which is switched off in default and can be set via the configuration item Enable2ndToneAnalyzer or the function SsmStart2ndToneAnalyzer , determines whether to use the second call progress tone detector or not.

· Fax Progress Tone Detector

It is used to examine if there are single fax progress tones on the line. Each tone detector has 2 fax progress tone detectors independent to each other. This detector becomes useless when K4 is connected to the second call progress tone detector.

· Simplified Busy Tone Detector

When the application program starts the FSK receiver on the analog trunk channel, the on-board DSP program will automatically switch off K2 so that the tone detector is disconnected and fails to work in a normal state. However, some particular occasions using the SHT Series boards require the application to detect busy tones while receiving FSK data to ensure an accurate judgement on the remote hangup behavior in time. The simplified busy tone detector is just designed for such requirements. The application can use it simply by switching on K1 and K3 at the time when K2 is automatically switched off by the DSP program. As this detector only accepts the energy of incoming signals output by the Barge-in detector, it is unable to conduct sufficient analysis over the signal frequency but has to examine the signal waveform to make sure if there are busy tones on the line. Therefore, we name it the simplified busy tone detector.

· Enhanced Tone Detector

As a perfect substitute for call progress tone detector and fax progress tone detector, the enhanced tone detector can detect not only the kinds of tones detected by these two detectors, but also some particular tones (such as SIT signals).

Note: So far only a part of Synway boards listed below support the enhanced tone detector. See the table for details.

Board Model | Enhanced Tone Detector Supported or Not
SHT-8A/PCI | Supported
SHT-8B/PCI | Supported
SHT-8B/PCI/FAX | Supported
SHT-8C/PCI/FAX | Supported
SHT-8C/PCI/EC | Supported
SHT-16A-CT/PCI | Supported
SHT-16B-CT/PCI | Supported
SHT-16B-CT/PCI/FAX | Supported
SHT-16B-CT/cPCI | Supported
SHT-16B-CT/cPCI/MP3 | Supported
SHT-16B-CT/cPCI/FAX | Supported
SHT-16C-CT/PCI/FAX | Supported
SHT-16C-CT/PCI/EC | Supported
SHT-4A/USB | Supported
SHT-2A/USB | Supported
SHT-2B/USB | Supported
SHT-4B/USB | Supported

· Answering Machine Detector

It is used to distinguish the answering machine from the human being that answers after remote pickup. K7 is used to control whether the answering machine auto-run . This function also can be sets via the configuration item EnableAMD , The default value of K7 is connected (switched on).

The following configuration items also can influence the action of answering machine detector. Details are shows as below.

AMDNoSoundAfterDialTime : Uses to judge the line silence time after dial tone overtime or not. If the line silence time is over the value of AMDNoSoundAfterDialTime, events E_CHG_AMD will be throw out.(at this condition, the value of E_CHG_AMD is 5)

AMDNoSoundTime : Uses to judge the silence time after tone or color ring detected overtime or not. If the silence time is over the value of AMDNoSoundTime, events E_CHG_AMD will be throw out.(at this condition, the value of E_CHG_AMD is 4)

AMDTimeOut : Uses to judge the whole AMD detecting process overtime or not. If this process is over the value of AMDTimeOut, events E_CHG_AMD will be throw out.(at this condition, the value of E_CHG_AMD is 3)

AMDToneCount : Uses to judge if the tone detected time is overtime or not. If this time is over the value of AMDToneCount, the event E_CHG_AMD will be thrown out (at this condition, the value of E_CHG_AMD is 1).

AMDTOn : Uses to set the lowest duration when the voice goes into the High voltage state.

AMDTOff : Uses to set the lowest duration when the voice goes into the low voltage state.

AMDTimeA : Uses to set the lowest silence duration before the phone pickup by man detected.

AMDTimeB : Uses to set the lowest duration when the phone pickup by man detected.

AMDTimeC : Uses to set the maximal duration when the phone pickup by man detected.

AMDTimeD : Uses to set the lowest silence duration after the phone pickup by man detected.

AMDSilentEnergy : Uses to set an energy value that can judge the voice is silence or not.


1.10.5.1 FFT

The FFT component in the on-board DSP chips provides FFT signal processing, transforming input voice signals from the time domain to the frequency domain and performing a FFT calculation of on-line voice signals every 16ms. The results are input to the subsequent component.

Following the FFT signal processing, the driver will send the events listed below to the application.

· E_OverallEnergy : sends the overall energy calculated by FFT to the application. The application need not respond to this event in most cases.

· E_CHG_PeakFrq : sends the calculated frequency and in-band energy of the peak signal in the spectrum to the application. The function SsmSetPeakFrqDetectBW is used to set the bandwidth of the peak frequency. The application need not respond to this event in most cases. Note that this event is thrown out only when the peak frequency changes.

Note:

l We do not use decibel (DB) as the dimensions for the output overall energy with the purpose of simplifying the calculation. If the application requires DB as the dimensions, the transformational relation between the output overall energy and DB can be expressed as follows (suppose X is the energy value obtained via API functions).

SHT Series: DB=10*lg(X/72,000,000)

SHD Series: DB=10*lg(X/33,000,000)

SHN Series: DB=10*lg(X/33,000,000)

ATP Series: DB=10*lg(X/72,000,000)

DTP Series: DB=10*lg(X/33,000,000)

DST Series: DB=10*lg(X/33,000,000)

24DA Boards: DB=10*lg(X/22,000,000,000)

l The FFT component quits working upon the start of the FSK receiver.


1.10.5.2 Noise Filter

Usually there is no need to reconfigure the noise filter, for its default settings are adequate for most situations.

The following figure demonstrates the operation principle of the noise filter.

When the overall energy is less than the threshold value specified by the configuration item MinimumVoiceDetermineEnergy (or the function SsmSetMinVocDtrEnergy ), the driver will identify the signal as a noise, otherwise as a true voice or tone.


1.10.5.3 Call Progress Tone Detector (SHT Series Only)

Since the analysis made by the call progress tone detector on the analog trunk channel has a direct effect on the call progress, it appears exceptionally important to properly use and configure the call progress tone. In general, application systems can be divided into two categories based on different connection methods: connection to direct line and connection to extension line.

Below is the application system that connects to the direct line (COT: Central Office Terminal).

Such application system only requires the board driver to detect one kind of call progress tone.

Below is the application system that connects to the extension line.

Since the proprietary PBX and the COT involved in the above situation probably differ in tone from each other, the board driver is required to detect two kinds of call progress tone at the same time.

There are two call progress tone detectors - the 1st and the 2nd - available for various cases. Its operation principle is shown in the figure below.

As illustrated above, the call progress tone detector consists of the frequency detector, the pulse-width filter, the dial tone detector, the echo (ringback) tone detector, the busy tone detector and the user-defined tone detector.

The user-defined tone detector is only applicable to some particular instances.

The dial tone detector, the echo (ringback) tone detector, the busy tone detector and the user-defined tone detector can work in double harness.

· Frequency Detector

The frequency detector examines the frequency of input signals to determine if there contain tones at the specified frequency. It calculates the percentage of in-band energy of dual tones to overall energy in real time and compares the result with a set threshold value. If the percentage is greater than the threshold value, it will conclude that the on-line signals are tones and output the judgement by voltage level (High voltage level means detection of tones while low level implies nondetection).

You can use the configuration item TonePara or the function SsmSetTonePara to set the two frequency parameters for the frequency detector in the 1st call progress tone detector, including the center frequency, the bandwidth and the threshold value for the percentage of in-band energy.

Likewise, you can use the configuration item 2ndTonePara or the function SsmSet2ndTonePara to set the two frequency parameters for the frequency detector in the 2nd call progress tone detector, including the center frequency, the bandwidth and the threshold value for the percentage of in-band energy.

· Pulse-width Filter

The pulse-width filter is used to filter signals by pulse width so as to eliminate the effect of interlarded tones on detection. In case the voltage level of the signal transforms from low to high, only if the signal stays at on state for more than the time specified by the configuration item ToneHighFilterPoint will the driver confirm the tone’s coming to being; In case the voltage level of the signal transforms from high to low, only if the signal stays at off state for more than the time specified by the configuration item ToneLowFilterPoint will the driver confirm the tone’s disappearing.

Note:

(1) The configuration parameters of the pulse-width filter also work on the 1st and 2nd call progress tone detectors as well as the fax progress tone detector.

(2) On the analog trunk channel or analog trunk recording channel, the results acquired by the dial tone detector, the echo (ringback) tone detector, the busy tone detector and the user-defined tone detector in the 1st call progress tone detector will automatically trigger corresponding events to change the state machine; however, whether the results obtained in the 2nd call progress tone detector trigger corresponding events to change the state machine or not is determined by the configuration item Check2ndToneOnAutoDial .


1.10.5.3.1 Dial Tone Detector

Detection of dial tones is accomplished by the dial tone detector. The figure below shows the typical dial-tone waveform.

The tone detector will throw out the event E_CHG_ToneAnalyze (with the parameter CHKTONE_DIALTONE) once the tone duration at on state counted by the driver reaches the threshold value Td which is set to judge the dial tone, and send off E_CHG_ToneAnalyze (with the parameter CHKTONE_NO_RESULT) when the dial tone disappears.

For the 1st call progress tone detector, Td is specified by the configuration item IsDialToneDetermineTime or the function SsmSetIsDialToneDtrTime ; for the 2nd (if available), Td is designated by the configuration item 2ndIsDialToneDetermineTime or the function SsmSet2ndIsDialToneDtrTime .


1.10.5.3.2 Ringback Tone Detector

Detection of ringback tones is accomplished by the ringback tone detector. The figure below shows the typical ringback-tone waveform.

Main parameters for the ringback tone includes Ton (duration at on state) and Toff (duration at off state). Once detecting a signal either at on or off state lasts for a time that matches the set value, the call progress tone detector considers the signal as a ringback tone and adds 1 to the ringback tone count. Both Ton and Toff accept the error of ±20％.

For the ringback (echo) tone detector in the 1st call progress tone detector, the configuration item RingEchoTonePara or the function SsmSetRingEchoTonePara can be used to set Ton and Toff; for that in the 2nd (if available), the configuration item 2ndRingEchoTonePara or the function SsmSet2ndRingEchoTonePara is used.

The driver will send off the event E_CHG_RingEchoToneTime every time when the count output by the ringback tone counter on a ringback tone detector in the 1st or 2nd call progress tone detector varies, but throw out the event E_CHG_ToneAnalyze (with the parameter CHKTONE_ECHOTONE) only when the count turns to 1. Also the function SsmGetRingEchoToneTime can be used to acquire the duration of ringback tones.


1.10.5.3.3 Busy Tone Detector


1.10.5.3.3.1 General Features

Detection of busy tones is accomplished by the busy tone detector. The figure below shows the typical busy-tone waveform.

As shown in the figure above, a busy tone cycle falls into two parts: one corresponding to the signal duration at on state (Ton) and the other to the duration at off state (Toff). Because the duty ratio of busy tones is 50％, the value of Ton is equal to that of Toff and the driver only uses the busy tone cycle to determine if the on-line signals are busy tones. The acceptable error in the busy tone cycle is ±20%.

Once the signal duration at on or off state matches the set parameters of busy tones, the busy tone detector will consider the input signals as busy tones, add 1 to the corresponding busy tone counter (i.e. ‘Count’ mentioned in the above figure) and throw out the E_CHG_BusyTone event; when the count output by the busy tone counter equals a specified value, it will send off the event E_CHG_ToneAnalyze (with the parameter CHKTONE_BUSYTONE). The results from the busy tone detector also can be obtained via the following functions.

Function Name | Description
SsmGetBusyAMDToneCount | Obtains the count of busy tone cycles output by the 1st call progress tone detector.
SsmGet2ndBusyAMDToneCount | Obtains the count of busy tone cycles output by the 2nd call progress tone detector.
SsmGetBusyToneLen | Obtains the busy tone duration output by the 1st call progress tone detector.
SsmGet2ndBusyToneLen | Obtains the busy tone duration output by the 2nd call progress tone detector.

Each busy tone detector is able to examine 4 groups of busy tones which differ in cycle at one time.

Configuring the busy tone detector in the 1st call progress tone detector:

· The configuration item BusyTonePeriod (or the functions SsmSetBusyTonePeriod , SsmSetBusyTonePeriodEx ) is used to set the busy tone cycle;

· The configuration item IsBusyToneDetermineCount (or the function SsmSetIsBusyToneDtrCnt ) is used to determine upon detection of which busy tone does the driver send off the E_CHG_ToneAnalyze event.

Configuring the busy tone detector in the 2nd call progress tone detector:

· The configuration item 2ndBusyTonePeriod (or the functions SsmSet2ndBusyTonePeriod , SsmSetBusyTonePeriodEx ) is used to set the busy tone cycle;

· The configuration item 2ndIsBusyToneDetermineCount (or the function SsmSet2ndIsBusyToneDtrCnt ) is used to determine upon detection of which busy tone does the driver throw out the E_CHG_ToneAnalyze event.

In practice, the driver may mistake some signals resembling busy tones occasionally involved in voice signals as busy tones. To solve such problem, the busy tone detector sets a guard time threshold value (marked as Tmax). When the interval between two busy tone cycles gets longer than Tmax, the busy tone counter will automatically set the count to 0 so as to avoid misdetection.

The configuration item MaxBsTnOffTime is used to set Tmax and is applicable to busy tone detectors in both the 1st and 2nd call progress tone detectors.


1.10.5.3.3.2 Back-to-back Busy Tone Detection

The conventional method to detect busy tones may become useless on the analog trunk channel in some particular instances, such as in the application system based on the SHT Series boards shown below.

The SHT board in the application system uses two trunk channels to connect with Subscriber A and Subscriber B respectively through PBX-A and PBX-B, which enables a two-way call between A and B via CT bus. When one party (e.g. Subscriber A) hangs up and PBX-A sends busy tones to the board, Subscriber B will hang up too upon hearing the busy tone and command PBX-B to deliver busy tones to the board. At that time if the on-board circuits are not thoroughly disconnected yet, busy tones on either channel will go distorted and lose the regular waveform under the influence of echoes. As a result, the busy tone detector fails to detect busy tones accurately and the two channels stay occupied all the time.

To solve such problem, the busy tone detector is designed with the capability of back-to-back busy tone detection, which requires no extra configuration. However, the result of back-to-back busy tone detection is not contained in those output by the tone detector but supplied solely by the E_CHG_BusyToneEx event to the application program. Also it can be acquired by using the function SsmGetBusyToneEx .

Note: Only the 1st call progress detector supports back-to-back busy tone detection.


1.10.5.3.4 User-defined Tone Detector

The user-defined tone detector is only applicable to some particular occasions, such as when it is required to detect some user-defined waveforms during the runtime of the dial tone detector, ringback tone detector and busy tone detector. This detector is able to detect both continuous and periodic tones.

Configuring the user-defined tone detector in the 1st call progress tone detector:

² The configuration item AppointedToneAnalyzerSwitch is used to start or stop the detection.

² The configuration item IsAppointedToneDetermineTime is used to set the minimum duration of continuous signals. This detector judges continuous signals in the same way as the dial tone detector. When the tone continues for more than the time specified by this configuration item, the driver will throw out the event E_CHG_ToneAnalyze (with the parameter CHKTONE_APPOINTEDTONE).

² The configuration items AppointedTonePara and IsAppointedToneDetermineCount are used to set the durations of periodic signals respectively at on and off states as well as the minimum count of tone cycles. This detector judges periodic signals in the same way as the ringback tone detector. When the count obtained is greater than the minimum count designated by IsAppointedToneDetermineCount, the driver will send off the event E_CHG_ToneAnalyze (with the parameter CHKTONE_APPOINTEDTONE).

Configuring the user-defined tone detector in the 2nd call progress tone detector:

² The configuration item 2ndAppointedToneAnalyzerSwitch is used to start or stop the detection.

² The configuration item 2ndIsAppointedToneDetermineTime is used to set the minimum duration of continuous signals. This detector judges continuous signals in the same way as the dial tone detector. When the tone continues for more than the time specified by this configuration item, the driver will throw out the event E_CHG_ToneAnalyze (with the parameter CHKTONE_APPOINTEDTONE).

² The configuration items 2ndAppointedTonePara and 2ndIsAppointedToneDetermineCount are used to set the durations of periodic signals respectively at on and off states as well as the minimum count of tone cycles. This detector judges periodic signals in the same way as the ringback tone detector. When the count obtained is greater than the minimum count designated by 2ndIsAppointedToneDetermineCount, the driver will send off the event E_CHG_ToneAnalyze (with the parameter CHKTONE_APPOINTEDTONE).


1.10.5.4 Fax Progress Tone Detector (CTI Series)

There are two fax progress tone detectors respectively called the 1st fax progress tone detector and the 2nd fax progress tone detector, which are used to detect at one time two fax progress tones at different frequency. The fax progress tone is a single continuous tone.

The figure below shows the typical fax-progress-tone waveform.

The fax progress tone detector starts counting when it detects the signal at specified frequency. When the count reaches the threshold value Td, the driver will throw out the events E_CHG_VocFxFlag and E_CHG_ToneAnalyze (with the parameter CHKTONE_VOICEF1 or CHKTONE_VOICEF2) in order. Also the application can obtain the result via the function SsmGetVocFxFlag .

The parameters of the fax progress tone detector include the center frequency, the bandwidth, the threshold value for the percentage of in-band energy to overall energy and the minimum guard time Td. Those of the 1st fax progress tone detector can be set via the configuration item VoiceFreqF1Para or the function SsmSetVoiceFxPara while those of the 2nd via the configuration item VoiceFreqF2Para or the function SsmSetVoiceFxPara .

Note: The detection of fax answering tones during AutoDial on the analog trunk channel or analog trunk recording channel usually indicates that the called party (fax machine) has picked up. Therefore, the result obtained by the fax progress tone detector will automatically trigger the corresponding event to change the state machine.


1.10.5.5 Simplified Busy Tone Detector

Its operation principle, relative configuration items or functions, output events are all shown in the following figure.

As illustrated above, the operation of the simplified busy tone detector is controlled by the switch K3 which can be set via the configuration item ToneAnalyzeAtRcvFsk .

The noise filter herein works in the same way as the ‘Noise Filter’ described in the previous section except that the threshold value for judging the noise is set via the configuration item TAARFDetermineEnergy . Usually there is no need to reconfigure the noise filter, for its default settings are adequate for most situations.

The pulse-width filter herein runs in an identical manner as the ‘Pulse-width Filter’ described in the previous section, involving the same configuration items.

What makes the simplified busy tone detector different from the call progress detector is that it doesn’t examine the frequency of input signals, i. e. it assumes all input signals are tones, so that it doesn’t contain the frequency detector.

The algorithm used to examine the busy tone waveform is the same as that supported by the call progress tone detector to examine the regular busy tone waveform. Like the busy tone detector in the 1st call progress tone detector, this detector is able to examine 4 groups of busy tones which differ in cycle at one time and uses the same waveform parameters, i.e.

² The configuration item BusyTonePeriod (or the functions SsmSetBusyTonePeriod , SsmSetBusyTonePeriodEx ) is used to set the busy tone cycle;

² The configuration item IsBusyToneDetermineCount (or the function SsmSetIsBusyToneDtrCnt ) is used to determine upon detection of which busy tone does the driver send off the E_CHG_ToneAnalyze event.

The simplified busy tone detector also has the ability to prevent misdetection of busy tones, which is enabled similarly by setting the guard time Tmax via the configuration item MaxBsTnOffTime .

This detector outputs in an identical manner as a standard busy tone detector. Every time when a busy tone cycle is detected, the detector will add 1 in the busy tone counter (i.e. ‘Count’ mentioned in the above figure) and throw out the E_CHG_BusyTone event; when the count reaches a specified value, it will send off the event E_CHG_ToneAnalyze (with the parameter CHKTONE_BUSYTONE).

Note:

l For the analog trunk channel, the E_CHG_ToneAnalyze event will be automatically triggered at the same time to change the state machine.

l Only the SHT Series analog trunk channel is designed with the simplified busy tone detector.


1.10.5.6 AMD (Answering Machine Detector)

the following figure show the principle diagram, relative configuration items, functions and output event of AMD.

文本框: Answering Machine Detector

SsmGetAMDResult

SsmClearAMDResult

EnableAMD

èE_CHG_AMD

K6

Answering Machine Detector

Answering machine detector is controlled by K6 which also can set by configuration item EnableAMD .

The AMD distinguish the answering machine from the human being through analyzing the on-line voice. This detector can widely uses in dialing system to improve the woke efficiency of seat telephone operator. Now, the successful rate of distinguishing the answering machine from the human being is higher then 90%.

The result of AMD can be obtain through output the parameter of event E_CHG_AMD or via calling the function SsmGetAMDResult to get it return value. calling the function SsmClearAMDResult can clear the detecting result of last time.

Note:

l AMD works normal only when the Tone Detector is enabled.

l If the channel is an analog trunk channel, AMD will auto-start after dialing. If the channel is a digital trunk channel, AMD will auto-start after the channel turns into the talking state.


1.10.5.7 Enhanced Tone Detector

The operation principle of the enhanced tone detector is to divide tones into three categories for detection, i.e. continuous tone, periodic tone and special information tone (SIT - three continuous single tones). Set with different parameters according to various characteristics of these three kinds of tones, this detector can properly detect all of them.

All parameters used are described as follows.

² The 1st mid-frequency F1

Ø For continuous tones, when a single tone is detected, F1 represents its frequency; when a dual tone is detected, F1 indicates the 1st mid-frequency of the tone.

Ø For periodic tones, when a single tone is detected, F1 represents its frequency; when a dual tone is detected, F1 indicates the 1st mid-frequency of the tone.

Ø For a special information tone (SIT), F1 represents the frequency of the 1st band.

² The 2nd mid-frequency F2

Ø For continuous tones, when a single tone is detected, F2 is equal to 0; when a dual tone is detected, F2 indicates the 2nd mid-frequency of the tone.

Ø For periodic tones, when a single tone is detected, F2 is equal to 0; when a dual tone is detected, F2 indicates the 2nd mid-frequency of the tone.

Ø For a special information tone (SIT), F2 represents the frequency of the 2nd band.

² The frequency of the 3rd band F3

Ø Only valid for special information tones (SIT), F3 represents the frequency of the 3rd band.

² Durations T1, T2, T3

Ø For continuous tones, T1 indicates the duration at on state; T2, T3 are invalid.

Ø For periodic tones, T1 indicates the duration at on state in a period; T2 indicates the duration at off state in a period; T3 is invalid.

Ø For a special information tone (SIT), T1, T2, T3 respectively indicate the durations of three continuous single tones.

² The filtering point number at on and off states Con, Coff (time length at each point is 16ms)

Ø Set the time to judge the wave form (upwards or downwards). When the filtering point number gets larger than Con, we say the wave goes into the on state; when the filtering point number is larger than Coff, the wave is considered getting the off state.

² The frequency error threshold Ferr(Hz)

Ø Sets the accepted error of the parameters F1, F2, F3.

These three kinds of tones are illustrated as follows:

l Continuous Tone

The dial tone and the fax tone F1/F2 belong to this kind and should be configured as continuous tones. Once the duration at on state T1 is detected, the events E_CHG_ToneDetector and E_CHG_ToneDetectorItem will be thrown out.

l Periodic Tone

The ringback tone, the howler tone and the busy tone all belong to this kind and should be configured as periodic tones. Once a complete cycle is detected, the events E_CHG_ToneDetector and E_CHG_ToneDetectorItem will be thrown out.

l SIT (Special Information Tone)

An SIT tone consists of three continuous single tones, each of which has its own frequency. Such kind of tones should be configured as SIT tones. Once three continuous single tones are detected, the events E_CHG_ToneDetector and E_CHG_ToneDetectorItem will be thrown out.

Relative configuration items:

² ToneDetectorItem[n] describes all parameters, such as frequency, signal duration at off state, signal duration at on state, etc., for the tones to be detected.

² MaxToneDetectorItem indicates how many kinds of tones will be detected by the enhanced tone detector.

² VoiceOffDetermineTime is used to set the time of silence detection. Its value depends on the period of the ringback tone in the common mode, usually being 1.2 times the period of the ringback tone. However, it needs to be set manually in the enhanced mode.

The parameter dwParam of the event E_CHG_ToneDetector tells the kind of tones and the N which this kind of tones corresponds to in ToneDetectorItem[N] . The event E_CHG_ToneDetectorItem records the period of tones, and the 2 lower bits of dwParam indicate how many periods the tone lasts.

To be compatible with previously developed application programs, the enhanced tone detector provides the following interfaces other than the event interfaces E_CHG_ToneDetector and E_CHG_ToneDetectorItem .

² API Interface: SsmStartToneAnalyze , SsmCloseToneAnalyze , SsmGetToneAnalyzeResult , SsmClearToneAnalyzeResult

² Event Interface: E_CHG_ToneAnalyze


1.10.6 Tone Generator (CTI Series)

The ‘tone’ mentioned herein refers to the call progress tone at a constant frequency and a certain tempo. It uses various tempos to imply different on-line states, for example, the remote end hangs up, the line is busy, etc. Each channel on the Synway boards has an independent tone generator.

The parameters of the tone generator include the center frequency (either single or dual), the amplitude and the tempo. Tones can be separated by tempo into two categories: the continuous tone and the periodic tone.

The continuous tone is the tone that keeps going at on state throughout the runtime of the tone generator. The dial tone is of this kind with the waveform as shown below.

The periodic tone is the tone which undergoes several signal cycles, each of which involves a duration at on state and a duration at off state. The busy tone and the ringback tone are of this kind with the typical waveform as shown below.

In the figure above, T1 and T2 respectively represent the 1st and 2nd cycles while Ton and Toff indicate the signal durations respectively at on and off states. The rate of Ton to Toff is called duty ratio: the busy tone’s duty ratio is 1:1 and the ringback tone’s is 1:4.


1.10.6.1 Configuring Tone Generator

Configuration items or functions related to frequency and amplitude are displayed in the following table.

Function Name | Description | Related Configuration Item
SsmQueryOpSendTone | Queries if the channel supports the tone generator. |
SsmSetTxTonePara | Sets frequency and amplitude of each channel’s tone generator. | DefaultSendToneFrequence DefaultSendToneVolume
SsmGetTxTonePara | Obtains frequency and amplitude of each channel’s tone generator. |


1.10.6.2 Tone Generation

Functions related to the tone generator are shown in the following table.

Function Name | Description
SsmSendTone | Starts the tone generator.
SsmSendToneEx | Starts the tone generator (allowed to set Ton and Toff in parameters).
SsmStopSendTone | Stops the tone generator.
SsmChkSendTone | Obtains the type of tones being sent by the tone generator.

Note: The operations listed below are forbidden once the tone generator is started (except for 120A series boards).

· Voice playing;

· Run of the DTMF generator;

· FSK data transmission.


1.10.7 Echo Canceller (CTI Series)

The echo cancellation feature helps effectively improve the quality of voice communications and greatly enhance the accuracy of the DTMF detector and the Barge-in detector.

The operating mode of the echo canceller can be set via the function SsmSetEchoCanceller or the configuration item EnableEchoCancellor , with a default setting of ‘Enabled’. Note: Because the echo canceller once enabled will change incoming signals, if FSK data reception is required to be performed on a channel, you should disable the echo canceller and not enable it until the reception is completed to ensure the reliability in data communication.

You can modify the configuration item LoadFskBin to optimize the performance and the effect of the echo canceller for the SHD Series 30/60/120-channel boards. However, it may cause those boards to lose the call recording and FSK data receive/transmit features due to the DSP resources being exhausted.

The echo canceller afforded by the Synway board in default is adequate for most application environments. If you are required to change the operating mode or reset the parameters of the echo canceller in some particular instances, please do it under the instruction of our technicians. Its parameters can be set via the function SsmSetEchoCancelDelaySize or the configuration item EchoCancelDelaySize .


1.10.8 Barge-in Detector

The Barge-in detector is used to detect voice activities on the line, often applicable to those occasions that involve the voice-controlled recording, the automatic speech recognition (ASR), etc. As long as a channel possesses the capability of echo cancellation, it will prevent the echoes of outgoing signals from the local end (e.g. voices generated during voice playing) going to the Barge-in detector, which thereby brings about quite precise results for the Barge-in detector. To know if a channel has the capability of echo cancellation, refer to relative hardware manuals.

The Barge-in detector is composed of the noise filter, the voice activity detector and the silence detector as shown in the figure below.

The switch K1 which is under an automatic control of the driver determines the operating mode of the Barge-in detector and the driver control mechanism is demonstrated by the following table:

Channel Type | Driver Behavior | Trigger Condition
The conferencing channel to be scheduled | Switch on K1 | The channel enters the conference room.
 | Switch off K1 | The channel leaves the conference room.
The TUP / ISUP channel The SS1 channel | Switch on K1 | The channel state transfers to S_CALL_TALKING.
 | Switch off K1 | The channel state transfers out of S_CALL_TALKING.
The ISDN channel | Switch on K1 | The channel state transfers to S_CALL_WAIT_REMOTE_PICKUP (outgoing call) or S_CALL_RINGING (incoming call).
 | Switch off K1 | The channel state transfers out of S_CALL_TALKING.
The analog trunk channel | Switch on K1 | The channel state transfers out of S_CALL_STANDBY.
 | Switch off K1 | The channel state transfers to S_CALL_STANDBY.
The station channel | Switch on K1 | The channel state transfers to S_CALL_PICKUPED.
 | Switch off K1 | The channel state transfers to S_CALL_STANDBY.
The analog trunk recording channel | Switch on K1 | Detects the pickup behavior.
 | Switch off K1 | Detects the hangup behavior.

If you are using the SHD Series boards, you can have K1 switched on all the time via the configuration item AlwaysDetectBargeIn no matter which state the channel transfers to.

If you are using the SHN Series boards, Switch K1 can be controlled only by the configuration item AlwaysDetectBargeIn but not by the driver.

The noise filter is used to distinguish on-line noises from real voice signals. You can use the configuration item VoiceEnergyMinValue to set the noise threshold value, judging the incoming or outgoing signals as on-line noises if the signal intensity stays lower than the set value; the function SsmSetBargeInSens or the configuration item BargeInSensitive to set the sensitivity of the noise filter; and the configuration item DefaultDtmfIsSound to determine whether to consider the DTMF digits interlarded in incoming signals as voice signals.

The voice activity detector is used to detect the on-line voice activities. The driver will throw out the E_SYS_BargeIn event once voice activities are detected in incoming signals which continue for more than the set value of the function SsmGetIsBargeInDtrmTime or the configuration item BargeInDtrmTime . Also the application can obtain the result via the SsmDetectBargeIn function.

The silence detector is used to judge if the line is silent or not. The E_SYS_NoSound event is triggered when the line keeps silent during an incoming call longer than the set value of the function SsmSetNoSoundDtrmTime or the configuration item IsNoSoundDtrmTime . The detected result can be obtained via the function SsmDetectNoSound and the silent duration can be acquired via the function SsmGetNoSoundTime .


1.10.9 TDM Capability

The Synway boards support two TDM modes:

Ø Interchannel Exchange: The capability to exchange voice data between on-board channels. Each Synway board has such capability.

Ø Interboard Exchange: The capability to exchange voice data between channels respectively on different boards. All Synway boards except the SHT and ATP Series 4-channel (the ‘-USB’ model) and 8-channel boards are equipped with such capability.

The cPCI boards use H.110 bus while the rest use H.100 bus.

The following figure demonstrates the operation principle of voice exchange by TDM.

In the figure above, the two-way connection between Ch A and Ch B is performed as follows: Put incoming voice data from Ch A to Time Slot i on TDM bus and then transmit them from Time Slot i to Ch B. In this way, Ch B is enabled to hear the incoming call from Ch A; likewise, Ch A can hear the incoming call from Ch B as long as incoming voice data from Ch B are put to Time Slot j on TDM bus and then transmitted from there to Ch A.

During system initialization, the driver will put incoming signals from each channel to a time slot on TDM bus provided the configuration item InVoiceToBus is set to 1 (default).

Related functions often used are listed in the following table.

Exchange Operation | Function Name | Description
Establishing Two-way Connection | SsmTalkWith | Establishes a two-way connection between 2 channels.
 | SsmTalkWithEx | Establishes a two-way connection between 2 channels, allowed to set the volume on the 2 channels.
Tearing off Two-way Connection | SsmStopTalkWith | Tears off the two-way connection between Ch 1 and Ch 2.
Establishing One-way Connection | SsmListenTo | Establishes a one-way connection from the talker channel to the listener channel.
 | SsmListenToEx | Establishes a one-way connection from the talker channel to the listener channel, allowing setting the volume on the talker channel.
 | SsmLinkFrom | Establishes a one-way connection from the talker channel to the listener channel, permitting the listener channel to listen to multiple channels simultaneously.
 | SsmLinkFromEx | Establishes a one-way connection from the talker channel to the listener channel, permitting the listener channel to listen to multiple channels simultaneously and allowing setting the volume on the talker channel as well.
 | SsmLinkFromAllCh | Establishes a number of one-way connections from one talker channel to multiple listener channels, permitting the listener channel to listen to multiple channels simultaneously and allowing setting the volume on the talker channel as well.
Tearing off One-way Connection | SsmStopListenTo | Tears off the one-way connection established by using the function SsmListenTo or SsmListenToEx.
 | SsmStopLinkFrom | Tears off the one-way connection established by using the function SsmLinkFrom or SsmLinkFromEx.
 | SsmUnLinkFromAllCh | Tears off the one-way connection established by using the function SsmLinkFromAllCh.
Tearing off all Connections | SsmClearChBusLink | Tears off all bus connections on the channel and recovers the channel to the state upon the driver’s initialization.

Below lists the advanced TDM functions which are used to establish or tear off the one-way connection between channels and time slots:

Exchange Operation | Function Name | Description
Channel to Time Slot | SsmLinkToBus | Changes the time slot which is set to receive the signals from the onto-bus mixer.
 | SsmUnLinkToBus | Reuses the default time slot to receive the signals from the onto-bus mixer.
Time Slot to Channel | SsmLinkFromBus | Establishes the one-way connection from a time slot to the listener channel.
 | SsmLinkFromBusEx | Establishes the one-way connection from a time slot to the listener channel, allowing setting the volume.
 | SsmUnLinkFromBus | Tears off the one-way connection from a time slot to the listener channel


1.10.10 Distributed Teleconferencing System (CTI Series)


1.10.10.1 Basic Concepts

Ø Distributed Conferencing Technology

The CTI Series boards equipped with an independent mixer on each channel support teleconferencing without the need for extra conferencing boards. This technology, which we call Distributed Conferencing Technology, is Synway’s patent technique. Note that the teleconferencing feature will be unsupported once the driver enables the soft-exchange over bus, and the multi-boards teleconferencing feature is not supported with those boards excluding the CT-Bus interface.

Ø Conference Room

A conference room consists of all channels that participate in a same conference. Each conference room has a unique number which is either specified by the application or allocated by the driver. The total number of channels in a conference room is allowed to range from 3 to the total number of all channels in the application system, which can be set via the configuration item ConfDefaultMaxGroupMember or designated by the function SsmCreateConfGroup while creating the conference room.

The total number of conference rooms can be determined via the configuration item ConfMaxGroup .

Ø Conference Room Number

Each conference room has a unique number which is called Conference Room Number and ranges from 0 to the set value of the configuration item ConfMaxGroup minus 1.

Ø Conference Channel

The channel which joins a teleconference is called Conference Channel.

Ø Conference Channel Number

It is the logical number for each channel in the conference room, counted from 0. Note that the conference channel number is not always the same as the channel number.

Ø Conference Scheduling Program

Since the available conference mixer sources are limited, when the number of channels speaking at one time in a conference room containing a relatively large number of members exceeds the maximum accepted by the conference mixer, there is bound to be some part of the on-channel voices incapable to enter the conference mixer. The SynCTI driver contains a conference scheduling program which provides an automatic scheduling over the conference and allows only those on-channel voice signals which meet the scheduling conditions to enter the conference mixer.

The conference scheduling is based on the priority level of the conference channel. All conference mixers on the board are allocated first to the channels of high priority level, and then to those of low priority.

Provided the number of schedulable mixer sources is N, the number of organizer channels is m, the number of chairman channels is n and the number of dynamic speaker channels being speaking is k, the conference scheduling follows the rules below.

(1) First of all, allocate the conference mixer sources to m organizer channels. Then go to the next step if still some mixer sources left.

(2) If n≤N-m, all the n chairman channels can obtain mixer sources; if n>N-m, the scheduling program will arrange them by voice signal intensity (volume) in a high-to-low order and ensure the first N-m ones to acquire mixer sources. Start the allocation in the next priority level if still some mixer sources left.

(3) If k≤N-m-n, all the k dynamic speaker channels being speaking can obtain mixer sources; if k>N-m-n, the scheduling program will arrange them by voice signal intensity (volume) in a high-to-low order and ensure the first N-m-n ones to acquire mixer sources. A dynamic speaker channel, after seizing a mixer, if there is no other channel with higher priority preempting mixer sources against it, will keep occupying the mixer.

Ø Conference Channel’s Speaking Mode

Each channel is given certain speaking rights when it enters a conference room. The SynCTI driver supports 6 speaking modes as described in the following table.

Speaking Mode | Description
Organizer | Can speak as well as listen to other channels. This mode is of the highest priority level. The channel in this mode is called Organizer Channel for short. It is suggested that the application program set only one organizer channel for each conference room.
Chairman | Can speak as well as listen to other channels. This mode is of the priority lower than the Organizer mode but higher than the Dynamic Speaker mode. The channel in this mode is called Chairman Channel for short.
Dynamic Speaker | Can speak as well as listen to other channels. This mode is of the priority lower than the Chairman mode. The channel in this mode is called Dynamic Speaker Channel for short.
Listener | Can listen to other channels but not speak. The channel in this mode is called Listener Channel for short, which is not involved in conference scheduling.
Background Music | Can speak but not listen to other channels, usually used to play background music to a conference room. Note: Whether a channel in this mode takes part in conference scheduling and is of which priority are both determined by the configuration item BackgroundVoicePriority . The channel in this mode is called Background Music Channel for short.
Dynamic Speaker ONLY | Can speak but not listen to other channels. The channel which serves as a dynamic speaker but cannot listen to other channels is called Dynamic Speaker ONLY Channel for short.

Ø DTMF Clamping

When a conference participant presses keys on the phone, the on-line DTMF tones will go into the conference mixer and be heard by other channels. The SynCTI driver supports the DTMF clamping feature which can effectively eliminate the DTMF signals generated by keypress.

The operation principle of this feature is: The incoming signals will be immediately interrupted once the on-board DTMF detector detects DTMF signals on the conference channel and resumed when all DTMF signals disappear.

The configuration item ClearInVoiceOnRxDtmf or the function SsmSetFlag (with the parameter F_ClearInVoiceOnRcvDtmf) is used to determine whether to enable the DTMF clamping feature or not.

Ø Coming Voice Blocking

In a normal situation, once a conference channel enters a conference room, the incoming voice signals on it are allowed to go into the conference mixer and be heard by other channels only if it meets the scheduling conditions. Invoke the function SsmSetFlag (with the parameter F_InVoiceToBus) or use the configuration item InVoiceToBus if you want to temporarily forbid this channel to speak.


1.10.10.2 Managing Conference Room

Below is a list of functions and configuration items related to the conference room.

Function Name | Category | Description
SsmCreateConfGroup | Function | Creates a conference room.
SsmFreeConfGroup | Function | Cancels a conference room.
ConfDefaultMaxGroupMember ConfDefaultMaxGroupSpeaker ConfDefaultMaxGroupSpeaking | Configuration Item | Set parameters in relation to the conference room
SsmGetConfCfgInfo SsmGetTotalConfGroup SsmGetConfGrpInfo SsmGetConfGrpCfgInfo SsmGetConfGrpId SsmValidateGrpId | Function | Obtain relative information about the conference room.
SsmGetConfGrpMmbrId SsmGetConfGrpMmbrInfo SsmGetConfChInfo | Function | Obtain relative information about members in the conference room.


1.10.10.3 Managing Conference Channel

Below is a list of functions and configuration items related to the conference channel.

Function Name | Category | Description
SsmJoinConfGroup | Function | Puts a channel into the conference room.
SsmExitConfGroup | Function | Puts a channel out of the conference room.
SsmSetListenVlmInConf | Function | Sets the voice volume in the conference room which is heard by a channel.


1.10.10.4 Playing Background Music to Conference Room

If you want to play background music and conference notice, etc. to the conference room, do it as follows:

Ø Choose a conference channel to play the voice. There are three ways available:

² Set an independent background music channel for the conference room. This method is quite flexible, allows the application to determine the priority of each channel according to the actual needs. However, the shortcoming is it requires an extra channel.

² Select a channel from those in the conference to be the organizer channel. It is the most ideal solution to have an organizer channel in the conference, but you should manage by programming to make this channel the last one to leave the conference.

² Select a chairman channel or a dynamic speaker channel if no organizer channel available in the conference room. In this case, we suggest the chairman channel be your first choice. The shortcoming of this method is that the application needs to turn over the play task to another conference channel if the playing channel leaves the conference midway due to some particular reasons (e.g. an accidental disconnection).

Ø Invoke the function SsmSetPlayDest to switch on k1-1 illustrated in the operation principle of the SHT/SHD/SHN Series boards. For more information, refer to the section Operation Principle of SHT Series or Operation Principle of SHD Series or Operation Principle of SHN Series in this chapter.

Ø Invoke the playing functions. See the section Voice Playing in this chapter for more information.


1.10.10.5 Recording Voice in Conference Room

If you need to record the voice played in the conference room, do it as follows:

Ø Choose a conference channel to record the voice. Although any conference channel can be used for recording, you’d better select the one which won’t leave the conference midway to avoid the handover of the record task between channels. Below are the suggested ways to make a choice among channels.

² Make a prior choice of the background music channel.

² Select an organizer channel.

² Select a chairman channel.

² Select a dynamic speaker channel.

² Select a listener channel or a dynamic speaker channel.

Ø Invoke the function SsmSetRecBack to switch on k6-1 and k6-2 illustrated in Operation Principle of SHD Series or Operation Principle of SHN Series if the channel is on the SHD/SHN board and required to record the voice and play the background music at the same time.

Ø Invoke the recording functions. See the section Voice Recording in this chapter for more information.


1.11 FSK Transceiver (CTI Series)

BFSK (Binary Frequency Shift Keying) is a digital communication technology using different carrier frequencies to represent the digits 0 and 1 in the binary system, often adopted to transmit the calling party number, short messages and so on through the phone line.

The BFSK data is composed of frames as illustrated below.

A complete BFSK data stream consists of three parts: the syn code, the flag code and the data. The syn code is of the 0/1 up-and-down waveform and the flag code is 1 at on state. In each data byte which is guided by the start bit 0 and followed by the stop bit 1, the digit at Bit 0 is the first to be transmitted while that at Bit 7 is the last.

Note: In some protocols the flag code is called ‘synchronization end character’, and it is together with the syn code called ‘synchronization indicator string’ which verifies the synchronization has been established.

The Synway CTI Series boards supply each channel on them with an FSK transceiver which works at the baud rate of 1200bps in the semiduplex mode. The frequency of the digit 1 herein is 1200Hz while 0 is 2200Hz.


1.11.1 FSK Transmitter

Related functions, configuration items and events are listed in the following table.

Category | Name | Description
Configuration Item | FreqBit0 FreqBit1 Baudrate MdlAmp | Set the parameters of the FSK transmitter.
Function | SsmSetFskPara | Sets the parameters of the FSK transmitter.
 | SsmTransFskData | Converts data into the BFSK data stream.
 | SsmStartSendFSK | Starts the FSK transmitter.
 | SsmCheckSendFsk | Queries the working progress of the FSK transmitter.
 | SsmStopSendFsk | Stops the FSK transmitter.
Event | E_PROC_SendFSK | The event which is sent to the application when the driver finishes transmitting all data.


1.11.2 FSK Receiver

It is ascertained that the FSK transceiver on the Synway board works at the baud rate of 1200bps, the frequency of the binary digit 1 is 1200Hz while 0 is 2200Hz. All these three values are not allowed to be modified via functions or configuration items.

FSK functions, configuration items and events are listed in the following table

Name | Description
Configuration Item: ToneAnalyzeAtRcvFsk | Determines whether the FSK receiver will analyze the tone during its runtime.
Configuration Item: FskMarkSignal | Sets the way to receive data for the FSK receiver.
Configuration Item: FskFrameMode | Sets the frame format that accepted by the FSK receiver.
Configuration Item: FskEchoCancelDelay Function: SsmSetFlag (with the parameter F_EchoCancelInFsk) | Sets whether to stop the echo canceller when the FSK receiver is working.
Function: SsmStartRcvFSK Function: SsmStartRcvFSK_II Function: SsmStopRcvFSK | Start/stop the FSK receiver.
Function: SsmGetRcvFSK Function: SsmCheckRcvFSK | Obtains the FSK data; Queries the working progress of the FSK receiver.
Function: SsmClearRcvFSKBuf | Clears the driver buffer of the FSK receiver.
Event: E_PROC_RcvFSK | The event which is sent to the application when the driver detects the end of the FSK task following starting the FSK receiver.


1.12 Fax (CTI Series)


1.12.1 Setting Number of Fax Channels

The following board models in SHT and SHD Series support fax channels.

Ø Those with ‘/FAX’ marked in the model are:

² SHT-8B/PCI/FAX

² SHT-8C/PCI/FAX

² SHT-16B-CT/PCI/FAX

² SHT-16B-CT/cPCI/FAX

² SHT-16C-CT/PCI/FAX

² SHD-30B-CT/PCI/SS7/FAX

² SHD-60B-CT/PCI/SS7/FAX

² SHD-30B-CT/cPCI/SS7/FAX

² SHD-60B-CT/cPCI/SS7/FAX

² SHD-30C-CT/PCI/FAX

² SHD-60C-CT/PCI/FAX

² SHD-30E-CT/PCI/FAX(SSW)

² SHD-60E-CT/PCI/FAX(SSW)

² SHD-120E-CT/PCI/FAX(SSW)

² SHD-240E-CT/PCI/FAX(SSW)

² SHD-30E-CT/PCIe/FAX

² SHD-60E-CT/PCIe/FAX

² SHD-120E-CT/PCIe/FAX

² SHD-240E-CT/PCIe/FAX

Ø Those without ‘/FAX’ marked in the model are:

² SHT-16B-CT/PCI

² SHT-16B-CT/cPCI

Both the fax and voice features are enabled by the processing performed via some algorithm on the DSP chips. Therefore, you can obtain more fax channels at the expense of some or all of the voice channels. The total number of fax channels is specified by the configuration item MaxFaxChannel . The table below unfolds the relationship among the set value of MaxFaxChannel, the board model and the total number of available fax channels.

Board Model | Set Value of MaxFaxChannel
 | 0 |  | 4 |  | 8 |  | 12 |  | 16 |  | 24 |  | 32 |  | 64
 | NFax | NVoc | NFax | NVoc | NFax | NVoc | NFax | NVoc | NFax | NVoc | NFax | NVoc | NFax | NVoc | NVoc | NFax
SHT-8B/PCI/FAX | 0 | 8 | 4 | 8 | - | - | - | - | - | - | - | - | - | - | - | -
SHT-8C/PCI/FAX | 0 | 8 | 4 | 8 |  |  |  |  |  |  |  |  |  |  | - | -
SHT-16B-CT/PCI/FAX | 0 | 16 | 4 | 16 | 8 | 8 | 12 | 0 | - | - | - | - | - | - | - | -
SHT-16B-CT/PCI | 0 | 16 | 4 | 8 | 8 | 0 | - | - | - | - | - | - | - | - | - | --
SHT-16B-CT/cPCI/FAX | 0 | 16 | 4 | 16 | 8 | 8 | 12 | 0 | - | - | - | - | - | - | - | -
SHT-16B-CT/cPCI | 0 | 16 | 4 | 8 | 8 | 0 | - | - | - | - | - | - | - | - | - | -
SHT-16C-CT/PCI/FAX | 0 | 16 | 4 | 16 | 8 | 8 | 12 | 0 | - | - | - | - | - | - | - | -
SHD-30B-CT/PCI/SS7/FAX | 0 | 30 | - | - | - | - | - | - | - | - | 24 | 30 | 32 | - | - | -
SHD-60B-CT/PCI/SS7/FAX | 0 | 60 | - | - | - | - | - | - | 16 | 60 | 24 | 30 | 32 | - | - | -
SHD-30B-CT/cPCI/SS7/FAX | 0 | 30 | - | - | - | - | - | - | - | - | 24 | 30 | 32 | - | - | -
SHD-60B-CT/cPCI/SS7/FAX | 0 | 60 | - | - | - | - | - | - | 16 | 60 | 24 | 30 | 32 | - | - | -
SHD-30C-CT/PCI/FAX | 0 | 30 | - | - | - | - | - | - | - | - | 24 | 30 | 32 | - | - | -
SHD-60C-CT/PCI /FAX | 0 | 60 | - | - | - | - | - | - | 16 | 60 | 24 | 30 | 32 | - | - | -
SHD-30E-CT/PCI/FAX(SSW) | - | - | - | - | - | - | - | - | - | - | - | - | -32 | 30 | - | -
SHD-60E-CT/PCI/FAX(SSW) | - | - | - | - | - | - | - | - | - | - | - | - | - |  | 64 | 60
SHD-120E-CT/PCI/FAX(SSW) | - | - | - | - | - | - | - | - | - | - | - | - | - | - | 64 | 120
SHD-240E-CT/PCI/FAX(SSW) | - | - | - | - | - | - | - | - | - | - | - | - | - | - | 64 | 240
SHD-30E-CT/PCIe/FAX | - | - | - | - | - | - | - | - | - | - | - | - | 32 | 30 | - | -
SHD-60E-CT/PCIe/FAX | - | - | - | - | - | - | - | - | - | - | - | - | - | - | 64 | 60
SHD-120E-CT/PCIe/FAX | - | - | - | - | - | - | - | - | - | - | - | - | - | - | 64 | 120
SHD-240E-CT/PCIe/FAX | - | - | - | - | - | - | - | - | - | - | - | - | - | - | 64 | 240

Note: In this table, NFax is ‘the total number of fax channels’, NVoc means ‘the total number of available voice channels’, and - implies ‘unsupported’.


1.12.2 Supported Fax Rate

Board Model | 4800bps |  | 9600bps |  | 12000bps |  | 14400bps
 | Transmit | Receive | Transmit | Receive | Transmit | Receive | Transmit | Receive
SHT-8B/PCI/FAX | Ö | Ö | Ö | Ö |  |  | Ö |
SHT-8C/PCI/FAX | Ö | Ö | Ö | Ö | Ö | Ö | Ö | Ö
SHT-16B-CT/PCI/FAX SHT-16B-CT/PCI | Ö | Ö | Ö | Ö |  |  | Ö |
SHT-16B-CT/cPCI/FAX SHT-16B-CT/cPCI | Ö | Ö | Ö | Ö |  |  | Ö |
SHT-16C-CT/PCI/FAX | Ö | Ö | Ö | Ö | Ö | Ö | Ö | Ö
SHD-30B-CT/PCI/SS7/FAX | Ö | Ö | Ö | Ö |  |  | Ö |
SHD-60B-CT/PCI/SS7/FAX | Ö | Ö | Ö | Ö |  |  | Ö |
SHD-30B-CT/cPCI/SS7/FAX | Ö | Ö | Ö | Ö |  |  | Ö |
SHD-60B-CT/cPCI/SS7/FAX | Ö | Ö | Ö | Ö |  |  | Ö |
SHD-30C-CT/PCI/FAX | Ö | Ö | Ö | Ö | Ö | Ö | Ö | Ö
SHD-60C-CT/PCI/ FAX | Ö | Ö | Ö | Ö | Ö | Ö | Ö | Ö
SHD-30E-CT/PCI/FAX(SSW) | Ö | Ö | Ö | Ö | Ö | Ö | Ö | Ö
SHD-60E-CT/PCI/FAX(SSW) | Ö | Ö | Ö | Ö | Ö | Ö | Ö | Ö
SHD-120E-CT/PCI/FAX(SSW) | Ö | Ö | Ö | Ö | Ö | Ö | Ö | Ö
SHD-240E-CT/PCI/FAX(SSW) | Ö | Ö | Ö | Ö | Ö | Ö | Ö | Ö
SHD-30E-CT/PCIe/FAX | Ö | Ö | Ö | Ö | Ö | Ö | Ö | Ö
SHD-60E-CT/PCIe/FAX | Ö | Ö | Ö | Ö | Ö | Ö | Ö | Ö
SHD-120E-CT/PCIe/FAX | Ö | Ö | Ö | Ö | Ö | Ö | Ö | Ö
SHD-240E-CT/PCIe/FAX | Ö | Ö | Ö | Ö | Ö | Ö | Ö | Ö


1.12.3 Supported Fax File Format

The fax channels on the Synway board support the fax protocol T.30 and T.4, allowed to transmit MH data and Tiff files.

The Tiff file is the mainstream one used to store fax data, which can be widely used and is easy to read, archive and modify. And the Tiff file supported by fax channels on the Synway board has the following properties.

ü Color: Black and white

ü Coding Format: MH

ü Resolution: 204*196, 204 * 98, 200 * 200, 200 * 100

ü Page Data: 1728 pixels per line

The operation principle for the application program to send files in any format is shown below.

As illustrated In the figure above, the virtual printer program is used to convert a file of any other format to a tiff file.

The analog/digital trunk channel as well as the fax channel are indispensable for a complete fax transmission or reception as shown below.

The fax transmission (or reception) process is divided into four distinct phases.

(1) Initiate and establish a call on the analog or digital trunk channel.

(2) Establish a two-way connection between the fax channel and the analog/digital trunk channel.

(3) Transmit (or receive) fax files.

(4) Disconnect the call.


1.12.4 Setting Faxing Parameters

Related functions which involve the faxing parameters are listed in the following table.

Function Name

Description

SsmFaxSetMaxSpeed

The initial faxing rate, also the maximum rate used to send or receive fax. This rate is applicable to all channels.

SsmFaxSetID

Sets the local fax identification code, usually using the local phone number or some letters. This code will be sent to the remote fax machine during faxing.


1.12.5 Acquiring Information on Faxing

Related parameters used in the faxing process can be obtained via the following functions.

Function Name | Description & Acquired Information
SsmFaxGetSpeed | Obtains the actual faxing rate, whose possible values are 24, 48, 72, 96, 120, 144, respectively representing 2400, 4800, 7200, 9600, 12000, 14400bps.
SsmFaxGetID | Obtains the remote fax identification code, usually after the handshake phase during faxing.
SsmFaxGetPages | Obtains the number of sent/received pages during faxing. If this function returns 0 when invoked after faxing, it indicates the current fax transmission or reception fails.
SsmFaxGetAllBytes | Obtains the total number of bytes on the fax page being sent.
SsmFaxGetSendBytes | Obtains the number of sent bytes on the current page during fax transmission. You can use this function to get such number after invoking the function SsmFaxStartSend .
SsmFaxGetRcvBytes | Obtains the number of received bytes on the current page during fax reception. You can use this function to get such number after invoking the function SsmFaxStartReceive .
SsmFaxGetChStateMsg | Obtains the information about the state of the specified channel during faxing.
SsmFaxCheckEnd | Obtains the fax channel state.


1.12.6 Fax Transmission

Functions related to fax transmission are listed in the following table.

Function Name | Description
SsmFaxStartSend | Starts transmission of a single fax file.
SsmFaxStartSendEx | Starts transmission of a single fax file, can specify the start page and the end page.
SsmFaxSendMultiFile | Starts transmission of multiple fax files.
SsmFaxSendMultiFileEx | Starts transmission of multiple fax files, can specify the start page and the end page.
SsmFaxAppendSend | Appends a single file to send. It works only if the fax channel stays in the fax-transmitting state.
SsmFaxCheckEnd | Obtains the fax channel state.
SsmFaxSetMaxSpeed | Sets the faxing rate.
SsmFaxSetID | Sets the local fax identification code which will be displayed on the LCD of the remote fax machine.
SsmFaxGetID | Obtains the remote fax identification code.
SsmFaxGetAllBytes | Obtains the total number of bytes on the fax page being sent.
SsmFaxGetSendBytes | Obtains the number of sent bytes on the current page during fax transmission.
SsmFaxGetSpeed | Obtains the current faxing rate.
SsmFaxGetPages | Obtains the number of sent/received pages during faxing.
SsmFaxStop | Stops the current faxing compulsorily.


1.12.7 Fax Reception

Functions related to fax reception are listed in the following table.

Function Name | Description
SsmFaxStartReceive | Starts fax reception. The received fax data will be stored in a set fax file.
SsmFaxCheckEnd | Obtains the fax channel state.
SsmFaxSetMaxSpeed | Sets the faxing rate.
SsmFaxSetID | Sets the local fax identification code which will be displayed on the LCD of the remote fax machine.
SsmFaxGetID | Obtains the remote fax identification code.
SsmFaxGetRcvBytes | Obtains the number of received bytes on the current page during fax reception.
SsmFaxGetSpeed | Obtains the current faxing rate.
SsmFaxGetPages | Obtains the number of sent/received pages during faxing.
SsmFaxStop | Stops the current faxing compulsorily.


1.13 On-board Audio Power Amplifier

Channel 0 on each ATP, DST or SHT Series board is equipped with the analog audio amplifier circuit and the speaker output jack, which allows the board to connect directly with the external speaker and enables the voice to be delivered to and played through the speaker. For detailed information about the on-board audio power amplifier, see the operation principle of the corresponding board.


1.14 Application Programming Based on Synway Board


1.14.1 Setting Event Output Mode

The written program based on the Synway board usually consists of three parts.

· Initialization codes, including both parts for initializing the board and the driver, used only once upon starting the application program.

· Processing codes, used to give commands to the driver and process in time the information returned via the event from the driver so as to enable particular features on demand.

· Uninstallation codes, covering the resources needed for releasing the board and the driver, used only once upon exiting the application program.

The SynCTI driver supports the following programming modes:

² Polling Mode: The application continuously calls the relative query functions supplied by the driver to obtain the information on task progress. These days this mode gradually goes out of use, for the high cost of computer resources and the low efficiency limit it to small application systems only. Therefore, this manual does not give further description on it.

² Event Polling Mode: The application program invokes the event polling functions offered by the driver. The application's caller thread is hung in case there is no event from the driver, and gets activated for event processing once some events available from the driver.

² Event Callback Mode: When the driver generates some event, it invokes the callback function which the application has been registered to process the event.

² Windows Message Mode (only applicable to Windows OS, the data structure of the output events can only be MESSAGE_INFO as well): The driver sends the events to the Windows message queue and processes them through the Windows unified message queue processing mechanism. Few applications use this mode for programming as it carries a limited number of parameters. That's why this manual does not elaborate this mode.

See how these four programming modes work through the following figure.

The switch K1 is controlled by the function SsmSetEvent. Every time the SynCTI driver starts up, it works in the polling mode. If the application need use Event Polling Mode or Event Callback Mode, the function SsmSetEvent should be called to change the mode. Refer to the programming examples listed below for details.


1.14.1.1 Programming Example in Event Polling Mode

#include <windows.h> //include the required Windows header file

#include "shpa3api.h" //include the header file required by the SynCTI driver

……

void main()

{

//initialize the SynCTI driver and the board

if ( ! SsmStartCti (……) )

{ //failed

……

MessageBox( "Initialize Voice card failure" );

return;

}

//obtain relative information about the board and the channel

int nMaxCh = SsmGetMaxCh(); //obtain the total number of channels

for (int ch=0; ch < nMaxCh; ch ++)

{

int nChType = SsmGetChType (ch); //get the channel type

……

}

//set the event output mode

EVENT_SET_INFO EventMode;

EventMode.DwWorkMode = EVENT_POLLING; //use the event polling mode

SsmSetEvent(0xffff, -1, true, &EventMode);

//transaction processing

MESSAGE_INFO Event;

While(1)

{

memset(&MessageInfo, 0, sizeof(PMESSAGE_INFO));

If (the application program exits) break; //codes for quitting the application program

//wait for and respond to the event thrown out by the driver

If ( SsmWaitForEvent (50, &Event) == 0 ) //wait for some event

{

switch(Event.EventCode)

{

case E_CHG_ChState： //the channel state changes

…… //transaction processing codes

break;

……

case E_XXXXXX：

……

break;

default:

break;

}

}

}

SsmCloseCti(); //close the driver upon exiting

}

In need of using the extended data structure of the output event, you may write the ‘transaction processing’ part among the above codes following the way below.

//transaction processing

UCHAR pucBuffer[300];

SSM_EVENT SsmEvent;

while(1)

{

memset(&SsmEvent, 0, sizeof(SSM_EVENT));

memset(pucBuffer, 0, sizeof(UCHAR)* 300);

SsmEvent.pvBuffer = (PVOID)pucBuffer;

SsmEvent.dwBufferLength = 300;

if(SsmWaitForEventA(50, &SsmEvent) == 0)

{

switch(SsmEvent.wEventCode)

{

case E_CHG_ChState:

…… //do something

break;

case E_RCV_DSTDChannel:

switch(SsmEvent.dwParam)

{

case DST_AUDIO_CHG:

…… //do something

break;

case DST_MSG_CHG:

…… //do something

break;

default:

break;

}

default:

break;

}

}

}


1.14.1.2 Programming Example in Event Callback Mode

#include <windows.h> //include the required Windows header file

#include "shpa3api.h" //include the header file required by the SynCTI driver

BOOL bExit = FALSE; //the variable to control whether the application program exits or not

……

//the callback function supplied by the application program to process the event thrown out by the driver

int CALLBACK MyCallback (WORD wEvent, int nReference, DWORD dwParam, DWORD dwUser)

{

switch(wEvent)

{

case E_CHG_ChState:

…… //do something

break;

case E_XXXXXX：

…… //do something

bExit = TRUE; //exit the application program

break;

……

default:

break;

}

return 1;

}

//the application’s main thread

void main()

{

……

if ( ! SsmStartCti (……) ) //initialize the SynCTI driver and the board

{ //failed

……

MessageBox( "Initialize Voice card failure" );

return;

}

int nMaxCh = SsmGetMaxCh(); //obtain the total number of channels

for (int ch=0; ch < nMaxCh; ch ++)

{

int nChType = SsmGetChType (ch); //get the channel type

……

}

//set the event output mode

EVENT_SET_INFO EventMode;

EventMode.DwWorkMode = EVENT_CALLBACK; //event callback mode

EventMode.lpHandlerParam = MyCallback; //register the callback function

SsmSetEvent(0xffff, -1, true, &EventMode);

While(!bExit) ; //wait for the program’s end

SsmCloseCti(); //close the driver upon exiting

}

In need of using the extended data structure of the output event, you may write the callback functions offered by the application program following the way below.

int CALLBACK MyCallback (PSSM_EVENT pEvent)

{

switch(pEvent->wEventCode)

{

case E_CHG_ChState:

…… //do something

break;

case E_XXXXXX：

…… //do something

bExit = TRUE; //exit the application program

break;

case E_RCV_DSTDChannel:

switch(pEvent->dwParam)

{

case DST_AUDIO_CHG:

…… //do something

break;

case DST_MSG_CHG:

…… //do something

break;

default:

break;

}

default:

break;

}

return 1;

}


1.14.2 Data Structure of Output Event

There are two data structures optional for the SynCTI driver to send off an event: MESSAGE_INFO and SSM_EVENT. While MESSAGE_INFO contains common parameters and is applicable to the CTI and REC Series boards, SSM_EVENT as the extension of MESSAGE_INF can offer more information about events and is mainly used for the DST Series boards provided the SynCTI driver is of the version 4.7.3.0 or above. But it is not applicable to the Windows Message programming mode. Use the configuration item EventInterfaceType to select the data structure for output events.

For example, if several boards are being used together and one of them is a DST Series board, only the SSM_EVENT data structure works and only the event polling mode and the event callback mode are choosesable.

Note: MESSAGE_INFO is applicable to functions SsmWaitForEvent and SsmGetEvent; SSM_EVENT is suitable for SsmWaitForEventA and SsmGetEventA.


1.14.2.1 MESSAGE_INFO

The MESSAGE_INFO structure declaration is:

typedef struct _MESSAGE_INFO

{

WORD wEvent; //event code

int nReference; //reference value

DWORD dwParam; //output parameter

}MESSAGE_INFO, *PMESSAGE_INFO;

Ø wEvent

wEvent represents the event code. Generally, the events thrown out by the SynCTI driver can be classified into the following categories.

² E_CHG_xxxx: An internal state or a counter of the driver changes;

² E_PROC_xxxx: A task submitted by the application progresses;

² E_SYS_xxxx: The driver detects some event occurs;

² E_RCV_xxxx: The driver receives a message or an event from the remote PBX.

’xxxx’ herein above implies the event designator.

The events generated in the SynCTI driver are separated into 2 categories: common event and uncommon event.

All event codes and corresponding behaviors are elaborated in the following table.

Event Code | Macro in shpa3api.h | Common Event | Description
0x0000 | E_PROC_Recognize | Ö | Voice recognition ends.
0x0001 | E_CHG_ISDNStatus | — | ISDN: The ISDN LAPD layer changes.
0x0002 | E_RCV_Ss7Msu | — | SS7: A new message (MSU) is received from the SS7 server.
0x0003 | E_CHG_Mtp3State | — | SS7: The SS7 MTP3 layer changes, usually to indicate if some DPC route is usable or not.
0x0004 | Reserved |  |
0x0005 | E_CHG_FaxPages | Ö | Fax Channel: The driver finishes receiving or transmitting a page of fax data.
0x0006 | E_PROC_FaxEnd | Ö | Fax Channel: The driver finishes receiving or transmitting all fax data.
0x0007 | E_CHG_PcmLinkStatus | Ö | The synchronization status of the digital trunk changes.
0x0008 | E_CHG_LineVoltage | — | The voltage on the analog phone line changes.
0x0009 | E_RCV_CAS | — | SS1 Channel: The ABCD signaling code from the remote PBX changes.
0x000A | E_RCV_R2 | — | SS1 Channel: The R2 signal from the remote PBX is received.
0x000B | E_PROC_WaitDTMF | Ö | The task of WaitDTMF is completed and submitted via the function SsmSetWaitDtmf , SsmSetWaitDtmfEx or SsmSetWaitDtmfExA .
0x000C | E_CHG_RcvDTMF | Ö | DTMF Detector: A DTMF digit is received.
0x000D | E_PROC_SendDTMF | Ö | DTMF Generator: The task of transmitting DTMF started by the function SsmTxDtmf is completed.
0x000E | E_PROC_SendFlash | Ö | The task of sending the flash signal is completed.
0x000F | E_PROC_PlayEnd | Ö | Voice Playing: The task of playing voice ends, which can be started by one of the following functions. ² SsmPlayFile ² SsmPlayIndexString ² SsmPlayIndexList ² SsmPlayFileList ² SsmPlayMem ² SsmPlayMemList ² SsmPlayMemBlock
0x0010 | E_PROC_PlayFile | — | Voice Playing: It indicates the file playing progress.
0x0011 | E_PROC_PlayFileList | — | Voice Playing: The driver finishes playing a file in the file queue.
0x0012 | E_PROC_PlayMem | — | Voice Playing: It indicates the voice playing progress in Single Buffer Mode.
0x0013 | E_PROC_RecordEnd | Ö | Voice Recording: The task of recording voice terminates.
0x0014 | E_PROC_RecordFile | — | Voice Recording: It indicates the file recording progress.
0x0015 | E_PROC_RecordMem | — | Voice Recording: It indicates the memory recording progress.
0x0016 | E_PROC_SendFSK | Ö | The FSK transmitter finishes sending all data.
0x0017 | E_PROC_RcvFSK | Ö | The task of RcvFSK ends.
0x0018 | E_CHG_ChState | Ö | State Machine: The channel state changes.
0x0019 | E_PROC_AutoDial | Ö | State Machine: The task of AutoDial progresses.
0x001A | E_CHG_RemoteChBlock | — | TUP/ISUP Channel: The operation to block the remote channel is completed.
0x001B | E_CHG_RemotePCMBlock | — | TUP/ISUP Channel: The operation to block the remote PCM is completed.
0x001C | E_SYS_ActualPickup | — | Analog Trunk Channel: The pickup command has been executed.
0x001D | E_CHG_RingFlag | — | Analog Trunk Channel/Analog Trunk Recording Channel: The voltage level of the ringing current changes.
0x001E | E_CHG_RingCount | Ö | Analog Trunk Channel: The counter for signal cycles in the ringing current detector changes.
0x001F | E_CHG_CIDExBuf | Ö | Extended buffer area that stores the CallerID information in FSK and DTMF: The size of Extended Caller ID Buffer changes.
0x0020 | E_CHG_RxPhoNumBuf | Ö | DTMF Detector: A new called party number is received.
0x0021 | E_CHG_PolarRvrsCount | — | Analog Trunk Channel: A polarity reversal is detected on the line.
0x0022 | E_SYS_RemotePickup | — | Analog Trunk Channel: The enhanced remote pickup detector detects that the called party picks up.
0x0023 | E_CHG_FlashCount | Ö | Station Channel or Recording Channel: A flash operation is detected on the phone.
0x0024 | E_CHG_HookState | Ö | Station Channel: A pickup or hangup behavior is detected on the phone.
0x0025 | E_CHG_ToneAnalyze | Ö | Tone Detector: The analyzed result changes.
0x0026 | E_OverallEnergy | — | Tone Detector: The overall energy on the line changes.
0x0027 | E_CHG_OvrlEnrgLevel | Ö | Tone Detector: It indicates the overall energy. Whether this event is output or not is determined by the configuration item OvrlEnrgEventOut .
0x0028 | E_CHG_BusyTone | Ö | Tone Detector: The call progress tone detector detects the change in number of busy tone cycles.
0x0029 | E_CHG_BusyToneEx | — | Tone Detector: The busy tone is detected by back-to-back busy tone detection.
0x002A | E_CHG_VocFxFlag | Ö | Tone Detector: The voltage level of single tones changes, usually for detecting the fax tone.
0x002B | E_CHG_ToneValue | — | Tone Detector: The tone voltage level changes.
0x002C | E_CHG_RingEchoToneTime | — | Tone Detector: The count of the ringback tone counter changes.
0x002D | E_CHG_PeakFrq | — | Tone Detector: The peak frequency changes.
0x002E | E_SYS_BargeIn | Ö | Barge-in Detector: The detected result changes.
0x002F | E_SYS_NoSound | Ö | Tone Detector: The line keeps silent.
0x0030 | E_SYS_TIMEOUT | Ö | Global Timer: The timer started by the function SsmStartTimer overflows.
0x0031 | E_CHG_SpyState | — | DTP Series: The state of the monitoring circuit changes.
0x0032 | Reserved |  |
0x003c | E_CHG_CICRxPhoNumBuf | — | SS7 Virtual Circuit: New called party numbers are received.
0x003d | E_CHG_CICState | — | SS7 Virtual Circuit: The circuit state changes.
0x003e | E_PROC_CICAutoDial | — | SS7 Virtual Circuit: The task of ShgAutoDial progresses.
0x003f | E_RCV_Ss7IsupUtuinf | — | SS7: The USR message is received.
0x0040 | E_CHG_Mtp2Status | Ö | SS7 signaling link: The signaling link state changes.
0x0041 | E_RCV_DSTDChannel | Ö | DST Series: The D-channel event
0x0042 | E_RCV_Ss7SpyMsu | — | SS7: New monitoring messages (MSU) are received from the SS7 server.
0x0043 | E_CHG_ToneDetector | Ö | Tone Detector: The event to output the detection result in the new mode.
0x0044 | E_CHG_ToneDetectorItem | — | Tone Detector: The event to count the periods of tones in the new mode.
0x0046 | E_PROC_FaxDcnTag | Ö | Fax Channel: When the fax reception is successfully completed, judge if the remote fax machine has ever been compelled to stop.
0x0047 | E_CHG_AMD | Ö | Tone detector, used to analyze if it is a man or an answer machine that picks up the phone.
0x0048 | E_RCV_Ss7IsupCpg | — | SS7: The CPG message is received.
0x0049 | E_CHG_CbChStatus | — | Large-capacity Channel Bank: To monitor any change in the connection state of a line between an on-board channel and a channel bank.
0x0050 | E_REFER_Status | — | SsmIpInitiateTransfer : Status after call transfer.
0x0051 | E_CHG_SpyHangupInfo | — | DTP series: The monitoring circuit receives the off-hook event.
0x0052 | E_CHG_CallBackRingCount | Ö | Analog Trunk Channel: The counter for signal cycles in the ringback current detector changes.
0x0053 | E_CHG_RcvMF | — | ATP series: New MF characters are received.
0x0054 | E_CHG_Pcm32LineState | Ö | PCM1280E: Changes in line synchronization status and signal state on PCM32 channels

Ø nReference & dwParam

The physical meanings of both parameters nReference and dwParam have relation to the value of wEvent as shown in the table below.

Event Type

nReference

dwParam

E_PROC_Recognize

Logical channel number

The recognition result within the range below

1: Obtain the recognition result (Accept)

2: Do not understand (Reject)

3: Do not hear properly (Failed)

4: Hear nothing (Silence)

E_CHG_ISDNStatus

Logical digital-trunk number

Unused. The function SsmISDNGetStatus can be used to acquire the particular output parameters.

E_RCV_Ss7Msu

unused

Unused. The function SsmGetSs7Msu is used to take out messages.

E_CHG_Mtp3State

DPC (Destination Point Code) number

The message to show if the route from the local end to the specified DPC supports SS7 signaling

1: Support;

0: Unsupport.

E_CHG_FaxPages

Logical channel number

The total number of pages sent or received by the driver

E_PROC_FaxEnd

Logical channel number

The detailed task (fax transmission or reception) progress

0: Task (including the handshake phase as well as the faxing process) unfinished;

1: Task finished. The channel turns back to the ‘idle’ state.

2: Error in faxing process or task terminated by the application program via the function SsmFaxStop . The channel turns back to the ‘idle’ state.

3: All fax data sent or received. Begins to negotiate the disconnection with the remote end.

E_PROC_FaxDcnTag

Logical channel number

0: The faxing process is complete.

1: If the fax reception is terminated by receiving a DCN message, it may result from the compulsive stop of the fax machine.

E_CHG_PcmLinkStatus

Logical digital-trunk number

The state of the digital trunk. See description on the parameter pwPcmLinkStatus in the function SsmGetPcmLinkStatus for details.

E_CHG_LineVoltage

Logical channel number

The voltage value (volt) on the analog phone line.

E_RCV_CAS

Logical channel number

The newly received ABCD signaling code, the 4 lower bits being valid

Bit3 Bit2 Bit1 Bit0: Correspond to the ABCD code

Rest bits: All set to 0

E_RCV_R2

Logical channel number

The newly received R2 signal

0: The R2 signal disappears.

1~15: The value of the forward R2 signal

1~6: The value of the backward R2 signal

E_PROC_WaitDTMF

Logical channel number

The reason why the task of WaitDTMF ends

1: Time out

2: The designated end character received

3: A DTMF string of the designated length received

The function SsmChkWaitDtmf can be used to acquire more information.

E_CHG_RcvDTMF

Logical channel number

The 16 higher bits represent the total number of received DTMF digits while the 16 lower bits are newly received digits, serving a purpose similar to a continuous call of the functions SsmGetRxDtmfLen and SsmGetLastDtmf .

E_PROC_SendDTMF

Logical channel number

=0: All DTMF digits in the buffer sent

=1: The transmitting task terminated by the application program

E_PROC_SendFlash

Logical channel number

Unused

E_PROC_PlayEnd

Logical channel number

The reason why the task of voice playing ends

1: All voice data played out

2: Terminates upon receiving DTMF digits

3: Terminates upon detecting voice activities on the line.

4: Terminates upon detecting the remote client’s hangup behavior.

5: Terminated by the application program

6: The task of file playing paused

7: Terminated by bus operation

8: The task of file playing terminated by the network fault

See description on the SsmCheckPlay function for more information.

E_PROC_PlayFile

Logical channel number

One of the following parameters:

² Percentage of played voice data

² Time for playing voice data

² Total number of played bytes

² Total number of unplayed bytes

It is the function SsmSetEvent that determines which one above to be output, the default value being ‘time for playing voice data’.

E_PROC_PlayFileList

Logical channel number

The index value of the voice file being played in the file queue (numbered from 0)

E_PROC_PlayMem

Logical channel number

One of the following parameters:

-1: The driver’s playing pointer goes beyond the middle position of the buffer.

-2: The driver’s playing pointer goes beyond the end of the buffer and back to the top.

Other values: The address offset of the driver’s playing pointer in the buffer (calculated by byte)

E_PROC_RecordEnd

Logical channel number

The reason why the task of voice recording ends

1: Terminated by the application program

2: Terminates upon detecting DTMF digits

3: Terminates upon detecting the remote client’s hangup behavior

4: Terminates when the recorded data reach a specified length or the recording operation lasts for a specified time.

5: The task of file recording paused

6: Writing recorded data to files failed

E_PROC_RecordFile

Logical channel number

One of the following parameters:

² Time for recording voice data

² Total number of recorded bytes

It is the function SsmSetEvent that determines which one above to be output, the default value being ‘time for recording voice data’.

E_PROC_RecordMem

Logical channel number

One of the following parameters:

-1: The driver’s recording pointer goes beyond the middle position of the buffer.

-2: The driver’s recording pointer goes beyond the end of the buffer.

Other values: The address offset of the driver’s recording pointer

E_PROC_SendFSK

Logical channel number

=0: The driver completes the transmission of all FSK data

=1: The transmission task is terminated by the function SsmStopSendFsk

E_PROC_RcvFSK

Logical channel number

The reason why the FSK receiver stops

1: Time out, reception failed

2: The designated end byte received

3: Received FSK data reach the designated length

4: Data of the specified format received

5: Interrupted by the application program via SsmStopRcvFSK .

The application can invoke the function SsmGetRcvFSK to acquire FSK data after getting this event.

E_CHG_ChState

Logical channel number

The 16 higher bits indicate the last channel state;

The 16 lower bits represent the new channel state.

See description on the function SsmGetChState for channel state values and more information.

E_PROC_AutoDial

Logical channel number

The progress value of the AutoDial task. See description on the function SsmChkAutoDial for the particular meaning of parameters.

E_CHG_RemoteChBlock

Logical channel number

The value to show the operation progress of blocking/unblocking the remote circuit.

0: The block caused by the local end successfully unblocked

1: The remote end successfully blocked

2: Waiting for the block-verified signal from the remote PBX

3: Waiting for the unblock-verified signal from the remote PBX

E_CHG_RemotePCMBlock

Logical digital-trunk number

The value to show the operation progress of blocking/unblocking the remote digital trunk. The 16 lower bits in the return value mean:

0: The block caused by the local end successfully unblocked

1: The remote end successfully blocked

2: Waiting for the block-verified signal from the remote PBX

3: Waiting for the unblock-verified signal from the remote PBX

The 16 higher bits indicate the blocking mode.

E_SYS_ActualPickup

Logical channel number

0 (reserved)

E_CHG_RingFlag

Logical channel number

The change in voltage level of the ringing current

Bit31: Ringing current voltage level flag - 1: ringing current available; 0: no ringing current.

Bit30~Bit0: The duration of ringing current at the last voltage level (ms)

E_CHG_RingCount

Logical channel number

The number of ringing current cycles

E_CHG_CIDExBuf

Logical channel number

The total number of characters in Extended Caller ID Buffer. The function call of SsmGetCallerIdEx can help acquire the calling party number.

E_CHG_RxPhoNumBuf

Logical channel number

The total number of characters in Extended Callee ID Buffer. The function call of SsmGetPhoNumStr can help acquire the called party number.

E_CHG_PolarRvrsCount

Logical channel number

The value of the counter for calculating polarity reversals in the driver

E_SYS_RemotePickup

Logical channel number

0 (reserved)

E_CHG_FlashCount

Logical channel number

The detected flash times

E_CHG_HookState

Logical channel number

The user phone’s behavior:

0: Hang up

1: Pick up

E_CHG_ToneAnalyze

Logical channel number

The result of the tone detector:

The busy tone detected result of the tone detector:

16 higher bits: Call progress tone detector number – 0: first group, 1: second group

16 lower bits: Detected tone

1: Dial tone detected

2: Busy tone detected

3: Ringback tone detected

4: The line keeps silent after detecting the ringback tone

5: No sound detected

6: Voice detected, used for examining if the called party answers (picks up) or not

7: Tone at F1 frequency (which is set by the function SsmSetVoiceFxPara ) detected, used for checking how the called party answers during audio dial

8: Tone at F2 frequency (which is set by the function SsmSetVoiceFxPara ) detected, used for checking how the called party answers during audio dial

9: Tone type specified by users detected

E_OverallEnergy

Logical channel number

The value of overall energy detected by the tone detector

E_CHG_AMD

Logical channel number

Analysis result of an AMD event:

0: Man’s pickup detected

1: Tone detected

2: Color ring or prompt tone detected

3: Time out

4: Line silent after tone or prompt tone detected

5: Line silent after dial tone detected

6: Busy tone detected

E_CHG_OvrlEnrgLevel

Logical channel number

The overall energy flag, the 16 lower bits being valid.

Bit15 (tone identification): 0/1 There are tones/no tones

Bit14 (function call status): 0 Reserved

Bit13-0 (duration): A period of time when there are tones/no tones

E_CHG_BusyTone

Logical channel number

The busy tone detected result of the tone detector:

16 higher bits: Tone detector number - 0: first group, 1: second group

16 lower bits: Number of busy tone cycles.

E_CHG_BusyToneEx

Logical channel number

About the busy tone detected by tone detector using back-to-back busy tone detection:

0: The busy tone disappears

1: Busy tone detected

E_CHG_VocFxFlag

Logical channel number

The type of fax tones.

1: Tone at F1 frequency detected

2: Tone at F2 frequency detected

E_CHG_ToneValue

Logical channel number

Tone Detector: The value to show changes in the tone voltage level

Only the 16 lower bits are in effect.

Bit15(tone identification): 0/1 There are tones/no tones

Bit14(function call status): 0/1 Successful/failed

Bit13-0(duration): A period of time when there are tones/no tones

E_CHG_RingEchoToneTime

Logical channel number

Tone Detector: The time that a ringback tone cycle takes (ms)

E_CHG_PeakFrq

Logical channel number

Tone Detector: Peak frequency

E_SYS_BargeIn

Logical channel number

The detected result of the Barge-in detector changes:

0: The line keeps silent

1: Voice detected on the line

E_SYS_NoSound

Logical channel number

Unused

E_SYS_TIMEOUT

Timer number

Unused

E_CHG_SpyState

Logical SpyCic number

The 16 higher bits represent the last SpyCic state.

The 16 lower bits imply the new SpyCic state.

See description on the function SpyGetState for SpyCic state values and more information.

E_CHG_CICRxPhoNumBuf

Virtual circuit number

The length of the called party number

The application program need invoke the function ShgGetPhoNumStr after getting this event to acquire the called party number.

E_CHG_CICState

Virtual circuit number

The circuit state value

See description on the function ShgGetChState for details.

E_PROC_CICAutoDial

Virtual circuit number

The progress value of the ShgAutoDial task

1: DIAL_ECHOTONE = 2, ringback tones are detected after sending the entire called party number

3: DIAL_BUSYTONE= 4, the called party is in a ‘busy’ state and the auto dial stops.

6: DIAL_VOICE= 7, the called party picks up and the auto dial stops.

9: DIAL_NOANSWER= 10, nobody answers and the auto dial fails.

10: DIAL_FAILURE= 11, the auto dial fails.

11: DIAL_INVALID_PHONUM = 12, the number unallocated and the auto dial stopped

E_RCV_DSTDChannel

Logical channel number

The subevent code, such as DST_AUDIO_CHG, DST_MSG_CHG which begin with ‘DST_’. See SynCTI Programmer’s Manual - D-channel Event User Manual for the meaning of each event code.

E_RCV_Ss7IsupUtuinf

Logical channel number

User-to-user information where the first byte means the data length (unsigned int) and the following are data (unsigned char[]).

E_CHG_Mtp2Status

SS7 signaling link number

The SS7 signaling link state value:

1: Out of service

2: Initial alignment

3: Aligned ready

4: Aligned not ready

5: In service

6: Processor outage

E_RCV_Ss7SpyMsu

Unused

Unused. The function SsmGetSs7SpyMsu is used to take out messages.

E_CHG_ToneDetector

Logical channel number

2 lower bits: The detected tone type

2 higher bits: Item number, i.e. the number for ToneDetectorItem

For more information, refer to the configuration item ToneDetectorItem

E_CHG_ToneDetectorItem

Logical channel number

2 lower bits: Count of periods

2 higher bits: Item number, i.e. the number for ToneDetectorItem

For more information, refer to the configuration item ToneDetectorItem

E_RCV_Ss7IsupCpg

Logical channel number

The size of the CPG message

E_CHG_CbChStatus

Logical channel number

0: Line connected

1: Line disconnected

E_REFER_Status

Logical channel number

Status values after call transfer. See below for details.

0: Refer is in an idle state

1: Refer is in a Trying state. That is, the subscription is pending

2: In a state of180RingBack

3: In a state of 200ok, 3XX

4: In a state of 4XX, 5XX, 6XX failure

40: Channel is in an unused state

E_CHG_SpyHangupInfo

Logical SpyCic number

The 16 higher bits represent the monitored PCM number for SpyCic that sends the disconnect message.

The 16 lower bits imply the hangup information of SpyCic. To be exact:

0: Called party hangs up first

1: Calling party hangs up first

See the description on the function SpyGetHangupInfo for more information.

E_CHG_CallBackRingCount

Logical channel number

The number of ringback current cycles.

E_CHG_RcvMF

Logical channel number

The 16 higher bits represent the total number of the received MF characters; the 16 lower bits represent the newly received characters.

E_CHG_Pcm32LineState

Logical channel number

Only the lower 16 bits are used to represent the line synchronization status and the signal state, among which bit0-bit7 indicate the line synchronization status and bit8-bit15 indicate the signal state. Refer to the function SsmGetPcm32LineState for details.


1.14.2.2 SSM_EVENT

The SSM_EVENT structure declaration is:

typedef struct _SSM_EVENT

{

WORD wEventCode; //event code

int nReference; //reference value

DWORD dwParam; //output parameter

DWORD dwUser; //user parameter

DWORD dwSubReason; //subreason value

DWORD dwXtraInfo; //extended information value

PVOID pvBuffer; //pointer in the buffer which holds event information

DWORD dwBufferLength; //size of the buffer which holds event information

DWORD dwDataLength; //size of event information

DWORD dwEventFlag; //event flag

DWORD dwReserved1; //reserved parameter 1

LONGLONG dwReserved2; //reserved parameter 2

}SSM_EVENT, *PSSM_EVENT;

Parameters involved in the structure are described as follows.

Ø wEventCode, nReference, dwParam

These three parameters have the same meaning as wEvent, nReference and dwParam in the MESSAGE_INFO structure.

Ø dwUser

The meaning of dwUser varies on the event output mode as shown in the table below.

Event Output Mode | Meaning
Event Polling Mode | In case the event is defined by users, its value equals to the value of the subsection dwUser in the parameter pEvent when the function SsmPutUserEventA is invoked. Otherwise it is meaningless.
Event Callback Mode | Directly passes the value of dwUser in the parameter pEventSet when the function SsmSetEvent is invoked by the application program.

Ø dwSubReason

The parameter dwSubReason is the subreason value which gets meaningful only when the value of the parameter wEventCode equals to that of E_RCV_DSTDChannel. The meaning of dwSubReason bears on the parameter dwParam carried in the event thrown out by the driver. For more information, see SynCTI Programmer’s Manual - D-channel Event User Manual.

Ø dwXtraInfo

The parameter dwXtraInfo is the extended information which gets meaningful only when the value of the parameter wEventCode equals to that of E_RCV_DSTDChannel. The meaning of dwXtraInfo bears on the parameter dwParam carried in the event thrown out by the driver. For more information, see SynCTI Programmer’s Manual - D-channel Event User Manual.

Ø pvBuffer, dwBufferLength, dwDataLength

The parameters pvBuffer, dwBufferLength and dwDataLength get meaningful only when the value of the parameter wEventCode equals to that of E_RCV_DSTDChannel. Their meanings vary on the event output mode as shown in the table below.

Event Output Mode | Meaning
Event Polling Mode | pvBuffer is the pointer to the buffer which stores event information. The application should allocate a buffer space of not less than 300 bytes to pvBuffer and set the value of dwBufferLength to the actual size of the allocated buffer space (byte) while calling the function SsmWaitForEventA or SsmGetEventA. After the function SsmWaitForEventA or SsmGetEventA returns events, the content in pvBuffer means differently based on the carried parameter dwParam of the event thrown out by the driver. See SynCTI Programmer’s Manual - D-channel Event User Manual for more information. dwDataLength is the true size of data in pvBuffer (byte).
Event Callback Mode | pvBuffer is the pointer to the buffer which stores event information. After generating the E_RCV_DSTDChannel event, the driver will automatically allocate a buffer space for pvBuffer before invoking the callback function previously registered by the application. In this case, the parameter dwBufferLength has no meaning. The content in pvBuffer means differently based on the carried parameter dwParam of the event thrown out by the driver. See SynCTI Programmer’s Manual - D-channel Event User Manual for more information. dwDataLength is the true size of data in pvBuffer (byte).

Ø dwEventFlag

dwEventFlag is the event flag where only Bit0 and Bit2 are in effect and other bits all reserved. See the table below for what Bit0 and Bit2 mean.

Bit

Meaning

Bit0

=0: This event is created by the driver

=1: This event is created by the application. To be exact, it is the self-defined event submitted to the driver by the function SsmPutUserEventA.

Bit2

=0: The event information is not truncated

=1: The event information is truncated

Bit2 gets meaningful only in the event polling mode. As long as one of the following two conditions is met, it will be set to 1 by the driver.

² The value of dwDataLength in the parameter pEventSet goes greater than 256 when the application invokes the function SsmPutUserEventA.

² The value of dwBufferLength in the parameter pEventSet when the application invokes the function SsmWaitForEventA is less than that of dwDataLength in the event temporarily saved to the driver before being output.

Ø dwReserved1, dwReserved2

Both are reserved parameters.


1.14.3 Event Filter

The application program may ask the SynCTI driver to or not to throw out an event. This feature is enabled via the function SsmSetEvent.

When the application invokes the function SsmSetEvent and uses the parameter wEvent=0xffff, whether the driver sends out an event or not is determined by the configuration of DefaultEventOutput. See description on this configuration item for details.


1.14.4 Self-defined Event

The application may generate events by itself during runtime, which are called self-defined events. To facilitate the application programming, the driver allows direct transmission of self-defined events, i.e. the application program can save its self-defined events to the event queue in the driver and process them via the function acquired through the driver supplied event.

The functions SsmPutUserEvent and SsmPutUserEventA can be used to submit the self-defined event to the driver.


1.14.5 SynCTI Programming Guide

This section highlights the keys to SynCTI driver programming respectively in MS VC/C++, VB, C++BUILDER, Delphi, PB6.5 and other compilation environments under Windows, as well as in C language under Linux.


1.14.5.1 MS VC/C++

The SynCTI driver provides the following files which are needed for programming in MS VC/C++:

² shpa3api.h: C/C++ header file

² shp_a3.lib: C/C++ import library file


1.14.5.2 VB

In Visual Basic 6.0, all functions in the dynamic-link library SHP_A3.DLL are declared by the file Shpa3api.bas from the driver. See Shpa3api.bas for details.

Actually the board operation in VB is also controlled via the call of shp_a3.dll. Therefore, the above description on programming in VC is also applicable to this section. Users are strongly recommended to first read through 1.14.5.1 MS VC/C++ and refer to the demo program compiled in C language while developing their application program based on the SynCTI driver.

In VB 6.0, a DLL function can be called only after it is declared. Regarding how to declare a DLL function, refer to the help file ‘Declare statement’ for VB.

Programmers can declare functions in VB by themselves referring to the function declaration in C language, if some new functions in shp_a3.dll are not declared in Shpa3api.bas. For example, below is a function declared in Shpa3api.h:

int WINAPI SsmPlayFile(int ch, LPSTR pszFileName, int nFormat, DWORD dwStartPos, DWORD dwLen);

Its declaration in Shpa3api.bas is:

Declare Function SsmPlayFile Lib ‘shp_a3.dll’ (ByVal ch As Long, ByVal pszFileName As String,

ByVal nFormat as Long, ByVal dwStartPos as Long,

ByVal dwLen As Long) As Long

Corresponding to 32-bit BOOL, 16-bit WORD and 32-bit DWORD in 32-bit VC environment, 32-bit Long, 16-bit Integer and 32-bit Long are used in VB environment. Note that each parameter and its return value should contain the same number of bytes.

Similar to programming in C language under Win9x/NT, programming for our voice boards in VB also can be performed by three steps:

Ø Initialization codes, including parts for initializing the driver and obtaining the total number and type of channels, written in the function Form_load.

Ø Processing codes, written in the timer or the function Form_Activate. For detailed information, refer to the relative demo program.

Ø Uninstallation codes, covering the components for uninstalling the driver and closing the board, written in the function Form_Unload.

Notes:

l Form_Activate is an endless-loop function. If it is used for writing processing codes, DoEvents must be called to ensure that other programs run normally.

l The fact that VB is an interpretive programming language requires you to take precautions that while using a DLL, the size of relative parameters must be defined before the function such as SsmGetLastErrMsg or SsmGetDtmfDStr, where each parameter takes a string and returns data following the function call in C language, being invoked in VB. For example:

Dim ErrStr As String * 200

SsmGetLastErrMsg( ErrStr)

l In case of programming in VB under WinNT, when the initialization and main processing codes are respectively written in the function Form_load and the timer, the codes in timer should not be invoked before successful call of the function SsmStartCti. See below for details. Method 1: Create a global variable (with the default value of ‘FALSE’) and set it to ‘TRUE’ at the end of the function Form_load. The timer will determine whether to run the main processing codes according to the value of this variable. Method 2: Set Timer.Enable=False at the beginning of the function Form_load and Timer.Enable=True at the end. At the same time, set Timer.Enable=False in the function Form_unload before calling the function SsmCloseCti.

l As VB 6.0 doesn’t support multithreading, when the event callback mode is used for programming, some of the functions (such as Right, Left, etc.) provided with VB 6.0 can’t work properly as part of callback functions and the IDE of VB 6.0 can’t set break points in callback functions, which bring a big trouble to debugging. Hence, we suggest using the event polling mode instead of the event callback mode for progrmaming in VB 6.0.


1.14.5.3 C++ BUILDER

The driver provides Shpa3api.h for your direct use.

Since shp_a3.lib is compiled in VC, it cannot be directly used by project files in C++BUILDER. However, you can take an import library LIB from DLL using the software tool IMPLIB.EXE provided by C++BUILDER. See the help file for IMPLIB.EXE to find how to use it. Here is a short example.

cd \windows\system

implib shp_a3.lib shp_a3.dll

What you need to do is copy the generated shp_a3.lib to the directory of your developed program.

Notes:

l If there are two C language development systems from Borland installed in the hard disk, IMPLIB.EXE provided by C++ BUILDER must be in use, or errors may occur at runtime.


1.14.5.4 Delphi

In Delphi, all functions in the dynamic-link library shp_a3.dll are declared by Shpa3api.pas. See Shpa3api.pas for details.

Just like in VB6.0, a DLL function can be called only after it is declared in Delphi. Regarding how to declare a DLL function, refer to the help file ‘external declarations’ for Delphi. Programmers can declare functions in Delphi by themselves referring to the function declaration in C language, if some new functions in shp_a3.dll are not declared in Shpa3api.pas. For example, below is a function declared in Shpa3api.h:

int WINAPI SsmPlayFile(int ch, LPSTR pszFileName, int nFormat, DWORD dwStartPos, DWORD dwLen);

Its declaration in Delphi is:

function SsmPlayFile (ch: Integer; pszFileName: PCHAR; nFormat:Integer; dwStartPos: DWORD;dwLen:DWORD ) : Integer; stdcall; external 'Shp_a3.dll'。

Notes:

l The statement “stdcall; external ‘Shp_a3.dll’”must be added to the end of the declaration.

l The char* data type used in C language should be declared as pchar data type in Delphi.


1.14.5.5 PB6.5

In Power Builder, all functions in the dynamic-link library shp_a3.dll are declared via the option ‘Global External Function’ in the ‘Declare’ menu. Programmers can declare functions in PB6.5 by themselves referring to the function declaration in C language, if some new functions in shp_a3.dll are not declared in Shpa3api.pas. For example, below is a function declared in Shpa3api.h:

int WINAPI SsmPlayFile(int ch, LPSTR pszFileName, int nFormat, DWORD dwStartPos, DWORD dwLen);

Its declaration in Power Builder is:

Function Long SsmPlayFile (Long ch,String pszFileName,Long nFormat, UnsignedLong dwStartPos,UnsignedLong dwLen) Library "shp_a3.dll"

Note: The parameter type used in PB6.5 is similar to that in VB. Refer to the preceding section 1.14.5.2 VB.


1.14.5.6 Other Programming Environments

Under 32-bit Win95/NT, a number of programming languages may be used in various ways to call functions in the dynamic-link library SHP_A3.DLL. As there are too many programming languages and each has its own requirements, we cannot describe all of them in this manual. Read carefully about the description on the programming language you are using.


1.14.5.7 Linux

The SynCTI driver provides the following files which are needed for programming in C/C++:

Ø shpa3api.h: C/C++ header file

Ø libshpa3.so: Shared library file

Generally, programming for our voice boards in C/C++ language under Linux are performed by three steps.

Ø Initialization codes, including parts for initializing the board and obtaining the total number and type of channels, used only once upon starting the application program.

Ø Processing codes, used to give commands to the driver and process the event from the driver. For detailed information, refer to the relative demo program.

Ø Uninstallation codes, covering the components for releasing the board and the driver, used only once upon exiting the application program.


1.14.5.8 Use of Character String

The use of character strings in not a few advanced languages differs from that in C language. Please follow the norms of C language when invoking functions which include character strings.

For the output character strings, like the second parameter in SsmGetDtmfStr, the application program should allocate storage space ahead of time. A lot of advanced languages support the automatic management of string’s space allocation. However, when they are invoked across different language platforms, there is still a need to allocate space manually because of the unexpected demand of the other end.

In VB6.0, strings can be used as follows:

Dim DtmfStr As String*200

SsmGetDtmfStr(Ch, DtmfStr)

In VB.Net, strings can be used as follows:

Dim DtmfStr As New String(Chr(0), 200)

SsmGetDtmfStr(Ch, DtmfStr)

In C#, strings can be used as follows:

String DtmfStr = new String((Char)0, 200);

SsmGetDtmfStr(Ch, DtmfStr);

For the input character strings, like the two parameters in SsmStartCti, no displayed space is required to be allocated as our DLL wouldn’t modify its content. However, don’t forget to add the character '\0' at the end of strings to comply with the standard of C language.

In VB.net, strings can be used as follows:

Dim ShConfig as String

Dim ShIndex As String

ShConfig = My.Application.Info.DirectoryPath & "\ShConfig.ini" & Chr(0)

ShIndex = My.Application.Info.DirectoryPath & "\ShIndex.ini" & Chr(0)

SsmStartCti(ShConfig, ShIndex)


1.14.6 Demo Program (CTI Series)

To help developers understand the way to use some functions and features as soon as possible, Synway provides a large number of demo programs which are listed in the following table.

Name | Description | Programming Environment
 |  | Windows |  |  |  |  | Linux
 |  | VB | VC | C# | PB | DELPHI | gcc
Call | Demonstrates how to process inbound calls. | Ö | Ö | － | Ö | Ö | Ö
Dial | Demonstrates how to enable outbound calls. | Ö | Ö | － | Ö | Ö | Ö
Conference Demo | Demonstrates how to enable teleconference, applicable to the station channel, analog trunk channel and digital trunk channel. See the file DemoConferenceUserManual.pdf (English) or DemoConferenceUserManual_cn.pdf (Chinese) in the Demo folder for more information. | － | Ö | － | － | － | －
Fax | Demonstrates how to make the Synway board serve as a simple fax server. Refer to the file DemoFAXUserManual.pdf (English) or DemoFAXUserManual_cn.pdf (Chinese) in the Demo folder for more information. | Ö | Ö | Ö | － | Ö | Ö
PBX | Demonstrates how to use the Synway board as a small PBX. Refer to the file DemoPbxUserManual.pdf (English) or DemoPbxUserManual_cn.pdf (Chinese) in the Demo folder for more information. | － | Ö | Ö | － | － | －
 | The digital trunk board debug platform, used to debug the application program for the digital trunk board, can work as a simple PBX. | － | Ö | － | － | － | －
FSK | Demonstrates how to use the Synway board in sending and receiving FSK data. | － | Ö | － | － | － | －
Ss7Server | It is the SS7 server. | － | Ö | － | － | － | －
Test | Demonstrates the use of API functions. | － | Ö | － | － | － | Ö
Multi-thread VC | Demonstrates how to do programming for the Synway board by multithreading. | － | Ö | － | － | － | －
Event-driven Demo | Demonstrates how to use the event thrown out by the SynCTI driver for programming. | － | Ö | － | － | － | －


1.14.7 Demo Program (REC Series)

To help developers understand the way to use some functions and features as soon as possible, Synway provides a large number of demo programs which are listed in the following table.

Name | Description | Programming Environment
 |  | Windows |  |  | Linux
 |  | VB | VC | C# | gcc
Recorder-ATP | Demonstrates how to use the ATP Series call-recording boards to monitor and record the analog phone line. Refer to the file DemoATPUserManual.pdf (English) or DemoATPUserManual_cn.pdf (Chinese) for details. | － | Ö | Ö | Ö
Recorder-DST | Demonstrates how to use the DST Series boards to monitor and record the digital subscriber line through high-impedance and parallel connection. Refer to the file DemoDSTUserManual.pdf (English) or DemoDSTUserManual_cn.pdf (Chinese) for details. | Ö | Ö | － | －
Recorder-DTP | Demonstrates how to use the DTP Series boards to monitor and record the digital trunk (E1). | Ö | Ö | － | －
RecPlay UseMemBlock | Demonstrates how to record in Pingpong Buffer Mode. | － | Ö | － | －


1.14.8 Driver-provided Timer

The driver provides two kinds of timers for the application program: Global Timer and Channel Timer.

u Global Timer

The driver has 128 system timers in it, using the hardware interrupt signal as the timed pulse, offering greater precision than timers provided by the operating system. The function SsmStartTimer is used to apply to the driver for a timer and set the parameters for it. The driver will throw out the E_SYS_TIMEOUT event every time when the timer overflows. The function SsmStopTimer is for terminating a timer.

u Channel Timer

The channel timer is applicable to the polling mode. When it is started, the driver can only save the current time to a variable but not judge if the timer overflows or not. Not until the application program calls the function ElapseTime will the driver return the timer’s duration. Each channel has 10 timers allocated by the driver. They are started via the function StartTimer.


1.14.9 Driver-provided Debugging Feature

The SynCTI driver has the capability of API and event debugging, usually for the application system being developed, tested or preliminarily run. When error occurs in the API function call by the application program, or in the event message, or in the driver, the driver will output an error message to help the developer find the cause as soon as possible provided that the corresponding ‘debugging information output’ option is enabled.

The following configuration items are usable for debugging the application.

Configuration Item | Description
EnableDebugAPI | Sets whether to output the API debugging information.
SetEventRange | Sets the event range to limit the output events to be written into the log in the use of EnableDebugAPI.
SetChRange | Sets the channel range to limit the output events to be written into the log in the use of EnableDebugAPI.

If the application uses the polling mode, it needs to continuously invoke some query functions in the timer, which leads to the output of a lot of function-call messages. The following configuration items may forbid some common query functions to output messages on function calls.

Configuration Item | Description
Mask_SsmGetNoSoundTime | Controls whether to output the message on the function call of SsmGetNoSoundTime.
Mask_SsmGetChStateKeepTime | Controls whether to output the message on the function call of SsmGetChStateKeepTime.
Mask_SsmGetPlayedTime | Controls whether to output the message on the function call of SsmGetPlayedTime.
Mask_SsmGetPlayedPercentage | Controls whether to output the message on the function call of SsmGetPlayedPercentage.
Mask_SsmGetPlayOffset | Controls whether to output the message on the function call of SsmGetPlayOffset.
Mask_SsmGetRecTime | Controls whether to output the message on the function call of SsmGetRecTime.
Mask_SsmGetRecOffset | Controls whether to output the message on the function call of SsmGetRecOffset.

The driver-output API debugging information can be displayed and observed with the help of the third-party software tool Debugview.exe, which supports Windows Me, Windows 2000, Whistler Beta 1, Beta 2 and RC 1.

You can download Debugview.exe from the website http://technet.microsoft.com/en-us/sysinternals/bb896647.aspx#top free of charge and run it directly after decompressing the ZIP file, without the need of installation.


1.15 SHT Series (CTI Series)


1.15.1 Brief Introduction of SHT Series

The features supported by the SHT Series boards are shown in the following table.

Board Model | Form Factor | Max. Ports | Voice Processing Capabilities | Conferencing Capabilities | Voltage Detector | Audio Socket | FSK | TDM Bus | Max Fax Resource
SHT-2A/USB | USB | 2 | Ö | Ö | Ö | Ö | Ö | N/A | N/A
SHT-4A/USB | USB | 4 | Ö | Ö | Ö | Ö | Ö | N/A | N/A
SHT-2B/USB | USB | 2 | Ö | Ö | Ö | Ö | Ö | N/A | N/A
SHT-4B/USB | USB | 4 | Ö | Ö | Ö | Ö | Ö | N/A | N/A
SHT-8A/PCI | PCI | 8 | Ö | Ö | Ö | Ö | Ö | N/A | N/A
SHT-8B/PCI | PCI | 8 | Ö | Ö | Ö | Ö | Ö | N/A | N/A
SHT-8B/PCI/FAX | PCI | 8 | Ö | Ö | Ö | Ö | Ö | N/A | 4
SHT-8C/PCI/FAX | PCI | 8 | Ö | Ö | Ö | Ö | Ö | N/A | 4
SHT-8C/PCI/EC | PCI | 8 | Ö | Ö | Ö | Ö | Ö | N/A | N/A
SHT-16C-CT/PCI/EC | PCI | 16 | Ö | Ö | Ö | Ö | Ö | H’100 | N/A
SHT-16A-CT/PCI | PCI | 16 | Ö | Ö | Ö | Ö | Ö | H.100 | N/A
SHT-16B-CT/PCI | PCI | 16 | Ö | Ö | Ö | Ö | Ö | H.100 | N/A
SHT-16B-CT/PCI/FAX | PCI | 16 | Ö | Ö | Ö | Ö | Ö | H.100 | 4
SHT-16C-CT/PCI/FAX | PCI | 16 | Ö | Ö | Ö | Ö | Ö | H.100 | 4
SHT-16B-CT/PCI/MP3 | PCI | 16 | Ö | Ö | Ö | Ö | Ö | H.100 | N/A
SHT-120A-CT/PCI | PCI | 120 | Ö | Ö | N/A | N/A | N/A | N/A | N/A
SHT-16B-CT/cPCI | cPCI | 16 | Ö | Ö | Ö | Ö | Ö | H.110 | N/A
SHT-16B-CT/cPCI/MP3 | cPCI | 16 | Ö | Ö | Ö | Ö | Ö | H.110 | N/A
SHT-16B-CT/cPCI/FAX | cPCI | 16 | Ö | Ö | Ö | Ö | Ö | H.110 | 8
SHT-120A-CT/cPCI | cPCI | 120 | Ö | Ö | N/A | N/A | N/A | N/A | N/A

Note: The SHT-16B-CT/PCI/FAX board and the SHT-16B-CT/PCI/MP3 board differ in the hardware structure. However, they have the same board ID written in the firmware due to historical reasons. Hence it is essential to set the configuration item DSP3WORKMODE to ensure that the driver can properly distinguish these two board models.


1.15.2 Operation Principle of SHT Series

The figure below shows the operation principle of the SHT Series boards.

Description of components and symbols in the figure above:

Name | Description
M1 | Outbound voice mixer.
K7 | The Voice Play/Fsk Transmitter switch, controlled by the driver. When the application calls the playing function, K7 connects to the component Decoder; when it calls the function SsmStartSendFSK to start FSK data transmission, K7 connects to the component FSK Generator. For more information about the playing functions, refer to the Voice Playing section.
A1 | The volume adjuster for voice playing. The volume can be set via the configuration item DefaultPlayVolume or the function SsmSetPlayVolume/SsmSetPlayGain, with the default value of 0.
K5-1 | The switch that controls the voice playing operation, usually keeping off under the automatic control of the driver. Only when the application program invokes the playing function does the driver automatically switch on K5-1 and then switch off it at the end of voice playing. For more information about the playing functions, refer to the Voice Playing section.
K5-3 | The switch that controls the signal output of Tone Generator and DTMF Generator, often keeping off under the automatic control of the driver. Only when the application program invokes the function SsmTxDtmf to start the DTMF generator or calls the function SsmSendTone/SsmSendToneEx to start the tone generator does the driver automatically switch on K5-3 and then switch off it at the task termination.
M2 | Off-bus mixer.
A4-1 … A4-6 | The volume adjuster used before the off-bus signals entering M2. Use the function SsmSetListenVlmInConf to set the volume, with the default value of 0DB. Or use the following configuration item or functions to set the volume for a channel with data to be off the bus. ² SsmTalkWithEx ² SsmListenToEx/SsmLinkFromEx/SsmLinkFromAllCh
M3 | Recording mixer The signals output from M3 enter the Encoder component and become the recording data.
A3 | The volume adjuster used before incoming signals entering M3. The volume can be set via the function SsmSetRecVolume or the configuration item DefaultRecordVolume, with the default value of 0DB.
A2 | The volume adjuster used before outgoing signals entering M3, switched on in default. The volume can be set via the function SsmSetRecMixer or the configuration item DefaultRecordMixerVolume, with the default value of -7.
M5 | Onto-bus mixer. Mixes the playing data, the incoming signals and those output from the off-bus mixer, and puts the mixed voice onto TDM bus. Upon board initialization, the output from M5 is transported to a time slot (marked as ‘ts’ for short) on TDM bus. You can use the function SsmLinkToBus to designate the ts.
K3 | The switch that controls whether the incoming signals enter the onto-bus mixer M5 or not, switched on in default. It can be set via the function SsmSetFlag (with the parameter F_InVoiceToBus) or the configuration item InVoiceToBus.
K1-2 | The switch that controls whether the signals output from M2 go back onto TDM bus, being switched off in default. It can be set via the function SsmSetFlag (with the parameter F_MixerResToBus).
K1-1 | The switch that controls whether the playing data enter the mixer M5 and go onto TDM bus or not, usually keeping off. It can be set via the function SsmSetPlayDest, used only for playing background music to the teleconference.
K2 | The switch that shifts between the FSK detector and other detectors, usually pointing to other detectors unless the FSK detector is started.

Ø Voice Playing

After the application invokes functions, the driver will automatically have K7 link to Decoder and switch on K5-1. The voice data processed by A1 have two places to go:

² Entering M1 and forming the final outgoing signals with other signal sources. The outgoing signals, if on Channel 0, will be sent to the on-board speaker output jack at the same time.

² Entering M5 under the control of K1-1 and forming the onto-bus signal sources with other signals, only for playing background music to the teleconference.

Ø Recording Example for Various Signal Sources

A lot of special applications are available via the flexible use of the above switches for recording control and volume adjusters. In the following examples, ch1 means Channel 1 and ch2 is just Channel 2.

² Example 1: Only record the incoming signals on ch1, using the default volume.

SsmSetRecVolume(ch1, 0); //start A3, set the volume gain to 0DB

SsmSetRecMixer(ch1, FALSE, 0); //stop A2

SsmRecToFile(ch1, ……); //start the task of file recording …

² Example 2: Record the incoming signals on ch1 (volume increased by 6DB) and the signals output from M2 (volume decreased by 3DB) at one time based on the establishement of a two-way call between ch1 and ch2.

SsmTalkWith(ch1, ch2); //establish a two-way connection between ch1 and ch2 via TDM bus

SsmSetRecVolume(ch1, 2); //start A3, set the volume gain to 2*3DB=6DB

SsmSetRecMixer(ch1, TRUE, -1); //start A2, set the volume gain to -1*3DB=-3DB

SsmRecToFile(ch1, ……); //start the task of file recording …

² Example 3: When ch1 joins a teleconference (assuming the conference room number is n), play background music on ch1 and record the conference through ch1. All signal sources go with normal volume, i.e. the gain is 0.

SsmJoinConfGroup(n, ch1, ……); //ch1 joins the conference

SsmSetPlayDest(int ch, 1); //switch on K1-1, put the playing data onto bus

SsmPlayFile(ch1, ……); //start the task of voice playing on ch1, play background music

SsmSetRecVolume(ch1, 0); //start A3, set the volume gain to 0DB

SsmSetRecMixer(ch1, TRUE, 0); //start A2, set the volume gain to 0DB

SsmRecToFile(ch1, ……); //start the task of file recording …

Ø On-board Speaker Output Jack

Channel 0 on the SHT Series boards is enabled by the analog audio amplifier circuit and the spearker output jack equipped on it to connect directly with the external speaker or headset and monitor voice signals in real time. This design is mainly for the following purposes.

² To transport incoming signals from any channel to the on-board speaker for play via TDM bus. This purpose can be achieved via the function SsmListenTo or SsmListenToEx.

² To send voice files recorded by the application straight to the on-board speaker for play via the call of playing functions. See the Voice Playing section in this chapter for details.

The AMP component in the figure above is the power amplifier for the analog audio amplifier circuit. Its gain can be set via the function SsmSetPowerAmpVlm.

Channel 0 on the USB voice box (with ‘/USB’ marked in the model) is equipped with not only a speaker output jack but also an on-board speaker, which enables the voice playing operation. The switch K8, providing choices for the signals output from Channel 0 to enter the on-board speaker or the speaker jack, can be set via the function SsmSetLine0OutTo or the configuration item USBLine0Output, with the default setting of ‘to the speaker jack’.

Note: Voices are sent onto the line as outgoing signals at the same time when transported to the on-board speaker on Channel 0.


1.15.3 Analog Trunk Channel


1.15.3.1 Generating Flash Signal on Analog Line

The flash signal is a short temporary on-hook pulse generated by a rapid clap on the hook switch of the analog phone during a call, generally used for such operations as transferring the call to an extension with the help of the PBX. You should do the clap as swift as possible lest the PBX mistakes the flash signal for the on-hook signal.

In the SynCTI driver, there are two ways available to generate a flash signal on the analog trunk.

Ø Invoke the function SsmTxFlash . In this way, the duration of the generated flash signal can be specified directly.

Ø Use the parameter – the ‘!’ character - while invoking the function SsmTxDtmf . In this case, the duration of the generated flash signal can be set via the configuration item DefaultTxFlashTime , with the default value of 500ms.


1.15.3.2 Detecting Polarity Reversal Signal

For detailed information about the polarity reversal detection, refer to the Change in Analog Phone Line Voltage section in this chapter.


1.15.3.3 Analog Trunk Channel State Machine

Each state identifier in the above diagram is described in the following table.

State Identifier

Value

Macro Definition

Description

Standby

0

S_CALL_STANDBY

‘Idle’ state

Before the channel state transfers to ‘Idle’, the driver:

Ø empties all buffers in DTMF Detector

Ø clears Caller ID Buffer

Ø closes DTMF Generator

Ø closes Tone Generator

Ø empties all buffers in the ringing current detector and then starts it

Ø empties all buffers in Tone Detector and then closes it

Ø starts (if the Caller ID detector is working in DTMF mode) or closes (if the Caller ID detector is working in FSK mode) the DTMF detector.

Ø closes the polarity reversal detector (if the polarity reversal detection is supported by hardware)

Ø sets the progress value of the AutoDial task to DIAL_STANDBY

Ø terminates the WaitDtmf task (if it has been started)

OffHook

1

S_CALL_PICKUPED

’Pickup’ state

Before the channel state transfers to ‘Pickup’, the driver:

Ø empties all buffers in the tone detector and then starts it

Ø empties all buffers in the ringing current detector and then closes it

Ø starts the DTMF detector if the Caller ID detector is working in FSK mode

Ringing

2

S_CALL_RINGING

’Ringing’ state

Connected

3

S_CALL_TALKING

’Talking’ state. Both parties can start talking when the channel is in such state.

Before the channel state transfers to ‘Talking’, the driver:

Ø empties all buffers in the tone detector and then starts it

Ø starts the DTMF detector if the Caller ID detector is working in FSK mode

Ø resets the counter of the ringing current detector to 0

WaitDialtone

4

S_CALL_ANALOG_WAITDIALTONE

’Waiting for Dial Tone’ state

Before the channel state transfers to ‘Waiting for Dial Tone’, the driver:

Ø empties all buffers in the tone detector

Ø sets the progress value of the AutoDial task to DIAL_DIALING

Dialing

5

S_CALL_ANALOG_TXPHONUM

’Dialing’ state

Before the channel state transfers to ‘Dialing’, the driver:

Ø empties all buffers in the tone detector and then closes it

Ø closes the DTMF detector

WaitRingBackTone

6

S_CALL_ANALOG_WAITDIALRESULT

’Waiting for Ringback Tone’ state

Before the channel state transfers to ‘Waiting for Ringback Tone’, the driver:

Ø empties all buffers in the tone detector and then starts it

Ø starts the enhanced remote pickup detector (see the Enhanced Remote Pickup Detector section in this chapter for details)

Ø starts the DTMF detector

Ø starts Remote Pickup Detector

Pending

7

S_CALL_PENDING

’Pending’ state

WaitAnswer

9

S_CALL_WAIT_REMOTE_PICKUP

’Waiting for Answer’ state. The called party can hear the ringing tone when the channel goes into such state. If it is the station channel that makes an outbound call through the digital trunk at the local end, there should be ringback tones sent to this channel.

Before the channel state transfers to ‘Waiting for Answer’, the driver:

Ø sets the progress value of the AutoDial task to DIAL_ECHOTONE and throw out the E_PROC_AutoDial event to the application program

All state values and corresponding macro definitions in the table above can be found in the file ShpA3Api.h.

The internal events automatically triggered by the driver itself are described as follows.

Name

Description

RingOn

This event is triggered once the driver detects ringing tones on the analog trunk. See the Ringing Current on Analog Phone Line section in this chapter for details.

RingOff

This event is triggered once the driver finds the ringing tone disappears on the analog trunk. See the Ringing Current on Analog Phone Line section in this chapter for details.

T1Out

The timer T1 overflows. T1 is set via the configuration item MaxWaitDialToneTime , with the default value of 3sec.

After T1 overflows, the driver:

Ø sets the progress value of the AutoDial task to DIAL_NO_DIALTONE and sends the E_PROC_AutoDial event to the application;

Ø sets PendingReason to ANALOGOUT_NO_DIALTONE and has the channel state transfer to ‘Pending’.

T2Out

The timer T2 overflows. T2 is set via the configuration item MaxWaitAutoDialAnswerTime , with the default value of 25sec.

After T2 overflows, the driver:

Ø sets the progress value of the AutoDial task to DIAL_NOANSWER and sends the E_PROC_AutoDial event to the application;

Ø sets PendingReason to ANALOGOUT_NOANSWER and has the channel state transfer to ‘Pending’.

Silence1

This event is triggered once the remote pickup detector outputs the E_CHG_ToneAnalyze event (with the parameter CHKTONE_NOVOICE). Refer to the Remote Pickup Detector section in this chapter for more information about the remote pickup detector.

The driver:

Ø sets the progress value of the AutoDial task to DIAL_NOVOICE and sends the E_PROC_AutoDial event to the application;

Ø sets PendingReason to ANALOGOUT_NOVOICE and has the channel state transfer to ‘Pending’.

Silence2

This event is triggered once the remote pickup detector outputs the E_CHG_ToneAnalyze event (with the parameter CHKTONE_ECHO_NOVOICE). Refer to the Remote Pickup Detector section in this chapter for more information about the remote pickup detector.

The driver:

Ø sets the progress value of the AutoDial task to DIAL_ECHO_NOVOICE and sends the E_PROC_AutoDial event to the application;

Ø sets PendingReason to ANALOGOUT_ECHO_NOVOICE and has the channel state transfer to ‘Pending’.

DialToneDetected

This event is triggered once the tone detector detects dial tones on the line. See the Tone Detector section in this chapter for details.

EndofDTMF

This event is triggered when the driver sends out all the digits in TxDtmfBuffer (after dialing).

RingBackTone

This event is triggered once the tone detector detects ringback tones on the line. See the Tone Detector section in this chapter for details.

Answered

This event is triggered once the tone detector detects the following results on the line.

² CHKTONE_VOICEF1: The driver sets the progress value of the AutoDial task to DIAL_VOICEF1 and sends the E_PROC_AutoDial event to the application.

² DIAL_VOICEF2: The driver sets the progress value of the AutoDial task to DIAL_VOICEF2 and sends the E_PROC_AutoDial event to the application.

² DIAL_VOICE: The driver sets the progress value of the AutoDial task to DIAL_VOICE and sends the E_PROC_AutoDial event to the application.

PolarReverse

This event is triggered when the voltage detector detects the polarity reversal signal on the line and the configuration item DisablePolarReverse is set to 0.

In case a channel stays in the Dialing, WaitRingBackTone or WaitAnswer state, the driver will set the progress value of the AutoDial task to DIAL_VOICE and send the E_PROC_AutoDial event to the application.

BusyTone

This event is triggered once the tone detector detects busy tones on the line. Refer to the Tone Detector section in this chapter for more information.

If a channel is in the Talking state at the time when busy tones are detected, the driver will:

Ø set PendingReason to ANALOGOUT_TALKING_REMOTE_HANGUPED and has the channel state transfer to ‘Pending’.

If a channel is in the WaitRingBackTone or WaitAnswer state at the time when busy tones are detected, the driver will:

Ø set the progress value of the AutoDial task to DIAL_BUSYTONE and sends the E_PROC_AutoDial event to the application;

Ø set PendingReason to ANALOGOUT_BUSYTONE and has the channel state transfer to ‘Pending’.

Kewl Start

Remote Hangup Detection mode: When a channel is in the Connected state, if the voltage detector detects that the line voltage keeps the value of KSVoltage Threshold for a period of time reaching KSKeepTime, the system will identify it as remote hangup and transfer the channel state to ‘Pending’.

The events output by the state machine are depicted in the following table.

Event Name | Description
E_CHG_ChState | The driver sends this event to the application when the channel state changes.
E_PROC_AutoDial | The driver sends this event to the application when the AutoDial task, which has been started by the function call of SsmAutoDial , progresses. Refer to the preceding content for detailed information on the driver’s throwing out this event.

Note: All event declarations are listed in the file ShpA3Api.h.


1.15.3.4 Remote Pickup Detector (SHT Series Only)

The remote pickup detector applies only to the analog trunk channel, used to detect with excruciating precision if the calling party has picked up in an outgoing call.

Sometimes it is difficult to judge if the called party has picked up or not when the called party number has been completely sent in an outgoing call on the analog trunk. At present, our boards support two ways to solve such problem: judging by polarity reversal detection and by voice detection.

For detailed information about the polarity reversal signal, refer to the Change in Analog Phone Line Voltage section in this chapter.

In case the remote pickup behavior is judged by voice detection, generally there are 2 different situations as stated below after dialing.

Ø The called party picks up the phone and speaks (e.g. say ‘hello’) after hearing the rings (no matter how long the phone rings before the pickup). In such situation, the calling channel detects the voice energy on the line and believes the called party has picked up as long as the voice energy and duration get greater than the preset threshold value. Note that this method goes invalid if the called party is provided with color ring service, because the PBX will play the color ring (voice signals) as the ringback tone to the calling party.

Ø The called party picks up the phone and keeps silent (does not speak) after hearing the rings. In such case, there will not be ringback tones as well as any other voice signals on the line to the calling party, which make the calling channel unable to decide if the called party has picked up. Hence the application program has to judge by itself.

The SynCTI driver provides an independent remote pickup detector based on voice detection for each analog trunk channel. Its operation principle, related configuration items, functions and output events are all illustrated in the following figure.

The remote pickup detector contains two different combinations: one is of Noise Filter and Ordinary Remote Pickup Detector and the other of K5, K6 and Enhanced Remote Pickup Detector as shown in the figure above. Both are controlled by the switch K1 which can be set via the function SsmStartToneAnalyze / SsmCloseToneAnalyze . Note: K1 controls both the tone detector and the Barge-in detector at one time.

The ordinary remote pickup detector receives the output from the FFT component, appropriate for ordinary occasions. The event it throws out is E_CHG_ToneAnalyze .

The enhanced remote pickup detector uses a special algorithm to judge the pickup behavior on the analog phone line, offering greater precision than the ordinary remote pickup detector. The event it sends off is E_SYS_RemotePickup .


1.15.3.4.1 Ordinary Remote Pickup Detector

The ordinary remote pickup detector detects the voice activities on the line.

The noise filter eliminates the noise on the line. Its operation principle and parameter settings are identical to those of the noise filter mentioned in the Tone Detector section. See relative parts in the Tone Detector section for details.

When the noise filter determine that there exist voice signals on the line, the ordinary remote pickup detector won’t agree until it is sure that the voice signal are not that specified by the 1st call progress tone detector.

The ordinary remote pickup detector outputs the E_CHG_ToneAnalyze event in one of the three situations stated below.

(1) The called party picks up the phone immediately when the phone rings and then keeps silent. In such case, there will not be ringback tones (Some flying ringback tones may appear on the line but are bound to be filtered out because they can’t constitute an entire cycle so as not to be detected) as well as any other voice signals on the line to the calling party as shown below.

In the figure above,

Ton, Toff: Indicate the signal durations respectively at on and off set by the parameters about the ringback tone waveform.

Te: The accepted maximum error of the ringback tone cycle, Te= (Ton+Toff)*(1+20%).

T1: The threshold value for silent duration after dialing, counted from t1. The driver outputs E_CHG_ToneAnalyze (with the parameter CHKTONE_NOVOICE) as long as the line keeps silent longer than T1 which is designated by the configuration item WaitAfterDialTime .

(2) The called party picks up the phone after at least one entire ring and then keeps silent. In such situation, the calling channel can detect at least one ringback tone but no voice activities as shown below.

In the figure above,

t0: Represents the time when the dialing is completed.

Ton, Toff: Indicate the signal durations respectively at on and off set by the parameters about the ringback tone waveform.

Te: The accepted maximum error of the ringback tone cycle, Te = (Ton+Toff)*(1+20%).

T2: The threshold value for silent duration after ringback tones’ disappearing, counted from t1 (i.e. the time when the ringback tone has surely gone). The driver outputs E_CHG_ToneAnalyze (with the parameter CHKTONE_ECHO_NOVOICE) as long as the line keeps silent longer than T2 which is designated by the configuration item MaxWaitVocAfterEcho .

(3) The called party picks up the phone after hearing the rings (no matter how long the phone rings before the pickup) and immediately speaks (e.g. say ‘hello’).

In the figure above, T3 is the threshold value for judging voice signals, counted from t1 when voice signals appear. The driver outputs E_CHG_ToneAnalyze (with the parameter CHKTONE_VOICE) as long as the voice signal lasts longer than T3 which is designated by the configuration item VoiceOnDetermineTime or the function SsmSetVoiceOnDetermineTime . The function SsmGetVoiceOnDetermineTime can be used to acquire the value of T3 saved in the driver.


1.15.3.4.2 Enhanced Remote Pickup Detector

The switch K5 is switched on after the successful system initialization. It is set by the configuration item RelativeEngyHookDetect or the function SsmSetFlag (with the parameter F_RELATIVEENGYHOOKDETECT) which also can be used to obtain the state of K5.

The switch K6 can be controlled both by the application program and the driver. It is switched off after the successful system initialization.

K6 will be automatically switched on to enable the remote pickup detector as one of the following conditions is satisfied.

Ø The application invokes the function SsmStartPickupAnalyze .

Ø The driver will send the called party number digit by digit to the remote PBX in the state of S_CALL_ANALOG_TXPHONUM after the application calls the function SsmAutoDial to start an outgoing call. When the called party number has been completely transmitted, the channel state will transfer to S_CALL_ANALOG_WAITDIALRESULT after the driver automatically switches on K6.

Ø The application invokes the function SsmAppendPhoNum when a channel stays in the S_CALL_ANALOG_TXPHONUM or S_CALL_ANALOG_WAITDIALRESULT state.

K6 will be automatically switched off by the driver to disable the remote pickup detector as one of the following conditions is satisfied.

Ø The remote pickup detector accomplishes a detection and outputs the E_SYS_RemotePickup event.

Ø The application invokes the function SsmHangup .

Ø The state machine of the analog trunk channel receives the E_CHG_BusyTone event which is thrown out by the tone detector.

The configuration item HookEngyConfigMulti , HookValidEngyCnt or the function SsmSetCalleeHookDetectP is used to set parameters for the enhanced remote pickup detector.

When the enhanced remote pickup detector detects the called party’s pickup behavior, it will send out the E_SYS_RemotePickup event to the call state machine for subsequent processing. The function SsmGetPickup can be used to obtain the result.


1.15.4 Station Channel


1.15.4.1 State Machine

Each state identifier in the above diagram is described in the following table.

State Identifier | Value | Macro Definition | Description
Standby | 0 | S_CALL_STANDBY | ‘Idle’ state. When the channel state transfers to ‘Idle’, the driver will: Ø empty all buffers in DTMF Detector Ø close DTMF Generator and terminate the unfinished WaitDtmf task. close Tone Generator.
OffHook | 1 | S_CALL_PICKUPED | ’Off-hook’ state. When the channel state transfers to ‘Off-hook’, the driver will: Ø start sending dial tones to the phone provided that the configuration item AutoSendDialTone is set to 1. Ø empty all buffers in DTMF Detector and then start it.

All state values and corresponding macro definitions in the table above can be found in the file ShpA3Api.h.

Note: The driver throws out the E_CHG_ChState event to the application every time when the channel state changes.

The internal events automatically triggered the driver itself are described as follows.

Name | Description
Offhook | This event is triggered once the driver detects the pickup behavior.
Onhook | This event is triggered once the driver detects the hangup behavior.


1.15.4.2 Pickup/hangup Detection

When the phone is picked up or hung up, some dithering signals may be generated on the line. To prevent misdetection, those signals should be filtered so as not to affect the accuracy in detecting the pickup/hangup behavior. The configuration item UserOnHookFilterTime is used to set the minimum pickup signal duration. Only when the driver detects the pickup signal lasts longer than the set value of this configuration item will it confirm the pickup behavior.

The driver throws out the E_CHG_HookState event to the application every time when it confirms a pickup/hangup behavior. Also the function SsmGetHookState can be used to obtain the off-hook/on-hook state of the station channel.


1.15.4.3 Flash Signal Detection

Because the station channel serves as the user circuit on analog PBXes, it has the capability of detecting flash signals generated on the phone. Refer to the Flash Signal on Analog Phone Line section in this chapter for more information about the flash signal.

The function SsmSetLocalFlashTime or the configuration item MaxLocalFlashTime is used to set N, the maximum interval for judging the flash signal. The user releases the hook switch on the phone in a short period of time (assumed as n) after pressing it. If n<N, the driver affirms what the user do is sending an flash signal, otherwise it regards this action as the hangup behavior.

The driver provides a flash signal counter for each station channel, adding 1 to the count and throwing out the E_CHG_FlashCount event to the application program every time when it detects a flash signal. Also the function SsmGetFlashCount can be used to acquire the count. The driver will automatically reset the counter to 0 whenever the channel state transfers to ‘Talking’ or ‘on-hook’. You can use the function SsmClearFlashCount to clear the count as well.


1.15.4.4 Sending Ringing Signals to Phone

Each station channel on the Synway board is equipped with a ringing current generator for sending ringing signals to the telephone. As viewed from the waveform, the regular ringing signal is periodic with 1sec on and 4sec off. However, the on and off duration can be adjusted by the function SsmSetRingPeriod, and also the signal can be set to consecutive by the configuration item UserChGenerateRingMode.

Both SsmStartRing and SsmStartRingWithCIDStr can be used to send ringing signals to the telephone. SsmStartRing is for the analog and magnet phones; SsmStartRingWithCIDStr is only for the station channel but can send the calling party information besides ringing signals. Because SsmStartRingWithCIDStr only accepts the modulated FSK bit stream, so it is often used with the function fPcm_ConvertFskCID.

The driver provides a ringing signal counter for each station or magnet channel, adding 1 to the count every time when it completes a signal transmission (at on state). Also the function SsmCheckSendRing can be used to acquire the count.

The application program can invoke the function SsmStopRing any time to stop sending ringing signals to the phone


1.15.4.5 Generating Polarity Reversal Signal on Phone Line

For detailed information about the polarity reversal signal, refer to the Change in Analog Phone Line Voltage section in this chapter.

Whether the station channel on the Synway board has the capability to generate the polarity reversal signal on the analog phone line depends on if it is equipped with a B-type 1.0 series station module and if the module has the capability to generate the polarity reversal signal (Note: Some of the B-type 1.0 series station modules don’t have such capability).

The polarity reversal feature needs to be enabled via the configuration item UserSendPolar.

The function SsmGetPolarState is used to get the current voltage polarity on the phone line and the function SsmSetPolarState to set the voltage polarity.


1.15.4.6 Auto-transmission of Dial Tones upon Pickup Detected

It is the configuration item AutoSendDialTone that determines if the driver, after the phone which is linked to the station channel picks up, will automatically send dial tones to the phone. As to whether the driver automatically stops sending dial tones upon detecting DTMF digits, it is set via the configuration item StopSendDialToneOnDtmf.


1.15.5 Composite Module

Synway offers a special kind of module to the SHT Series boards, that is, a module fitted with two put-in circuits respectively to an analog trunk channel and a station channel. This kind of module is called the composite module. The great advantage of this module is it enables direct connection between trunk and station which keeps call uninterrupted during power outage. To be exact, when the power of the application system is accidentally cut off, the analog trunk channel and the station channel linked to a same composite module connects directly to each other. Therefore, the station channel is still able to communicate with the telephone network via the analog trunk channel in such case.

The relationship between the analog trunk channel and the station channel on the composite module is set via the function SsmSetUnimoduleState or the configuration item UnimoduleState.


1.15.6 Magnet Channel


1.15.6.1 Overview

The channel fitted with the magnet module on the SHT Series boards is called the magnet channel for short, used to connect with the magnet phone.

The internal structure of the magnet module is similar to that of a magnet phone whose operation principle is illustrated below.

As shown in the figure above, the magnet phone is composed of the transmitter circuit, the receiver circuit, the electric bell, the electrical generator and the switches K1, K2 (Although it seems all the components are connected by single lines, the actual thing is they are connected by double lines and form a loop with each other). When the crank is turned, K2 automatically switches to the point 1 so as to send the ringing current to the electric bell of the remote telephone; when K1 is pressed (equivalent to the situation that the hook switch on an ordinary telephone is released), which makes the transmitter circuit be in connection and enabled to send out voices (The main purpose to set K1 is to disconnect the dry battery at the time as no voices are transmitted).

The magnet module has the following features.

Ø The magnet module has only three states: ‘idle’, ‘sending rings’ and ‘ringing’, and does not support the pickup/hangup behavior. It is the same as the station module in the rhythm of sending the ringing current, that is, ring for 1sec and keep silent for 4sec. The ring can be properly detected even in the 4sec when the signal goes at off state;

Ø The internal ringing current generator can generate the ringing current on the line. Its operation principle is identical to that of the ringing current generator on the station module for the SHT/B Series boards or above model. On the one hand, the magnet module is not allowed to send the ringing current if the ringing current is already available on the line; on the other hand, the magnet module will automatically stop sending the ringing current if it detects the ringing current on the line midway in transmission;

Ø The magnet module leaves out K1 so that the receiver circuit and the transmitter circuit are always in connection when it stays in the ‘idle’ or ‘ringing’ state.

Note:

The on-board module identification circuit cannot recognize the magnet module but mistakes it as the analog trunk module. Hence it is essential to set the configuration item IsMagnetModule to ensure that the driver can properly distinguish these two kinds of modules.


1.15.6.2 State Machine

In the figure above,

State Identifier | Value | Macro Definition | Description
Standby | 0 | S_CALL_STANDBY | ’Idle’ state. The channel goes into this state after the driver’s successful initialization.
SendRing | 100 | S_CALL_SENDRING | ’Sending rings’ state. In this state, the channel is sending rings to the magnet phone and examining if there is ringing current on the line at the same time. The ringing current detection can be set via the configuration RingDetectFilterPara item.
Ringing | 2 | S_CALL_RINGING | ‘Ringing’ state. The magnet phone is ringing and the driver checks if rings have disappeared in this state.


1.15.7 EM Module

E&M is a universal technology involving trunk signaling over telephone switches and PBXs. EM interface is a type of analog interface, through which information and signaling are separated. Like other kind of modules from Synway, an EM module corresponds to two channels: one is an EM Control channel and the other is an EM Voice channel.

The supported functions for the EM control channel include the API functions SsmPickup, SsmHangup and the functions SsmGetChState, SsmGetHookState for acquiring status. SsmPickup and SsmHangup are used to send 1 and 0 signals to the remote end; SsmGetHookState is used to detect the 1 or 0 signal from the remote end; SsmGetChState is used to get the local on-hook and off-hook states which change with the local end invoking SsmPickup and SsmHangup.

The operations on the EM Voice channel are the same as those on other voice channels.


1.15.8 Non-module Channel

The SHT Series boards use the modular structure, composed of the main board and different modules. The on-board DSP chips can work properly even if there is no module installed so that the non-module channel also supports voice processing. However, since no physical interface circuits for telephone lines available on the board, voice signals can be acquired only from TDM bus. In some particular occasions when other boards with TDM bus are required to record voices, what you need do is put the voice data via TDM bus to the non-module channel and use the output from the Barge-in detector as the pre-requisites for recording control. Such feature can be enabled via the configuration item NoModuleChBusRec or the function SsmSetNoModuleChBusRec. The non-module channel has the following voice processing capabilities: recording, data exchange via TDM bus, DTMF reception and Barge-in detection.

Note: In case there is no module installed on the main board of the SHT Series, the channel type number of 20 means it is the non-module channel.


1.16 SHD Series (CTI Series)


1.16.1 Brief Introduction of SHD Series

The features supported by the SHD Series boards are shown in the following table.

Board Model | Form Factor | Trunk Type | Max. Ports | Voice Processing Capabilities | Conferencing Capabilities | FSK | Max Fax Resource | SS1 | ISDN PRI | SS7 | SS7 Signaling Links
SHD-30A-CT/PCI/SS1 | PCI | 1 E1 | 30 | Ö | Ö | Ö | N/A | Ö | N/A | N/A | N/A
SHD-30A-CT/PCI/ISDN | PCI | 1 E1 | 30 | Ö | Ö | Ö | N/A | Ö | Ö | N/A | N/A
SHD-30A-CT/PCI/SS7 | PCI | 1 E1 | 30 | Ö | Ö | Ö | N/A | Ö | Ö | Ö | 1
SHD-60A-CT/PCI/SS1 | PCI | 2 E1 | 60 | Ö | Ö | Ö | N/A | Ö | N/A | N/A | N/A
SHD-60A-CT/PCI/ISDN | PCI | 2 E1 | 60 | Ö | Ö | Ö | N/A | Ö | Ö | N/A | N/A
SHD-60A-CT/PCI/SS7 | PCI | 2 E1 | 60 | Ö | Ö | Ö | N/A | Ö | Ö | Ö | 2
SHD-120A-CT/PCI/SS1 | PCI | 4 E1 | 120 | Ö | Ö | Ö | N/A | Ö | N/A | N/A | N/A
SHD-120A-CT/PCI/ISDN | PCI | 4 E1 | 120 | Ö | Ö | Ö | N/A | Ö | Ö | N/A | N/A
SHD-120A-CT/PCI/SS7 | PCI | 4 E1 | 120 | Ö | Ö | Ö | N/A | Ö | Ö | Ö | 4
SHD-30B-CT/PCI/SS7/FAX | PCI | 1 E1 | 30 | Ö | Ö | Ö | 24 | Ö | Ö | Ö | 1
SHD-60B-CT/PCI/SS7/FAX | PCI | 2 E1 | 60 | Ö | Ö | Ö | 16 | Ö | Ö | Ö | 2
SHD-30C-CT/PCI | PCI | 1 E1/T1 | 30/23 | Ö | Ö | Ö | N/A | Ö(E1 Only) | Ö | Ö(E1 Only) | 1
SHD-30C-CT/PCI/FAX | PCI | 1 E1/T1 | 30/23 | Ö | Ö | Ö | 24 | Ö(E1 Only) | Ö | Ö(E1 Only) | 1
SHD-60C-CT/PCI | PCI | 2 E1/T1 | 60/46 | Ö | Ö | Ö | N/A | Ö(E1 Only) | Ö | Ö(E1 Only) | 2
SHD-60C-CT/PCI/ FAX | PCI | 2 E1/T1 | 60/46 | Ö | Ö | Ö | 16 | Ö(E1 Only) | Ö | Ö(E1 Only) | 2
SHD-120D-CT/PCI | PCI | 4 E1/T1/J1 | 120/92 | Ö | Ö | Ö | N/A | Ö | Ö | Ö | 4
SHD-120D-CT/PCI/EC | PCI | 4 E1/T1/J1 | 120/92 | Ö | Ö | Ö | N/A | Ö | Ö | Ö | 4
SHD-120D-CT/PCI/CAS | PCI | 8 E1/T1 | 120/92 | Ö | Ö | Ö | N/A | Ö | Ö | Ö | N/A
SHD-240D-CT/PCI | PCI | 8 E1/T1/J1 | 240/184 | Ö | Ö | Ö | N/A | Ö | Ö | Ö | 8
SHD-240D-CT/PCI/EC | PCI | 8 E1/T1/J1 | 240/184 | Ö | Ö | Ö | N/A | Ö | Ö | Ö | 8
SHD-240D-CT/PCI/CAS | PCI | 8 E1/T1 | 240/184 | Ö | Ö | Ö | N/A | Ö | Ö | Ö | N/A
SHD-30E-CT/PCI(ssw) | PCI(ssw) | 1 E1 | 30/23 | Ö | Ö | Ö | N/A | Ö | Ö | Ö | 1
SHD-30E-CT/PCI/FAX(ssw) | PCI(ssw) | 1 E1 | 30/23 | Ö | Ö | Ö | 32 | Ö | Ö | Ö | 1
SHD-30E-CT/PCI/EC(ssw) | PCI(ssw) | 1 E1 | 30/23 | Ö | Ö | Ö | N/A | Ö | Ö | Ö | 1
SHD-60E-CT/PCI(ssw) | PCI(ssw) | 2 E1 | 60/46 | Ö | Ö | Ö | N/A | Ö | Ö | Ö | 2
SHD-60E-CT/PCI/FAX(ssw) | PCI(ssw) | 2 E1 | 60/46 | Ö | Ö | Ö | 64 | Ö | Ö | Ö | 2
SHD-60E-CT/PCI/EC(ssw) | PCI(ssw) | 2 E1 | 60/46 | Ö | Ö | Ö | N/A | Ö | Ö | Ö | 2
SHD-120E-CT/PCI(ssw) | PCI(ssw) | 4 E1 | 120/92 | Ö | Ö | Ö | N/A | Ö | Ö | Ö | 4
SHD-120E-CT/PCI/FAX(ssw) | PCI(ssw) | 4 E1 | 120/92 | Ö | Ö | Ö | 64 | Ö | Ö | Ö | 4
SHD-120E-CT/PCI/EC(ssw) | PCI(ssw) | 4 E1 | 120/82 | Ö | Ö | Ö | N/A | Ö | Ö | Ö | 4
SHD-240E-CT/PCI(ssw) | PCI(ssw) | 8 E1 | 240/184 | Ö | Ö | Ö | N/A | Ö | Ö | Ö | 8
SHD-240E-CT/PCI/FAX(ssw) | PCI(ssw) | 8 E1 | 240/184 | Ö | Ö | Ö | 64 | Ö | Ö | Ö | 8
SHD-240E-CT/PCI/EC(ssw) | PCI(ssw) | 8 E1 | 240/184 | Ö | Ö | Ö | N/A | Ö | Ö | Ö | 8
SHD-30E-CT/PCIe | PCIe | 1 E1 | 30/23 | Ö | Ö | Ö | N/A | Ö | Ö | Ö | 1
SHD-30E-CT/PCIe/FAX | PCIe | 1 E1 | 30/23 | Ö | Ö | Ö | 32 | Ö | Ö | Ö | 1
SHD-30E-CT/PCIe/EC | PCIe | 1 E1 | 30/23 | Ö | Ö | Ö | N/A | Ö | Ö | Ö | 1
SHD-60E-CT/PCIe | PCIe | 2 E1 | 60/46 | Ö | Ö | Ö | N/A | Ö | Ö | Ö | 2
SHD-60E-CT/PCIe/FAX | PCIe | 2 E1 | 60/46 | Ö | Ö | Ö | 64 | Ö | Ö | Ö | 2
SHD-60E-CT/PCIe/EC | PCIe | 2 E1 | 60/46 | Ö | Ö | Ö | N/A | Ö | Ö | Ö | 2
SHD-120E-CT/PCIe | PCIe | 4 E1 | 120/92 | Ö | Ö | Ö | N/A | Ö | Ö | Ö | 4
SHD-120E-CT/PCIe/FAX | PCIe | 4 E1 | 120/92 | Ö | Ö | Ö | 64 | Ö | Ö | Ö | 4
SHD-120E-CT/PCIe/EC | PCIe | 4 E1 | 120/82 | Ö | Ö | Ö | N/A | Ö | Ö | Ö | 4
SHD-240E-CT/PCIe | PCIe | 8 E1 | 240/184 | Ö | Ö | Ö | N/A | Ö | Ö | Ö | 8
SHD-240E-CT/PCIe/FAX | PCIe | 8 E1 | 240/184 | Ö | Ö | Ö | 64 | Ö | Ö | Ö | 8
SHD-240E-CT/PCIe/EC | PCIe | 8 E1 | 240/184 | Ö | Ö | Ö | N/A | Ö | Ö | Ö | 8
SHD-30A-CT/cPCI/SS7 | cPCI | 1 E1 | 30 | Ö | Ö | Ö | N/A | Ö | Ö | Ö | 1
SHD-60A-CT/cPCI/SS7 | cPCI | 2 E1 | 60 | Ö | Ö | Ö | N/A | Ö | Ö | Ö | 2
SHD-120A-CT/cPCI/SS7 | cPCI | 4 E1 | 120 | Ö | Ö | Ö | N/A | Ö | Ö | Ö | 4
SHD-240A-CT/cPCI | cPCI | 8 E1 | 240 | Ö | Ö | N/A | N/A | N/A | Ö | Ö | 8
SHD-480A-CT/cPCI | cPCI | 16 E1 | 480 | Ö | Ö | N/A | N/A | N/A | Ö | Ö | 16
SHD-30B-CT/cPCI/SS7/FAX | cPCI | 1 E1 | 30 | Ö | Ö | Ö | 24 | Ö | Ö | Ö | 1
SHD-60B-CT/cPCI/SS7/FAX | cPCI | 2 E1 | 60 | Ö | Ö | Ö | 16 | Ö | Ö | Ö | 2
SHD-240S-CT/cPCI | cPCI | 8 E1 | 240 | Ö | N/A | N/A | N/A | N/A | Ö | Ö | 8
SHD-480S-CT/cPCI | cPCI | 16 E1 | 480 | Ö | N/A | N/A | N/A | N/A | Ö | Ö | 16

Note: All SHD Series boards have the capability of exchanging data via TDM bus.


1.16.2 Operation Principle of SHD Series

The figure below shows the operation principle of the SHD Series boards.

Below is description on components and symbols related to the recording operation illustrated above:

Name | Description
M1 | Outbound voice mixer.
K5-3 [1] | The switch that controls the signal output of Tone Generator and DTMF Generator, often being off under the automatic control of the driver. Only when the function SsmTxDtmf or SsmSendTone/SsmSendToneEx is called to start the DTMF generator or the tone generator does the driver switch on K5-3 and switch off it again after the operation concerned is complete.
M2 | Off-bus mixer.
A4-1 … A4-6 | The volume adjuster which is used for off-bus signals before they are sent to M2. Use the function SsmSetListenVlmInConf to set the volume, with the default value of 0DB. Or use the following configuration item or functions to set the volume for a channel with data to be off the bus. ² SsmTalkWithEx ² SsmListenToEx/SsmLinkFromEx/SsmLinkFromAllCh
K5-2 [1] | The switch that controls output signals from the off-bus mixer, automatically controlled by the driver. The driver will automatically switch off K5-2 when off-bus operation functions are called by the application program, and then switch it on again when the input to M2 is thoroughly cut off. See the TDM Capability section in this chapter for more information.
M3 | Recording mixer. The signals from M3 is sent to the Encoder component for recording purpose.
A3 | The volume adjuster which is used for incoming signals before they are sent to M3. The volume can be set via the function SsmSetRecVolume or the configuration item DefaultRecordVolume, with the default value of 0DB.
A2 | The volume adjuster which is used for outgoing signals before they are sent to M3. By default, it is on. The volume can be set via the function SsmSetRecMixer or the configuration item DefaultRecordMixerVolume, with the default value of -7.
M4 | Outbound voice mixer for recording. Mixes signals from the off-bus mixer, data being played on a channel and signals from the tone generator/DTMF generator, and then puts them onto M3.
K6-1 K6-2 | Switch K6-1 controls whether to put signals form M2 into M3; Switch K6-2 controls whether to put voice data being played into M3. Both can be set via the function SsmSetRecBack.
M5 | Onto-bus mixer. Mixes data being played on a channel, incoming signals and those from the off-bus mixer M2, and then puts them onto TDM bus. Upon board initialization, the output from M5 is transported to a time slot (marked as ‘ts’ for short) on TDM bus. You can use the function SsmLinkToBus to designate the ts.
K3 | The switch that controls whether to put incoming signals into M5 or not. By default, it is on. It can be set via the function SsmSetFlag (with the parameter F_InVoiceToBus) or the configuration item InVoiceToBus.
K1-1 [1] | The switch that controls whether to put data being played on a channel first into M5 and then onto TDM bus or not, usually being off. It can be set via the function SsmSetPlayDest, used only for playing background music to a teleconference.
K1-2 | The switch that controls whether to put signals from M2 back onto TDM bus. By default, it is off. It can be set via the function SsmSetFlag (with the parameter F_MixerResToBus).
 | Below is the description on components and symbols concerning the playback operation
K7 | The Voice Play/Fsk Transmitter switch, automatically controlled by the driver. When the application calls the playing function, K7 connects to the component Decoder; when it calls the function SsmStartSendFSK to start FSK data transmission, K7 connects to the component FSK Generator. For more information about the playing functions, refer to the Voice Playing section.
A1 | The volume adjuster for voice playing. The volume can be set via the configuration item DefaultPlayVolume or the function SsmSetPlayVolume/SsmSetPlayGain, with the default value of 0.
K5-1 [1] | The switch that controls the voice playing operation, automatically controlled by the driver. Only when the application program invokes the playing function does the driver automatically switch on K5-1 and then switch it off at the end of voice playing. For more information about the playing functions, refer to the Voice Playing section.
K2 | The switch that shifts between the FSK detector and other detectors, usually connected to other detectors unless the FSK detector is started.

Note[1]：

l For some board models in SHD Series, due to the limited on-board DSP resources, only one of K5-1, K5-2, K5-3 can be switched on when K1-1 is off. As a result, in case a channel is playing voices (K5-3 is already on at that time) or starts the tone generator (K5-1 is already on at that time), and the application program invokes the function for bus operation which causes K5-2 to be off, if the configuration item LinkFromStopPlayAndTone is set to 1, the playing operation will be stopped immediately and K5-2 will be switched on; if the configuration item LinkFromStopPlayAndTone is set to 0, K5-2 will get on only after the playing operation ends up in a normal way. The bus operation functions which cause K5-2 to get off include:

Ø SsmTalkWith / SsmTalkWithEx

Ø SsmListenTo / SsmListenToEx / SsmLinkFrom / SsmLinkFromEx / SsmLinkFromAllCh

Ø SsmLinkFromBus / SsmLinkFromBusEx

Involved board models are:

Ø SHD-30A-CT/PCI/SS1

Ø SHD-30A-CT/PCI/ISDN

Ø SHD-30A-CT/PCI/SS7

Ø SHD-30B-CT/PCI/SS7/FAX

Ø SHD-60A-CT/PCI/SS1

Ø SHD-60A-CT/PCI/ISDN

Ø SHD-60A-CT/PCI/SS7

Ø SHD-60B-CT/PCI/SS7/FAX

Ø SHD-120A-CT/PCI/SS1

Ø SHD-120A-CT/PCI/ISDN

Ø SHD-120A-CT/PCI/SS7

Ø SHD-30A-CT/cPCI/SS7

Ø SHD-30B-CT/cPCI/SS7/FAX

Ø SHD-60A-CT/cPCI/SS7

Ø SHD-60B-CT/cPCI/SS7/FAX

Ø SHD-120A-CT/cPCI/SS7

Ø SHD-30C-CT/PCI

Ø SHD-60C-CT/PCI

Ø SHD-30C-CT/PCI/FAX

Ø SHD-60C-CT/PCI/FAX

l If K1-1 is on, K5-1 and K5-2 are allowed to be switched on at the same time but K5-3 must keep off.

Ø Voice Playing

After the application invokes the playing function, the driver will automatically have K7 linked to Decoder and switch on K5-1. The voice data processed by A1 will:

² Enter M1 and form the final outgoing signals with other signal sources; or

² Enter M4 under the control of K6-2 and form the recording signal sources with other signals; or

² Enter M5 under the control of K1-1 and form the onto-bus signal sources with other signals, only for playing background music to the teleconference.

Ø Recording Example for Various Signal Sources

A lot of special applications are available via the flexible use of the above switches for recording control and volume adjusters. In the following examples, ch1 and ch2 respectively mean Channel 1 and Channel 2.

² Example 1: Only record the incoming signals on ch1 and use the default volume.

SsmSetRecVolume(ch1, 0); //start A3, set the volume gain to 0DB

SsmSetRecMixer(ch1, FALSE, 0); //stop A2

SsmRecToFile(ch1, ……); //start the task of file recording …

² Example 2: Record the incoming signals on ch1 (volume increased by 6DB) and the signals output from M2 (volume decreased by 3DB) at one time based on the establishement of a two-way call between ch1 and ch2.

SsmTalkWith(ch1, ch2); //establish a two-way connection between ch1 and ch2, switch on K5-2

SsmSetRecBack(ch1,2); //switch on K6-1, switch off K6-2

SsmSetRecVolume(ch1, 2); //start A3, set the volume gain to 2*3DB=6DB

SsmSetRecMixer(ch1, TRUE, -1); //start A2, set the volume gain to -1*3DB=-3DB

SsmRecToFile(ch1, ……); //start the task of file recording …

² Example 3: When ch1 joins a teleconference (assuming the conference room number is n) as the organizer, play background music on ch1 and record the conference (including the background music) through ch1. All signal sources go with normal volume, i.e. the gain is set to 0.

SsmJoinConfGroup(n, ch1, ……); //ch1 joins the conference: switch on K5-2 and K3

SsmSetPlayDest(int ch, 1); //switch on K1-1

SsmSetRecBack(ch1,1); //switch on K6-1 and K6-2

SsmPlayFile(ch1, ……); //start the task of voice playing on ch1: link K7 to Decoder, switch on K5-1

SsmSetRecVolume(ch1, 0); //start A3, set the volume gain to 0DB

SsmSetRecMixer(ch1, TRUE, 0); //start A2, set the volume gain to 0DB

SsmRecToFile(ch1, ……); //start the task of file recording …


1.16.3 Number-receiving Rule for Incoming Call

Incoming calls are automatically handled via the channel state machine. What the application need do is preset the rule to receive numbers. The number-receiving rule means the rule followed by the local end to receive Caller ID, Callee ID and other information from the remote PBX.

As to the number-receiving rule, there are two modes available which can be set by the configuration item DefaultRcvPhoNumLen.

² Fixed-length Mode: The local end has only one phone number of fixed length (e.g. ‘110’). When the driver fully receives the preset length of the called party number, the number-receiving process is considered to be over. The configuration items DefaultRcvCallerID and RcvPhoNumCfgLen are used to set particular rules in this mode.

² Prefix Mode: You can set several called party numbers for the application program at the local end, each of which begins with a prefix. The configuration items MaxPhoNumRule and Rule are used to set particular rules in this mode.

You are allowed to set independent number-receiving rules respectively for TUP channel, ISUP channel, ISDN channel and SS1 channel.

² The rule for TUP channel is set in the [TUP] section;

² The rule for ISUP channel is set in the [ISUP] section;

² The rule for ISDN channel is set in the [ISDN] section;

² The rule for SS1 channel is set in the [SS1] section.


1.16.4 SS7 Programming


1.16.4.1 OPC & DPC

Signaling Point (SP) is a node in a signaling network that originates and receives signaling messages, or transfers signaling messages from one signaling link to another, or both. CCITT suggests the use of a signaling point code (SPC) with a unique 14-bit format used at the international level for signaling message routing and identification of signaling points involved, i.e. International Signaling Point Code (ISPC). See the table below for the grouping of ISPC.

3bit | 8bit | 3bit
ZONE | AREA | POINT

The format of the 24-bit binary code is used for the identification of national signaling points in China (i.e. National Signaling Point Code (NSPC) Format in China). NSPC is grouped as follows.

8bit | 8bit | 8bit
MAIN AREA | SUBAREA | POINT

The Synway SHD Series boards support both International Signaling Point Code (ISPC) Format and National Signaling Point Code (NSPC) Format in China.

The specific signaling point code (OPC-Originating Point Code or DPC- Destination Point Code) is configured in the file Ss7Server.ini.


1.16.4.2 Time Slot Allocation

The PCM time slots on the SHD Series boards are allocated as shown in the following table.

Board Model | Sync. Time Slot | Voice Time Slot | Signaling Time Slot
 |  |  | SS1 | ISDN PRI | SS7
SHD-30A-CT/PCI/SS1 | 0 | 1-15,17-31 | 16 | N/A | N/A
SHD-30A-CT/PCI/ISDN | 0 | 1-15,17-31 | 16 | 16 | N/A
SHD-30A-CT/PCI/SS7 | 0 | 1-15,17-31 | 16 | 16 | 16[1]
 |  | 2-31 | - | - | 1[1]
SHD-60A-CT/PCI/SS1 | 0 | 1-15,17-31 | 16 | N/A | N/A
SHD-60A-CT/PCI/ISDN | 0 | 1-15,17-31 | 16 | 16 | N/A
SHD-60A-CT/PCI/SS7 | 0 | 1-15,17-31 | 16 | 16 | 16[1]
 |  | 2-31 | - | - | 1[1]
SHD-120A-CT/PCI/SS1 | 0 | 1-15,17-31 | 16 | N/A | N/A
SHD-120A-CT/PCI/ISDN | 0 | 1-15,17-31 | 16 | 16 | N/A
SHD-120A-CT/PCI/SS7 | 0 | 1-15,17-31 | 16 | 16 | 16[1]
SHD-30B-CT/PCI/SS7/FAX | 0 | 1-15,17-31 | 16 | 16 | 16[1]
 |  | 2-31 | - | - | 1[1]
SHD-60B-CT/PCI/SS7/FAX | 0 | 1-15,17-31 | 16 | 16 | 16[1]
 |  | 2-31 | - | - | 1[1]
SHD-30C-CT/PCI | 0(E1) N/A(T1) | 1-15,17-31(E1) 0-22(T1 ISDN) | 16(E1) | 16(E1) 23(T1) | 16[1](E1)
SHD-30C-CT/PCI/FAX | 0(E1) N/A(T1) | 1-15,17-31(E1) 0-22(T1 ISDN) | 16(E1) | 16(E1) 23(T1) | 16[1](E1)
SHD-60C-CT/PCI | 0(E1) N/A(T1) | 1-15,17-31(E1) 0-22(T1 ISDN) | 16(E1) | 16(E1) 23(T1) | 16[1](E1)
SHD-60C-CT/PCI/ FAX | 0(E1) N/A(T1) | 1-15,17-31(E1) 0-22(T1 ISDN) | 16(E1) | 16(E1) 23(T1) | 16[1](E1)
SHD-120D-CT/PCI | 0 | 1-15,17-31 | 16 | 16 | 16[1]
SHD-120D-CT/PCI/EC | 0 | 1-15,17-31 | 16 | 16 | 16[1]
SHD-120D-CT/PCI/CAS | 0 | 1-15,17-31 | 16 | - | -
SHD-240D-CT/PCI | 0 | 1-15,17-31 | 16 | 16 | 16[1]
SHD-240D-CT/PCI/EC | 0 | 1-15,17-31 | 16 | 16 | 16[1]
SHD-240D-CT/PCI/CAS | 0 | 1-15,17-31 | 16 | - | -
SHD-30E-CT/PCI(ssw) | 0 | 1-15,17-31 | 16 | 16 | 16[1]
SHD-30E-CT/PCI/FAX(ssw) | 0 | 1-15,17-31 | 16 | 16 | 16[1]
SHD-30E-CT/PCI/EC(ssw) | 0 | 1-15,17-31 | 16 | 16 | 16[1]
SHD-60E-CT/PCI(ssw) | 0 | 1-15,17-31 | 16 | 16 | 16[1]
SHD-60E-CT/PCI/FAX(ssw) | 0 | 1-15,17-31 | 16 | 16 | 16[1]
SHD-60E-CT/PCI/EC(ssw) | 0 | 1-15,17-31 | 16 | 16 | 16[1]
SHD-120E-CT/PCI(ssw) | 0 | 1-15,17-31 | 16 | 16 | 16[1]
SHD-120E-CT/PCI/FAX(ssw) | 0 | 1-15,17-31 | 16 | 16 | 16[1]
SHD-120E-CT/PCI/EC(ssw) | 0 | 1-15,17-31 | 16 | 16 | 16[1]
SHD-240E-CT/PCI(ssw) | 0 | 1-15,17-31 | 16 | 16 | 16[1]
SHD-240E-CT/PCI/FAX(ssw) | 0 | 1-15,17-31 | 16 | 16 | 16[1]
SHD-240E-CT/PCI/EC(ssw) | 0 | 1-15,17-31 | 16 | 16 | 16[1]
SHD-30E-CT/PCIe | 0 | 1-15,17-31 | 16 | 16 | 16[1]
SHD-30E-CT/PCIe/FAX | 0 | 1-15,17-31 | 16 | 16 | 16[1]
SHD-30E-CT/PCIe/EC | 0 | 1-15,17-31 | 16 | 16 | 16[1]
SHD-60E-CT/PCIe | 0 | 1-15,17-31 | 16 | 16 | 16[1]
SHD-60E-CT/PCIe/FAX | 0 | 1-15,17-31 | 16 | 16 | 16[1]
SHD-60E-CT/PCIe/EC | 0 | 1-15,17-31 | 16 | 16 | 16[1]
SHD-120E-CT/PCIe | 0 | 1-15,17-31 | 16 | 16 | 16[1]
SHD-120E-CT/PCIe/FAX | 0 | 1-15,17-31 | 16 | 16 | 16[1]
SHD-120E-CT/PCIe/EC | 0 | 1-15,17-31 | 16 | 16 | 16[1]
SHD-240E-CT/PCIe | 0 | 1-15,17-31 | 16 | 16 | 16[1]
SHD-240E-CT/PCIe/FAX | 0 | 1-15,17-31 | 16 | 16 | 16[1]
SHD-240E-CT/PCIe/EC | 0 | 1-15,17-31 | 16 | 16 | 16[1]
SHD-30A-CT/cPCI/SS7 | 0 | 1-15,17-31 | 16 | 16 | 16[1]
 |  | 2-31 | - | - | 1[1]
SHD-60A-CT/cPCI/SS7 | 0 | 1-15,17-31 | 16 | 16 | 16[1]
 |  | 2-31 | - | - | 1[1]
SHD-120A-CT/cPCI/SS7 | 0 | 1-15,17-31 | 16 | 16 | 16[1]
 |  | 2-31 | - | - | 1[1]
SHD-240A-CT/cPCI | 0 | 1-15,17-31 | N/A | 16 | 16[1]
SHD-480A-CT/cPCI | 0 | 1-15,17-31 | N/A | 16 | 16[1]
SHD-30B-CT/cPCI/SS7/FAX | 0 | 1-15,17-31 | 16 | 16 | 16[1]
 |  | 2-31 | - | - | 1[1]
SHD-60B-CT/cPCI/SS7/FAX | 0 | 1-15,17-31 | 16 | 16 | 16[1]
 |  | 2-31 | - | - | 1[1]
SHD-240S-CT/cPCI | 0 | 1-15,17-31 | N/A | 16 | 16[1]
SHD-480S-CT/cPCI | 0 | 1-15,17-31 | N/A | 16 | 16[1]

Note [1]: It is the configuration items UseTS16AsCircuit and Ss7SignalingTS that determine if SS7 links are available on the digital trunk and which time slot serves as the signaling link.


1.16.4.3 Setting Spare Address Codes

In TUP and ISUP calls, called party number, calling party number and other information within messages are displayed in address code format instead of ASCII format. However, the driver adopts ASCII characters to present CallerId and CalleeId, so it is essential to establish a rule for translating address codes into unified ASCII characters. As shown in the table below, the configuration item AddressSignal is used to map the spare codes to some particular characters.

Address Code |  | Corresponding ASCII Character | Property
Hexadecimal | Decimal
0 | 0 | ‘0’ | Fixed
1 | 1 | ‘1’ | Fixed
2 | 2 | ‘2’ | Fixed
3 | 3 | ‘3’ | Fixed
4 | 4 | ‘4’ | Fixed
5 | 5 | ‘5’ | Fixed
6 | 6 | ‘6’ | Fixed
7 | 7 | ‘7’ | Fixed
8 | 8 | ‘8’ | Fixed
9 | 9 | ‘9’ | Fixed
a | 10 | spare | Configurable via the configuration item AddressSignal
b | 11 | spare | Configurable via the configuration item AddressSignal
c | 12 | spare | Configurable via the configuration item AddressSignal
d | 13 | spare | Configurable via the configuration item AddressSignal
e | 14 | spare | Configurable via the configuration item AddressSignal
f | 15 | ST signal | Fixed


1.16.4.4 Configuration Instance for SS7 Server

Refer to Chapter 4 Application and Configuration Instance for SS7 Server in this manual for details.


1.16.4.5 TUP Programming and Application


1.16.4.5.1 TUP Channel State Machine

The internal events automatically triggered by the driver itself are described as follows.

Event Name

Description

Mtp3Usable

The driver will send this event to all channel state machines after receiving signaling from the SS7 server so as to change the channel state from Unusable to Reseting and reset the circuit.

CicReset

This event is triggered when the driver receives the circuit reset message (GRA, GRS or RSC) following the successful reset of the circuit.

What the driver does: If the local end blocks the remote end or is waiting for the reply after sending the blocking message to the remote end, the driver will send the BLO message to the remote end to keep it blocked and throw out the E_CHG_RemoteChBlock event to the application program at the same time.

Blocking

This channel is blocked by the local end (Local Blocking) or the remote end (Remote Blocking). This event is triggered in the following two situations.

· Remote Blocking: The driver receives the group blocking message (MGB, SGB, HGB) or the circuit blocking message (BLO) from the remote PBX.

· Local Blocking: The application invokes the function SsmBlockLocalCh or SsmBlockLocalPCM.

UnblockedByPBX

Remote Unblocked: This event is triggered when the driver receives the MGU, HGU, SGU or UBL message from the remote PBX.

UnblockedByApp

Local Unblocked: This event is triggered after the application invokes the function SsmUnblockLocalPCM or SsmUnblockLocalCh to unblock the local end.

RcvIAI

The driver receives the incoming call request message (i.e. IAI or IAM) from the remote PBX. That whether the driver accepts this request or not depends on the channel state at that time.

Channel State | Description
BlockedByPBX BlockedByApp | When the local end is blocked, the channel does not support outgoing calls and only accept incoming calls.
Dialing | The reception of the IAI/IAM message from the remote PBX during the outgoing call indicates the ‘collision’ phenomenon occurs. As stipulated in TUP, if the channel’s CIC represents the circuit controlled by the local end, the local end will abandon the IAI/IAM message and continue the outgoing call; otherwise, the local end will quit the outgoing call and process the incoming call.
OffHook Locked | The channel is preparing to make an outgoing call but does not send the IAI or IAM message yet. The driver will reply the incoming call request message received at that time from the remote end.
Standby | The channel accepts the incoming call.
Others | The channel rejects the incoming call.

In case the driver accepts the incoming call, it will throw out the E_CHG_RxPhoNumBuf event to the application program after saving the called party number within the IAM message to the buffer and change the channel state to RcvPhoNum.

RcvRLG

The driver receives the RLG (Release-guard signal) message from the remote PBX.

RcvCLF

The driver receives the CLF message from the remote PBX. When this event is triggered, if the channel stays in the state:

· RcvPhoNum or Ringing：

it indicates the remote PBX (the calling party) cancels this call during the incoming call establishment.

In case the channel stays in the Ringing state and the configuration item RingToPending is set to 1, the driver will set PendingReason to PEND_RemoteHangupOnRinging and transfer the channel state to Pending; otherwise, the driver will start to disconnect this incoming call.

· S_TUP_WaitCLF (a substate of Release)：

it indicates the channel receives the CLF message as expected during the call disconnection, which ends up the disconnection process.

· Pending：

No matter what causes the channel to go into the Pending state, the reception of the CLF message in this state will prompt the driver to automatically send the RLG message and start disconnecting the call.

· Connected：

For the incoming call, the reception of the CLF message in the Connected state means it is the calling party that first hangs up the phone. The driver will set PendingReason to PEND_RemoteHangupOnTalking and then transfer the channel state to Pending. However, it won’t send the RLG message.

RcvACM

The driver receives the ACM (Address Complete Message) message from the remote PBX. In the outgoing call progress implementation, the driver will send the IAI/IAM message to the remote PBX when the application calls the function SsmAutoDial to start an outgoing call. Then the remote PBX will send the ACM message to the local end as it believes all necessary information including the Callee ID has been received.

The driver responds to this event only when the channel stays in the Dialing or AppSetCallerID state. After receiving the ACM message, the driver will save it, set the progress value of the AutoDial task to DIAL_ECHOTONE and then transfer the channel state to WaitAnswer. The function SsmGetKB can be used to acquire the received ACM message.

Answered

This event is triggered when the driver receives the answering signal from the remote PBX. During an outgoing call, when the remote PBX is sending rings to the called party, it will send answering signals to the local end once the called party picks up the phone. The answering signal indicates one of the following messages:

² ANU message (answering signal, without instruction on fees)

² ANC (answering signal, charge)

² ANN (answering signal, no charge)

The function SsmGetTupFlag can be used to obtain the specific content of the answering signal.

This event will lead to the channel state transition from WaitAnswer to Connected. Before the channel goes into the new state, the driver will automatically

² start the DTMF Detector if the configuration item AlwaysEnableRxDtmf is set to 0;

² start the Barge-in Detector if the configuration item AlwaysDetectBargeIn is set to 0;

² clear the Tone Detector and start it;

² set the progress value of the AutoDial task to DIAL_VOICE, end up the task and throw out the event E_PROC_AutoDial to the application program.

RcvCBK

The driver receives the CBK message from the remote PBX. When this event is triggered, if the channel stays in the state

· Connected：

it indicates that the remote user first hangs up the phone in an outgoing call. The driver will set PendingReason to PEND_CalleeHangupOnTalking and transfer the channel state to Pending.

· WaitAnswer：

it indicates that the called party refuses this call and the AutoDial task ends. The driver will

² set the progress value of the AutoDial task to DIAL_FAILURE and the failure reason to ATDL_RcvCBK, and throw out the E_PROC_AutoDial event to the application;

² set PendingReason to PEND_CalleeHangupOnWaitRemotePickUp and then transfer the channel state to Pending.

RcvCCL

The driver receives the CCL message from the remote PBX, which indicates that the remote user hangs up first in an incoming call after two parties are connected.

After receiving the RcvCCL event, the driver will set PendingReason to PEND_RemoteHangupOnTalking and then transfer the channel state to Pending. If the application invokes the function SsmSetCalleeHoldFlag to enable the ‘Caller Holding’ feature when the channel stays in the Connected state, the driver will automatically send the OPR message to the remote PBX and keep the channel in Connected.

T1Out

The timer T1 overflows. T1 is set to 60sec and will be automatically started when the channel goes into the Locked or OffHook state.

T2Out

The timer T2 overflows. T2 is set to 30sec and will be automatically started when the channel goes into the Dialing state. After T2 overflows, the driver will

² set the progress value of the AutoDial task to DIAL_FAILURE and the failure reason to ATDL_WaitDialAnsTimeout, and throw out the E_PROC_AutoDial event to the application;

² set PendingReason to PEND_AutoDialFailed and then transfer the channel state to Pending.

T4Out

The timer T4 overflows. T4 is set by the configuration item MaxWaitAutoDialAnswerTime and will be automatically started when the channel goes into the WaitAnswer state. After T4 overflows, the driver will

² set the progress value of the AutoDial task to DIAL_NOANSWER and the failure reason to ATDL_WaitRemotePickupTimeout, and throw out the E_PROC_AutoDial event to the application;

² set PendingReason to PEND_AutoDialFailed and then transfer the channel state to Pending.

T5Out

The timer T5 overflows. T5 is set to 20sec and will be automatically started when the channel goes into S_TUP_WaitPrefix or S_TUP_WaitSAM (a substate of RcvPhoNum). After T5 overflows, the driver will automatically send the ADI (Address Incomplete) message to the remote PBX and then change the channel state to Release.

PhoNumOK

This event will be triggered when the driver

² receives all necessary information including the called party number according to the preset number-receiving rule;

² stops waiting for the GSM message from the remote PBX as the channel stays in _TUP_WaitGSM (a substate of RcvPhoNum) and the timer with the preset value of 5sec overflows;

² receives the GSM message from the remote PBX when the channel stays in _TUP_WaitGSM (a substate of RcvPhoNum).

After this event is triggered, if the application enables the ‘Auto-answer of Incoming Call’ feature via the function SsmEnableAutoSendKB or the configuration item AutoSendACM, the driver will automatically send the ACM message to the remote PBX and transfer the channel state to Ringing. The configuration item DefaultACM is used to specify the message indicator field which shows the called party state in the ACM message automatically sent by the driver. The configuration item RcvPhoNumCfgLen is used to set the method for the driver to save the called party number. The function SsmSetKB is for setting the charge indicator in the backward call indicator field of the ACM message. If the ‘Auto-answer of Incoming Call’ feature is not enabled, the driver will set PendingReason to PEND_WaitBckStpMsg, transfer the channel state to Suspend, and let the application determine whether to accept this call or not.

Error

This event is triggered when the driver detects one of the following situations.

Ø The synchronization signal through TS0 on the digital trunk where this channel stays gets lost (e.g. line disconnected, clock configuration error and so on).

Ø The TCP/IP connection between the TUP stack and the SS7 server is broken.

Ø The signaling unusable message is received from the SS7 server.

When this event is triggered, the driver’s operation is in relation to the channel state. See below for details.

Ø In the state Dialing, AppSetCallerID or WaitAnswer: The driver will set the progress value of the AutoDial task to DIAL_FAILURE and the failure reason to ATDL_PcmSyncLos or ATDL_Mtp3Unusable, and throw out the E_PROC_AutoDial event to the application;

Ø In the state Dialing, AppSetCallerID, WaitAnswer, Connected or Pending: The driver will set PendingReason to PEND_PcmSyncLos or PEND_SsxUnusable, and then transfer the channel state to Pending.

CallFailure

If the call fails during the outgoing process, the driver triggers this event. The outgoing call fails in the following situations.

Ø The driver receives the call failure message from the remote PBX. The call failure message includes:

l The CFL message (call failed). The driver will

² set the result of the AutoDial task to DIAL_FAILURE and the failure reason to ATDL_RcvCFL, and throw out the E_PROC_AutoDial event to the application;

² transfer the channel state to Pending after setting PendingReason: if the channel stays in the WaitAnswer state, PendingReason is set to PEND_CalleeHangupOnWaitRemotePickUp; if the channel stays in the Dialing state, PendingReason is set to PEND_AutoDialFailed.

l The SSB, SLB, STB (Called Subscriber Busy) message. The driver will

² set the result of the AutoDial task to DIAL_BUSYTONE and the failure reason to ATDL_RcvSSB, ATDL_RcvSLB or ATDL_RcvSTB, and throw out the E_PROC_AutoDial event to the application;

² set PendingReason to PEND_AutoDialFailed, and then transfer the channel state to Pending.

l The UNN message (Callee ID unallocated). The driver will

² set the result of the AutoDial task to DIAL_INVALID_PHONUM and the failure reason to ATDL_RcvUNN, and throw out the E_PROC_AutoDial event to the application;

² set PendingReason to PEND_AutoDialFailed, and then transfer the channel state to Pending.

l The SEC, CGC, NNC, LOS, SST, ACB, DPN, EUM or ADI message (other errors in call). The driver will

² set the result of the AutoDial task to DIAL_FAILURE and the failure reason respectively to ATDL_RcvSEC, ATDL_RcvCGC, ATDL_RcvNNC, ATDL_RcvLOS, ATDL_RcvSST, ATDL_RcvACB, ATDL_RcvDPN, ATDL_RcvEUM, ATDL_RcvADI, and throw out the E_PROC_AutoDial event to the application;

² set PendingReason to PEND_AutoDialFailed, and then transfer the channel state to Pending.

a) The CicReset event is triggered.

b) The Blocking event is triggered.

c) The Error event is triggered.

Each state identifier in the above diagram is described in the following table.

State Identifier

Description

Unusable

The channel is unusable.

Reseting

The circuit is being reset.

BlockedByPBX

Remote Blocking: When the remote PBX is stopped for maintenance, it will send the blocking message to the local end to prevent new calls. When the channel stays in such state, the driver will refuse the Outgoing Call instruction given by the application program and only accept and process incoming calls.

BlockedByApp

Local Blocking: The application program can not make an outgoing call in this state. It is often used for system maintenance. The application can block the channel via the function call of SsmBlockLocalCh or SsmBlockLocalPCM so as to inform the driver to prevent starting the outgoing call. Note: The channel in such state still can accept and process incoming calls.

Standby

Idle: The channel should go into this state provided it is normally reset after the successful driver initialization. The application can invoke the function SsmAutoDial to start an outgoing call in this state.

The driver will automatically clear the Caller ID buffer when the channel state transfers to Idle at the end of the call, provided that the configuration item AutoClearCallerIdBufOnHangup is set to 1.

OffHook

Off-hook: The application can invoke the function SsmAutoDial to start an outgoing call in this state. The driver will start the timer T1 when the channel goes into the OffHook state. If the application does not call the function SsmAutoDial before T1 overflows, the driver will reset the channel back to the idle state.

Locked

Outgoing Call Locked: The application can invoke the function SsmAutoDial to start an outgoing call in this state. The driver will start the timer T1 when the channel goes into this state. If the application does not call the function SsmPickup or SsmAutoDial before T1 overflows, the driver will reset the channel back to the idle state.

Pending

It is the pending state.

RcvPhoNum

It is an internal state during an incoming call, including three substates: S_TUP_WaitSAM, S_TUP_WaitPrefix and S_TUP_WaitGSM.

The driver judges the received called party number according to the preset number-receiving rule. If the number complies with the rule, the channel will transfer to the subsequent state. For more information about the number-receiving rule, refer to the section Number-receiving Rule for Incoming Call in this chapter.

If the called party number involved in the IAM/IAI message from the remote PBX proves incomplete, the channel will stay in the S_TUP_WaitSAM substate. Every time when the driver receives the SAO or SAM message from the remote PBX, it will save the message to its internal buffer and throw out the E_CHG_RxPhoNumBuf event to the application.

After the driver receives the complete called party number according to the number-receiving rule, if it is required to receive the calling party information (such as Caller ID, Calling party category, etc.) which is not yet supplied by the remote PBX, the driver will send the GRQ message to the remote PBX and transfer the channel state to S_TUP_WaitGSM. The configuration item ReqTypeIndicators is used to customize the Request Type Indicator field in the GRQ message sent to the remote PBX.

If the called party number received by the channel does not conform to the number-receiving rule, the driver will automatically send the REL message (carrying the unallocated-number reason) and transfer the channel state to Release.

In the RcvPhoNum state, the application can

² invoke the function SsmHangup/SsmHangupEx to refuse this call. Then the driver will send the REL message. The configuration item DefaultHangupRELInd or the function SsmSetIsupFlag (with the parameter ISUP_REL_DENY_SetToOther) can be used to set the reason why the call fails written in the REL message.

Ringing

The local end is ringing. The application program can use the function SsmPickup to accept the call and the function SsmHangup to refuse the call.

Dialing

It is an internal state during the incoming call, including the substates S_TUP_WaitDialAnswer and S_TUP_WaitSetCallerID.

The function call of SsmAutoDial or SsmAutoDialEx by the application will prompt the driver to send the IAM message to the remote PBX and transfer the channel state to S_TUP_WaitDialAnswer. In the S_TUP_WaitDialAnswer substate, if the remote PBX wants to receive the calling party information which is not contained in the IAM/IAI message, it will send the GRQ message to the local end. After the driver receives the GRQ message,

Ø in case the Caller ID buffer is empty during an outgoing call on the channel while the received GRQ message shows the remote PBX is asking the local end for the calling party number,

² the driver will automatically send the GSM message provided the configuration item AutoSendGSM is set to 1;

² the driver will bring the channel into the S_TUP_WaitSetCallerID state to wait for the application to set the calling party number and the like, and start a timer with the preset value of 2sec at the same time, provided the configuration item AutoSendGSM is set to 0. If the timer overflows before the application invokes the function SsmSetTxCallerId, the driver will transfer the channel state back to S_TUP_WaitDialAnswer.

Ø otherwise, the driver will take the string in the Caller ID buffer as the calling party number and send the GSM message automatically.

WaitAnswer

The channel is waiting for the called party to pick up the phone. This state is only applicable to the outgoing call. The called party should be able to hear ringing tones in such state, and if at the local end is the station channel that makes an outgoing call through the digital trunk channel it should send the ringback tone to the station channel.

Connected

Both parties are connected and able to talk with each other. When the channel state transfers to Connected, the driver will

· start the DTMF Detector if the configuration item AlwaysEnableRxDtmf is set to 0;

· start the Barge-in Detector if the configuration item AlwaysDetectBargeIn is set to 0;

· clear the Tone Detector and start it.

Release

It is the disconnection state, including the substates S_TUP_WaitCLF and S_TUP_WaitRLG.

All state values and corresponding macro definitions can be found in the file ShpA3Api.h.

Each state identifier in the state machine is declared in the header file ShpA3Api.h as follows.

State Identifier | Value in ShpA3Api.h | Macro Definition in ShpA3Api.h
Standby | 0 | S_CALL_STANDBY
OffHook | 1 | S_CALL_PICKUPED
Ringing | 2 | S_CALL_RINGING
Connected | 3 | S_CALL_TALKING
Pending | 7 | S_CALL_PENDING
WaitAnswer | 9 | S_CALL_WAIT_REMOTE_PICKUP
BlockedByPBX | 10 | S_CALL_RemoteBlock
Unusable | 11 | S_CALL_UNAVAILABLE
Locked | 12 | S_CALL_LOCKED
BlockedByApp | 20 | S_CALL_LocalBlock
Reseting | 70 | S_TUP_WaitPcmReset
RcvPhoNum | 71 | S_TUP_WaitSAM
 | 72 | S_TUP_WaitGSM
 | 74 | S_TUP_WaitPrefix
Dialing | 75 | S_TUP_WaitDialAnswer
 | 77 | S_TUP_WaitSetCallerID
Release | 73 | S_TUP_WaitCLF
 | 76 | S_TUP_WaitRLG

All state values and corresponding macro definitions in the table above can be found in the file ShpA3Api.h.

In the above state machine, ChUsable is the driver’s internal component to judge the channel’s usability. It will output values as shown in the table below.

Output Value | Description
Unusable | The channel is unusable if the Error event keeps effective.
BlockedByApp | The event Blocking keeps effective and the channel is blocked by the application program.
BlockedByPBX | The Blocking event keeps effective and the channel is blocked by the remote PBX.
Standby | The Error event stays invalid.

Note:

At this stage, the driver also performs the following operations.

² Clear the tone detector and automatically close it;

² Automatically stop the WaitDtmf task if it has been started by the application;

² Automatically stop the task of DTMF transmission if it has been started by the application;

² Automatically clear the buffer of the DTMF detector, and close the DTMF detector if the configuration item AlwaysEnableRxDtmf is set to 0;

² Automatically close the Barge-in detector if the configuration item AlwaysDetectBargeIn is set to 0;

² Automatically clear the Caller ID buffer if the configuration item AutoClearCallerIdBufOnHangup is set to 1.


1.16.4.5.2 Channel Blocked and Unblocked


1.16.4.5.2.1 Basic Concepts

(1) Channel Blocked

After a channel is blocked, it is forbidden to make outgoing calls but still able to accept incoming calls in a normal way.

(2) Local Blocking

The local application program invokes functions to block a stated local channel.

(3) Remote Blocking

The remote PBX sends specific circuit/circuit group blocking messages to block a local channel/PCM. The blocking messages sent by the remote PBX are automatically processed by the driver.

(4) Remote Blocked

The local application sends particular circuit/circuit group blocking messages to block the remote PBX.


1.16.4.5.2.2 Usage

This feature is only applicable to the digital trunk channel. When the application program is required to stop the system for maintenance, the 4 steps below must be followed to ensure nomal exit.

(1) Block all local channels to stop new outgoing calls.

(2) Block all remote channels to stop new outgoing calls.

(3) Wait for the current call progress to end up.

(4) Exit the program.

When a channel is blocked, the driver will not process new outgoing calls any more (i.e. all function calls related to the auto outgoing call progress will fail).


1.16.4.5.2.3 Blocking Ways

(1) A channel can be blocked by receiving blocking messages from the remote PBX. In TUP, the channel may be blocked as it receives the circuit blocking message (BLO) or the circuit group blocking message (SGB, HGB or MGB) from the remote PBX; or

(2) The application program can invoke the function SsmBlockLocalCh() to block the local channel and/or the function SsmBlockLocalPCM() to block the local PCM.


1.16.4.5.2.4 Function List

The functions used for blocking channels are listed in the following table.

Blocking Mode |  | Function Name | Output Event
Local Blocked | Channel Blocked | SsmBlockLocalCh |
 |  | SsmUnblockLocalCh |
 |  | SsmQueryLocalChBlockState |
 | Circuit Group Blocked | SsmBlockLocalPCM |
 |  | SsmUnblockLocalPCM |
 |  | SsmQueryLocalPCMBlockState |
Remote Blocked | Channel Blocked | SsmQueryOpBlockRemoteCh |
 |  | SsmBlockRemoteCh | Throw out the E_CHG_RemoteChBlock event upon reception of the acknowledgement message (BLA or UBA) from the remote end.
 |  | SsmUnblockRemoteCh
 |  | SsmGetRemoteChBlockStatus | Throw out the E_CHG_RemotePCMBlock event upon reception of the group acknowledgement message (MBA/HBA/SBA or MUA/HUA/SUA) from the remote end.
 | Circuit Group Blocked | SsmBlockRemotePCM
 |  | SsmUnblockRemotePCM |
 |  | SsmGetRemotePCMBlockStatus |

Note: When the local driver is to block the remote end, the Range field in the circuit group blocking message it sends to the remote PBX can be set via the configuration item SendGRMRange.


1.16.4.5.3 Circuit Resetting

The TUP state machine will automatically send the circuit group reset message to the remote PBX and reset all TUP channels when

² the SS7 server detects that the service supplied by the MTP3 level becomes usable again, or

² the synchronization signal of the digital trunk is resumed.

The Range field in the circuit group reset message can be set via the configuration item SendGRMRange.


1.16.4.5.4 ‘Caller Holding’ Feature

During an incoming call that both parties have joined, if the calling party first hangs up the phone, the remote PBX will send the CCL message to the local end. Upon reception of the CCL message, the driver will send back the OPR message to the remote PBX provided the application invokes the function SsmSetCalleeHoldFlag to enable the ‘Caller Holding’ feature.


1.16.4.5.5 TUP Configuration

The table below shows all relative configuration items for TUP protocol.

Configuration Section | Configuration Item | Description
[BoardId=x] | PcmNumber | set the total number of on-board digital trunks as well as the signaling type, the clock operating mode and the line type for each digital trunk.
 | PcmSSx
 | PcmClockMode
 | PcmLinkType
 | UseTS16AsCircuit Ss7SignalingTS | determine whether some of the digital trunks serve as SS7 signaling links and specify the time slot number to support the signaling links.
[PcmInfo] | TotalPcm | set the total number of all digital trunks involved in the PC and build the mapping relationship between the logical number and the physical number of each digital trunk.
 | Pcm
[SS7] | AutoHandleTup | sets whether to use the call state machine supplied by the driver.
 | Ss7ServerIP | set the SS7 server address and the IP address of the local PC.
 | SecondServerIP
 | LocalIP
[TUP] | MaxWaitAutoDialAnswerTime | Outgoing Call: set relative parameters.
 | CalloutCallerId
 | SetSTSignal
 | AutoSendGSM
 | ConnectReqMsg
 | AddressSignal
 | CalloutIAM_MsgPntr | Outgoing Call: customize the IAM message to be sent to the remote PBX.
 | CalloutIAM_CAT
 | CallingIndicatorBit
 | ReqTypeIndicators
 | OriginalCalleeAddrInd
 | CallerAddrInd
 | DefaultACM | Incoming Call: set relative parameters.
 | AutoSendACM
 | ReqTypeIndicators
 | RingToPending
 | RcvPhoNumCfgLen | Incoming Call: set the number-receiving rule.
 | DefaultRcvPhoNumLen
 | DefaultRcvCallerID
 | MaxPhoNumRule
 | Rule
 | HangupRingSendCBK | Incoming Call: set the message type used for refusing the incoming call.

Note: Those written in the XXXX font are essentially configured items while those in XXXX are optionally configured ones.


1.16.4.6 ISUP Programming and Application


1.16.4.6.1 ISUP Configuration

The table below lists all relative configuration items for the use of ISUP.

Configuration Section | Configuration Item | Description
[BoardId=x] | PcmNumber | set the total number of on-board digital trunks as well as the signaling type, the clock operating mode and the line type for each digital trunk.
 | PcmSSx
 | PcmClockMode
 | PcmLinkType
 | UseTS16AsCircuit Ss7SignalingTS | determine whether some of the digital trunks serve as SS7 signaling links and specify the time slot number to support the signaling links.
[PcmInfo] | TotalPcm | set the total number of all digital trunks involved in the PC and build the mapping relationship between the logical number and the physical number of each digital trunk.
 | Pcm
[SS7] | TotalIsupPcm | set the digital trunks which uses ISUP in the local PC.
 | IsupPcm
 | AutoHandleIsup | sets whether to use the call state machine supplied by the driver.
 | Ss7ServerIP | set the SS7 server address and the IP address of the local PC.
 | SecondServerIP
 | LocalIP
[ISUP] | MaxWaitAutoDialAnswerTime | Outgoing Call: set relative parameters.
 | CalloutCallerId
 | SetSTSignal
 | DefaultNatureOfConnectionInd | Outgoing Call: customize the IAM message to be sent to the remote PBX.
 | DefaultIAM_ForwardCallInd
 | DefaultIAM_CAT
 | DefaultIAM_TransmissionMediumRequirment
 | DefaultIAM_CalleeParam
 | DefaultIAM_CallerParam
 | DefaultIAM_OriginalCalleeParam
 | DefaultIAM_RedirectingNumber
 | bSubscriberSI，SubscriberSI
 | bOptionalFCI，OptionalFCI
 | Usr2UsrInfo
 | AutoSendINF | Outgoing Call: sets the mode to reply to the INF message.
 | RingToPending | Incoming Call: set relative parameters.
 | AutoSendACM
 | DefaultCalledPickupMsg
 | DefaultBackwardCallInd
 | DefaultHangupRELInd
 | DefaultCauseInd
 | SaveRGNTo1stPhoNumStr
 | DefaultRcvPhoNumLen | Incoming Call: set the number-receiving rule.
 | DefaultRcvCallerID
 | MaxPhoNumRule
 | Rule
 | AddressSignal | sets the parameters of the ISUP state machine.

Note: Those written in the XXXX font are essentially configured items while those in XXXX are optionally configured ones.


1.16.4.6.2 ISUP Channel State Machine

The internal events automatically triggered by the driver itself are described as follows.

Event Name

Description

Mtp3Usable

The driver will send this event to all channel state machines after receiving signaling from the SS7 server so as to change the channel state from Unusable to Reseting and reset the circuit.

CicReset

This event is triggered when the driver receives the circuit reset message (GRA, GRS or RSC).

After this event is triggered, in case the channel stays in the AutoDial or WaitAnswer state and the outgoing call fails, the driver will throw out the E_PROC_AutoDial event to the application. The function SsmGetAutoDialFailureReason can be used to acquire the specific reason why the AutoDial task fails.

Blocking

This channel is blocked by the local end (Local Blocking) or the remote end (Remote Blocking).

Remote Blocking: The driver receives the group blocking message (CGB) or the circuit blocking message (BLO) from the remote PBX.

UnblockedByPBX

Local Unblocked: This event is triggered when the driver receives the CGU, UBL messages from the remote PBX.

RcvIAM

The driver receives the incoming call request message (IAM) from the remote PBX.

The driver will automatically save the newly received IAM message. The function SsmGetIsupUPPara (with the parameter C_ISUP_IAM) can be used to acquire this message, and SsmGetRedirectionInfReason, SsmGetKA can be used respectively to obtain the redirection reason value and the ‘Calling Party Category’ parameter in the IAM message.

That whether the driver accepts this request or not depends on the channel state at that time.

Channel State | Description
BlockedByPBX | When the local end is blocked, although the channel does not support outgoing calls, it still can accept incoming calls. Therefore, the driver will respond to the IAM message in such case.
AutoDial | The reception of the IAI message from the remote PBX during the outgoing call progress implementation indicates the ‘collision’ phenomenon occurs. As stipulated in ISUP, if the channel’s CIC represents the circuit controlled by the local end, the local end will abandon the IAI message and continue the outgoing call; otherwise, the local end will quit the outgoing call and process the incoming call, which indicates this outgoing call fails. At that time the driver will throw out the E_PROC_AutoDial event to the application. The function SsmGetAutoDialFailureReason can be used to acquire the specific reason why the AutoDial task fails.
OffHook Locked | The channel is preparing to make an outgoing call but does not send the IAM message yet. The driver will respond to the incoming call request message IAM received at that time from the remote PBX.
Standby | The channel accepts the incoming call.
Others | The channel rejects this IAM message.

In case the driver accepts the incoming call, it will throw out the E_CHG_RxPhoNumBuf event to the application program after saving the called party number within the IAM message to the buffer and change the channel state to RcvPhoNum.

EnfofRcvPhoNum

The driver receives all called party numbers according to the preset number-receiving rule. For more information about the number-receiving rule, refer to the section Number-receiving Rule for Incoming Call in this chapter.

RcvINF

The driver receives the INF message which contains relative information about the calling party from the remote PBX.

RcvREL

The driver receives the disconnection message (REL) from the remote PBX. The function SsmGetReleaseReason can be used to obtain the specific reason why the call gets disconnected.

When this event is triggered, if the channel stays in the state

· RcvPhoNum：

it indicates the remote PBX (the calling party) cancels this call during the incoming call establishment.

· Ringing：

it indicates during the incoming call establishment, the remote PBX cancels this call when the local end is in the Ringing state. The application can determine whether to interfere in the channel state transition via the control over the switch K2 which is set by the configuration item RingToPending. If the configuration item RingToPending is set to 1, the driver will set PendingReason to PEND_RemoteHangupOnRinging and transfer the channel state to Pending for the further processing by the application program; otherwise, the driver will set out to disconnect this incoming call.

· Connected：

it indicates the calling party has hung up the phone. The driver will set PendingReason to PEND_RemoteHangupOnConnected and then transfer the channel state to Pending.

RcvRLC

The driver receives the RLC message from the remote PBX which means the disconnection phase ends up.

RcvACM

The driver receives the ACM (Address Complete Message) message from the remote PBX.

In the outgoing call progress implementation, the driver will send the IAM message to the remote PBX when the application calls the function SsmAutoDial to start an outgoing call. Then the remote PBX will send the ACM message to the local end as it believes all necessary information including the Callee ID has been received in order to show the idle state of the called party. After receiving the ACM message via the function SsmGetIsupUPPara (with the parameter C_ISUP_ACM), the driver will save it to the internal buffer, set the progress value of the AutoDial task to DIAL_ECHOTONE and then transfer the channel state to WaitAnswer. The function SsmGetKB can be used to acquire the 8 lower bits of the backward call indicator field (2 bytes) in this ACM message.

The remote PBX may send the CPG (Call Progress) message following the ACM message. The function SsmGetCpg can be used to get the CPG message.

Answered

During an outgoing call, after the remote PBX finishes receiving the called party number, it will send ringing signals to the called party if the called party is in the idle state; or it will send the ANM (Answer) message to the local end if the called party picks up the phone.

After receiving the ANM message, the driver will set the progress value of the AutoDial task to DIAL_VOICE, ending up the AutoDial task, and throw out the E_PROC_AutoDial event to the application.

RcvSUS

The driver receives the SUS (Suspend) message from the remote PBX.

RcvRES

The driver receives the REC (Recover) message from the remote PBX.

CallFailure

If the driver receives the REL message from the remote PBX during an outgoing call, which means the call fails, it will send the E_PROC_AutoDial event to the application. The function SsmGetAutoDialFailureReason can help to acquire the specific reason why the AutoDial task fails.

T1Out

The timer T1 overflows. T1 is set to 60sec and will be automatically started when the channel goes into the Locked or OffHook state.

T2Out

The timer T2 overflows. T2 is set to 25sec and will be automatically started when the channel goes into S_ISUP_WaitDialAnswer (a substate of AutoDial). After T2 overflows, which indicates this call fails, the driver will throw out the E_PROC_AutoDial event to the application. The function SsmGetAutoDialFailureReason can help to acquire the specific reason why the AutoDial task fails.

T3Out

The timer T3 overflows. T3 is set to 60sec and will be automatically started when the channel goes into the Pending state.

T4Out

The timer T4 overflows. T4 is set by the configuration item MaxWaitAutoDialAnswerTime and will be automatically started when the channel goes into the WaitAnswer state. After T4 overflows, the driver will throw out the E_PROC_AutoDial event to the application. The function SsmGetAutoDialFailureReason can help to acquire the specific reason why the AutoDial task fails.

T5Out

The timer T5 overflows. T5 is set to 10sec and will be automatically started when the channel goes into S_ISUP_WaitINF (a substate of RcvPhoNum). After T5 overflows, the driver will stop waiting for the INF message from the remote PBX.

T6Out

The timer T6 overflows. T6 is set to 180sec and will be automatically started when the channel goes into the Suspend state.

Error

This event is triggered when the driver detects one of the following situations.

² The synchronization signal through TS0 on the digital trunk where this channel stays gets lost (e.g. line disconnected, clock configuration error and so on).

² The TCP/IP connection between the ISUP stack and the SS7 server is broken.

² The signaling unusable message is received from the SS7 server.

If the channels stays in the AutoDial or WaitAnswer state when this event is triggered, the outgoing call fails. The driver will throw out the E_PROC_AutoDial event to the application in such case. The function SsmGetAutoDialFailureReason can help to acquire the specific reason why the AutoDial task fails.

Each state identifier in the above diagram is described in the following table.

State Identifier

Description

Unusable

The channel is unusable.

Reseting

The circuit is being reset.

BlockingRemote

The remote PBX is blocked.

In the BlockingRemote state, the outgoing call can be started not by the remote PBX but by the local end.

BlockedByPBX

The channel is blocked by the remote PBX (Remote Blocking).

When the remote PBX is stopped for maintenance, it will send the blocking message to the local end to prevent new calls. When the channel stays in such state, the driver will refuse the Outgoing Call instruction given by the application program and only accept and process incoming calls.

Standby

‘Idle’ state

The channel should go into this state provided it is normally reset after the successful driver initialization.

The application can invoke the function SsmAutoDial to start an outgoing call in this state.

The driver will automatically clear the Caller ID buffer when the channel state transfers to Idle at the end of the call, provided the configuration item AutoClearCallerIdBufOnHangup is set to 1.

Locked

’Outgoing Call Locked’ state

The application can invoke the function SsmAutoDial to start an outgoing call in this state.

The driver will start the timer T1 when the channel goes into this state. If the application does not call the function SsmPickup or SsmAutoDial before T1 overflows, the driver will reset the channel back to the idle state. The set value of T1 is 60sec.

OffHook

’Off-hook’ state

The application can invoke the function SsmAutoDial to start an outgoing call in this state.

The driver will start the timer T1 when the channel goes into the OffHook state. If the application does not call the function SsmAutoDial before T1 overflows, the driver will reset the channel back to the idle state.

AutoDial

It is an internal state during an outgoing call, including the substates S_ISUP_WaitDialAnswer and S_ISUP_WaitSetCallerID.

The function call of SsmAutoDial or SsmAutoDialEx by the application will prompt the driver to send the IAM message to the remote PBX and transfer the channel state to S_ISUP_WaitDialAnswer. In the S_ISUP_WaitDialAnswer substate, if the remote PBX wants to receive the calling party information which is not contained in the IAM message, it will send the INR message to the local end. After the driver receives the INR message,

² if the Caller ID buffer is not empty during an outgoing call, the driver will put the calling party information into the INF message and send the INF message back to the remote PBX as well as keep the channel in the current state.

² if the Caller ID buffer is empty during an outgoing call and the configuration item AutoSendINF is set to 1, the driver will take the calling party information set by the configuration item CalloutCallerId or the function SsmSetTxCallerId as the parameter, automatically reply to the INF message and keep the channel in the current state;

² if the Caller ID buffer for the outgoing call within the driver is empty and the configuration item AutoSendINF is set to 0, the driver will transfer the channel state to S_ISUP_WaitSetCallerID and start the timer T3 at the same time. In the S_ISUP_WaitSetCallerID substate, if the application invokes the function SsmSetTxCallerId, the driver will put the preset calling party information into the INF message and then send the INF message back to the remote PBX. If the application does not call the function SsmSetTxCallerId before T3 overflows, the driver will take the set value of the configuration item CalloutCallerId as the parameter, automatically send the INF message to the remote end and transfer the channel state to S_ISUP_WaitDialAnswer.

WaitAnswer

The channel is waiting for the called party to pick up the phone. This state is only applicable to the outgoing call.

The called party should be able to hear ringing tones in such state, and if at the local end is the station channel that makes an outgoing call through the digital trunk channel it should send the ringback tone to the station channel.

Pending

‘Pending’ state. The function SsmGetPendingReason can help get the specific reason why the call becomes pending.

Ø If PendingReason is set to PEND_WaitBckStpMsg, it indicates the driver has completed the incoming call progress implementation and is waiting for the application to accept or refuse the incoming call. The application program can

² invoke the function SsmSetKB to accept or refuse the incoming call.

u If KB=1/6/7, the driver will send the ACM message to the remote PBX to accept the incoming call. If the application has invoked the function SsmSetIsupUPPara (with the parameter C_ISUP_ACM) to submit a self-built ACM message to the driver before the function call of SsmSetKB, this ACM message will be sent to the remote PBX; otherwise, the driver will use the ACM message which is automatically set up. After the ACM message is transmitted, the channel will transfer to the S_CALL_RINGING state;

u If KB=2/3/4/5/9, the driver will send the REL message to the remote PBX to refuse the incoming call. The reason value carried in the REL message is Called Subscriber Busy/Address Incomplete/Call Refused/No Answer/User Absent. The channel sets out to disconnect the call and goes into the Release state;

u If KB=8, the driver will send the INR message to the remote PBX and transfer the channel state back to RcvPhoNum.

² invoke in order the function SsmSetIsupUPPara (with the parameter C_ISUP_ACM) and the function SsmSendIsupMsg to accept the incoming call. Then the channel will go into the S_CALL_RINGING state.

² invoke the function SsmHangup or SsmHangupEx to refuse the coming call. The driver sets out to disconnect the call and transfers the channel state to Release. See description on relative functions for more information.

² invoke the function SsmPickup to accept the incoming call. The driver will send the CON message to the remote PBX and then transfer the channel state to Connected.

Note: if the driver receives the REL message from the remote PBX in this state, it will automatically send the RLC message and then transfer the channel state to Standby.

Ø No matter what causes the channel to go into the Pending state, the application can command the driver to send the REL message containing the number redirection information to the remote PBX and prompt the channel to transfer to the Release state via the function call of SsmSetIsupFlag (with the parameter ISUP_PhoNumREL).

Ø If PendingReason is set to:

² PEND_RemoteHangupOnTalking (the calling party is detected to first hang up the phone during the connected incoming call);

² PEND_CalleeHangupOnTalking (the called party is detected to first hang up the phone during the connected outgoing call);

² PEND_RemoteHangupOnRinging (the calling party cancels the incoming call when the local end is ringing);

the application program can call the function SsmHangup or SsmHangupEx to hang up the phone.

RcvPhoNum

It is an internal state during an incoming call progress, including the substates S_ISUP_Suspend and S_ISUP_WaitINF.

The driver judges the received called party number according to the preset number-receiving rule. If the number complies with the rule, the channel will transfer to the subsequent state. For more information about the number-receiving rule, refer to the section Number-receiving Rule for Incoming Call in this chapter.

Ø In the incoming call, the switch K1 controls the ‘Auto-answer of Incoming Call’ feature. When the channel receives the complete called party number and other relative information,

² if the ‘Auto-answer of Incoming Call’ feature is enabled, the driver will automatically send the ACM message to the remote PBX and transfer the channel state to Ringing. The configuration item DefaultBackwardCallInd is used to set the backward call indicator in the ACM message sent automatically by the driver while the function SsmSetKB is used to set the charge indicator contained in the backward call indicator field in the ACM message.

² if the ‘Auto-answer of Incoming Call’ feature is not enabled, the driver will set PendingReason to PEND_WaitBckStpMsg, transfer the channel state to Suspend, and let the application determine whether to accept this call or not.

The switch K1 can be set via the function SsmEnableAutoSendKB or the configuration item AutoSendACM, being switched off by default.

Ø Every time when the driver receives the SAM message from the remote PBX, it will save the message to its internal buffer and throw out the E_CHG_RxPhoNumBuf event to the application.

Ø If the called party number received by the channel does not conform to the number-receiving rule, the driver will automatically send the REL message (carrying the unallocated-number reason) and transfer the channel state to Release.

Ø Also the application can invoke the function SsmHangup/SsmHangupEx to refuse this call. In default, the driver will send the REL message with the reason value after that. You can use the configuration item DefaultHangupRELInd to set the reason value telling why the call fails in the REL message, or the parameter nType=ISUP_REL_DENY_SetToOther(=100) in the function SsmSetIsupFlag to change the reason value.

Ringing

‘Ringing’ state

The application program can

² invoke the function SsmPickup or SsmPickupANX to accept the call. The two configuration items DefaultCalledPickupMsg and DefaultBackwardCallInd are used respectively to select the type (ANM or CON) of the message to be sent by the driver to the remote PBX and to set the backward call indicator in the ACM/COM message.

² invoke the function SsmHangup or SsmHangupEx to refuse the call

If the driver receives the REL message (i.e. the RcvRLC event in the state machine above) from the remote PBX when the channel is in the Ringing state, it indicates the remote PBX cancels this call. At that time, the switch K2 which is set via the configuration item RingToPending can be used to control the channel state transition. If the configuration item RingToPending is set to 1, the driver will set PendingReason to PEND_RemoteHangupOnRinging and transfer the channel state to Pending for the further processing by the application program; otherwise, the driver will set out to disconnect this incoming call at once.

Connected

’Talking’ state. Both parties are connected and able to talk with each other.

When the channel state transfers to Connected, the driver will

² start the DTMF Detector if the configuration item AlwaysEnableRxDtmf is set to 0;

² start the Barge-in Detector if the configuration item AlwaysDetectBargeIn is set to 0;

² clear the Tone Detector and start it.

The application program can

² invoke any function related to voice processing.

² invoke the function SsmHangup or SsmHangupEx to terminate this call at any time.

If the driver receives the REL message (i.e. the RcvRLC event in the state machine above) from the remote PBX when the channel is in the Connected state, it indicates the remote party of the call has hung up the phone.

Paused

’Suspend’ state

Release

’Disconnection’ state

When the channel is in the Release state, the driver will wait for the remote PBX to send the RLC (Release Complete) message.

Each state identifier in the table above is declared in the file ShpA3Api.h as follows.

State Identifier | Declaration in ShpA3Api.h
 | Value | Macro
Standby | 0 | S_CALL_STANDBY
OffHook | 1 | S_CALL_PICKUPED
Ringing | 2 | S_CALL_RINGING
Connected | 3 | S_CALL_CONNECTED
Pending | 7 | S_CALL_PENDING
WaitAnswer | 9 | S_CALL_WAIT_REMOTE_PICKUP
Unusable | 11 | S_CALL_UNAVAILABLE
Locked | 12 | S_CALL_LOCKED
Release | 121 | S_ISUP_WaitRLC
Reseting | 122 | S_ISUP_WaitReset
BlockingRemote | 123 | S_ISUP_LocallyBlocked
BlockedByPBX | 124 | S_ISUP_RemotelyBlocked
Paused | 129 | S_ISUP_Suspend
RcvPhoNum | 120 | S_ISUP_WaitSAM
 | 126 | S_ISUP_WaitINF
AutoDial | 125 | S_ISUP_WaitDialAnswer
 | 127 | S_ISUP_WaitSetCallerID

In the above state machine, ChUsable is the driver’s internal component to judge the channel’s usability. It will output values as shown in the table below.

Output Value | Description
Unusable | The channel is unusable if the Error event keeps effective.
BlockedByPBX | The channel is blocked by the remote PBX.
BlockingRemote | The channel keeps blocking the remote PBX.
Standby | The Error event stays invalid.

Note: At this stage, the driver also performs the following operations.

· Clear the tone detector and automatically close it;

· Automatically terminate the WaitDtmf task if it has been started by the application;

· Automatically terminate the task of DTMF transmission if it has been started by the application;

· Automatically clear the buffer of the DTMF detector, and close the DTMF detector if the configuration item AlwaysEnableRxDtmf is set to 0;

· Automatically close the Barge-in detector if the configuration item AlwaysDetectBargeIn is set to 0;

· Automatically clear the Caller ID buffer if the configuration item AutoClearCallerIdBufOnHangup is set to 1.


1.16.4.6.3 ISUP Channel Serving as Tandem Exchange

Generally, the SHD Series boards based on ISUP protocol work as the terminating office. However, if necessary, you can configure the ISUP channel to serve as the tandem exchange following the way below.

Assume that the circuit number on PBX-A that corresponds to Channel m in the application is m and the ‘Auto-answer of Incoming Call’ feature is disabled for Channel m, the circuit number on PBX-B that Channel n corresponds to is n. The following figure illustrates how the ISUP channel works as the tandem exchange to establish a call.

In the figure above,

Blue Words describe the driver’s internal operation;

Sm, Sn respectively indicate the state of Channel m and that of Channel n;

XXXm, XXXn respectively represent the ISUP message transmitted between the application and PBX-A, and that between the application and PBX-B;

Yellow Words describe the application’s behavior.


1.16.4.6.4 SynCTI-provided ISUP State Machine Unused

In some case, the application is required to handle MSU messages in ISUP protocol by itself. Such feature can be enabled via the configuration item AutoHandleIsup. Upon reception of MSU messages from the remote end, the driver will deliver them to the application directly so that the ISUP state machine is not used. For more information, refer to the Advanced SS7 Programming section.


1.16.4.7 Advanced SS7 Programming


1.16.4.7.1 MTP3 Service

The application program is allowed to process any protocol at the 4th level in SS7 via the direct use of the MTP3 interface provided by the SynCTI driver. In case the following configuration items are set to 0:

² AutoHandleTup (for TUP)

² AutoHandleIsup (for ISUP)

² AutoHandleSccp (for SCCP)

every time when the driver receives a message from the SS7 server, it will save the message not to its internal state machine but to a buffer, and at the same time throw out the E_RCV_Ss7Msu event. When receiving E_RCV_Ss7Msu, the application program can invoke the function SsmGetSs7Msu to take out this message for subsequent processing. The function SsmSendSs7Msu can be used to send a message.

Every time when the route from the SS7 server to a DPC varies in state (usable or unusable), relative information will be sent to the SynCTI driver, which prompts the driver to send the E_CHG_Mtp3State event to the application. In an application system involving only one DPC, the function SsmGetMtp3State can be used to get information of the route to this DPC; in the system connecting with multiple DPCs, the function SsmGetMtp3StateEx can help acquire the usability of the route to the specified DPC. The function SsmGetMtp2Status is used to obtain the state of the specified 64Kbps signaling link.


1.16.4.7.2 Client Software Programming Interface on SS7 Server

The client software programming interface on the SS7 server enables those devices which are not compliant with the SS7 protocol to be capable of handling SS7 signaling messages in cooperation with the SS7 server based on the SHD series boards, via the connection by TCP/IP. The interface is provided in the form of dynamic link libraries, consisting of the TCP/IP Communications component and the SS7 Signaling Processing component, facilitating user-end development. For more information, refer to the manual Client Software Programming Interface on SS7 Server.


1.16.4.7.3 Virtual Circuit Programming Interface on SS7 Server

The virtual circuit is the circuit which does not occupy any voice resource in the SS7 circuit switching, generally used for the prepaid system.

The SynCTI driver can configure the virtual circuit that is not bound to some physical digital trunk by setting the parameter i in the configuration item Pcm[k]=i to -1, and is able to bind the virtual digital trunk and the destination signaling point code via the [ISUPRouter] section in the configuration file ss7server.ini in the SS7 server. Fore more information about the API functions related to the virtual circuit, refer to the document SynCTI Programmer’s Manual – Programming for Virtual Circuit on SS7 server. doc.


1.16.4.7.4 SCCP Programming Interface

The SynCTI driver provides the advanced SCCP programming interface. See the description in relative documents for details. If the application is required to support SCCP by itself, it needs to set the configuration item AutoHandleSccp to 0 and use the MTP3 service offered by the SynCTI driver. See the MTP3 Service section in this chapter for more information.


1.16.5 ISDN Programming


1.16.5.1 Basic Concepts


1.16.5.1.1 Network-side Mode and User-side Mode

Because the protocols for connection used at the two ends of a digital trunk may differ from each other, there are two distinguishing definitions ‘user-side’ and ‘network-side’ used in the ISDN protocol. The User Side indicates the user terminal, i.e. the end to connect with the ISDN PBX; the Network Side is the other end to connect with the ISDN user terminal. In this manual, we call the digital trunk working in the User-side mode as the user-side digital trunk, and that in the Network-side mode as the network-side digital trunk.


1.16.5.1.2 TEI Value

TEI, i.e. Terminal Equipment Identifier, is used to identify the service access point in the point-to-point data link connection. The subfield of TEI is allowed to stipulate 128 TEI values, thereby offering the range of 0~127, among which 0~63 are fixed TEI values (selected by the device), indicating the TEI used by L2 to receive/transmit the I or UI frame is unchangeable; 64~126 are dynamic TEI values, indicating the TEI used by L2 to receive/transmit the I or UI frame is changeable (selected by the network); 127 is only applicable to the broadcast link.

The configuration items UserTEIValue and NetTEIValue are used to set the TEI values respectively for the user side and the network side.


1.16.5.1.3 Representation of Channel Identification Information

What tells the information about the channel used in an ISDN call is named the channel identification information element. It is used to identify channels under the control of the signaling program and can be represented by the following 2 ways:

² Time Slot Diagram: The channel identification information element is represented by 32 Bit (4 bytes), corresponding to 32 time slots. If bit=1, it indicates this time slot is being used; if bit=0, it indicates this time slot is unused. In practice, usually only one bit is set to 1 with the rest all set to 0.

² Number: The channel identification information element is represented by 8 Bits (1 byte), the highest Bit7 with the fixed value of 1 and the other 7 bits (i.e. Bit6~Bit0) indicating the corresponding time slot numbers.

This element contains up to 34 octets, of which the 4th bit in the 3rd octet determines its representation way. The configuration items NetChIdentify and UserChIdentify are used to set the representation way respectively for the network side and the user side.


1.16.5.1.4 Terminating Office Mode vs. Tandem Exchange Mode

The telephone network is separated into two categories: Local Telephone Network and Long-distance Telephone Network. The local telephone network is the network covering the area with the same number, composed of the terminating office, the tandem exchange and the transmission links; the long-distance telephone network is the network covering the areas with different numbers in communication, composed of the long-distance exchange and the transmission links. At present, the telephone exchange is the core of the telephone network, using the digital SPC switching technology. That is, each call is encoded by the 64Kbit/s digital signal and occupies a time slot in the primary group, connects to different users via data switching between time slots under the control of signaling. The telephone exchange can be classified depending on the size of the service area into the first-level centre, the second-level centre, the third-level centre, the fourth-level centre and the fifth-level centre, i.e. C1, C2, C3, C4 and C5, among which C1, C2, C3, C4 are long-distance tandem exchanges while C5 is the terminating office. With the digitization of the telephone network, C1 and C2 are integrated into one level, i.e. DC1; C3 and C4 are integrated into one level, i.e. DC2. As a result, the China’s telephone network has evolved from the 5-level network to the 3-level network, forming a network connection between a number of first-level centres.

The ISDN state machine supplied by the SynCTI driver is allowed to work not only in the Terminating Office mode but also in the Tandem Exchange mode. It can be set via the configuration item UserIsReceivePhoNum (user-side) or NetIsReceivePhoNum (network-side). During the incoming call processing, if the driver works in the Terminating Office mode, it will receives the called party number and other information according to the preset number-receiving rule; if the driver works in the Tandem Exchange mode, it will accept any incoming number regardless of the number-receiving rule. For more information about the number-receiving rule, refer to the section Number-receiving Rule for Incoming Call in this chapter.


1.16.5.1.5 ISDN Number and ISDN Address

The ISDN number is different form the ISDN address according to ITU-T specifications. The ISDN number is the number in relation to the ISDN network and the ISDN numbering scheme. It contains enough information for the network to choose a correct route for the call. An ISDN address includes the ISDN number as well as the appended necessary and/or optional addressing information which is not for the ISDN network to select the call route but for users to allocate the call to appropriate terminals.


1.16.5.2 ISDN Channel State Machine

In the diagram above, the internal events automatically triggered by the driver itself are described as follows.

Event Name

Description

DataLinkConnected

This event is triggered when the data link level is successfully connected with the remote PBX. The driver will throw out the E_CHG_ISDNStatus event to the application in such case.

DataLinkDisconnected

This event is triggered when the data link level is disconnected from the remote PBX. The driver will throw out the E_CHG_ISDNStatus event to the application in such case.

RcvSetup

The driver receives the SETUP (Call Setup Request) message from the remote PBX.

The driver will decide whether to accept this call or not according to the current channel state:

² In the Standby state: to accept the call. The driver will save the called party number and other information in the SETUP message to its internal buffer and throw out the E_CHG_RxPhoNumBuf event to the application program. If the driver works in the Tandem Exchange mode, the number-receiving rule for incoming calls will be ignored. Therefore, any number can be accepted by the driver. In such case, the driver will directly transfer the channel state to Ringing. The switch K1 is used to control if the call is progressed in the Tandem Exchange mode or not. Its state can be set by the configuration item UserIsReceivePhoNum (user-side) or NetIsReceivePhoNum (network-side). For more information, refer to the section Terminating Office Mode vs. Tandem Exchange Mode in this chapter.

² In other states: to discard the SETUP message.

PhoNumOK

The driver receives all numbers (including both the calling party number and the called party number) according to the preset number-receiving rule.

RcvDisconnect

The driver receives the DISCONNECT message from the remote PBX.

When this event is triggered, if the channel stays in the state

² RcvPhoNum, WaitAnswer or Ringing: it indicates the remote PBX (the calling party) cancels this call during the incoming call establishement;

² Connect: for the incoming call, the reception of the DISCONNECT message in the Connect state indicates the remote PBX first hangs up the phone. The driver will send the RELEASE message to the remote PBX and transfer the channel state to Pending after setting PendingReason to PEND_ ISDN_CALLOVER;

² Dialing: it indicates the outgoing call fails. The specific reason why the call fails can be acquired via the function SsmGetAutoDialFailureReason.

RcvConnectAck

The driver receives the CONNECT ACK message from the remote PBX. If the local end receives the CONNECT ACK message after sending the CONNECT message to the remote PBX, it indicates the call has been connected.

RcvConnect

The driver receives the CONNECT message from the remote PBX. If the channel stays in the WaitAnswer state at that time, the driver will automatically reply to the remote PBX by sending the CONNECT ACK message.

RcvAlerting

The driver receives the ALERTING message from the remote PBX. At that time the called party has gone into the ringing state.

RcvCallProceeding

The driver receives the CALL PROCEEDING message from the remote PBX. At that time the called party has gone into the ringing state.

RcvSetupAck

The driver receives the SETUP ACK message from the remote PBX. The event has no effect on the state transition.

RcvRelease

The driver receives the RELEASE message from the remote PBX. It will automatically respond to the remote PBX by sending the RELEASE COMPLETE message and set out to disconnect the call.

RcvReleaseComplete

The driver receives the RELEASE COMPLETE message from the remote PBX. If the local end receives the RELEASE COMPLETE message after sending the RELEASE message to the remote PBX, it indicates the call has been thoroughly disconnected.

T300Out

The timer T300 overflows. T300 is set to 60sec, the time limit on the operation after finding an idle channel and performing the pickup behavior on it to ensure the full use of the channel. The time can be set via the configuration item UserDialTime (user-side) or NetDialTime (network-side).

T302Out

In an incoming call, when the driver receives the SETUP message from the remote PBX, it will check the called party number in the message according to the preset number-receiving rule. If the number is incomplete, the driver will transfer the channel state to S_ISDN_IN_RCVING_NO (a substate of RcvPhoNum) and start the timer T302. If T302 overflows, this call fails and the driver will automatically send the RELEASE message to the remote PBX and change the channel state to Standby.

T302 can be set via the configuration item UserT302 (user-side) or NetT302 (network-side).

T313Out

In an incoming call, when the channel goes into the Ringing state, if the application calls the function SsmPickup to pick up the phone, the driver will automatically send the CONNECT message to the remote PBX, transfer the channel state to WaitConnect, and start the timer T313 at the same time. If T313 overflows, this incoming call fails and the driver will send the DISCONNECT message to the remote PBX.

T313 can be set via the configuration item UserT313, only for user-side.

T303Out

In an outgoing call, when the local end sends out the SETUP message, the driver will start the timer T303. If the driver does not yet receive the ALERTING, CALL PROCEEDING, SETUP ACK or CONNECT message from the remote PBX before T303 overflows, it will send the SETUP message once again and restart T303. If T303 overflows, this outgoing call fails and the driver will send the RELE COMP message to the remote PBX and change the channel state to Pending.

T303 can be set via the configuration item UserT303 (user-side) or NetT303 (network-side).

T304Out

In an outgoing call, if the remote PBX can not obtain all necessary information (such as the called party number) from the SETUP message which has been sent by the local end, it will transmit the SETUP ACK message to the local end. Then the local end will wait for the application to append the called party number and start the timer T304 at the same time after receiving the SETUP ACK message. In this case, the application can invoke the function SsmAppendPhoNum to append the called party number. The driver will send the INFO message to the remote PBX and restart T304 when receiving the new number. If the driver does not yet receive the CALL PROCEEDING, ALERTING, CONNECT or DISCONNECT message from the remote PBX before T304 overflows, this outgoing call fails and the driver will send the DISCONNECT message to the remote PBX and transfer the channel state to Pending.

T304 can be set via the configuration item UserT304 (user-side) or NetT304 (network-side).

T310Out

In an outgoing call, after the local end sends out the SETUP message and receive the CALL PROCEEDING message from the remote PBX, the driver will start the timer T310. If the driver does not yet receive the ALERTING or CONNECT message from the remote PBX before T310 overflows, this outgoing call fails and the driver will send the DISCONNECT message to the remote PBX and transfer the channel state to Pending.

T310 can be set via the configuration item UserWaitAfterCallProceeding (user-side) or NetWaitAfterCallProceeding (network-side).

Error

This event is triggered when the driver detects one of the following situations.

² The synchronization signal through TS0 on the digital trunk where this channel stays gets lost (e.g. line disconnected, clock configuration error and so on).

² The driver receives error messages from the remote PBX.

² The data link level can not be connected with the remote PBX.

What the driver does:

² If the channel stays in Dialing or WaitAnswer state: the outgoing call fails. The driver will set the progress value of the AutoDial task to DIAL_FAILURE, the reason value to ATDL_PcmSyncLos, and throw out the E_PROC_AutoDial event to the application.

² If the channel stays in other states: the driver will transfer the channel state to Unusable.

Each state identifier in the above diagram is described in the following table.

State Identifier

Description

Unusable

‘Unusable’ state.

² As long as one of the two events DatalinkDisconnect, Error keeps valid, the channel gets unusable and outputs the ‘Unusable’ state.

² In other situations, the channel stays idle and outputs the ‘Standby’ state.

Standby

’Idle’ state

The channel should go into this state provided the ISDN data link level is properly connected to the remote PBX after the successful driver initialization. The application can invoke the function SsmAutoDial to start an outgoing call in this state.

The driver will automatically clear the Caller ID buffer when the channel state transfers to Standby at the end of the call, provided the configuration item AutoClearCallerIdBufOnHangup is set to 1.

OffHook

’Off-hook’ state

The driver will start the timer T300 when the channel goes into the OffHook state. If the application does not call the function SsmAutoDial before T300 overflows, the driver will reset the channel back to the idle state.

Locked

’Outgoing Call Locked’ state

When the application calls the function SsmSearchIdleCallOutCh, the driver will temporarily lock the channel specified by its return value and start the timer T300 at the same time. If the application does not call the function SsmPickup or SsmAutoDial before T300 overflows, the driver will reset the channel back to the idle state.

Dialing

It is an internal state during the outgoing call, including the substates S_ISDN_OUT_WATI_NET_RESPONSE and S_ISDN_OUT_PLS_APPEND_NO. After the application invokes the function SsmAutoDial, the driver will:

² send the SETUP message to the remote PBX;

² start the timer T303 at the same time;

² transfer the channel state to S_ISDN_OUT_WATI_NET_RESPONSE, waiting for the responding signals from the remote PBX;

² throw out the E_PROC_AutoDial event to the application.

The reception of the SETUP ACK message from the remote PBX in the S_ISDN_OUT_WATI_NET_RESPONSE substate means the remote party wants the local end to provide more information about numbers. In such case, the driver will transfer the channel state to S_ISDN_OUT_PLS_APPEND_NO and start the timer T304 at the same time.

WaitAnswer

The channel is waiting for the called party to pick up the phone. The driver will start the timer T310 when the channel goes into this state.

The function SsmGetFlag (with the parameter F_ISDNNet_WaitRemotePickup) can be used to acquire the specific reason why the channel goes into this state.

WaitConnect

The channel is waiting for the remote PBX to respond by sending back the CONNECT ACK message. The driver will start the timer T313 when the channel goes into this state.

Connect

’Talking’ state. Both parties are connected and able to talk with each other.

When the channel state transfers to Connected, the driver will

² start the DTMF Detector if the configuration item AlwaysEnableRxDtmf is set to 0;

² start the Barge-in Detector if the configuration item AlwaysDetectBargeIn is set to 0;

² clear the Tone Detector and start it.

The driver’s internally triggered events:

² RcvDisconnect: indicates the remote party first hangs up the call. This event is triggered when the driver sets the hangup reason to ISDN_CALLOVER and transfers the channel state to ‘Pending’;

² Error: The channel will go into the ‘Unusable’ state if it receives one of the Error events in a call.

Ringing

’Ringing’ state

The channel has received all called party numbers and other relative information.

Pending

’Pending’ state. The channel is waiting for further commands from the application in this state.

Pending1

’Pending’ state, which can be ignored by the application. Without further commands, the driver program will automatically jump to the ‘Standby’ state.

RcvPhoNum

It is an internal state during the incoming call, including the substates S_ISDN_IN_CHK_CALL_IN and S_ISDN_IN_RCVING_NO.

If the SETUP message received from the remote PBX contains all necessary information for the local end, the driver will trigger the internal event PhoNumOK; otherwise, it will send the SETUP ACK message to the remote PBX and transfer the channel state to S_ISDN_IN_CHK_CALL_IN, waiting for further number information from the remote PBX. If receiving the INFO message from the remote PBX in the S_ISDN_IN_CHK_CALL_IN substate, the driver will transfer the channel state to S_ISDN_IN_RCVING_NO.

If the received called party number does not comply with the number-receiving rule, the driver will automatically send the RELEASE message to the remote PBX and transfer the channel state to S_CALL_STANDBY.

The configuration items DefaultRcvPhoNumLen, DefaultRcvCallerID and RcvPhoNumCfgLen or DefaultRcvPhoNumLen, MaxPhoNumRule and Rule can be used together to set the number-receiving rule. For more information about the number-receiving rule, refer to the section Number-receiving Rule for Incoming Call in this chapter.

Which state the channel will go into after completing the number reception depends on the switch K2. It is K2 that determines the ALERTING message is sent by the driver itself or the application for responding. The state of K2 can be set via the configuration item UserSideAutoSendAck (user-side)/NetSideAutoSendAck (network side) or the function SsmEnableAutoSendKB. If the setting of ‘driver’s automatic response’ is chosen, the driver will transfer the channel state to SsmEnableAutoSendKB after sending the ALERTING message to the remote PBX; otherwise, it will start a timer whose time length is specified via the configuration item UserSideDefaultAckTimer (user-side) or NetSideDefaultAckTimer (network-side), set PendingReason to PEND_WaitBckStpMsg and then transfer the channel state to Pending, asking the application to decide the acceptance of this call. If the timer overflows, the driver will automatically send the reply message to the remote PBX according to settings of the configuration item UserSideDefaultAck (user-side) or NetSideDefaultAck (network-side).

Each state identifier in the table above is declared in the file ShpA3Api.h as follows.

State Identifier | Value in ShpA3Api.h | Macro Definition in ShpA3Api.h
Unusable | 11 | S_CALL_UNAVAILABLE
Standby | 0 | S_CALL_STANDBY
OffHook | 1 | S_CALL_PICKUPED
Dialing | 81 | S_ISDN_OUT_WAIT_NET_RESPONSE
 | 82 | S_ISDN_OUT_PLS_APPEND_NO
WaitAnswer | 9 | S_CALL_WAIT_REMOTE_PICKUP
Connect | 3 | S_CALL_TALKING
WaitConnect | 85 | S_ISDN_IN_WAIT_TALK
Ringing | 2 | S_CALL_RINGING
Pending | 7 | S_CALL_PENDING
Locked | 12 | S_CALL_LOCKED
RcvPhoNum | 83 | S_ISDN_IN_CHK_CALL_IN
 | 84 | S_ISDN_IN_RCVING_NO

In the above state machine, ChUsable is the driver’s internal component to judge the channel’s usability. It will output values as shown in the table below.

Output Value | Description
Unusable | The channel is unusable if one of the events Error, DataLinkDisconnect, Circuit Reset keeps valid.
Standby | The channel goes into the idle state provided the Error event becomes invalid, the DataLinkConnect event keeps valid and the circuit restart is successful.

Note: At this stage, the driver also performs the following operations.

· Clear the tone detector and automatically close it;

· Automatically terminate the WaitDtmf task if it has been started by the application;

· Automatically terminate the task of DTMF transmission if it has been started by the application;

· Automatically clear the buffer of the DTMF detector, and close the DTMF detector if the configuration item AlwaysEnableRxDtmf is set to 0;

· Automatically close the Barge-in detector if the configuration item AlwaysDetectBargeIn is set to 0;

· Automatically clear the Caller ID buffer if the configuration item AutoClearCallerIdBufOnHangup is set to 1.

The output events of the state machine are described in the following table.

Event Name | Description
E_CHG_ChState | The driver sends out this event to the application when the channel state changes.
E_PROC_AutoDial | The driver throws out this event to the application when there is any progress in the AutoDial task which is started by the function call of SsmAutoDial with the application.
E_CHG_RxPhoNumBuf | Every time when the driver receives the called party information from the remote PBX in an incoming call, it will throw out this event to the application.
E_CHG_ISDNStatus | This event is triggered and sent to the application when the driver receives the ‘ISDN data link level usable’ message.

Note: Event declarations can be found in the file ShpA3Api.h.


1.16.5.3 ISDN Configuration

The configuration items concerning ISDN calls are listed in the table below.

Configuration Section | Configuration Item |
[BoardId=x] | PcmNumber | set the total number of on-board digital trunks as well as the signaling type, the clock operating mode and the line type for each digital trunk.
 | PcmSSx
 | PcmClockMode
 | PcmLinkType
[PcmInfo] | TotalPcm | set the total number of all digital trunks involved in the PC and build the mapping relationship between the logical number and the physical number of each digital trunk.
 | Pcm
[ISDN] | AutoHandleIsdn | sets whether to use the call state machine supplied by the driver.
 | UseISDNMode | sets the ISDN mode: User-side mode or Network-side mode.
 | TotalUserLinker | set the total number of all digital trunks working in the ISDN user-side mode involved in the PC and build the mapping relationship between the logical number and the physical number of each digital trunk.
 | UserPcmLink
 | UserTEIValue | set the main parameters for the ISDN user side.
 | UserRestarTime
 | UserEstablishTime
 | UserT302
 | UserCrcMode
 | UserStatusReason
 | UserDialTime | Outgoing Call in ISDN User-side Mode: set relative parameters.
 | UserWaitAfterCallProceeding
 | UserTxCallingPartyNum
 | NetTxCallingPartyNum
 | UserChIdentify | Outgoing Call in ISDN User-side Mode: customize the SETUP message to be sent to the remote PBX.
 | UserCalledNoSet
 | UserCallingNoSet
 | UserNumIsFull
 | UserChPreference
 | UserHighLayerCompatible
 | UserLowLayerCompatible
 | CalloutCallerId
 | UserSideAutoSendAck | Incoming Call in ISDN User-side Mode: set relative parameters.
 | UserSideDefaultAckTimer
 | UserIsReceivePhoNum
 | UserVoiceFormat | sets the hardware-based CODEC in the ISDN user-side mode.
 | TotalNetLinker | set the total number of all digital trunks working in the ISDN network-side mode involved in the PC and build the mapping relationship between the logical number and the physical number of each digital trunk.
 | NetPcmLink
 | NetTEIValue | set the main parameters for the ISDN network side.
 | NetRestarTime
 | NetEstablishTime
 | NetT302
 | NetCrcMode
 | NetStatusReason
 | NetDialTime | Outgoing Call in ISDN Network-side Mode: set relative parameters.
 | NetWaitAfterCallProceeding
 | NetChIdentify | Outgoing Call in ISDN Network-side Mode: customize the SETUP message to be sent to the remote PBX.
 | NetCalledNoSet
 | NetCallingNoSet
 | NetNumIsFull
 | NetChPreference
 | NetHighLayerCompatible
 | NetLowLayerCompatible
 | CalloutCallerId
 | NetSideAutoSendAck | Incoming Call in ISDN Network-side Mode: set relative parameters.
 | NetSideDefaultAckTimer
 | NetIsReceivePhoNum
 | DefaultRcvCallerID
 | NetVoiceFormat | sets the hardware-based CODEC in the ISDN Network-side mode.
 | DefaultRcvPhoNumLen | Incoming Call in ISDN User-side and Network-side Modes: set the number-receiving rule.
 | MaxPhoNumRule
 | Rule
 | UserStatusReason NetStatusReason | Advanced items for the ISDN user side and network side.
[DebugView] | IsdnLogEnable | set the log output in the ISDN user side and network side.
 | DecodeIsdnMsg
 | IsdnDebugLog
 | LogCreatePeriod
 | LogMaxKeep
 | LogMaxPeriod
 | LogFilePath

Note: Those written in the XXXX font are essentially configured items while those in XXXX are optionally configured ones.


1.16.5.4 Advanced ISDN Programming Interface

The SynCTI driver also provides the advanced programming interface to output the original messages at the HDLC level. The ISDN messages are processed by the application program itself. See the table below for the configuration items and functions related to the advanced ISDN programming interface.

 | Name | Description
Configuration Item | AutoHandleIsdn | sets whether to use the advanced ISDN programming interface or not
Function | SsmSendIsdnMSU | sends a message
 | SsmCheckIsdnMSU | queries if there are some messages available.
 | SsmGetIsdnMSU | takes out an ISDN message.


1.16.6 SS1 Programming


1.16.6.1 Choice of Signaling Protocols

SynCTI supports SS1 and the Line side protocol, which can be set via the configuration item ProtocolType . To configure the SS1 protocol, you can use the configuration item mfcr2_Protocol to select countries.


1.16.6.2 Setting Call Progressing Parameters

The configuration item TxCas_CD is used to set the value of the C/D code element in the ABCD signaling code sent by the local end to the remote end. The configuration item RxCASFilterTime is used to set the minimum duration of the ABCD signaling send out by the remote PBX so as to eliminate the signal dithering on the line, appropriate for the E1/T1 line of low quality.

The minimum duration of the R2 signal can be set via the configuration item RxR2FilterTime or the function SsmSetFlag (with the parameter F_RXR2FILTERTIME).

When the application program exits, the configuration item IsBlockSS1In is used to decide whether to send the blocking command to the remote PBX, asking it not to start any new call towards the local end.


1.16.6.3 Setting Operation Mode for Channels in State Machine

The configuration item EnableAutoCall helps decide if to use the call state machine provided by the SynCTI driver; the function SsmSetAutoCallDirection or the configuration item AutoCallInTimeSlot is used to set the call direction for a channel. For example, a channel can be set to process incoming calls only or outgoing calls only as required.


1.16.6.4 China SS1 State Machine


1.16.6.4.1 Number Hold-up Feature

The ‘Called Number Hold-up’ feature is often used by some key sectors for the purpose of eliminating the effect of the calling party’s misdialing on the application system. For example, a 110 alarm system set up on the Synway board will process the call only if the dialed number is ‘110’. That is, it will reject the call in detection of any other number, such as 1101.

The ‘Called Number Hold-up’ feature as well as the way it works is controlled by the configuration item PhoNumHoldup or the function SsmSetFlag (with the parameter F_RCVPHONUMHOLDUP). Relative parameters can be set via the configuration items A1ToA3pWaitTime and A3pTime . For example, you can configure the 110 alarm system to hold up the called number in the form of 110x as follows.

PhoNumHoldup=1

A1ToA3pWaitTime=1000

A3pTime=150


1.16.6.4.2 Connection to Dialogic SS1 Channel

While connecting the SS1 channel on the Synway board with the Dialogic SS1 channel to establish a call, you need to set the configuration item ToRingingDelayTime if the Synway board is required to serve as the incoming end.


1.16.6.4.3 China SS1 State Machine

In the diagram above, the internal events automatically triggered by the driver itself are described as follows.

Event Name | Description
RemoteCancel | The remote PBX cancels the call.
SyncLos | The synchronization signal through TS0 on the digital trunk gets lost.
SyncOK | Detects the synchronization signal through TS0 on the digital trunk.
Setup | Receives the incoming call request from the remote PBX.
T1Out | The timer T1 overflows. T1 is started when the channel state transfers to ‘Ringing’, with the set value of 75sec.
T2Out | The timer T2 overflows. The SS1 channel is required to wait for the reply signal from the remote PBX in an incoming call. T2 is used to set the maximum waiting time. The T2 overflow indicates this interactive process fails. T2 can be set via the configuration item MaxWaitMfcTime.
T3Out | The timer T3 overflows. In an incoming call, after the local end receives the complete called party number, the SS1 channel will send the A3 signal to the remote PBX and start T3 at the same time, waiting for the KD signal. If T3 overflows before the remote PBX sends out the KD signal, the incoming call progress fails. T3 can be set via the configuration item MaxWaitKDTime.
T4Out | The timer T4 overflows. In an incoming call, after the local end receives the complete called party number, the SS1 channel will go into the ‘Pending’ state and start T4 at the same time provided the configuration item is set to 0, which indicates the application wants to decide by itself whether to respond to this call. If T4 overflows before the application invokes the function SsmSetKB to reply, the driver will refuse this call. T4 can be set via the configuration item MaxWaitSetKBTime.
T5Out | The timer T5 overflows. After the application program calls the function SsmAutoDial to start an outgoing call, the driver will send the use request signal to the remote PBX and wait for the acknowledge signal from it. If T5 overflows before the reception of the acknowledge signal from the remote PBX, this call fails. T5 can be set via the configuration item MaxWaitOccupyAckTime.
T6Out | The timer T6 overflows. After the application invokes the function SsmAutoDial to start an outgoing call, the channel will start T6 provided the called party is idle. If T6 overflows before the called party picks up the phone, this outgoing call fails. T6 can be set via the configuration item MaxWaitAutoDialAnswerTime.
RcvA4 | Receives the A4 signal (key congestion, the encounter with an unallocated number before the call reaches the called party) from the remote PBX in the outgoing call progress, indicating this call fails.
RcvA5 | Receives the A5 signal (unallocated-number signal) in the outgoing call progress, indicating this call fails.
RcvKB4 | Receives the KB signal of 4 (user’s busy or key congestion) from the remote PBX in the outgoing call progress, indicating this call fails.
RcvKB5 | Receives the KB signal of 5 (the called party number unallocated) from the remote PBX in the outgoing call progress, indicating this call fails.
Accepted | The remote PBX sends the KB signal of 1 or 6 to the local end after receiving the complete called party number in the outgoing call progress, indicating the called party is in the idle state.
Answered | The called party accepts the call in the outgoing call progress.
ReleaseOK | Finishes the disconnection from the remote PBX.

Each state identifier in the above diagram is described in the following table.

State Identifier

Description

Standby

‘Idle’ state

The channel should go into this state provided it is normally reset after the successful driver initialization. The application can invoke the function SsmAutoDial to start an outgoing call in this state.

The driver will automatically clear the Caller ID buffer when the channel state transfers to Idle at the end of the call, provided the configuration item AutoClearCallerIdBufOnHangup is set to 1

OffHook

‘Off-hook’ state

If the SyncLos event is triggered in this state, the driver will

² set the progress value of the AutoDial task to DIAL_FAILURE and the failure reason to ATDL_PcmSyncLos, and throw out the E_PROC_AutoDial event to the application;

² set the pending reason to PEND_PcmSyncLos.

Ringing

The local end is ringing. The application program can

² invoke the function SsmGetCallerId to acquire the calling party information.

² call the function SsmPickup to accept the call or the function SsmHangup to refuse the call

Connected

Both parties are connected and able to talk with each other. When the channel state transfers to Talking, the driver will

² start the DTMF Detector;

² start the Barge-in Detector;

² clear the Tone Detector and start it.

How the driver responds to the following events:

Ø The RemoteCancel Event:

indicates the remote end first hangs up the phone in the call. The driver will set the pending reason to PEND_RemoteHangupOnTalking and then transfer the channel state to Pending;

Ø The SyncLos Event:

² The driver will set the progress value of the AutoDial task to DIAL_FAILURE and the failure reason to ATDL_PcmSyncLos, and throw out the E_PROC_AutoDial event to the application;

² set the pending reason to PEND_PcmSyncLos.

Pending

Waiting for further commands from the application.

How the driver responds to the following events:

Ø The T4Out Event:

The driver will automatically set the KB signal to 4 (key congestion) and resume the call progress.

Ø The application invokes the function SsmSetKB:

The driver will set the pending reason to PEND_WaitBckStpMsg and resume the call progress for the channel.

Ø The SyncLos Event:

² The driver will set the progress value of the AutoDial task to DIAL_FAILURE and the failure reason to ATDL_PcmSyncLos, and throw out the E_PROC_AutoDial event to the application;

² set the pending reason to PEND_PcmSyncLos.

Ø The application invokes the function SsmHangup:

If the pending reason is set to PEND_PcmSyncLos, the channel state will transfer to ‘Unusable’; otherwise, the channel will go into the ‘Release’ state.

WaitAnswer

The channel is waiting for the called party to pick up the phone. The called party should be able to hear ringing tones in such state, and if at the local end is the station channel that makes an outgoing call through the digital trunk channel, it should send the ringback tone to the station channel.

How the driver responds to the following events:

Ø The T6Out Event:

² The driver will set the progress value of the AutoDial task to DIAL_NOANSWER and the failure reason to ATDL_WaitRemotePickupTimeout, and throw out the E_PROC_AutoDial event to the application;

² set the pending reason to SS1OUT_NOANSWER.

Ø The SyncLos Event:

² The driver will set the progress value of the AutoDial task to DIAL_FAILURE and the failure reason to ATDL_PcmSyncLos, and throw out the E_PROC_AutoDial event to the application;

² set the pending reason to PEND_PcmSyncLos.

Ø The RemoteCancel Event:

² The driver will set the progress value of the AutoDial task to DIAL_FAILURE and the failure reason to ATDL_SS1RcvCAS_HANGUP, and throw out the E_PROC_AutoDial event to the application;

² set the pending reason to SS1OUT_DIALING_BWD_HANGUP.

Unusable

The channel is unusable.

Locked

’Outgoing Call Locked’ state

Release

‘Disconnection’ state

RcvPhoNum

It is an internal state during the incoming call progress implementation, including several substates. The driver judges the received called party number according to the preset number-receiving rule. If the number complies with the rule, the channel will transfer to the subsequent state. For more information about the number-receiving rule, refer to the section Number-receiving Rule for Incoming Call in this chapter.

Ø In an incoming call, when the channel receives the complete called party number and other necessary information, it is required to send the KB signal to the remote PBX.

² If the ‘Auto-answer of Incoming Call’ feature is enabled, the driver will send the value of the configuration item MfcKB as the KB signal to the remote PBX and transfer the channel state to Ringing;

² If the ‘Auto-answer of Incoming Call’ feature is not enabled, the driver will set PendingReason to PEND_WaitBckStpMsg, transfer the channel state to Pending, and let the application decide whether to accept this call or not.

The ‘Auto-answer of Incoming Call’ feature can be set via the function SsmEnableAutoSendKB or the configuration item AutoSendKB, with the default value of ‘Enabled’.

Ø Every time when the driver receives a calling party number, it will throw out the E_CHG_RxPhoNumBuf event.

AutoDial

It is an internal state during the outgoing call progress implementation, including several substates.

The parameters which can be set by the application for the outgoing call include:

Ø The KA signal (Calling Party’s Category) that should be provided by the local end for the remote PBX, configurable via the function SsmSetKA or the configuration item MfcKA;

Ø The KD signal (Originating Service Type) that should be provided by the local end for the remote PBX, configurable via the function SsmSetKD or the configuration item MfcKD;

Ø If the remote PBX asks the local end for the calling party number, the driver will automatically send the local end number saved in the buffer to the remote PBX after receiving the A6 signal and sending the KA signal. The local end number can be set via the function SsmSetTxCallerId or the configuration item TxCallerId.

In case the outgoing call fails, the driver will process as follows according to the internal event type.

Ø The SyncLos Event:

² The driver will set the progress value of the AutoDial task to DIAL_FAILURE and the failure reason to ATDL_PcmSyncLos, and throw out the E_PROC_AutoDial event to the application;

² set the pending reason to PEND_PcmSyncLos.

Ø The T5Out Event:

² The driver will set the progress value of the AutoDial task to DIAL_NO_DIALTONE and the failure reason to ATDL_SS1WaitOccupyAckTimeout, and throw out the E_PROC_AutoDial event to the application;

² set the pending reason to SS1OUT_NOBWDACK.

Ø The RemoteCancel Event:

² The driver will set the progress value of the AutoDial task to DIAL_FAILURE and the failure reason to ATDL_SS1RcvCAS_HANGUP, and throw out the E_PROC_AutoDial event to the application;

² set the pending reason to SS1OUT_DIALING_BWD_HANGUP.

Ø The RcvA4 Event:

² The driver will set the progress value of the AutoDial task to DIAL_BUSYTONE and the failure reason to ATDL_SS1RcvA4, and throw out the E_PROC_AutoDial event to the application;

² set the pending reason to SS1OUT_BWD_A4.

Ø The RcvKB4 Event:

² The driver will set the progress value of the AutoDial task to DIAL_BUSYTONE and the failure reason to ATDL_SS1RcvKB4, and throw out the E_PROC_AutoDial event to the application;

² set the pending reason to SS1OUT_BWD_KB4.

Ø The RcvA5 Event:

² The driver will set the progress value of the AutoDial task to DIAL_INVALID_PHONUM and the failure reason to ATDL_SS1RcvA5, and throw out the E_PROC_AutoDial event to the application;

² set the pending reason to SS1OUT_BWD_A5.

Ø The RcvKB5 Event:

² The driver will set the progress value of the AutoDial task to DIAL_INVALID_PHONUM and the failure reason to ATDL_SS1RcvKB5, and throw out the E_PROC_AutoDial event to the application;

² set the pending reason to SS1OUT_BWD_KB5.

Ø The T2Out Event:

The driver will set the progress value of the AutoDial task to DIAL_FAILURE and the failure reason to one of the following values:

u ATDL_SS1WaitAxTimeout

u ATDL_SS1WaitAxStopTimeout

u ATDL_SS1WaitAxTimeoutOnTxCallerId

u ATDL_SS1WaitAxStopTimeoutOnTxCallerId

u ATDL_SS1WaitKBTimeout

u ATDL_SS1WaitKBStopTimeout

respectively set the corresponding pending reason to:

u SS1OUT_TIMEOUT_BWD_A

u SS1OUT_TIMEOUT_BWD_A_STO

u SS1OUT_TIMEOUT_CALLERID_BWD_A1

u SS1OUT_TIMEOUT_CALLERID_BWD_A1_STOP

u SS1OUT_TIMEOUT_BWD_KB

u SS1OUT_TIMEOUT_BWD_KB_STOP；

and throw out the E_PROC_AutoDial event to the application;

Each state identifier and its corresponding value are listed in the table below.

State Identifier | Value | Corresponding Macro Definition in ShpA3Api.h
Standby | 0 | S_CALL_STANDBY
OffHook | 1 | S_CALL_PICKUPED
Ringing | 2 | S_CALL_RINGING
Connected | 3 | S_CALL_TALKING
Pending | 7 | S_CALL_PENDING
WaitAnswer | 9 | S_CALL_WAIT_REMOTE_PICKUP
Unusable | 11 | S_CALL_UNAVAILABLE
Locked | 12 | S_CALL_LOCKED
Release | 36 | S_CALL_SS1WaitIdleCAS
RcvPhoNum | － | S_CALL_Ss1InWaitPhoNum S_CALL_Ss1InWaitFwdStop S_CALL_Ss1InWaitCallerID S_CALL_Ss1InWaitKD S_CALL_Ss1InWaitKDStop S_CALL_SS1WaitIdleCAS S_CALL_SS1PhoNumHoldup S_CALL_Ss1InWaitStopSendA3p
AutoDial | － | S_CALL_Ss1OutWaitBwdAck S_CALL_Ss1OutTxPhoNum S_CALL_Ss1OutWaitAppendPhoNum S_CALL_Ss1OutTxCallerID S_CALL_Ss1OutWaitKB S_CALL_Ss1OutDetectA3p

The output events of the state machine are shown in the table below.

Event Name | Description
E_CHG_ChState | When the channel state changes, the driver will throw out this event to the application.
E_CHG_RxPhoNumBuf | Every time when the driver receives the called party information from the remote PBX, it will throw out this event to the application.
E_RCV_R2 | When the application invokes the function SsmGetR2 to acquire the R2 message, the driver will throw out this event to the application if it receives a new R2 signal value from the remote end.
E_RCV_CAS | When the application program calls the function SsmGetCAS to acquire the current value of the ABCD signaling transmitted on the specified channel, the driver will throw out this event to the application if it receives the current CAS value.
E_CHG_CIDExBuf | The driver throws out this event when it detects the Extended Caller ID Buffer varies. The application can call the function SsmGetCallerIdEx to obtain the content in the buffer after receiving this event.


1.16.6.4.4 Debugging Information Output during Outgoing Call

The configuration item MfcR2ToRxCallerIdBuf is used to control whether to save the R2 signal sent by the remote PBX during the call into the Extended Caller ID Buffer to facilitate the observation on the entire call process. And the function SsmGetCallerIdEx is used to take out strings form this buffer.

The configuration item Ss1LogEnable helps control whether to output the received/sent ABCD signaling codes and R2 signals to the log file Ss1Output.log.


1.16.6.5 Line Side State Machine

In the diagram above, the internal events automatically triggered by the driver itself are described as follows.

Event Name | Description
SyncLos | The synchronization signal through TS0 on the digital trunk gets lost.
SyncOK | Detects the synchronization signal through TS0 on the digital trunk.
ABCDè00xx | The ABCD signaling code of the remote PBX changes to 00xx.
ABCDè01xx | The ABCD signaling code of the remote PBX changes to 01xx.
ABCDè10xx | The ABCD signaling code of the remote PBX changes to 10xx.
ResetRemote | The driver has reset the circuit for the remote PBX, i.e. has sent the ABCD signaling code indicating the idle state to the remote PBX. The specific ABCD signaling code that indicates the idle state is determined by the configuration item Ss1SendIdleState.
T1Out | The timer T1 overflows. T1 is started when the channel state transfers to ‘Off-hook’, and can be set via the configuration item LSWaitPickup.

Each state identifier in the above diagram is described in the following table.

State Identifier | Description
Standby | ‘Idle’ state The channel should go into this state provided it is normally reset after the successful driver initialization. If the application invokes the function SsmPickup in this state, the driver will send ABCD=11xx to the remote PBX.
OffHook | ’Off-hook’ state The application can send the called party number and other information to the remote PBX. How to send such information to the remote PBX depends on the PBX model. Query PBX manufacturers for details. T1 is started when the channel goes into the ‘Off-hook’ state.
Ringing | The local end is ringing. In this state, the application program can invoke the function SsmPickup to accept the call or the function SsmHangup to refuse the call.
Connected | ’Talking’ state. Both parties are connected and able to talk with each other. The driver will automatically start the DTMF detector when the channel state transfers to ‘Connected’.
Suspend | ’Pending’ state. Note that the driver won’t set the pending reason. Hence there is no sense for the application to invoke the function SsmGetPendingReason.
Unusable | The channel is unusable.
Reseting | The circuit is being reset.

Each state identifier and its corresponding value are listed in the table below.

State Identifier | Value | Corresponding Macro Definition in ShpA3Api.h
Standby | 0 | S_CALL_STANDBY
OffHook | 1 | S_CALL_PICKUPED
Ringing | 2 | S_CALL_RINGING
Connected | 3 | S_CALL_TALKING
Suspend | 7 | S_CALL_PENDING
Unusable | 11 | S_CALL_UNAVAILABLE
Reseting | 36 | S_CALL_SS1WaitIdleCAS

The output events of the state machine are shown in the table below.

Event Name | Description
E_CHG_ChState | When the channel state transfers, the driver will throw out this event to the application.


1.16.6.6 Advanced SS1 Programming Interface

The state machine provided by the SynCTI driver is enough for most application instances. If the application likes to perform the entire call process by itself, the low-level API functions can be used. The driver-provided state machine can be disabled via the configuration item EnableAutoCall or the function SsmSetAutoCallDirection after the system start-up. The driver can enable the mutual control between the SS1 stack and MFC by transmitting/receiving CAS and R2 after it disables the SS1 state machine.

The events related to the SS1 progress control include:

l E_RCV_CAS

l E_RCV_R2

The advanced programming interface functions related to the China SS1 progress control contain:

l SsmSendCAS

l SsmGetSendingCAS

l SsmGetCAS

l SsmSetRxR2Mode

l SsmGetR2

l SsmSendR2

l SsmSendR2Ex

l SsmStopSendR2

l SsmGetSendingR2

l SsmEnableRxDtmf

Note:

l If the application program wants to receive DTMF digits after using the low-level progress control functions to finish the signaling progress, it must call the function SsmEnableRxDtmf to start the DTMF receiver and should call this function again to close the DTMF receiver at the end of the call.

l If the application is required to have the SS7 signaling cover for SS1 in a smooth way, it is not the functions in this section but the auto call progress functions provided by the system that should be used to control the call progress.


1.16.6.7 SS1 Configuration

Below are the relative configuration items in the use of SS1.

Configuration Section | Configuration Item |
[BoardId=x] | PcmNumber | set the total number of on-board digital trunks as well as the signaling type, the clock operating mode and the line type for each digital trunk.
 | PcmSSx
 | PcmClockMode
 | PcmLinkType
 | EnableAutoCall | auto SS1 progress control
 | AutoCallInTimeSlot | sets the input and output direction of the SS1 channel to the digital trunk
[PcmInfo] | TotalPcm | set the total number of all digital trunks involved in the PC and build the mapping relationship between the logical number and the physical number of each digital trunk.
 | Pcm
[SS1Config] | TxCas_CD | set the parameters for SS1 CAS and R2 progress.
 | RxCASFilterTime
 | MaxWaitMfcTime
 | IsBlockSS1In
 | tonesgroupA
 | tonesgroupB
 | tonesendofinfo
 | tonesanswer
 | tonesrepeatrequest
 | PcmSyncMask
 | ProtocolType | select the Lineside protocol type and set conditions for the channel state transition.
 | LSWaitPickup
 | Ss1SendIdleState
 | mfcr2_Protocol | selects the country for the MFC-R2 protocol and sets the corresponding parameter.
 | MaxWaitAutoDialAnswerTime | SS1 Outgoing Call: set relative parameters
 | MaxWaitOccupyAckTime
 | MaxWaitKBTime
 | RepeatPhoNumOn1stR2bwdIsA5
 | MfcKD | SS1 Incoming Call: set relative parameters
 | MfcKA
 | TxCallerId
 | MaxWaitSetKBTime
 | MaxWaitKDTime
 | ToRingingDelayTime
 | A1ToA3pWaitTime
 | MfcKB
 | AutoSendKB
 | PhoNumHoldup
 | A3pTime
 | DefaultRcvPhoNumLen
 | DefaultRcvCallerID
 | MaxPhoNumRule
 | Rule
 | MfcR2ToRxCallerIdBuf | set the log output for SS1 CAS and R2.
 | IsBlockSS1In
[DebugView] | Ss1LogEnable | set the log output for SS1 CAS and R2.
 | Ss1LogCreateMode
 | LogCreatePeriod
 | LogMaxKeep
 | LogMaxPeriod
 | LogFilePath

Note: Those written in the XXXX font are essentially configured items while those in XXXX are optionally configured ones.


1.16.7 Connection to Channel Bank

All SHD Series boards can connect directly to the channel bank to set up the large-capacity station system. After they are connected to the channel bank, the channel on them will be set to the station channel which has all features owned by the station channel on the SHT Series boards.

The configuration item UsageMode helps decide whether the SHD Series boards are used to start a call or connect to the channel bank.

The configuration item CBProtocolType is used to set the signaling protocol used in connecting the board to the channel bank.

The configuration item CBChannelType is used to set the channel type after the board connects to the channel bank.

After the SHD Series boards are connected to the channel bank, the outward features of the channel on them are identical to those of the corresponding channel on the SHT Series boards. Therefore, both the SHD and SHT channels in this case have the same configuration items and are configured in the same way. See description on the SHT boards for details.


1.17 SHV Series (CTI Series)


1.17.1 Brief Introduction of SHV Series

The features supported by the SHV Series boards are shown in the following table.

Board Model | Form Factor | Max. Ports | TDM Bus
SHV-120A-CT/PCI | PCI | 120 | H.100
SHV-240A-CT/PCI | PCI | 240 | H.100
SHV-240A-CT/cPCI | cPCI | 240 | H.110


1.17.2 Operation Principle of SHV Series

The figure below shows the typical application of the SHV Series boards.

In the figure above, the two-way connection is established between ChA and ChB via TDM bus. The incoming signals on ChB arrive at ChA through TS i and form the outgoing signals on ChA; the incoming signals on ChA enter the voice-alteration channel through TS j for processing, and then reach ChB via TS k and form the outgoing signal on ChB. In this way, the voice on ChB heard by ChA is the original voice while that on ChA heard by ChB is the altered voice.


1.17.3 List of Voice-alteration Functions

The SHV Series are the resource board and must be used with the SHD or SHT Series boards. Here is a list of functions related to voice alteration.

Function Name | Description
SsmGetMaxVCh | Obtains the total number of voice-alteration channels in the application system.
SsmGetMaxFreeVCh | Obtains the total number of idle voice-alteration channels
SsmBindVCh | Binds the voice channel to the voice-alteration channel.
SsmUnbindVCh | Unbinds the voice channel from the voice-alteration channel.
SsmSetVoiceEffect | Sets the voice alteration effect.
SsmGetVoiceEffect | Obtains the voice alteration effect


1.18 SHN Series (CTI Series)


1.18.1 Brief Introduction of SHN Series

The features supported by the SHN Series boards are shown in the following table.

Board Model | Form Factor | Max. Ports | Voice Processing Capabilities | Conferencing Capabilities | Voltage Detector | TDM Bus | Max Fax Resource | SIP | H.323
SHN-32A-CT/PCI | PCI | 32 | Ö | Ö | Ö | Ö | N/A | Ö | N/A
SHN-8B-CT/PCI+ | PCI | 8 | Ö | Ö | Ö | Ö | N/A | Ö | N/A
SHN-16B-CT/PCI+ | PCI | 16 | Ö | Ö | Ö | Ö | N/A | Ö | N/A
SHN-32B-CT/PCI+ | PCI | 32 | Ö | Ö | Ö | Ö | N/A | Ö | N/A
SHN-60B-CT/PCI+ | PCI | 60 | Ö | Ö | Ö | Ö | N/A | Ö | N/A
SHN-120B-CT/PCI+ | PCI | 120 | Ö | Ö | Ö | Ö | N/A | Ö | N/A


1.18.2 Operation Principle of SHN-32A-CT/PCI

The figure below shows the operation principle of the SHN-32A-CT/PCI board.

文本框: Outgoing call format 文本框: Incoming call format 文本框: Recording control 文本框: Playing Control

Below is the description on symbols in the figure above which are related to the recording operation:

Name | Description
M1 | Outbound voice mixer
M2 | Off-bus mixer
M3 | Recording mixer The signals from M3 is sent to the Encoder component for recording purpose.
M4 | Outbound voice mixer for recording Mixes signals from the off-bus mixer, data being played on a channel and signals from the tone generator/DTMF generator, and then puts them into M3.
M5 | Onto-bus mixer Mixes data being played on a channel, incoming signals and those from the off-bus mixer M2, and then puts them onto TDM bus. Upon board initialization, the output of M5 is transported to a time slot (marked as ‘ts’ for short) on TDM bus. You can use the function SsmLinkToBus to designate the ts.
A1 | The volume adjuster for voice playing. The volume can be set via the configuration item DefaultPlayVolume or the function SsmSetPlayVolume / SsmSetPlayGain , with the default value of 0.
A2 | The volume adjuster which is used for outgoing signals before they are sent to M3. By default, it is on. The volume can be set via the function SsmSetRecMixer or the configuration item DefaultRecordMixerVolume , with the default value of -7.
A3 | The volume adjuster which is used for incoming signals before they are sent to M3. The volume can be set via the function SsmSetRecVolume or the configuration item DefaultRecordVolume , with the default value of 0.
A4-1 … A4-6 | The volume adjuster which is used for off-bus signals before they are sent to M2. The volume can be set via the function SsmSetListenVlmInConf , with the default value of 0DB.
K1-1 | The switch that controls whether to put data being played on a channel first into M5 and then onto TDM bus or not, usually being off. It can be set via the function SsmSetPlayDest , used only for playing background music to a teleconference.
K1-2 | The switch that controls whether to put signals from M2 back onto TDM bus. By default, it is off. It can be set via the function SsmSetFlag (with the parameter F_MixerResToBus).
K3 | The switch that controls whether to put incoming signals into M5 or not. By default, it is on. It can be set via the function SsmSetFlag (with the parameter F_InVoiceToBus) or the configuration item InVoiceToBus .
K4 | DTMF signals or tones cannot be sent at the same time when voices are played outbound.
K6-1 K6-2 | Switch K6-1 controls whether to put signals form M2 into M3; Switch K6-2 controls whether to put voice data being played into M3. Both can be set via the function SsmSetRecBack .

Ø Voice Playing

After the application invokes the playing function, the decoded voice data after being processed by A1 will:

² Enter M1 and form the final outgoing signals with other signal sources; or

² Enter M4 under the control of K6-2 and form the recording signal sources with other signals; or

² Enter M5 under the control of K1-1 and form the onto-bus signal sources with other signals, only for playing background music to the teleconference.

Ø Recording Example for Various Signal Sources

A lot of special applications are available via the flexible use of the above switches for recording control and volume adjusters. In the following examples, ch1 and ch2 respectively mean Channel 1 and Channel 2.

² Example 1: Only record the incoming signals on ch1 and use the default volume.

SsmSetRecVolume(ch1, 0); //start A3, set the volume gain to 0DB

SsmSetRecMixer(ch1, FALSE, 0); //stop A2

SsmRecToFile(ch1, ……); //start the task of file recording …

² Example 2: Record the incoming signals on ch1 (volume increased by 6DB) and the signals output from M2 (volume decreased by 3DB) at one time based on the establishement of a two-way call between ch1 and ch2.

SsmTalkWith(ch1, ch2); //establish a two-way connection between ch1 and ch2

SsmSetRecBack(ch1,2); //switch on K6-1, switch off K6-2

SsmSetRecVolume(ch1, 2); //start A3, set the volume gain to 2*3DB=6DB

SsmSetRecMixer(ch1, TRUE, -1); //start A2, set the volume gain to -1*3DB=-3DB

SsmRecToFile(ch1, ……); //start the task of file recording …

² Example 3: When ch1 joins a teleconference (assuming the conference room number is n) as the organizer, play background music on ch1 and record the conference (including the background music) through ch1. All signal sources go with normal volume, i.e. the gain is set to 0.

SsmJoinConfGroup(n, ch1, ……); //ch1 joins the conference: switch on K3

SsmSetPlayDest(int ch, 1); //switch on K1-1

SsmSetRecBack(ch1,1); //switch on K6-1 and K6-2

SsmPlayFile(ch1, ……); //start the task of voice playing on ch1: switch on K4 to link left and right ends

SsmSetRecVolume(ch1, 0); //start A3, set the volume gain to 0DB

SsmSetRecMixer(ch1, TRUE, 0); //start A2, set the volume gain to 0DB

SsmRecToFile(ch1, ……); // start the task of file recording …


1.18.3 Operation Principle of SHN B Series


1.18.4 SIP Channel Programming


1.18.4.1 Basic Concepts

Ø SIP Message

There are two types of SIP message:

l Request: sent from Client to Server

l Response: sent from Server to Client

The table below lists all requests supported by the SIP channel on the Synway SHN Series boards.

Method | Description
INVITE | to establish a session between participants; or to modify an existing session (re-INVITE)
ACK | to confirm the reception of the final response to INVITE
BYE | to terminate a session
CANCEL | to terminate a call before it has been answered
OPTIONS | to allow a UA to query another UA or a proxy server as to its capabilities
REGISTER | to add, remove, and query bindings between address-of-record and one or more contact addresses
INFO | to carry application level information along the SIP signaling path, including out-of-band DTMF digits for the SHN Series boards
MESSAGE | to send instant messages
SUBSCRIBE | to request current state and state updates from a remote node
NOTIFY | to inform subscribers of changes in state to which the subscriber has a subscription

Ø Message Format

An SIP message consists of:

l a start-line

l one or more header fields

l an empty line indicating the end of the header fields

l an optional message-body

The start-line, each message-header line, and the empty line must be terminated by a carriage-return line-feed sequence (CRLF). Note that the empty line must be present even if the message-body is not.

Ø SDP

SDP is a session description protocol for multimedia sessions (RFC2327). It specifies the way to encode necessary information about the session. The SDP message is carried by the SIP message in a way that is analogous to a document attachment being carried by an email message, or a web page being carried in an HTTP message.

An SDP package usually contains both session information and media information.

Session information includes the following:

l The owner and identifier of the session

l Time(s) the session is active

As resources necessary to participate in a session may be limited, some additional information may also be desirable:

l Information about the bandwidth to be used by the session

l Contact information for the person responsible for the session (E-Mail address, phone number, etc)

Media information includes the following:

l The type of media (video, audio, etc)

l The transport protocol (RTP/UDP/IP, H.320, etc)

l The format of the media (H.261 video, MPEG video, etc)

l Multicast address for media and transport port for media (IP multicast session)

l Remote address for media and Transport port for contact address (IP unicast session)


1.18.4.2 SIP Channel State Machine

Each state identifier in the above diagram is described in the following table.

State Identifier

Description

Unusable

‘Unusable’ state

² The channel, staying in whichever state in the above diagram, will turn into the ‘UNUSABLE’ state upon the reception of the evDisableCh event.

Standby

’Idle’ state

The channel will go into this state just after the successful board initialization.

² When the function SsmAutoDial is invoked to start a call, the channel will turn into the ‘DIALING’ state.

² When the function SsmSearchIdleCallOutCh is invoked to find an idle channel, it will turn into the ‘Locked’ state.

² When the function SsmPickup is invoked, an idle channel will be locked and turn into the ‘Locked’ state.

² When an idle channel is available upon the reception of an incoming call, it will turn into the ‘Ringing’ state.

² When no idle channels are available upon the reception of an incoming call, A3 will automatically send the response code 403 and set the reason.

² When the event evDisableCh (indicating network error or usable channel unavailable) is received, the channel will turn into the ‘Unusable’ state.

DIALING

‘Waiting for Answer’ state

The channel will keep in this state until it receives responses from the remote end.

² In this state, if the evRingback event (indicating the reception of the response code 180 from the remote end) is received, the channel will turn into the ‘WaitAnswer’ state.

² If the evRedire event (indicating the reception of the response code 3xx from the remote end) is received, SynSIP will call again on the same channel and automatically send an ACK message to the remote.

² If the evUnauth event (indicating the reception of the 401/407 response from the remote end) is received, SynSIP will automatically send a call request with authentication information to the remote.

² If the evAnswered event (indicating the reception of the 2xx response from the remote end) is received, the channel will turn into the ‘Talking’ state and SynSIP will automatically send an ACK message to the remote at the same time.

² If the evReject event (the call is refused by the remote end), the evError event (the dial function is asynchronous), the evTimeout event (the timer overflows) and the evCountUnauth event (unauthorized) are received, the channel will turn into the ‘Standby’ state and set the reason as well. At this time, SynSIP will determine whether to send an ACK message to the remote according to the current events (evErrAnsw and evCountUnauth).

² If the function SsmHangup is invoked to hang up the phone in this state, the channel will turn into the ‘Standby’ state and SynSIP will automatically send a CANCEL message to the remote at the same time.

² SynSIP will start Timer B and Timer C when the channel goes into the ‘Dialing’ state. If the application doesn’t change in state before the timer overflows, the driver will reset the channel back to the idle state.

² If the event evDisableCh (indicating network error or usable channel unavailable) is received, the channel will turn into the ‘Unusable’ state.

Locked

‘Outgoing Call Locked’ state

² When the function SsmSearchIdleCallOutCh is invoked by the application, the driver will temporarily lock the channel specified by the function’s return value

² If the event evDisableCh (indicating network error or usable channel unavailable) is received, the channel will turn into the ‘Unusable’ state.

WaitAnswer

‘Ringback’ state

² In this state, if the evAnswered event (indicating the reception of the 2xx response from the remote end) is received, the channel will turn into the ‘Talking’ state.

² If the evReject event (the call is refused by the remote end) and the evTimeout event (the timer overflows) are received, the channel will turn into the ‘Pending’ state and set the reason as well. At this time, SynSIP will dermine whether to send an ACK message to the remote according to the current error reason.

² If the function SsmHangup is invoked to hang up the phone in this state, the channel will turn into the ‘Standby’ state and SynSIP will automatically send a CANCEL message to the remote at the same time.

² If the event evDisableCh (indicating network error or usable channel unavailable) is received, the channel will turn into the ‘Unusable’ state.

Ringing

‘Called Party Ringing’ state

When an idle channel is available upon the reception of an incoming call, SynSIP will automatically react to the 180 response to lock the idle channel and turn it into this state.

² In this state, if users are determined to accept the current call request and invoke the function SsmPickup , the channel will turn into the ‘WaitConnected’ state and SynSIP will automatically send the 200 OK response to the remote at the same time.

² If users choose to refuse the call and invoke the function SsmHangup , the channel will turn into the ‘Standby’ state and SynSIP will automatically generate a 403 Forbidden response and send it to the remote at the same time.

² If the evRecvCancel event (indicating the call is cancelled by the calling party) is received, the channel will turn into the ‘Standby’ state and SynSIP will automatically generate a 200 OK response to the CANCEL message.

² If the evTimeout event (indicating the timer overflows) is received, the channel will turn into the ‘Standby’ state and SynSIP will automatically generate a 400 Bad Request response and send it to the remote at the same time.

² If the event evDisableCh (indicating network error or usable channel unavailable) is received, the channel will turn into the ‘Unusable’ state.

WaitConnected

Waiting for connection’ state

² If the function SsmHangup is invoked to hang up the phone in this state, the channel will turn into the ‘Standby’ state and SynSIP will automatically send a BYE message to the calling party at the same time.

² If the evRecvCancel event (indicating the call is cancelled by the calling party) is received, the channel will turn into the ‘Standby’ state and SynSIP will automatically generate a 200 OK response to the CANCEL message.

² If the evRecvAck event (indicating the connection of the calling party) is received, the channel will turn into the ‘Talking’ state.

² If the evRecvBye event is received, the channel will turn into the ‘Pending’ state and SynSIP will generate a 200 OK response to the BYE message

² If the evError event and the evTimeout event (indicating the timer overflows) are received, the channel will turn into the ‘Standby’ state.

² If the event evDisableCh (indicating network error or usable channel unavailable) is received, the channel will turn into the ‘Unusable’ state.

Talking

‘Talking’ state

All voice channels are connected in this state.

² In this state, both calling and called parties can invoke the function SsmHangup to hang up the phone. Then SynSIP will generate a BYE message and send it to the remote and the channel will turn into the ‘Standby’ state at the same time.

² If the evRecvBye event (indicating the phone is hung up by the remote end) is received, the channel will turn into the ‘Pending’ state.

² If the event evDisableCh (indicating network error or usable channel unavailable) is received, the channel will turn into the ‘Unusable’ state.

Pending

‘Pending’ state

² When the ‘Call Terminated’ state as specified by the SIP protocol is received during the call state transition, the call cannot be connected any longer and users must release all resources allocated throughout the call process and reset the circuit. Only via the call of SsmHangup can the channel go back to the ‘Standby’ state.

² If the event evDisableCh (indicating network error or usable channel unavailable) is received, the channel will turn into the ‘Unusable’ state.

Each state identifier in the above diagram is described in the header file ShpA3Api.h as follows.

State Identifier | Value in ShpA3Api.h | Macro Definition in ShpA3Api.h
Unusable | 134 | S_CALL_VOIP_CHANNEL_UNUSABLE
Standby | 0 | S_CALL_STANDBY
Dialing | 132 | S_CALL_VOIP_DIALING
Locked | 12 | S_CALL_LOCKED
WaitAnswer | 9 | S_CALL_WAIT_REMOTE_PICKUP
Ringing | 2 | S_CALL_RINGING
WaitConnect | 133 | S_CALL_VOIP_WAIT_CONNECTED
Talking | 3 | S_CALL_TALKING
Pending | 7 | S_CALL_PENDING

In the above state machine, the driver’s internal component for judging the channel’s usability has two values to output as shown in the table below.

Output Value | Description
Unusable | The channel is unusable if one of the events evDisableCh, DataLinkDisconnect, Circuit Reset keeps valid.
Standby | The channel goes into the idle state provided the evDisableCh event becomes invalid, the DataLinkConnect event keeps valid and the circuit restart is successful.

Note: At this stage, the driver also performs the following operations.

· Clear and close the tone detector;

· Automatically terminate the WaitDtmf task if it has been started by the application;

· Automatically terminate the task of DTMF transmission if it has been started by the application;

· Automatically clear the buffer of the DTMF detector, and close the DTMF detector if the configuration item AlwaysEnableRxDtmf is set to 0;

· Automatically close the Barge-in detector if the configuration item AlwaysDetectBargeIn is set to 0;

· Automatically clear the Caller ID buffer if the configuration item AutoClearCallerIdBufOnHangup is set to 1;

· Reset all timers in SynSIP.

The output events of the state machine are described in the following table.

Event Name | Description
E_CHG_ChState | The driver sends out this event to the application when the channel state changes.
E_PROC_AutoDial | The driver throws out this event to the application when there is any progress in the AutoDial task which is started by the function call of SsmAutoDial with the application.

Note: Event declarations can be found in the file ShpA3Api.h.


1.18.4.3 SIP Channel Configuration

Configuration items for using the SHN-32A-CT/PCI board with SIP protocol are listed below.

Configuration Section | Configuration Item |
[BoardId=x] | ProtocolType | Set the IP communication protocol for the VoIP board or set the VoIP board to be a VoIP resource board; Set the DTMF reception mode for the board.
 | RecvDtmfType
 | DisplayName | Set operation parameters for an SIP session. They are in sequence: ² Displayed name ² DTMF transmission mod ² Adopted voice CODECs
 | SendDtmfType
 | AudioCodecList
 | UserName | Set the parameters of the Register request. They are in sequence: ² Register a user name upon the start of registration, or set the part before @ in SIP Uri as the user name. ² Whether to enable the registration ² Address of the registered server ² Password for registration (if necessary) ² Alias of the SIP server ² Register a valid expiration time, with the default value of 3600 and the minimum value of 300.
 | Register
 | Domain
 | RegPassword
 | RegRealm
 | RegExpires
[SIP] | LocalSipIp | Set the intercepted address and port for the SIP protocol.
 | LocalSipPort
 | RTPRange | RTP port range
 | LogFile | Set the advanced board configuration items. They are in sequence: ² Log file ² Log level ² Size of the thread pool to capture SIP events ² Port heartbeat interval (for NAT traversal)
 | LogLevel
 | EventThreadNum
 | HeartInterval
 | SipTransportProtocol | Set whether SIP is used over TCP or UDP

Configuration items for using the SHN B Series boards with SIP protocol are listed below.

Configuration Section | Configuration Item |
[BoardId=x] | ProtocolType | Set the IP communication protocol and DTMF reception mode used by the board.
 | RecvDtmfType
 | BoardIP | Set network card information for the SHN B series. They are in sequence: ² IP address of the network card (voice channels) ² Subnet mask ² Gateway address DNS address
 | Submask
 | Gateway
 | DNS
 | RTPRange | Set operation parameters for an SIP session. They are in sequence: ² RTP port range ² Displayed name ² DTMF transmission mode Adopted voice CODECs
 | DisplayName
 | SendDtmfType
 | AudioCodecList
 | UserName | Set the parameters of the Register request. They are in sequence: ² Register a user name upon the start of registration, or set the part before @ in SIP Uri as the user name. ² Whether to enable the registration ² Address of the registered server ² Password for registration (if necessary) ² Alias of the SIP server Register a valid expiration time, with the default value of 3600 and the minimum value of 300.
 | Register
 | Domain
 | RegPassword
 | RegRealm
 | RegExpires
[SIP] | LocalSiplp | Set the intercepted address and port for the SIP protocol.
 | LocalSipPort
 | RTPRange | RTP port range
 | LogFile | Set the advanced board configuration items. They are in sequence: ² Log file ² Log level ² Size of the thread pool to capture SIP events Port heartbeat interval (for NAT traversal)
 | LogLevel
 | EventThreadNum
 | HeartInterval
 | SipTransportProtocol | Set whether SIP is used over TCP or UDP

Note: Those written in the XXXX font are essentially configured items while those in XXXX are optionally configured ones.


1.18.5 Special Parameters and Structure for VoIP Resource Boards


1.18.5.1 RTP Transmit and Receive Modes for VoIP Resource Boards

#define IPM_SENDRECV 0x0000 // Receive and transmit

#define IPM_SENDONLY 0x0001 // Transmit only

#define IPM_RECVONLY 0x0002 // Receive only


1.18.5.2 Special Structure for VoIP Resource Boards

struct MediaParam

{

int mode;

char localIP[50];

int localPort;

char remoteIP[50];

int remotePort;

int sendCodecType;

int dtmfpayload;

};

mode: RTP transmit and receive modes, having the following three values.

IPM_SENDRECV (Receive and transmit)

IPM_SENDONLY (Transmit only)

IPM_RECVONLY (Receive only)

localIP: The local address intercepted in RTP.

localPort: The local port intercepted in RTP.

remoteIP: The remote address sent in RTP.

remotePort: The remote port sent in RTP.

SendCodecType: The codec for RTP load. 0: 711U, 8: 711A, 18: G729, 3: GSM.

dtmfpayload: DTMF digits sent in RFC2833.


1.19 DST Series (REC Series)


1.19.1 Brief Introduction of DST Series

When a digital PBX, such as Siemens HIPath, Alcatel 4200 and Alcatel 4400 Series, is connected to a digital telephone, what goes through the line is not the analog signal but the pure digital signal. The physical line used to connect the digital PBX and the digital telephone is called the digital subscriber line. It is made of a D-channel and two B-channels, each channel supporting the rate of 64kbps. The D-channel is used to transmit call signaling messages, and the two B-channels can work simultaneously transporting voice data and others, like fax data, etc.

The DST Series boards are the proprietary call-recording board used for recording the voice data on the B-channel and the signaling data on the D-channel in the digital subscriber line. They have the high-impedance circuits for the input lines, equip the instantly-programmable chips in the signal recording circuit, and can enable a same board to support different PBX and digital phone models via simple settings with the application program.

So far, the DST Series boards are classified into two types : A and B.

They commonly have the following voice processing abilities:

Ø High-impedance recording of voice data on the B-channel, neither to cause any interruption on both parties in a call nor to be detected by them;

Ø Compression and recording of voice data by using the specified voice CODEC;

Ø Automatic Gain Control (AGC) support in data recording;

Ø DTMF detection;

Ø Detection of voice activities;

Ø Detection of single or dual tones at a specific frequency;

Ø Real-time playing of recorded voice signals;

Ø TDM capability;

Ø Playback of recorded voice data.

Besides these mentioned above, the DST series B-type boards also support the following new features.

Ø Detection of line faults, including line break and errors in voltage level, signal-to-noise ratio and frame synchronization;

Ø Flexible switch between voice channels B1 and B2;

Ø Board models with the suffix + support GSM, G.729A and MP3 encoding in hardware.

The D-channel signaling messages can be used to acquire the relative call information. The D-channel on the DST Series boards has the signaling processing capabilities that include the detection of the following operations by the digital phone as well as the changes in channel state.

Ø Off-hook, On-hook;

Ø Dial keys;

Ø Function keys;

Ø Voice channel open/closed;

Ø LED;

Ø Content displayed on LCD.

The board models in the DST Series are shown in the table below.

Board Model | Form Factor | Max. Ports per Board | Module Type | Max. Modules per Board
SHR-16DA-CT/PCI | PCI / PCI-X | 16 | MOD_16DA | 4
SHR-24DA-CT/PCI | PCI / PCI-X | 24 | MOD_24DA | 3
DST-24B/PCI | PCI | 24 | MOD_24DB | 3 (including a module for board fixing)
DST-24B/PCI(SSW) | PCI | 24 | MOD_24DB | 3 (including a module for board fixing)
DST-24B/PCI+ | PCI | 24 | MOD_24DB | 3 (including a module for board fixing)
DST-24B/PCI+(SSW) | PCI | 24 | MOD_24DB | 3 (including a module for board fixing)
DST-24B/PCIe | PCIe | 24 | MOD_24DB | 3 (including a module for board fixing)
DST-24B/PCIe+ | PCIe | 24 | MOD_24DB | 3 (including a module for board fixing)

The module types supported by the DST Series boards are listed in the table below.

Module Type | Number of channels in the case of 2-line input | Number of channels in the case of 4-line input
MOD_16DA | 4 | 2
MOD_24DA | 8 | 4
MOD_24DB | 8 | 4


1.19.2 DST Series Supported PBX Models

For the PBX models supported by the DST Series boards, refer to the document DST Boards Supported PBX Models supplied separately by Synway.


1.19.3 Operation Principle of DST Series

The figure below shows the operation principle of the DST Series A-type boards.

Components and symbols in the figure above are described in the following table.

Name | Description
M2 | Off-bus mixer, used to mix outgoing signals with incoming ones.
A4-1 | The volume adjuster for incoming signals (by reference to the digital phone). The volume can be set via the function DTRSetMixerVolume, with the default value of 0DB.
A4-2 | The volume adjuster for outgoing signals (by reference to the digital phone). The volume can be set via the function DTRSetMixerVolume, with the default value of 0DB.
A3 | Recording volume adjuster. The volume can be set via the configuration item DefaultRecordVolume or the function SsmSetRecVolume.
A5 | Used to put the output signals from the mixer onto bus for recording and monitoring purpose. Usually there is no need to operate A5.

The figure below shows the operation principle of the DST Series B-type boards.

Components and symbols in the figure above are described in the following table.

Name | Description
M2 | Off-bus mixer, used to mix outgoing signals with incoming ones.
V-2 | The volume adjuster for incoming signals (by reference to the digital phone). The volume can be set via the function DTRSetMixerVolume, with the default value of 0DB.
V-3 | The volume adjuster for outgoing signals (by reference to the digital phone). The volume can be set via the function DTRSetMixerVolume, with the default value of 0DB.
V1 | Recording volume adjuster. The volume can be set via the configuration item DefaultRecordVolume or the function SsmSetRecVolume.

Ø Recording Example for Various Signal Sources

A lot of special applications are available via the flexible use of the above switches for recording control and volume adjusters.

² Example 1: Record both the incoming and the outgoing signals, using the normal volume.

DTRSetMixerVolume(ch, 0, 0, 0); //set the volume gain of A4-1 and that of A4-2 to 0DB

SsmSetRecVolume(ch, 0); //start A3, set the volume gain to 0DB

SsmRecToFile(ch, ……); //start the task of file recording …

² Example 2: Only record the incoming signals, using the default volume.

DTRSetMixerVolume(ch, 0, 3, -7); //set the volume gain of A4-1 to 3*3DB=9DB and that of A4-2 to -∞

SsmSetRecVolume(ch, -3); //start A3, set the volume gain to -3*3DB=-9DB

SsmRecToFile(ch, ……); //start the task of file recording …

Ø Data Flow Direction in Voice Playing

Only Channel 0 supports the voice playing operation. When the application program invokes the playing functions for Channel 0, the driver will automatically put the voices to be played onto bus and then get them off bus to arrive at the on-board audio power amplifier.

Ø On-board Speaker Output Jack

Channel 0 on each DST board is enabled by the analog audio amplifier circuit and the spearker output jack equipped on it to connect voice signals directly with the external speaker or headset. This design is mainly for the following purposes.

² To transport incoming signals from any channel on this board (or transport voice signals from channels on other board via CT-BUS) to the on-board speaker for play. This purpose can be achieved via the function SsmListenTo or SsmListenToEx.

² To send voice data recorded by the application straight to the on-board speaker for play via the call of playing functions for Channel 0. See the Voice Playing section in this chapter for details.

The AMP component in the figure above is the power amplifier for the analog audio amplifier circuit. Its gain can be set via the function SsmSetPowerAmpVlm.


1.19.4 DST Board Configuration

The configuration items PBXType and PhoneType are used respectively to set the PBX and the digital phone models; the configuration item DefaultVoiceFormat is used to set the CODEC supported by the digital subscriber line.

The configuration item DEventUpdates is used to filtrate repeated events.

Besides, some new configuration items are added for B-type digital station tap boards. DstRecRawData is used to set the board working mode; SetVoxChSelectEnable and VoxChSelect are used to select voice channels; SetAnalogCtrlEnable, AnalogCtrl, SetFilterSwitchEnable, FilterSwitch, SetVoltageReferenceEnable and VoltageReference are advanced configuration items which don’t need to be reconfigured in most situations (If it is necessary to reconfigure them, please do under the instruction from our technicians).


1.19.5 Voice Operation on DST Series

The DST Series boards support the following voice operations.

Ø Recording

Support voice recording in File Mode and Buffer Mode. The supported CODECs include A-Law, µ-Law, IMA ADPCM, G.729A, etc. See the Voice Recording section in this chapter for more information.

Ø Playing

Channel 0 on each DST board supports the voice playing operation, including the play in Single File Mode and Single Buffer Mode. The supported CODECs include A-Law, µ-Law, IMA ADPCM, G.729A, etc. See the Voice Playing section in this chapter for more information.

Ø Real-time Monitoring

The on-board speaker output jack can help each DST board to monitor the input voice signals on any channel in real time. The application can invoke the function SsmListenTo , SsmListenToEx , SsmLinkFrom or SsmLinkFromEx to start the real-time monitoring, and the function SsmStopListenTo or SsmStopLinkFrom to stop it. The function SsmSetPowerAmpVlm can be used to adjust the volume. Note that CT-BUS is required for connecting boards if the monitored port and the speaker output jack are not on the same board.

Ø Volume Adjusting for Input Voice Signals

The function DTRSetMixerVolume can be used to set the volume for the voice signals from the PBX to the phone or from the phone to the PBX.

Ø DTMF Detector

See the DTMF Detector section in this chapter for more information.

Ø Tone Detector

See the Tone Detector section in this chapter for more information.

Ø Barge-in Detector

In case the D-channel signaling messages are difficult to be analyzed, you can use the detected result of the Barge-in detector (voice activities detected/silence detected) as the condition to start or stop the recording and other operations. See the Barge-in Detector section in this chapter for more information.


1.19.6 Programming Guide for DST Series

The signaling protocol used for the D-channel has not been unified and is usually decided by the PBX or telephone manufacturers. As a result, different manufacturers, even one manufacturer, may produce various product Series which are quite distinct.

The driver picks up the original signaling messages on the D-channel and passes them to the application by throwing out D-channel events. Then according to these D-channel events, the application program completes the signaling analysis over the call process.


1.19.6.1 D-channel Signaling Messages

Among the D-channel signaling messages, those sent from the PBX to the phone are called PBX messages, and the corresponding events are PBX events; those sent from the phone to the PBX are called phone messages, and the corresponding events are phone events. Common PBX events include:

² Ring events;

² Audio events;

² Display events;

² LED (Light) events.

Common phone events mainly cover:

² Hook events;

² Button events.

Besides, the phone doesn’t need to report some particular operations on it to the PBX, so it won’t send any message to the PBX in such case. Thus even if the driver acquires all original signaling messages on the D-channel, it is probably not able to get any information about those operations on the phone, which include:

² Users operate the volume adjuster on the phone;

² The phone displays on the LCD some of the information that is independent of the PBX, such as settings of some function buttons;

² The phone changes the voice channel state, which is unnecessary to be reported to the PBX;

² The LED on the phone varies in the state, which is unnecessary to be reported to the PBX.

For detailed information about the D-channel signaling messages, refer to DST Event Manual.

The application should set up an exclusive state machine for a particular PBX/phone model by using some or all of the D-channel signaling messages as the condition to trigger the state transition, then properly record the relative information during the call process and the relevant voice operations, like the start and stop of recording, according to the changes in the channel state.

Those events which may affect the call state machine but are unavailable in the D-channel signaling messages, such as busy tones, ringback tones on the B-channel, can be obtained via other voice processing features the driver provides. See the Voice Processing section in this chapter for more information.


1.20 ATP Series (REC Series)


1.20.1 Brief Introduction of ATP Series

The features supported by the ATP Series boards are shown in the following table.

Board Model | Form Factor | Max. Ports | Voltage Detector | CallerID Detector | DTMF Detector | Tone Detector | Energy Detector | TDM Bus | Audio Socket
SHT-2A/USB | USB | 2 | Ö | Ö | Ö | Ö | Ö | N/A | Ö
SHT-2B/USB | USB | 2 | Ö | Ö | Ö | Ö | Ö | N/A | Ö
SHT-4A/USB | USB | 4 | Ö | Ö | Ö | Ö | Ö | N/A | Ö
SHT-4B/USB | USB | 4 | Ö | Ö | Ö | Ö | Ö | N/A | Ö
SHT-8A/PCI | PCI | 8 | Ö | Ö | Ö | Ö | Ö | N/A | Ö
SHT-8B/PCI | PCI | 8 | Ö | Ö | Ö | Ö | Ö | N/A | Ö
SHT-16A-CT/PCI | PCI | 16 | Ö | Ö | Ö | Ö | Ö | H.100 | Ö
SHT-16B-CT/PCI | PCI | 16 | Ö | Ö | Ö | Ö | Ö | H.100 | Ö
SHT-16B-CT/PCI/MP3 | PCI | 16 | Ö | Ö | Ö | Ö | Ö | H.100 | Ö
ATP-24A/PCI | PCI | 24 | Ö | Ö | Ö | Ö | Ö | N/A | Ö
ATP-24A/PCI+ | PCI | 24 | Ö | Ö | Ö | Ö | Ö | N/A | Ö
ATP-24A/PCIe | PCIe | 24 | Ö | Ö | Ö | Ö | Ö | N/A | Ö
ATP-24A/PCIe+ | PCIe | 24 | Ö | Ö | Ö | Ö | Ö | N/A | Ö
SHT-16B-CT/cPCI | cPCI | 16 | Ö | Ö | Ö | Ö | Ö | H.110 | Ö
SHT-16B-CT/cPCI/MP3 | cPCI | 16 | Ö | Ö | Ö | Ö | Ö | H.110 | Ö


1.20.2 Operation Principle of ATP Series

The figure below shows the operation principle of the ATP Series boards.

Symbols related to the recording operation in the figure above are described in the following table.

Name | Description
M1 | Real-time monitoring mixer. Either the off-bus voices or the voices played on channel 0 are allowed to enter this mixer at a time.
A4-1 | The volume adjuster for off-bus signals
A1 | The volume adjuster for voice playing on Channel 0. The volume can be set via the function SsmSetPlayVolume/SsmSetPlayGain or the configuration item DefaultPlayVolume, with the default value of 0.
K5-1 | The switch that controls the voice playing operation, usually keeping off under the automatic control of the driver. Only when the application program invokes the playing function on Channel 0 does the driver automatically switch on K5-1 and then switch off it at the end of voice playing. For more information about the playing functions, refer to the Voice Playing section.
M3 | Recording mixer The signals from M3 is sent to the Encoder component for recording purpose.
A3 | The volume adjuster which is used for incoming signals before they are sent to the recording mixer. The volume can be set via the configuration item DefaultRecordVolume or the function SsmSetRecVolume, with the default value of 0. Note: A3 will become invalid once the AGC feature is enabled.
A2 | The volume adjuster which is used for bus signals before they are sent to M3, switched on in default. The volume can be set via the function SsmSetRecMixer or the configuration item DefaultRecordMixerVolume, with the default value of -7. This volume adjuster is only applicable to a few particular occasions. It only supports the boards with bus in ATP Series boards. Boards like ATP-24A/PCI are unsupported as they don’t include bus.
K3 | The switch that controls whether to put the incoming signals into the onto-bus mixer or not, switched on in default. It can be set via the function SsmSetFlag (with the parameter F_InVoiceToBus) or the configuration item InVoiceToBus.
K2 | The switch that shifts between the FSK detector and other detectors, usually connected to other detectors unless the FSK detector is started.

Ø Channel Type and Modules

The ATP Series boards accept two kinds of modules installed on them. They are Analog Trunk Recording Module and Microphone Recording Module. The driver does not distinguish these two kinds of modules and regards their corresponding channel types both as the analog recording channel. The configuration item MicGain is used to set the gain of the input signals to the analog trunk recording channel: if the voice signals come from the analog phone line, the gain should be set to the normal value; if the voice signals come from the moving coil microphone, the gain should be set to 20DB.

Ø Voice Playing

Only Channel 0 supports the voice playing operation. When the application calls playing functions for Channel 0, voice data will be sent to the on-board audio power amplifier.

Ø Voice Recording

The recording operation based on the ATP Series boards is quite easy to be performed. The only one thing required is to control the gain of A3.

² Example 1: Record the incoming signals on Ch1, using the default volume.

SsmSetRecVolume(ch1, 0); //start A3, set the volume gain to 0DB

SsmRecToFile(ch1, ……); //start the task of file recording …

Ø On-board Speaker Output Jack

Channel 0 on each ATP board is enabled by the analog audio amplifier circuit and the spearker output jack equipped on it to connect directly with the external speaker or headset and monitor voice signals in real time. This design is mainly for the following purposes.

² To transport incoming signals from any channel to the on-board speaker for play via TDM bus. This purpose can be achieved via the function SsmListenTo or SsmListenToEx.

² To send voice files recorded by the application straight to the on-board speaker for play via the call of playing functions. See the Voice Playing section in this chapter for details.

The AMP component in the figure above is the power amplifier for the analog audio amplifier circuit. Its gain can be set via the function SsmSetPowerAmpVlm.

Channel 0 on the USB recording box (with ‘/USB’ marked in the model) is equipped with not only a speaker output jack but also an on-board speaker, which enables the voice playing operation. The switch K8, providing choices for the signals output from Channel 0 to enter the on-board speaker or the speaker jack, can be set via the function SsmSetLine0OutTo or the configuration item USBLine0Output, with the default setting of ‘to the speaker jack’.

Note: Although there is no TDM bus available on the 8-channel ATP boards, the driver provides the soft-switch feature which also allows the transmission of voice data from one board to another (it is usually the board linked with an external speaker) for real-time monitoring. Don’t forget to set the configuration item BusPlayListen in such case.

Ø Special Application of Non-module Channel

A channel on the ATP Series boards equipped with no modules can be used as the recording channel. In such case, the Barge-in detector and the recording encoder still work in a normal way, and the off-bus operation goes well as usual, which allow the recording of voice data from TDM bus via function calls. The Barge-in detector is used for voice control purpose. This special application can be set via the configuration item NoModuleChBusRec or the function SsmSetNoModuleChBusRec.

Note:

The volume adjuster A3 should be switched on via the function SsmSetRecVolume or the configuration item DefaultRecordVolume before the start of voice recording.


1.20.3 Analog Trunk Recording Channel State Machine

Each state identifier in the above diagram is described in the following table.

State Identifier

Value

Macro Definition

Description

Standby

0

S_CALL_STANDBY

’Idle’ state. The channel goes into this state after the successful driver initialization.

OffHook

1

S_CALL_PICKUPED

’Off-hook’ state. When the channel state transfers to ‘Off-hook’, the driver will:

² clear the tone detector and then start it;

² start the DTMF detector;

² start the prerecord task if this feature has been enabled.

Ringing

2

S_CALL_RINGING

’Ringing’ state, indicating there comes a call. In this state, the application can invoke the function SsmGetCallerId or SsmGetCallerIdEx to obtain the calling party number. See the Caller ID on Analog Phone Line section in this chapter for more information.

OffLine

8

S_CALL_OFFLINE

’Off-line’ state

AnalogClear

10

S_CALL_ANALOG_CLEAR

It is the internal ‘disconnection’ state, only lasting for 8ms, mainly used for the driver to do the following things:

² clear the tone detector and then close it;

² clear the Caller ID buffer within the driver provided the configuration item AutoClearCallerIdBufOnHangup is set to 1;

² start the Caller ID detector and close the DTMF detector if the Caller ID is received in the FSK mode; otherwise, start the DTMF detector;

² immediately stop the prerecord operation if it is still going on;

² clear the DTMF buffer within the driver;

² start the ringing current detector.

In the diagram above, the internal events automatically triggered by the driver itself are described as follows.

Event | Description
RingSignalOn | The driver detects the ringing signal. See the Ringing Current on Analog Phone Line section in this chapter for more information.
RingSignalOff | The ringing signal disappears.
OffHook | The driver detects the pickup behavior on the monitored phone. Refer to the Change in Analog Phone Line Voltage section in this chapter for more information.
OnHook | The driver detects the hangup behavior on the monitored phone.
OffLine | The connection between the monitored phone and the PBX or that between the high-impedance parallel lines and the on-board ports is broken. See the Change in Analog Phone Line Voltage section in this chapter for more information.
OnLine | The connection is recovered.


1.20.4 Detection of Off-hook/On-hook State

For detailed information about the detection of the pickup and hangup behaviors on the recording channel, see the Change in Analog Phone Line Voltage section in this chapter.


1.21 DTP Series (REC Series)


1.21.1 Brief Introduction of DTP Series

The features supported by the DTP Series boards are shown in the following table.

Board Model | Form Factor | Trunk Type | Max. Ports | Hi-Z Line Interface Circuit | Voice Processing Capabilities | TDM Bus | DSS1 | ISDN PRI | SS7 | SS7 Signaling Links
SHD-30A-CT/PCI/FJ | PCI | E1 | 30 | Ö | Ö | H.100 | Ö | Ö | Ö | 1
SHD-60A-CT/PCI/FJ | PCI | E1 | 60 | Ö | Ö | H.100 | Ö | Ö | Ö | 2
SHD-30B-CT/PCI/FJ | PCI | E1/T1 | 30/23 | Ö | Ö | H.100 | Ö | Ö | Ö | 1
SHD-60B-CT/PCI/FJ | PCI | E1/T1 | 60/46 | Ö | Ö | H.100 | Ö | Ö | Ö | 2
DTP-30C/PCI | PCI | E1/T1 | 30/23 | Ö | Ö | H.100 | Ö | Ö | Ö | 1
DTP-30C/PCI+ | PCI | E1/T1 | 30/23 | Ö | Ö | H.100 | Ö | Ö | Ö | 1
DTP-60C/PCI | PCI | E1/T1 | 60/46 | Ö | Ö | H.100 | Ö | Ö | Ö | 2
DTP-60C/PCI+ | PCI | E1/T1 | 60/46 | Ö | Ö | H.100 | Ö | Ö | Ö | 2
DTP-120C/PCI | PCI | E1/T1 | 120/92 | Ö | Ö | H.100 | Ö | Ö | Ö | 4
DTP-120C/PCI+ | PCI | E1/T1 | 120/92 | Ö | Ö | H.100 | Ö | Ö | Ö | 4
DTP-30C/PCIe | PCIe | E1/T1 | 30/23 | Ö | Ö | H.100 | Ö | Ö | Ö | 1
DTP-30C/PCIe+ | PCIe | E1/T1 | 30/23 | Ö | Ö | H.100 | Ö | Ö | Ö | 1
DTP-60C/PCIe | PCIe | E1/T1 | 60/46 | Ö | Ö | H.100 | Ö | Ö | Ö | 2
DTP-60C/PCIe+ | PCIe | E1/T1 | 60/46 | Ö | Ö | H.100 | Ö | Ö | Ö | 2
DTP-120C/PCIe | PCIe | E1/T1 | 120/92 | Ö | Ö | H.100 | Ö | Ö | Ö | 4
DTP-120C/PCIe+ | PCIe | E1/T1 | 120/92 | Ö | Ö | H.100 | Ö | Ö | Ö | 4

The voice processing capabilities mentioned above include:

ü DTMF Detector

ü Tone Detector

ü Barge-in Detector

ü Voice Recording

ü Voice Playing

ü TDM Capability

The line interface unit (LIU) on the DTP Series boards is enabled by the high-impedance circuit equipped on it to connect directly with the monitored E1/T1 lines, without the need of extra devices for high-impedance parallel connection.

In monitoring one E1/T1 link, the onto-PCM and off-PCM signals must be recorded and processed at the same time. Therefore, two E1/T1 LIU which only need to process input signals are essential for this process.

The information acquired through monitoring can be separated into two parts: signaling messages and voice channel data.


1.21.2 Operation Principle of DTP Series

The figure below shows the operation principle of the DTP Series boards.

Those symbols related to the board in the figure above are described in the following table.

Name | Description
M3 | Recording mixer. The signals from M3 is sent to the Encoder component for recording purpose.
A3 | The volume adjuster which is used for incoming signals before they are sent to M3. The volume can be set via the function SsmSetRecVolume or the configuration item DefaultRecordVolume, with the default value of 0.
A2 | The volume adjuster which is used for outgoing signals before they are sent to M3, switched on in default. The volume can be set via the function SsmSetRecMixer or the configuration item DefaultRecordMixerVolume, with the default value of -7.
K3 | The signaling/protocol switch. It can be set via the configuration item PcmSSx. Note that so far the driver is not yet able to pass original signaling messages directly to the application program through Msg Queue.

The driver is capable of analyzing SS1, ISDN, SS7-TUP and SS7-ISUP signaling with the help of its internal call state machine. The application can control and visit this state machine by using the unified API functions (i.e. Global Call API in the figure above). This section focuses on the content concerning the Global Call API functions.

In a SS7 ISUP or TUP call, the call state machine provided by the driver can save the received original messages to its internal buffer while processing the ISUP or TUP message, provided the configuration item bOpenSpySS7Msu is set to 1. And the application may call the function SsmGetSs7SpyMsu to acquire the original ISUP or TUP message from this buffer.

The operation on voice data is also quite easy. The DTP Series boards provide independent voice channels respectively for incoming signals and outgoing signals. Each voice channel is designed with the independent DTMF detector, tone detector, Barge-in detector, decoder and recording mixer.


1.21.3 Concerned Terms

· Physical PCM

It indicates the on-board hardware circuit which has the capability of data processing for digital trunks. Unlike that on the SHD Series boards, the PCM on the DTP boards only processes input signals, incapable of outputting signals. That is, the PCM on the DTP Series works in a simplex mode.

See the Digital Trunk section in this chapter for detailed information about the physical PCM.

· PCM Line to Be Monitored (referred to as ‘SpyPCM’ for short in this manual)

SpyPCM is the E1/T1 line parallely connected through high-impedance circuits as shown in the figure above.

Because the E1/T1 line works in the full-duplex mode (one for transmission, one for reception), to record and process the onto-SpyPCM and off-SpyPCM signals at the same time, the board requires two sets of PCM circuits (i.e. the physical PCM) independently for processing the onto-SpyPCM signals and the off-SpyPCM signals. These two physical digital trunks are logically combined with necessary circuits and well able to support the recording and processing of voice signals and signaling messages on SpyPCM.

The application is required to provide the SpyPCM number (i.e. the logical SpyPCM number) while calling relative functions. The logical SpyPCM number is numbered from 0. The binding relationship between this number and the two physical PCM is determined by the configuration items TotalSpyPcm and SpyPcm.

When one of the two physical PCM bound to SpyPcm changes in status, the function SpyGetLinkStatus can be used to obtain the SpyPcm state.

· Circuit in SpyPCM (referred to as ‘SpyCic’ for short in this manual)

SpyCic indicates a specific time slot (circuit) in the SpyPCM. For SS7 signaling, SpyCic is just the CIC field in the TUP or ISUP message; for ISDN PRI and SS1 signaling, SpyCic is the time slot number in PCM.

Each SpyCic has two numbers: the physical number and the logical number. The physical SpyCic number means the SpyCic number in one PCM which corresponds to the time slot number in the same PCM as shown below.

Physical SpyCic Number | 0~14 | 15~29
Corresponding Time Slot Number in PCM | 1~15 | 17~31

The logical SpyCic number is the unified number given to each SpyCic in all PCM involved in the whole application system, beginning with 0. All SpyCic functions provided by the driver take the logical SpyCic number as the input parameter. The mapping relationship between the logical SpyCic number and the physical SpyCic number is determined by the configuration items TotalAppSpyCIC and AppSpyCIC in the [AppSpyCICTable] section in the configuration file. The function SpyGetMaxCic can be used to acquire the total number of SpyCic in the application system.

Because one SpyPCM is bound to two physical PCM, there is an one-to-one correspondence between the logical SpyCic number and the physical SpyCic number. Logically, one SpyCic is made up of two channels in the driver.

· Calling Party Channel & Called Party Channel

The 2 channels bound to SpyCic may serve as either the calling party or the called party in a call. In the SynCTI-provided state machine for signaling analysis, the channel processing the voice signals from the calling party to the called party is named the calling party channel, and that processing the signals from the called party to the calling party is named the called party channel. What you should pay attention is the calling party channel or the called party channel is changeable, depending mainly on the call direction. For example, a channel serves as the called party in a call, so this time it is the calling party channel; however, it may serve as the called party in the next call, then it becomes the called party channel.

The functions SpyGetCallInCh and SpyGetCallOutCh are used respectively to obtain the calling party channel number and the called party channel number for the 2 channels bound to SpyCic in this call. The function SpyChToCic can be used to query the logical SpyCic number according to the channel number.

The SynCTI-provided state machine for signaling analysis is based on SpyCic. However, the application can invoke relative functions for voice processing on any bound channel to acquire DTMF digits and other information in the onto-PCM and off-PCM signals.


1.21.4 Voice Processing on DTP Series Boards


1.21.4.1 DTMF Detection

When the call based on a SpyCic is established, the calling party channel number and the called party channel number in this call can be obtained respectively via the functions SpyGetCallInCh and SpyGetCallOutCh. And those DTMF detection functions having these two numbers contained in their parameters can be invoked to acquire DTMF signals from both parties. For more information about the DTMF detector, refer to the DTMF Detector section in this chapter.


1.21.4.2 Voice Recording

As to the voice recording feature, only the file mode is supported. Relative functions and events are listed below.

Function/Event Name | Description
SpyRecToFile | A function based on the circuit number, used to start the file recording task
SpyStopRecToFile | A function based on the circuit number, used to stop the file recording task
E_PROC_RecordFile | The event thrown out by the driver at the end of the file recording task

Relative configuration items include:

Configuration Item | Description
DspCoder | Sets the coder loaded by an on-board DSP which gives more formats for recording (so far support of GSM and G.729A).

There are many ways available to perform voice recording on the DTP Series boards. Assuming that a SpyCic is made up of a calling party channel (referred to as CallingPartyCh) and a called party channel (referred to as CalledPartyCh), the calling party’s voice (using the default volume) and the called party’s voice (using the default volume) on this SpyCic should be recorded in a mixed way after both parties come into the call. The processing codes for this purpose are written as follows.

SpyRecToFile(SpyCic, 2, “Voc.wav”, 7, 0, 0xffffffff, 0xffffffff, 0);

If the voice recording process should be controlled more precisely, you can use the functions based on the channel. For example, to achieve the above purpose, but to increase the volume of the calling party’s voice by 3DB and decrease that of the called party’s voice by 3DB, the processing codes are as follows.

int CalledPartyCh = SpyGetCallInCh(SpyCic); //obtain the calling party channel number

int CallingPartyCh= SpyGetCallOutCh (SpyCic); //obtain the called party channel number

SsmListenTo(CallingPartyCh, CalledPartyCh); //switch on the switch K1 on CalledPartyCh

SsmSetRecVolume(CalledPartyCh, 1); //start A3, set the volume gain to 1*3DB=3DB

SsmSetRecMixer(CalledPartyCh, TRUE, -1); //start A2, set the volume gain to -1*3DB=-3DB

SsmRecToFile(CalledPartyCh, “Voc.wav”,…); //start the task of file recording …

People who use G.729A or GSM for recording should pay attention that as GSM and G.729A recordings are enabled by extra DSPs, there are limits to use of these two formats. See below for details:

1. One board can use only one of the two formats for recording. That is, it is not allowed to use different formats for different channels. (Use of other formats like A-Law, μ-Law, etc. is not confined to such limit.)

2. You may perform independent-recording or mixed-recording of calling or called channel, but cannot do it of both at the same time.

3. Because the available ways for bus exchange have been locked, when you use the precise volume control mode, parameters of the function SsmListenTo must be calling and called channels for a same CIC. Whereas, for those bus functions with volume parameters, such as SsmListenToEx, the volume parameters will be ignored.


1.21.5 Driver-provided State Machine


1.21.5.1 Universal State Machine Model for Digital Trunk Recording Channel

Below is the SynCTI-provided state machine commonly used by the DTP Series boards.

Every time when the SpyCic state changes, the driver will throw out the E_CHG_SpyState event to the application. The function SpyGetState can be used to obtain the current SpyCic state.


1.21.5.2 Acquisition of Call Information

The functions and events used to obtain the information about the call state machine include:

Function/Event Name | Description
E_CHG_SpyState | This event is thrown out by the driver when the state machine for SS1, ISDN, SS7 TUP or SS7 ISUP changes.
E_CHG_SpyHangupInfo | This event is thrown out by the driver when a disconnect message is detected on the line in ISDN.
SpyGetState | Obtains the SpyCic state.
SpyGetCallerId | Obtains the calling party number in this call.
SpyGetCalleeId | Obtains the called party number in this call.
SpyGetCallInCh | Obtains the calling party channel number in this call.
SpyGetCallOutCh | Obtains the called party channel number in this call.
SpyGetHangupInfo | Obtains the hangup information about this call.


1.21.6 Application and Configuration Instance for DTP Series


1.21.6.1 System Using SS1/ISDN PRI

In the figure above, SpyPCM[0] uses the SS1 protocol while SpyPCM[1] uses the ISDN protocol. This system involves two SHD-30A-CT/PCI/FJ boards. Relative configuration items in the configuration file ShConfig.ini could be set as follows.

[BoardId=0]

∙∙∙∙∙∙

PcmNumber=2

PcmSSx[0]=1 //SS1

PcmSSx[1]=1 //SS1

PcmClockMode[0]=2 //slave clock

PcmClockMode[1]=2 //slave clock

[BoardId=1]

∙∙∙∙∙∙

PcmNumber=2

PcmSSx[0]=0 //ISDN

PcmSSx[1]=0 //ISDN

PcmClockMode[0]=0 //master clock, line synchronization

PcmClockMode[1]=2 //slave clock

[PcmInfo]

TotalPcm=4

Pcm[0]=0,0

Pcm[1]=0,1

Pcm[2]=1,0

Pcm[3]=1,1

[SpyPcm]

TotalSpyPcm=2

SpyPcm[0]=Pcm[0],Pcm[1]

SpyPcm[1]=Pcm[2],Pcm[3]

[AppSpyCICTable]

TotalAppSpyCIC=60 //totally 60 SpyCIC (voice channel)

AppSpyCIC[0]=SpyPcm[0],0..29 //SpyCIC[0] corresponds to Channel 0 and Channel 1, and the like…

AppSpyCIC[30]=SpyPcm[1],0..29


1.21.6.2 System Using SS7

As to the system used to monitor SS7 links, except the above configuration items necessarily set for the system using SS1 or ISDN, the section [SS7Spy] is also required. See below for the typical application.

In the figure above, there are 2 digital trunks between PBX-A and PBX-B. TS16 of SpyPCM[0] serves as the signaling link, using the SS7 TUP protocol. TS16 of SpyPCM[1] is unused while the rest all used as voice channels. Assume SpyPCM[0] is numbered as 4 in the CIC field of the TUP message and SpyPCM[1] is numbered as 5. Taking the TUP protocol for example, you can follow the way below to set the configuration file in the application program.

[BoardId=0]

∙∙∙∙∙∙

PcmNumber=4

PcmSSx[0]=7 //SS7

PcmSSx[1]=7 //SS7

PcmSSx[2]=7 //SS7

PcmSSx[3]=7 //SS7

PcmClockMode[0]=0 //master clock, line synchronization

PcmClockMode[1]=2 //slave clock

PcmClockMode[2]=2 //slave clock

PcmClockMode[3]=2 //slave clock

[PcmInfo]

TotalPcm=4

Pcm[0]=0,0

Pcm[1]=0,1

Pcm[2]=0,2

Pcm[3]=0,3

[SpyPcm]

TotalSpyPcm=2

SpyPcm[0]=Pcm[0],Pcm[1]

SpyPcm[1]=Pcm[2],Pcm[3]

[AppSpyCICTable]

TotalAppSpyCIC=60 //totally 60 SpyCIC (voice channel)

AppSpyCIC[0]=SpyPcm[0],0..29 //SpyCIC[0] corresponds to Channel 0 and Channel 1, and the like…

AppSpyCIC[30]=SpyPcm[1],0..29

[SS7Spy]

TotalSpyLinkSet=1 //totally 1 signaling link set

SpyLinkSet[0]=SpyPcm[0] //set the physical position of the signaling link in the link set

SpyLinkSet[0].SpyCICPcm[4]=SpyPcm[0]

SpyLinkSet[0].SpyCICPcm[5]=SpyPcm[1]

SpySpCodeLen=24 //Set the encoding standard for signaling points: 24bit is the National Signaling Point Code (NSPC) format, 14bit is the International Signaling Point Code (ISPC) format.


2 SynCTI API Function Description


2.1 System Functions


2.1.1 Driver Platform Initialization Functions


2.1.1.1 SsmStartCti

SsmStartCti is the entry function for the entire SynCti API, used to initialize the SynCTI driver platform and voice boards.

Format:

int SsmStartCti( LPSTR lpSsmCfgFileName, LPSTR lpIndexCfgFileName)

Parameter Description:

lpSsmCfgFileName | The name of the configuration file (*.INI). If it’s a NULL string, under the Windows operating system, the driver will automatically use the configuration file ‘ShConfig.ini’ under the system directory; under the Linux operating system, the driver will automatically use the configuration file ‘ShConfig.ini’ under the directory of ‘/etc/shcti/’.
lpIndexCfgFileName | The configuration file for preloading voice data (*.INI). If it’s a NULL string, under the Windows operating system, the driver will automatically use the configuration file ‘ShIndex.ini’ under the system directory; under the Linux operating system, the driver will automatically use the configuration file ‘ShIndex.ini’ under the directory of ‘/etc/shcti/’.

Return Value:

-2 | Initialization is failed, because the driver is loaded
-1 | Initialization is failed, the failure reason can be obtained by SsmGetLastErrMsg
0 | Initialization is successful

Function Description:

It’s the entry of the SynCTI driver program. The following operations will be executed:

l Initializes the voice board;

l If lpIndexCfgFileName is not NULL, the preload voice data will be loaded into the memory from the configuration file ‘lpIndexCfgFileName’;

l Based on the basic information such as the model and quantity of voice board, port address, and interruption number, it registers and initializes a variety of voice boards and allocates the system resources.

l Allocates system resources for voice recording and playback.

l Establishes an interrupt service routine (ISR).

Note:

l Only ‘SsmStartCti’ has been called successfully, the other functions in the driver platform can be called (except SsmGetLastErrMsg and SsmGetLastErrCode).

l Before exiting the application program, SsmCloseCti must be called to close the driver program in order to release the resources occupied by the driver.

l For detailed information about the configuration file, refer to Chapter 4.

l If multiple boards have been configured and only a part of them is successfully initialized, the driver also returns 0. The application program can determine whether all the boards are initialized successfully through the functions SsmGetMaxCfgBoard and SsmGetMaxUsableBoard.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Functions: SsmCloseCti, SsmGetMaxCfgBoard , SsmGetMaxUsableBoard


2.1.1.2 SsmCloseCti

Closes the SynCTI driver program.

Format:

int SsmCloseCti (void)

Parameter Description:

None

Return Value:

1

Successful to close the SynCTI driver program

Function Description:

Closes the SynCTI driver program.

Note:

  • Before the application program exits the operating system, this function must be called.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmStartCti


2.1.2 Setting API Functions and Event Output Mode


2.1.2.1 SsmSetLogEnable

Sets whether to output the logs of specified types and the way to output logs.

Format:

int WINAPI SsmSetLogEnable(int nLogType,int nLogEnable,int nLogCreateMode)

Parameter Description:

nLogType | Log type, with the value range of 0~5: =0: ShCtiApiLog =1: ShCtiSs1Log =2: ShCtiIsdnLog =3: ShCtiSpySs7Log =4: ShCtiSpySs1Log =5: ShCtiSpyIsdnLog
nLogEnable | Determines whether to output logs. When nLogType=0, nLogEnable can be of the following values: =0: Not output logs =1: Output API function calls information to DebugView =2: Output API function calls information to the LOG file =3: Output events information to the LOG file =4: Output both API function calls and events information to the LOG file When nLogType=1, 2, 3, 4, 5, nLogEnable can be of the following values: =0: Not output =1: Output to the LOG file =2: Output to DebugView
nLogCreateMode | The mode to create a log. It gets valid only when nLogEnable is set to output logs. =0: All channel information written into a log file =1: Each channel has an independent log file. This value gets valid only when nLogType=0, 1, 4

Return Value:

-1 | Call failed
0 | Call successful

Function Description:

Sets whether to output the logs of specified types and the way to output logs. No matter to output which type of logs, the driver will create the ShCtiLog folder and save all generated log files in this folder.

The log types described by nLogType are as follows.

Log Type | Definition
ShCtiApiLog | Records information about API function calls and events thrown out by the driver.
ShCtiSs1Log | Records received and sent ABCD codes and R2
ShCtiIsdnLog | Records a frame of messages on the data link layer of ISDN protocol
ShCtiSpySs7Log | Records a frame of messages that the driver receives
ShCtiSpySs1Log | Records information about SS1 CAS and R2 that the driver receives
ShCtiSpyIsdnLog | Records a frame of messages that the driver receives

The following configuration items can be used to achieve the same purpose.

ApiLogEnable

ApiLogCreateMode

Ss1LogEnable

Ss1LogCreateMode

SpySs1LogEnable

SpySs1CreateMode

IsdnLogEnable

SpySs7LogEnable

SpyIsdnLogEnable

Note: None

Related Information:

Driver version | SynCTI Ver.5.1.1.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSetLogAttribute, SsmGetLogAttribute, SsmSetApiLogRange


2.1.2.2 SsmSetLogAttribute

Sets the period to generate a log, the maximum number of saved latest logs, the number of cycles to stop log output and the log output path.

Format:

int WINAPI SsmSetLogAttribute(int nLogCreatePeriod,int nLogMaxKeep,int nLogMaxPeriod,LPSTR pLogFilePath)

Parameter Description:

nLogCreatePeriod | The period to generate a log, calculated by hour, with the value range of nLogCreatePeriod>0.
nLogMaxKeep | When the number of generated log files is greater than the set value of this parameter, the first generated files will be deleted automatically. The value range is nLogMaxKeep >0. If nLogMaxKeep =-1, it means there is no limit on the number to save log files and no log files will be deleted.
nLogMaxPeriod | When the number of log generating periods reaches the set value of this parameter, the log output will be stopped automatically. The value range is nLogMaxPeriod >0. If nLogMaxPeriod = -1, it means there is no limit on the number to generate log files.
pLogFilePath | The path to save logs. Note that it must be a path already existing, such as ‘D:\’, or the function call will fail. If pLogFilePath is set to null, it indicates the current working path; if pLogFilePath is set to a name, a folder with such name will be created under the current working path.

Return Value:

-1 | Call failed
0 | Call successful

Function Description:

Sets the period to generate a log, the maximum number of saved latest logs, the number of cycles to stop log output and the log output path.

Settings of this function are valid to the following logs.

Log Type | Definition
ShCtiApiLog | Records information about API function calls and events thrown out by the driver.
ShCtiSs1Log | Records received and sent ABCD codes and R2
ShCtiIsdnLog | Records a frame of messages on the data link layer of ISDN protocol
ShCtiSpySs7Log | Records a frame of messages that the driver receives
ShCtiSpySs1Log | Records information about SS1 CAS and R2 that the driver receives
ShCtiSpyIsdnLog | Records a frame of messages that the driver receives

The following configuration items can be used to achieve the same purpose.

LogCreatePeriod

LogMaxKeep

LogMaxPeriod

LogFilePath

Note: None

Related Information:

Driver version | SynCTI Ver.5.1.1.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSetLogEnable, SsmGetLogAttribute, SsmSetApiLogRange


2.1.2.3 SsmSetApiLogRange

Sets the range of channels where events and API functions should be written into the log and the range of events that should be recorded into the log.

Format:

int WINAPI SsmSetApiLogRange(int nChStart, int nChEnd, int nEventStart, int nEventEnd)

Parameter Description:

nChStart | Indicates the start channel number for logging events and API functions. When nChStart=-1, it means the channel range is <nChEnd.
nChEnd | Indicates the end channel number for logging events and API functions. When nChEnd=-1, it means the channel range is >nChStart.
nEventStart | Indicates the start event number that should be written into the log. When nEventStart =-1, it means the event range is <nEventEnd.
nEventEnd | Indicates the end event number that should be written into the log. When nEventEnd=-1, it means the event range is >nEventStart.

Return Value:

-1 | Call failed, the failure reason can be obtained from the function SsmGetLastErrMsg
0 | Call successful

Function Description:

Sets the range of channels where events and API functions should be written into the log and the range of events that should be recorded into the log on condition that ApiLogEnable is set to output logs.

The following configuration items can be used to achieve the same purpose.

ApiLogSetEventRange

ApiLogSetChRange

Note: None

Related Information:

Driver version | SynCTI Ver. 5.1.1.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSetLogEnable, SsmSetLogAttribute, SsmGetLogAttribute


2.1.2.4 SsmGetLogAttribute

Gets the period to generate a log, the maximum number of saved latest logs, the number of cycles to stop log output and the log output path.

Format:

int WINAPI SsmGetLogAttribute(PINT pLogCreatePeriod,PINT pLogMaxKeep,PINT pLogMaxPeriod,LPSTR pLogFilePath)

Parameter Description:

pLogCreatePeriod | The period to generate a log, calculated by hour, with the value range of pLogCreatePeriod>0.
pLogMaxKeep | When the number of generated log files is greater than the set value of this parameter, the first generated files will be deleted automatically. The value range is pLogMaxKeep >0. If pLogMaxKeep =-1, it means there is no limit on the number to save log files and no log files will be deleted.
pLogMaxPeriod | When the number of log generating periods reaches the set value of this parameter, the log output will be stopped automatically. The value range is pLogMaxPeriod >0. If pLogMaxPeriod = -1, it means there is no limit on the number to generate log files.
pLogFilePath | The path to save logs. Note that it must be a path already existing, such as ‘D:\’, or the function call will fail. If pLogFilePath is set to null, it indicates the current working path; if pLogFilePath is set to a name, a folder with such name will be created under the current working path.

Return Value:

-1 | Call failed
0 | Call successful

Function Description:

Gets the period to generate a log, the maximum number of saved latest logs, the number of cycles to stop log output and the log output path.

Note: None

Related Information:

Driver version | SynCTI Ver.5.1.1.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSetLogEnable, SsmSetLogAttribute, SsmSetApiLogRange


2.1.3 Timer Functions


2.1.3.1 SsmStartTimer

Is applicable to the driver for a system timer.

Format:

int SsmStartTimer(WORD wDelay, WORD wMode)

Parameter Description:

wDelay | The initial value (millisecond) of the timer, range of value: 0x0008~0xffff
wMode | Sets the timer operating mode: =0(TIMER_ONE): One-shot mode: Once the timer overflows, it stops automatically =1(TIMER_PERIODIC): Periodic mode: Every time when the timer overflows, the driver program automatically reloads the initial value wDelay until the application program calls SsmStopTimer

Return Value:

-1 | Failed
≥0 | The timer application is successful and ‘SsmStartTimer’ returns the timer ID

Function Description:

The application is applicable to the driver for a system timer and sets the operating parameter of the timer. Every time when the timer overflows, the driver throws out an event E_SYS_TIMEOUT For more details, refer to ‘Driver-provided Timer’ in Chapter 1.

Note:

l This function must be called after SsmSetEvent, otherwise the driver won’t output the event TIMEOUT.

Related Information:

Driver version | SynCTI Ver.4.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Functions: SsmStopTimer，StartTimer

Related Events: E_SYS_TIMEOUT


2.1.3.2 SsmStopTimer

Stops a Timer.

Format:

int SsmStopTimer(int nTimer)

Parameters Description:

nTimer

Timer ID ,the return value of SsmStartTimer

Return Value:

-1 | Failed
0 | Successful

Function Description:

Stops a timer which is started by SsmStartTimer .

Note:

Related Information:

Driver version: | SynCTI Ver. 4.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmStartTimer


2.1.3.3 StartTimer

Starts a channel timer.

Format:

int StartTimer(int ch, WORD wClockID)

Parameter Description:

ch | Channel Number
wClockID | Timer ID, range of value: 0~9

Return Value:

-1 | Failed
0 | Successful

Function Description:

Starts a channel timer.

After the channel timer has been started, the driver only saves the current time in a variable and doesn’t determine whether the timer overflows. Only when the application calls the function of ElapseTime, will the driver return the timer elapsed time.

Note:

l The timer started by StartTimer() doesn’t output any events.

Related Information:

Driver version | SynCTI Ver. 4.7.1.5 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: ElapseTime


2.1.3.4 ElapseTime

Obtains the elapsed time since the channel timer is started.

Format:

DWORD ElapseTime(int ch, WORD ClockType)

Parameter Description:

ch | Channel number
ClockType: | Timer ID, value range: 0~9

Return Value:

Elapsed time, the value is n x 8ms, n=1, 2, 3…

Function Description:

Obtains the elapsed time since the channel timer is started.

Note:

Related Information:

Driver version | SynCTI Ver. 4.7.1.5 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: StartTimer


2.1.4 Functions to Get System Error Messages


2.1.4.1 SsmGetLastErrCode

Obtains the error code when the application is failed to call the API functions.

Format:

int SsmGetLastErrCode()

Parameter Description:

None

Return Value:

Below are the return values:

Return Value | Macro in shpa3api.h | Description
0 | C_ERROR_INIT_FAILURE | Initialization is failed
1 | C_ERROR_SSMAPI_UNOPENED | The API interface of the driver is not open to the application
2 | C_ERROR_INVALID_APPCH | Invalid channel number
3 | C_ERROR_UNSUPPORTED_OP | Unsupported operation
4 | C_ERROR_INDEX_UNOPENED | The function of the voice playback via memory is not open to application
5 | C_ERROR_INVALID_BUSCH | Invalid logical number of the CT-Bus channel
6 | C_ERROR_OP_UNOPENED | The specified operation is not open to the application
7 | C_ERROR_INVALID_FORMAT | Invalid voice CODEC format
8 | C_ERROR_INVALID_PARAMETER | Invalid parameters
9 | C_ERROR_FILEOP_FAILURE | File operation failed
10 | C_ERROR_MEMORY_FAILURE | Memory access failed
11 | C_ERROR_RESOURCE_USEUP | The related resource is exhausted
12 | C_ERROR_SYSTEM | System error
13 | C_ERROR_IdleChNotFound | No idle channel is available
14 | C_ERROR_OP_FAILURE | Operation failed
15 | C_ERROR_INVALID_APPSPYCIC | Invalid monitored CIC(Circuit Identification Code) number
16 | C_ERROR_FAX_NOFILE | Fax file error
17 | C_ERROR_VCH_INVALID_SCALE | Parameter value is out of range

Function Description:

Obtains the error code when the application is failed to call the API functions.

Note:

Related Information:

Driver version | SynCTI Ver.3.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function:SsmGetLastErrMsg


2.1.4.2 SsmGetLastErrMsg

Refer to SsmGetLastErrMsgA


2.1.4.3 SsmGetLastErrMsgA

Obtains the error message generated by the last failed API function call.

Format:

void SsmGetLastErrMsg(LPSTR szErrMsgBuf)

char* SsmGetLastErrMsgA(void)

Parameter Description:

szErrMsgBuf

The first address pointer pointing to the string which stores error messages. The storage buffer is allocated by the application and no less than 300 bytes

Return Value:

void | Nil
char* | The first address pointer pointing to the string which stores error messages in the driver

Function Description:

Obtains the error message generated by the last failed API function call.

Note:

l Needs to be called immediately upon the failure of the API function call.

Related Information:

Driver version | SynCTI Ver.2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetLastErrCode


2.1.4.4 fBmp_GetErrMsg

Obtains the error message generated by the last failed function call of Bmp.

Format:

void fBmp_GetErrMsg(char *buf)

Parameter Description:

buf

Pointer pointing to the buffer area storing the error information string

Return Value: None

Function Description:

When the function call of Bmp is failed, the driver will provide the detailed error message and the error code which can be obtained by invoking this function.

Note:

Related Information:

Driver Version | SynCTI Ver. 2.0 or above
Header | BmpApi.h
Library | BmpUtil.lib
DLL | BmpUtil.dll

Related Function:


2.1.5 Functions to Obtain Board Information


2.1.5.1 Obtaining Installed Board Information


2.1.5.1.1 SsmGetMaxCfgBoard

Obtains the total number of the voice boards which is set in the configuration file.

Format:

int SsmGetMaxCfgBoard()

Parameter Description: None

Return Value:

-1 | Failed
≥0 | Returns the total number of the boards

Function Description:

Obtains the total number of the voice boards which is set in the configuration file.

Note: None.

Related Information:

Driver version | SynCTI Ver. 3.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetMaxUsableBoard


2.1.5.1.2 SsmGetMaxUsableBoard

Obtains the total number of the boards which are successfully initialized by the driver.

Format:

int SsmGetMaxUsableBoard()

Parameter Description: None

Return Value:

-1 | Failed
≥0 | Maximum usable boards number

Function Description:

Obtains the total number of the boards which are successfully initialized by the driver.

Note: None.

Related Information:

Driver version | SynCTI Ver. 3.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetMaxCfgBoard


2.1.5.1.3 GetTotalPciBoard

Obtains the total number of the installed boards in the system.

Format:

int GetTotalPciBoard(int *pTotalBoards)

Parameter Description:

pTotalBoards

The integer pointer storing the total number of boards

Return Value:

-1 | Call failed
0 | Successful

Function Description:

Obtains the total number of the installed boards in the system. If this function is called successfully, the total number of the boards will be put into pTotalBoards.

Note:

This function call can be performed without the control of Shp_a3.dll. The total number of installed boards can be obtained directly. Because this function can be called before Shp_a3.dll is started, the configuration file of ShConfig.ini may be modified by some application program to ensure the successful call of the function SsmStartCti.

If you install or uninstall a board after the load of Shinitpci.dll, you should invoke ReloadPciBoardInfo before invoking this function to get the latest information.

Related Information:

Driver Version | Independent of SynCTI driver
Header | Shinitpci.h
Library | Shinitpci.lib
DLL | Shinitpci.dll

Related Functions: GetPciBoardSerialNo, GetPciBoardModel, ReloadPciBoardInfo


2.1.5.1.4 ReloadPciBoardInfo

Rereads the board information.

Format:

int ReloadPciBoardInfo()

Parameter Description: None

Return Value:

-1 | Call failed
0 | Successful

Function Description:

Rereads the board information. Usually it is invoked only after a board is installed or uninstalled

The information about GetPciBoardSerialNo, GetPciBoardModel and GetTotalPciBoard has been initialized in loading Shinitpci.dll.

If you install or uninstall a board after the load of Shinitpci.dll, you should invoke this function before invoking others in Shinitpci.dll.

Note:

This function call can be performed without the control of Shp_a3.dll.

Related Information:

Driver Version | Independent of SynCTI driver
Header | Shinitpci.h
Library | Shinitpci.lib
DLL | Shinitpci.dll

Related Functions: GetTotalPciBoard, GetPciBoardSerialNo, GetPciBoardModel


2.1.5.2 Obtaining Board Authorization Code


2.1.5.2.1 SsmGetAccreditId

Refer to SsmGetAccreditIdEx


2.1.5.2.2 SsmGetAccreditIdEx

Obtains the authorization code saved in the board firmware. The return values of SsmGetAccreditId() include the board model and authorization code. SsmGetAccreditIdEx() only returns the authorization code.

Format:

int SsmGetAccreditId(int nBId)

int SsmGetAccreditIdEx(int nBId)

Parameter Description:

nBId

The board ID number specified in the configuration file

Return Value:

-1 | Call failed, the failure reason can be acquired from the function SsmGetLastErrMsg
0 | There is no authorization code on the board
>0 | SsmGetAccreditId | Return value includes 16 bits, namely Bit15…Bit0: Bit15~Bit10：Board model Bit 9~Bit0 ：Authorization code
 | SsmGetAccreditIdEx | Returns the authorization code

Function Description:

Obtains the authorization code saved in the board firmware.

Note:

Related Information:

Driver version | SynCTI Ver.3.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetBoardModel


2.1.5.3 Obtaining Board Model


2.1.5.3.1 SsmGetBoardModel

Obtains the board model.

Format:

int SsmGetBoardModel(int nBId)

Parameter Description:

nBId

The board ID specified in the configuration file

Return Value:

If the return value is -1,the call failed (the failure reason can be obtained by function SsmGetLastErrMsg); If the return value is not -1, below are the corresponding models :

Return Value | Board Model
0x07 | SHD-60A-CT/PCI/SS1
0x09 | SHT-16A-CT/PCI
0x0a | SHT-8A/PCI
0x0b | SHD-60A-CT/PCI/SS7
0x0c | SHD-60A-CT/PCI/ISDN
0x0d | SHD-120A-CT/PCI/SS1
0x0e | SHD-120A-CT/PCI/SS7
0x0f | SHD-120A-CT/PCI/ISDN
0x14 | SHT-16B-CT/cPCI
0x15 | SHD-60A-CT/PCI/FJ
0x16 | SHD-30A-CT/cPCI
0x17 | SHD-60A-CT/cPCI
0x18 | SHD-120A-CT/cPCI
0x1d | SHD-30A-CT/PCI/SS1
0x1e | SHD-30A-CT/PCI/SS7
0x1f | SHD-30A-CT/PCI/ISDN
0x20 | SHD-30A-CT/PCI/FJ
0x24 | SHT-16B-CT/PCI
0x25 | SHT-16B-CT/PCI/FAX 或 SHT-16B-CT/PCI/MP3 [1]
0x26 | SHT-8B/PCI
0x27 | SHT-8B/PCI/FAX
0x28 | SHD-30B-CT/PCI/FAX
0x29 | SHD-60B-CT/PCI/FAX
0x2c | SHD-240A-CT/cPCI
0x2d | SHD-480A-CT/cPCI
0x2f | SHD-240S-CT/cPCI
0x30 | SHD-480S-CT/cPCI
0x31 | SHT-16B-CT/cPCI/MP3
0x32 | SHT-16B-CT/cPCI/FAX 或 SHT-16B-CT/cPCI/MP3 [1]
0x36 | SHD-60B-CT/cPCI/FAX
0x3b | SHR-16DA-CT/PCI
0x43 | DST-1600
0x46 | SHT-2A/USB
0x47 | SHT-4A/USB
0x4b | SHD-30C-CT/PCI
0x4c | SHD-30C-CT/PCI/FAX
0x4d | SHD-60C-CT/PCI
0x4e | SHD-60C-CT/PCI/FAX
0x55 | SHV-120A-CT/PCI
0x56 | SHV-240A-CT/PCI
0x57 | SHD-240D-CT/PCI
0x58 | SHD-240D-CT/PCI/EC
0x59 | SHD-120D-CT/PCI
0x5a | SHD-120D-CT/PCI/EC
0X5b | SHT-8C/PCI/FAX
0x5c | SHT-16C-CT/PCI/FAX
0x5d | SHN-32A-CT/PCI
0x5f | SHT-2B/USB
0x60 | SHT-4B/USB
0x65 | SHV-240A-CT/cPCI
0x66 | SHD-30B-CT/PCI/FJ
0x67 | SHD-60B-CT/PCI/FJ
0x68 | ATP-24A/PCI
0x69 | DST-24B/PCI
0x69 | DST-24B/PCI(SSW)
0x6a | SHT-16C-CT/PCI/EC
0x6b | SHT-8C/PCI/EC
0x6c | ATP-24A/PCI+
0x6d | SHN-120B-CT/PCI+
0x6e | DST-24B/PCI+
0x6e | DST-24B/PCI+(SSW)
0x6f | DTP-30C/PCIe
0x70 | DTP-30C/PCIe+
0x71 | DTP-60C/PCIe
0x72 | DTP-60C/PCIe+
0x73 | DTP-120C/PCIe
0x74 | DTP-120C/PCIe+
0x75 | SHD-30E-CT/PCIe
0x76 | SHD-30E-CT/PCIe/EC
0x77 | SHD-30E-CT/PCIe/FAX
0x78 | SHD-60E-CT/PCIe
0x79 | SHD-60E-CT/PCIe/EC
0x7a | SHD-60E-CT/PCIe/FAX
0x7b | SHD-120E-CT/PCIe
0x7c | SHD-120E-CT/PCIe/EC
0x7d | SHD-120E-CT/PCIe/FAX
0x7e | SHD-240E-CT/PCIe
0x7f | SHD-240E-CT/PCIe/EC
0x80 | SHD-240E-CT/PCIe/FAX
0x83 | SHN-60B-CT/PCI+
0x84 | ATP-24A/PCIe
0x85 | ATP-24A/PCIe+
0x86 | SHD-120D-CT/PCI/CAS
0x87 | SHD-240D-CT/PCI/CAS
0x88 | SHN-32B-CT/PCI+
0x89 | SHN-16B-CT/PCI+
0x8a | SHN-8B-CT/PCI+
0x8b | DST-24B/PCIe
0x8c | DST-24B/PCIe+
0x8e | SHD-120E-CT/PCI(ssw)
0x8f | SHD-120E-CT/PCI/EC(ssw)
0x90 | SHD-120E-CT/PCI/FAX(ssw)
0x91 | SHD-240E-CT/PCI(ssw)
0x92 | SHD-240E-CT/PCI/EC(ssw)
0x93 | SHD-240E-CT/PCI/FAX(ssw)
0x94 | SHD-30E-CT/PCI(ssw)
0x95 | SHD-30E-CT/PCI/EC(ssw)
0x96 | SHD-30E-CT/PCI/FAX(ssw)
0x97 | SHD-60E-CT/PCI(ssw)
0x98 | SHD-60E-CT/PCI/EC(ssw)
0x99 | SHD-60E-CT/PCI/FAX(ssw)
0x9d | DTP-30C/PCI
0x9e | DTP-30C/PCI+
0x9f | DTP-60C/PCI
0xa0 | DTP-60C/PCI+
0xa1 | DTP-120C/PCI
0xa2 | DTP-120C/PCI+

Note[1]: The SHT-16B-CT/PCI/FAX board and the SHT-16B-CT/PCI/MP3 board differ in the hardware structure. However, they have the same board ID written in the firmware due to historical reasons.The configuration item DSP3WORKMODE is used to distinguish these two board models.

Function Description:

Obtains the board model.

Note:

Related Information:

Driver version | SynCTI Ver.3.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetAccreditIdEx, SsmGetAccreditId


2.1.5.3.2 GetPciBoardModel

Obtains the board model.

Format:

int GetPciBoardModel(int nBId, LPSTR lpBoardModel)

Parameter Description:

nBId | The ID number of the actually installed board
lpBoardModel | The model of the board with designated number, it’s denoted in the below list of strings

Board Model & Corresponding String

Return Value | Meaning
“SHD-60A-CT/PCI/SS1” | 60-channel PCI SS1 board
“SHD-60A-CT/PCI/SS7” | 60-channel PCI SS7 board
“SHD-60A-CT/PCI/ISDN” | 60-channel PCI ISDN board
“SHD-120A-CT/PCI/SS1” | 120-channel PCI SS1 board
“SHD-120A-CT/PCI/SS7” | 120-channel PCI SS7 board
“SHD-120A-CT/PCI/ISDN” | 120-channel PCI ISDN board
“SHD-60B-CT/PCI/FAX” | 60-channel PCI B-type board, configurable to be a signaling board with fax channels
“SHD-30B-CT/PCI/FAX” | 30-channel PCI B-type board, configurable to be a signaling board with fax channels
“SHD-30A-CT/PCI/SS1” | 30-channel PCI SS1 board
“SHD-30A-CT/PCI/SS7” | 30-channel PCI SS7 board
“SHD-30A-CT/PCI/ISDN” | 30-channel PCI ISDN board
“SHD-30A-CT/PCI/FJ” | 30-channel PCI A-type board, supporting high-impedance parallel connection
“SHD-60A-CT/PCI/FJ” | 60-channel PCI A-type board, supporting high-impedance parallel connection
“SHD-30B-CT/PCI/FJ” | 30-channel PCI B-type board, supporting high-impedance parallel connection
“SHD-60B-CT/PCI/FJ” | 60-channel PCI B-type board, supporting high-impedance parallel connection
“SHT-16B-CT/PCI/FAX or SHT-16B-CT/PCI/MP3 [1]” | 16-channel PCI B-type call-recording board, supporting soft faxing or MP3 codec.
“SHT-8B/PCI” | 8-channel PCI B-type board
“SHT-8B/PCI/FAX” | 8-channel PCI B-type board with soft-faxing component
“SHT-8C/PCI/FAX” | 8-channel PCI C-type board with soft-faxing component
“SHT-8C/PCI/EC” | 8-channel PCI C-type board
“SHT-16C-CT/PCI/EC” | 16-channel PCI C-type board
“SHT-16B-CT/PCI” | 16-channel PCI B-type board
“SHT-16C-CT/PCI/FAX” | 16-channel PCI C-type board with soft-faxing component
“SHT-16A-CT/PCI/FAX” | 16-channel PCI A-type board with soft-faxing component
“DST-1600” | 16-channel PCI B-type board
“SHT-16B-CT/cPCI” | 16-channel cPCI B-type board
“SHD-30A-CT/cPCI” | 30-channel cPCI board, supporting SS1, ISDN and SS7
“SHD-60A-CT/cPCI” | 60-channel cPCI board, supporting SS1, ISDN and SS7
“SHT-16B-CT/cPCI/MP3 or SHT-16B-CT/cPCI/FAX” | 16-channel cPCI B-type call-recording board, supporting MP3 Codec or soft faxing
“SHD-480A-CT/cPCI” | 16E1 cPCI board, supporting teleconferencing
“SHD-480S-CT/cPCI” | 16E1 cPCI board, not supporting teleconferencing
“SHD-60B-CT/cPCI/FAX” | 60-channel cPCI B-type board, configurable to be a signaling board with fax channels
“SHR-16DA-CT/PCI” | 16-channel PCI digital station tap board
“SHR-24DA-CT/PCI” | 24-channel PCI digital station tap board
“SHT-120A-CT/PCI” | 120-channel PCI high-capacity analog board
“SHT-2B/USB” | 2-channel B-type analog board, including USB interface
“SHT-4B/USB” | 4-channel B-type analog board, including USB interface
“SHT-2A/USB” | 2-channel A-type analog board, including USB interface
“SHT-4A/USB” | 4 channel A-type analog board, including USB interface
“SHT-120A-CT/cPCI” | 120-channel cPCI high-capacity analog board
“SHD-240D-CT/PCI” | 8E1/T1 PCI digital trunk board
“SHD-240D-CT/PCI/EC” | 8E1/T1 PCI digital trunk board, having enhanced capability in echo cancellation
“SHD-120D-CT/PCI” | 4E1/T1 PCI digital trunk board
“SHD-120D-CT/PCI/EC” | 4E1/T1 PCI digital trunk board, having enhanced capability in echo cancellation
“SHD-120D-CT/PCI/CAS” | 4E1 PCI digital trunk board, support of SS1
“SHD-240D-CT/PCI/CAS” | 8E1 PCI digital trunk board, support of SS1
“SHD-30C-CT/PCI” | 30-channel PCI C-type board
“SHD-30C-CT/PCI/FAX” | 30-channel PCI C-type board with soft-faxing component
“SHD-60C-CT/PCI” | 60-channel PCI C-type board
“SHD-60C-CT/PCI/FAX” | 60-channel PCI C-type board with soft-faxing component
“DTP-30C/PCI” | 30-channel PCI board, supporting high-impedance parallel connection
“DTP-30C/PCI+” | 30-channel PCI board, supporting high-impedance parallel connection
“DTP-60C/PCI” | 60-channel PCI board, supporting high-impedance parallel connection
“DTP-60C/PCI+” | 60-channel PCI board, supporting high-impedance parallel connection
“DTP-120C/PCI” | 120-channel PCI board, supporting high-impedance parallel connection
“DTP-120C/PCI+” | 120-channel PCI board, supporting high-impedance parallel connection
“DTP-30C/PCIe” | 30-channel PCIe board, supporting high-impedance parallel connection
“DTP-30C/PCIe+” | 30-channel PCIe board, supporting high-impedance parallel connection
“DTP-60C/PCIe” | 60-channel PCIe board, supporting high-impedance parallel connection
“DTP-60C/PCIe+” | 60-channel PCIe board, supporting high-impedance parallel connection
“DTP-120C/PCIe” | 120-channel PCIe board, supporting high-impedance parallel connection
“DTP-120C/PCIe+” | 120-channel PCIe board, supporting high-impedance parallel connection
“SHN-32A-CT/PCI” | 32-channel VoIP A-type board
“SHN-8B-CT/PCI+” | 8-channel VoIP B-type board
“SHN-16B-CT/PCI+” | 16-channel VoIP B-type board
“SHN-32B-CT/PCI+” | 32-channel VoIP B-type board
“SHN-60B-CT/PCI+” | 60-channel VoIP B-type board
“SHN-120B-CT/PCI+” | 120-channel VoIP B-type board
“ATP-24A/PCI” | ATP-24A/PCI analog tap passive board
“ATP-24A/PCI+” | ATP-24A/PCI+ analog tap passive board
“ATP-24A/PCIe” | ATP-24A/PCIe analog tap passive board
“ATP-24A/PCIe+” | ATP-24A/PCIe+ analog tap passive board
“DST-24B/PCI” | 24-channel PCI B-type digital station tap board
“DST-24B/PCI(SSW)” | 24-channel PCI B-type digital station tap board
“DST-24B/PCI+” | 24-channel PCI B-type digital station tap board with enhanced capability
“DST-24B/PCI+(SSW)” | 24-channel PCI B-type digital station tap board with enhanced capability
“DST-24B/PCIe” | 24-channel PCIe B-type digital station tap board
“DST-24B/PCIe+” | 24-channel PCIe B-type digital station tap board with enhanced capability
SHD-30E-CT/PCI(ssw) | 1 E1/T1/J1 PCI digital trunk board
SHD-30E-CT/PCI/FAX(ssw) | 1 E1/T1/J1 PCI digital trunk board with soft-faxing component
SHD-30E-CT/PCI/EC(ssw) | 1 E1/T1/J1 PCI digital trunk board, having enhanced capability in echo cancellation
SHD-60E-CT/PCI(ssw) | 2 E1/T1/J1 PCI digital trunk board
SHD-60E-CT/PCI/FAX(ssw) | 2 E1/T1/J1 PCI digital trunk board with soft-faxing component
SHD-60E-CT/PCI/EC(ssw) | 2 E1/T1/J1 PCI digital trunk board, having enhanced capability in echo cancellation
SHD-120E-CT/PCI(ssw) | 4 E1/T1/J1 PCI digital trunk board
SHD-120E-CT/PCI/FAX(ssw) | 4 E1/T1/J1 PCI digital trunk board with soft-faxing component
SHD-120E-CT/PCI/EC(ssw) | 4 E1/T1/J1 PCI digital trunk board, having enhanced capability in echo cancellation
SHD-240E-CT/PCI(ssw) | 8 E1/T1/J1 PCI digital trunk board
SHD-240E-CT/PCI/FAX(ssw) | 8 E1/T1/J1 PCI digital trunk board with soft-faxing component
SHD-240E-CT/PCI/EC(ssw) | 8 E1/T1/J1 PCI digital trunk board, having enhanced capability in echo cancellation
SHD-30E-CT/PCIe | 1 E1/T1/J1 PCIe digital trunk board
SHD-30E-CT/PCIe/FAX | 1 E1/T1/J1 PCIe digital trunk board with soft-faxing component
SHD-30E-CT/PCIe/EC | 1 E1/T1/J1 PCIe digital trunk board, having enhanced capability in echo cancellation
SHD-60E-CT/PCIe | 2 E1/T1/J1 PCIe digital trunk board
SHD-60E-CT/PCIe/FAX | 2 E1/T1/J1 PCIe digital trunk board with soft-faxing component
SHD-60E-CT/PCIe/EC | 2 E1/T1/J1 PCIe digital trunk board, having enhanced capability in echo cancellation
SHD-120E-CT/PCIe | 4 E1/T1/J1 PCIe digital trunk board
SHD-120E-CT/PCIe/FAX | 4 E1/T1/J1 PCIe digital trunk board with soft-faxing component
SHD-120E-CT/PCIe/EC | 4 E1/T1/J1 PCIe digital trunk board, having enhanced capability in echo cancellation
SHD-240E-CT/PCIe | 8 E1/T1/J1 PCIe digital trunk board
SHD-240E-CT/PCIe/FAX | 8 E1/T1/J1 PCIe digital trunk board with soft-faxing component
SHD-240E-CT/PCIe/EC | 8 E1/T1/J1 PCIe digital trunk board, having enhanced capability in echo cancellation

Return Value:

0 | Successful
-1 | Failed

Function Description:

This function obtains the model of the board with designated ID number. If this function is successfully called, the model will be put in lpBoardModel.

Note:

This function call can be performed without the control of Shp_a3.dll. The model of installed boards in the operating system can be obtained directly.

If you install or uninstall a board after the load of Shinitpci.dll, you should invoke ReloadPciBoardInfo before invoking this function to get the latest information.

Related Information:

Driver Version | Independent of SynCTI driver
Header | Shinitpci.h
Library | Shinitpci.lib
DLL | Shinitpci.dll

Related Function: GetTotalPciBoard，GetPciBoardSerialNo, ReloadPciBoardInfo


2.1.5.3.3 SsmGetBoardName

Obtains the board model.

Format:

int SsmGetBoardName (int nBId, LPSTR lpBoardModel)

Parameter Description:

nBId | The board ID specified in the configuration file
lpBoardModel | The model of the board with designated number, it’s denoted in the below list of strings

Board Model & Corresponding String

Return Value | Meaning
“SHD-60A-CT/PCI/SS1” | 60-channel PCI SS1 board
“SHD-60A-CT/PCI/SS7” | 60-channel PCI SS7 board
“SHD-60A-CT/PCI/ISDN” | 60-channel PCI ISDN board
“SHD-120A-CT/PCI/SS1” | 120-channel PCI SS1 board
“SHD-120A-CT/PCI/SS7” | 120-channel PCI SS7 board
“SHD-120A-CT/PCI/ISDN” | 120-channel PCI ISDN board
“SHD-60B-CT/PCI/FAX” | 60-channel PCI B-type board, configurable to be a signaling board with fax channels
“SHD-30B-CT/PCI/FAX” | 30-channel PCI B-type board, configurable to be a signaling board with fax channels
“SHD-30A-CT/PCI/SS1” | 30-channel PCI SS1 board
“SHD-30A-CT/PCI/SS7” | 30-channel PCI SS7 board
“SHD-30A-CT/PCI/ISDN” | 30-channel PCI ISDN board
“SHD-30A-CT/PCI/FJ” | 30-channel PCI A-type board, supporting high-impedance parallel connection
“SHD-60A-CT/PCI/FJ” | 60-channel PCI A-type board, supporting high-impedance parallel connection
“SHD-30B-CT/PCI/FJ” | 30-channel PCI B-type board, supporting high-impedance parallel connection
“SHD-60B-CT/PCI/FJ” | 60-channel PCI B-type board, supporting high-impedance parallel connection
“SHT-16B-CT/PCI/FAX or SHT-16B-CT/PCI/MP3 [1]” | 16-channel PCI B-type call-recording board, supporting soft faxing or MP3 codec
“SHT-8B/PCI” | 8-channel PCI B-type board
“SHT-8B/PCI/FAX” | 8-channel PCI B-type board with soft-faxing component
“SHT-8C/PCI/FAX” | 8-channel PCI C-type board with soft-faxing component
“SHT-8C/PCI/EC” | 8-channel PCI C-type board
“SHT-16C-CT/PCI/EC” | 16-chennel PCI C-type board
“SHT-16B-CT/PCI” | 16-channel PCI B-type board
“SHT-16C-CT/PCI/FAX” | 16-channel PCI C-type board with soft-faxing component
“SHT-16A-CT/PCI/FAX” | 16-channel PCI A-type board with soft-faxing component
“DST-1600” | 16-channel PCI B-type board
“SHT-16B-CT/cPCI” | 16-channel cPCI B-type board
“SHD-30A-CT/cPCI” | 30-channel cPCI board, supporting SS1, ISDN and SS7
“SHD-60A-CT/cPCI” | 60-channel cPCI board, supporting SS1, ISDN and SS7
“SHT-16B-CT/cPCI/MP3 or SHT-16B-CT/cPCI/FAX” | 16-channel cPCI B-type call-recording board, supporting MP3 codec or soft faxing
“SHD-480A-CT/cPCI” | 16E1 cPCI board, supporting teleconferencing
“SHD-480S-CT/cPCI” | 16E1 cPCI board, not supporting teleconferencing
“SHD-60B-CT/cPCI/FAX” | 60-channel cPCI B-type board, configurable to be a signaling board with fax channels
“SHR-16DA-CT/PCI” | 16-channel PCI digital station tap board
“SHR-24DA-CT/PCI” | 24-channel PCI digital station tap board
“SHT-120A-CT/PCI” | 120-channel PCI high-capacity analog board
“SHT-2B/USB” | 2-channel B-type analog board, including USB interface
“SHT-4B/USB” | 4-channel B-type analog board, including USB interface
“SHT-2A/USB” | 2-channel A-type analog board, including USB interface
“SHT-4A/USB” | 4-channel A-type analog board, including USB interface
“SHT-120A-CT/cPCI” | 120-channel cPCI high-capacity analog board
“SHD-240D-CT/PCI” | 8E1/T1 PCI digital trunk board
“SHD-240D-CT/PCI/EC” | 8E1/T1 PCI digital trunk board, having enhanced capability in echo cancellation
“SHD-120D-CT/PCI” | 4E1/T1 PCI digital trunk board
“SHD-120D-CT/PCI/EC” | 4E1/T1 PCI digital trunk board, having enhanced capability in echo cancellation
“SHD-120D-CT/PCI/CAS” | 4E1 PCI digital trunk board, support of SS1
“SHD-240D-CT/PCI/CAS” | 8E1 PCI digital trunk board, support of SS1
“SHD-30C-CT/PCI” | 30-channel PCI C-type board
“SHD-30C-CT/PCI/FAX” | 30-channel PCI C-type board with soft-faxing component
“SHD-60C-CT/PCI” | 60-channel PCI C-type board
“SHD-60C-CT/PCI/FAX” | 60-channel PCI C-type board with soft-faxing component
“DTP-30C/PCI” | 30-channel PCI board, supporting high-impedance parallel connection
“DTP-30C/PCI+” | 30-channel PCI board, supporting high-impedance parallel connection
“DTP-60C/PCI” | 60-channel PCI board, supporting high-impedance parallel connection
“DTP-60C/PCI+” | 60-channel PCI board, supporting high-impedance parallel connection
“DTP-120C/PCI” | 120-channel PCI board, supporting high-impedance parallel connection
“DTP-120C/PCI+” | 120-channel PCI board, supporting high-impedance parallel connection
“DTP-30C/PCIe” | 30-channel PCIe board, supporting high-impedance parallel connection
“DTP-30C/PCIe+” | 30-channel PCIe board, supporting high-impedance parallel connection
“DTP-60C/PCIe” | 60-channel PCIe board, supporting high-impedance parallel connection
“DTP-60C/PCIe+” | 60-channel PCIe board, supporting high-impedance parallel connection
“DTP-120C/PCIe” | 120-channel PCIe board, supporting high-impedance parallel connection
“DTP-120C/PCIe+” | 120-channel PCIe board, supporting high-impedance parallel connection
“SHN-32A-CT/PCI” | 32-channel VoIP A-type board
“SHN-8B-CT/PCI+” | 8-channel VoIP B-type board
“SHN-16B-CT/PCI+” | 16-channel VoIP B-type board
“SHN-32B-CT/PCI+” | 32-channel VoIP B-type board
“SHN-60B-CT/PCI+” | 60-channel VoIP B-type board
“SHN-120B-CT/PCI+” | 120-channel VoIP B-type board
“ATP-24A/PCI” | ATP-24A/PCI analog tap passive board
“ATP-24A/PCI+” | ATP-24A/PCI+ analog tap passive board
“ATP-24A/PCIe” | ATP-24A/PCIe analog tap passive board
“ATP-24A/PCIe+” | ATP-24A/PCIe+ analog tap passive board
“DST-24B/PCI” | 24-channel PCI B-type digital station tap board
“DST-24B/PCI+” | 24-channel PCI B-type digital station tap board with enhanced capability
“DST-24B/PCIe” | 24-channel PCIe B-type digital station tap board
“DST-24B/PCIe+” | 24-channel PCIe B-type digital station tap board with enhanced capability
SHD-30E-CT/PCI(ssw) | 1E1/T1/J1 PCI digital trunk board
SHD-30E-CT/PCI/FAX(ssw) | 1E1/T1/J1 PCI digital trunk board with soft-faxing component
SHD-30E-CT/PCI/EC(ssw) | 1E1/T1/J1 PCI digital trunk board, having enhanced capability in echo cancellation
SHD-60E-CT/PCI(ssw) | 2E1/T1/J1 PCI digital trunk board
SHD-60E-CT/PCI/FAX(ssw) | 2E1/T1/J1 PCI digital trunk board with soft-faxing component
SHD-60E-CT/PCI/EC(ssw) | 2E1/T1/J1 PCI digital trunk board, having enhanced capability in echo cancellation
SHD-120E-CT/PCI(ssw) | 4E1/T1/J1 PCI digital trunk board
SHD-120E-CT/PCI/FAX(ssw) | 4E1/T1/J1 PCI digital trunk board with soft-faxing component
SHD-120E-CT/PCI/EC(ssw) | 4E1/T1/J1 PCI digital trunk board, having enhanced capability in echo cancellation
SHD-240E-CT/PCI(ssw) | 8E1/T1/J1 PCI digital trunk board
SHD-240E-CT/PCI/FAX(ssw) | 8E1/T1/J1 PCI digital trunk board with soft-faxing component
SHD-240E-CT/PCI/EC(ssw) | 8E1/T1/J1 PCI digital trunk board, having enhanced capability in echo cancellation
SHD-30E-CT/PCIe | 1E1/T1/J1 PCIe digital trunk board
SHD-30E-CT/PCIe/FAX | 1E1/T1/J1 PCIe digital trunk board with soft-faxing component
SHD-30E-CT/PCIe/EC | 1E1/T1/J1 PCIe digital trunk board, having enhanced capability in echo cancellation
SHD-60E-CT/PCIe | 2E1/T1/J1 PCIe digital trunk board
SHD-60E-CT/PCIe/FAX | 2E1/T1/J1 PCIe digital trunk board with soft-faxing component
SHD-60E-CT/PCIe/EC | 2E1/T1/J1 PCIe digital trunk board, having enhanced capability in echo cancellation
SHD-120E-CT/PCIe | 4E1/T1/J1 PCIe digital trunk board
SHD-120E-CT/PCIe/FAX | 4E1/T1/J1 PCIe digital trunk board with soft-faxing component
SHD-120E-CT/PCIe/EC | 4E1/T1/J1 PCIe digital trunk board, having enhanced capability in echo cancellation
SHD-240E-CT/PCIe | 8E1/T1/J1 PCIe digital trunk board
SHD-240E-CT/PCIe/FAX | 8E1/T1/J1 PCIe digital trunk board with soft-faxing component
SHD-240E-CT/PCIe/EC | 8E1/T1/J1 PCIe digital trunk board, having enhanced capability in echo cancellation

Return Value:

0 | Successful
-1 | Failed

Function Description:

This function obtains the model of the board with designated ID number. If this function is successfully called, the model will be put in lpBoardModel.

Note:

This function can achieve the same purpose as GetPciBoardModel. However, this function call is performed under the control of Shp_a3.dll.

Related Information:

Driver Version | SynCTI Ver.5.2.0.3
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetAccreditIdEx, SsmGetAccreditId, SsmGetBoardModel


2.1.5.4 Obtaining Board Serial Number


2.1.5.4.1 SsmGetPciSerialNo

Obtains the board serial number.

Format:

DWORD SsmGetPciSerialNo(int nBId)

Parameter Description:

nBId

Board ID, corresponding to the value of x in the section [BoardId=x] of the configuration file

Return Value:

0 | Call failed, the failure reason can be acquired from the function SsmGetLastErrMsg
>0 | Board serial number

Function Description:

Obtains the board serial number. The leaving factory boards have a label with serial number sticked on the back side. For more information, refer to the hardware manual of voice boards.

Note:

Related Information:

Driver version | SynCTI Ver.3.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function:SsmGetAccreditIdEx, SsmGetAccreditId


2.1.5.4.2 GetPciBoardSerialNo

Obtains the board serial number.

Format:

DWOR GetPciBoardSerialNo (int nBId, DWORD pSerialNo )

Parameter Description:

nBId | The ID number of the actually installed board
pSerialNo | The pointer storing the serial number of the board

Return Value:

-1 | Call failed
0 | Successful

Function Description:

Obtains the serial number of the designated board. If it’s successfully called, the board serial number will be put into pSerialNo.

Note:

This function call can be performed without the control of Shp_a3.dll. The serial number of the installed board in the operating system can be obtained directly.

If you install or uninstall a board after the load of Shinitpci.dll, you should invoke ReloadPciBoardInfo before invoking this function to get the latest information.

Related Information:

Driver Version | Independent of SynCTI driver
Header | Shinitpci.h
Library | Shinitpci.lib
DLL | Shinitpci.dll

Related Functions: GetPciBoardModel , GetTotalPciBoard, ReloadPciBoardInfo


2.1.5.5 Obtaining Version Information


2.1.5.5.1 SsmGetDllVersion

Obtains the version information of the file ‘shp_a3.dll’.

Format:

int SsmGetDllVersion(PSSM_VERSION pDLLVersion)

Parameter Description:

pDLLVersion

Struct pointer storing the file version information

Return Value:

-1 | Call failed, the failure reason can be obtained from the function call of SsmGetLastErrMsg
0 | Successful

Function Description:

Obtains the version information of the file ‘shp_a3.dll’.

The structure of the returned version information is as follows:

typedef struct _VERSION
{ UCHAR ucMajor;// Major version
UCHAR ucMinor;// Minor version
USHORT usInternal;// Internal version
USHORT usBuild;// Build number
UCHAR ucRelease;// Compilation mode
UCHAR ucFeature;// Compilation environment
}SSM_VERSION, *PSSM_VERSION;

For example, invoke this function based on SynCTI 5.0.3.0 and the following information appears:

typedef struct _VERSION
{ UCHAR ucMajor;//=5
UCHAR ucMinor;//=0
USHORT usInternal;//=3
USHORT usBuild; //=0
UCHAR ucRelease; //= blank (Reserved)
UCHAR ucFeature; //= blank (Reserved)
}SSM_VERSION, *PSSM_VERSION;

Note:

Related Information:

Driver Version | SynCTI Ver.3.1 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Functions:


2.1.6 Funtions to Obtain Channel Attributes


2.1.6.1 SsmGetMaxCh

Obtains the total channel number in the application program.

Format:

int SsmGetMaxCh(void)

Parameter Description: None

Return Value:

-1 | Failed
≥0 | Total channel number

Function Description:

Obtains the total channel number in the application program

Note:

Related Information:

Driver version | SynCTI Ver.3.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetChType


2.1.6.2 SsmGetChType

Obtains the channel type.

Format:

int SsmGetChType(int ch)

Parameter Description:

ch

The logical number of the channel

Return Value:

-1 | Failed
0 | Analog trunk channel
2 | Station channel
3 | Analog trunk recording channel
4 | SS1 channel
6 | TUP channel
7 | ISDN channel ( user side)
8 | ISDN channel ( network side)
9 | Fax channel
10 | Magnetic channel
11 | ISUP channel ( China SS7 signaling ISUP)
12 | Digital trunk recording channel
13 | Channel Bank EM channel
14 | Voice-alteration channel
16 | SIP channel
17 | IP channel
20 | SHT board channel without any module
21 | EM Control channel
22 | EM Voice channel

Function Description:

Obtains the channel type.

Note:

l To obtain more detailed information about the channel type, use this function with SsmGetAutoCallDirection.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetMaxCh


2.1.6.3 SsmGetChHdInfo

Obtains the ID of the board where the channel is located ,also obtains the channel’s physical number on the board.

Format:

int SsmGetChHdInfo(int ch, int * pnBId, int * pnBCh)

Parameter Description:

ch | Channel number
pnBId | Returns the ID of the board where the channel is located. Its storage space is allocated by the application program
pnBCh | Returns the channel’s physical number on the board. Its storage space is allocated by the application program

Return Value:

-1 | Failed. The failure reason can be acquired by the function SsmGetLastErrMsg .
0 | Successful

Function Description:

Obtains the ID of the board where the channel is located ,also obtains the channel’s physical number on the board.

Note:

Related Information:

Driver version | SynCTI Ver. 4.7.1.5 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetAppChId


2.1.6.4 SsmGetAppChId

Inquires the channel logical number based on the board ID and the channel physical number.

Format:

int SsmGetAppChId(int * ch, int nBId, int nBCh)

Parameter Description:

ch | Returns the channel logical number. The storage space is allocated by the application program
nBId | The ID of the board where the channel is located
nBCh | The channel physical number

Return Value:

-1 | Failed. The failure reason can be acquired by the function SsmGetLastErrMsg .
0 | Successful

Function Description:

Inquires the channel logical number based on the board ID and the channel physical number.

Note:

Related Information:

Driver version | SynCTI Ver. 4.7.1.5 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetChHdInfo


2.1.7 Functions to Set Channel Attributes


2.1.7.1 SsmSetFlag

Sets the control attributes of the channel.

Format:

int SsmSetFlag(int ch, int nType, long lPara)

Parameter Description:

ch

Channel Number

nType

lPara

nType is the type of the parameter that needs to be set, Ivalue is the parameter value.

The value range and the physical meaning of nType and Ivalue are listed in the table below:

nType |  | Description | lPara
Value | Macro in shpa3api.h
1 | F_RCVDTMFSENS | Sets the minimum DTMF signal durations respectively at on and off states. For more information, refer to configuration item ReceiveDtmfSensitive | Please refer to the configuration item ReceiveDtmfSensitive
2 | F_TXDTMFAMP | Sets the magnitude of the DTMF signal generated by the DTMF generator, with the default value of 0X8976. | High 8 bits and low 8 bits respectively indicate the two frequency magnitudes of the DTMF signal.
5 | F_RXR2FILTERTIME | Sets the minimum sustaining time for MFC R2 signal. For more information, refer to the configuration item RxR2FilterTime . | Range of value: 16~96 ( Must be integer times of 16 ). Unit: ms
9 | F_ClearInVoiceOnRcvDtmf | Sets the DTMF clamping function. For more information, refer to the configuration item: ClearInVoiceOnRxDtmf . | =0: Disabled =1: Enabled
10 | F_MixerResToBus | Sets the output signal of ‘off-bus signal mixer” whether or not to be the input signal source of ‘on-bus signal mixer’. This function only supports SHT Series ( 8/16 Channels) and SHD Series voice boards. For more information, refer to the switch of K1-2 in the corresponding voice board’s principle diagram. | =0: No =1: Yes
11 | F_HighAndLowFreqEnScale | Sets the proportion of the high-frequency energy to the low-frequency energy in the DTMF signal. For more information, refer to the configuration item HighAndLowFreqEnScale. | Refer to the description of the configuration item HighAndLowFreqEnScale .
12 | F_DualAndAllFreqEnScale | Sets the threshold percentage of the in-band energy in the overall frequency energy in the DTMF signal. For more details, refer to the configuration item DualAndAllFreqEnScale . | Refer to the configuration item of DualAndAllFreqEnScale .
13 | F_EchoCancelInFsk | When the FSK receiver is working, sets whether or not to enable/disable the echo-canceller. For more details, refer to the configuration item FskEchoCancelDelay. | =0: Disabled =1: Enabled
17 | F_ClearInVoiceOnRcv450Hz | Sets whether to put tones onto bus. | =0: Onto bus (default) =1: Not onto bus
18 | FSKMinGate | Sets an energy threshold value for FSK receiving. | =0: No threshold value n(n>0): The set threshold value
19 | F_RECTOFILEA_CALLBACKTIMEA | Sets the callback time for the function SsmRecToFileA or SsmRecToFileB. For more information, refer to the corresponding function description. Note: This parameter goes invalid if the software-based MP3 is used as the recording format. | Value Range: 16~4000 (ms) Note: When the used recording format is IMA ADPCM, if the callback time is set to 128~192 (inclusive of 128 but exclusive of 192), the function will be called back every 128ms; if the callback time is set to a value less than 128, the function will be called back every 64ms; if the software-based GSM is used as the recording format, the callback time is set to 64~4000.
20 | F_CALLERIDTYPE | Sets the mode for the remote PBX to send the calling party number on the analog phone line. For more information, refer to the description of the configuration item CallerIdStyle. | =0: DTMF mode =1: FSK mode
21 | F_InVoiceToBusA | Determines whether to put incoming signals to the TDM bus. That is, sets the switch K3 in the figure of board operation principle. For more information, refer to the description of the configuration item InVoiceToBus. | =0: Disabled =1: Enabled
22 | F_EchoCancelInFskA | Sets whether to disable the echo canceller when the FSK transceiver is working. For more information, refer to the description of the configuration item FskEchoCancelDelay. | =0: Disabled =1: Enabled
23 | F_ChToRingingOnRingCntA | Sets the parameters for the ringing current detector. For more information, refer to the Ringing Current on Analog Phone Line section in Chapter 1 or the description of the configuration item ChToRingingOnRingCnt. | Refer to the configuration item ChToRingingOnRingCnt.
24 | F_SetAdjustCtlA | Sets whether to enable Echo Study. | =0: Disabled =1: Enabled
25 | F_RCVPHONUMHOLDUPA | Sets the control switch of the ‘Called Number Hold-up’ feature. For more information, refer to the description of the configuration item PhoNumHoldup. | Value Range: 0/1/2
26 | F_RELATIVEENGYHOOKDETECTA | Sets the working status of the ‘Enhanced remote pickup detector’ on the analog trunk channel. For more information, refer to ‘Enhanced Remote Pickup Detector’ in Chapter 1 or the configuration item RelativeEngyHookDetect. | =0: Disabled =1: Enabled
27 | F_CUTDTMFWHILERECORDING | Sets whether to clamp DTMF digits when the monitoring board is doing recording. | =0: Disabled =1: Enabled

Return Value:

-1 | Call Failed, this function is not supported
0 | Call failed, the failure reason can be obtained from the function SsmGetLastErrMsg
1 | Successful

Function Description

Sets the control attributes of the channel.

Note:

Related Information:

Driver Version | SynCTI Ver. 4.0.0.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetFlag


2.1.7.2 SsmGetFlag

Obtains the status of the functional switch on the channel.

Format:

int SsmGetFlag(int ch, int nType, long* plValue)

Parameter Description:

ch

Channel Number

nType

plValue

nType: selects the parameter type to be set. For the value of the parameters, refer to the description of the functions. plValue returns the parameter’s setup value.

Below are the physical meanings of nType and plValue.

nType |  | Description
Value | MACRO in shpa3api.h
1 | F_RCVDTMFSENS | For more details, refer to the function SsmSetFlag.
2 | F_TXDTMFAMP
5 | F_RXR2FILTERTIME
9 | F_ClearInVoiceOnRcvDtmf
10 | F_MixerResToBus
11 | F_HighAndLowFreqEnScale
12 | F_DualAndAllFreqEnScale
15 | F_ISDNNet_WaitRemotePickup | plValue returns the detailed reason that the driver transfers the channel state to the state of S_CALL_WAIT_REMOTE_PICK, i.e, the type of the message which is received from remote PBX: ² plValue=4：CALL PROCEEDING; ² plValue=5：ALERTING; ² plValue=6：CONNECT; Note: This function requires SynCTI version 4.7.1.5 or above.
17 | F_ClearInVoiceOnRcv450Hz | Refer to the description of the function SsmSetFlag for details.
18 | F_FSKMinGate
19 | F_RECTOFILEA_CALLBACKTIMEA
20 | F_CALLERIDTYPE
21 | F_InVoiceToBusA
22 | F_EchoCancelInFskA
23 | F_ChToRingingOnRingCntA
24 | F_SetAdjustCtlA
25 | F_RCVPHONUMHOLDUPA
26 | F_RELATIVEENGYHOOKDETECTA

Return Value:

-1 | Call failed, the failure reason can be acquired from the function SsmGetLastErrMsg.
0 | Successful.

Function Description:

Obtains the status of the functional switch on the channel.

Note:

Related Information:

Driver Version | SynCTI Ver. 4.0.0.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSetFlag


2.2 Functions for Event-mode Programming


2.2.1 Obtaining Events

Refer to SsmGetEventA


2.2.1.1 SsmWaitForEvent

Refer to SsmGetEventA


2.2.1.2 SsmWaitForEventA

Refer to SsmGetEventA


2.2.1.3 SsmGetEvent

Refer to SsmGetEventA


2.2.1.4 SsmGetEventA

Obtains the events thrown out by Synway driver program. SsmGetEvent and SsmGetEventA are synchronous functions which return immediately regardless whether there are events generated or not. SsmWaitForEvent and SsmWaitForEventA are asynchronous functions: If there are events generated, the functions return immediately ; If there are no events generated, the caller’s thread will be blocked and the functions return until there are events generated or timeout.

Format:

int SsmWaitForEvent( DWORD dwTimeOut, PMESSAGE_INFO pEvent)

int SsmWaitForEventA( DWORD dwTimeOut, PSSM_EVENT pEventEx)

int SsmGetEvent(PMESSAGE_INFO pEvent)

int SsmGetEventA(PSSM_EVENT pEventEx)

Parameter Description:

dwTimeOut

Sets the operating mode of the function SsmWaitForEvent(), the value range:

0: SsmWaitForEvent works under the synchronization mode, i.e, the function returns immediately regardless of whether there are events. In this mode, SsmWaitForEvent and SsmGetEvent perform a same function.

0xffffffff: If there are no events, the function gets suspended and only returns until there are events generated.

Others: Sets the maximum waiting time, calculated by millisecond. When waiting for events, if there are events generated, the function returns immediately; if there are no events, the function returns until the waiting time exceeds the set value of dwTimeOut.

pEvent

pEventEx

The pointer to the MESSAGE_INFO(pEvent) structure or the SSM_EVENT(pEventEx) structue. The pointer returns the information of the events and the value of the pointer is valid only when the return value of the function is 0. For more information, refer to ‘MESSAGE_INFO’ or ‘SSM_EVENT’ in Chapter 1.

Return Value:

-2 | One of the followings occurs: ² API interfaces are unopened; ² The event polling mode is not set as the programming mode; ² In-memory message queues are unallocated.
-1 | Timeout
0 | There are events generated and event information is returned by pEvent or pEventEx.

Function Description:

Obtains the events thrown out by Synway driver program.

If the event buffer of the driver is not empty, SsmWaitForEvent or SsmWaitForEventA returns immediately; If there are no events available, the function will wait for the events and return until the waiting time exceeds the set value of dwTimeOut.

Note:

l The functions can be called Only when the driver is working under event polling mode, otherwise the function calls will return a failure.

l For the configuration item EventInterfaceType , if it is set to be 0, only SsmWaitForEvent or SsmGetEvent can be called; If it is set to be 1 , only SsmWaitForEventA or SsmGetEventA can be called , otherwise the function calls will return a failure.

Function SsmWaitForEvent and SsmWaitForEventA as well as function SsmGetEvent and SsmGetEventA have the same functions except that the data structures of the output events are different . SsmWaitForEventA and SsmGetEventA are usually used for the D-channel event programming of the DST Series boards.

Related Information:

Driver Version | Needs to be SynCTI Ver. 4.0 or above for SsmWaitForEvent and SsmGetEvent Needs to be SynCTI Ver. 4.7.3.0 or above for SsmWaitForEventA and SsmGetEventA
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSetEvent


2.2.1.5 SsmGetInterEventType

Gets the value of the configuration item EventInterfaceType.

Format:

int WINAPI SsmGetInterEventType()

Parameter Description: None

Return Value:

-1 | Call failed
0 | The event output parameter is only allowed to be obtained by the MESSAGE_INFO structure.
1 | The event output parameter is only allowed to be obtained by the SSM_EVENT structure

Function Description:

This function is used to get the value of the configuration item EventInterfaceType.

Note:

l We suggest that you invoke this function to determine which structure (MESSAGE_INFO or SSM_EVENT) you will use to obtain the event before the call of SsmSetEvent.

l If the returen value does not comply with the structure being used, the program may run abnormal.

Related Information:

Driver Version | SynCTI Ver.4.8.0.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSetEvent


2.2.1.6 SsmSetInterEventType

Sets the value of the configuration item EventInterfaceType.

Format:

int WINAPI SsmSetInterEventType(int nType)

Parameter Description:

nType

The type of the parameter

Return Value:

-1 | Failed
0 | Successful

Function Description:

This function is used to set the value of the configuration item EventInterfaceType.

Note:

l We suggest that you invoke this function before the call of SsmSetEvent. In such way, the call of SsmSetEvent will be independent of the configuration, so you don’t need to worry about if the configuration is set properly or if the program is running well.

Related Information:

Driver Version | SynCTI Ver.4.8.0.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetInterEventType


2.2.2 Filtering Output Events


2.2.2.1 SsmSetEvent

Sets the event output mode of the driver program and permits or forbids the driver to output one particular event.

Format:

int SsmSetEvent(WORD wEvent, int nReference, BOOL bEnable, PEVENT_SET_INFO pEventSet)

Parameter Description:

wEvent

Selects the event and the range of values:

0~0xfffe: Event code. For the value range of values, refer to MESSAGE_INFO in Chapter 1. The function SsmSetEvent informs the driver program whether to throw out a specified event or not.

0xffff: Sets the working mode of the driver program, i.e. the event polling mode and the event callback mode, where the parameter nReference must be -1. The event queue depth in the driver can be set with the configuration item MaxEventPerChannel. For more information, please refer to ‘Setting Event Output Mode’ in Chapter 1.

nReference

The reference value of the event. If wEvent=0xffff, this parameter must be -1, used to set the working mode for the whole driver; if wEvent≠oxffff, the physical meaning of nReference depends on the type of wEvent as shown in the following list:

wEvent | The meaning of nReference and it’s range of values
E_CHG_ISDNStatus E_CHG_PcmLinkStatus E_CHG_RemotePCMBlock | The logical number of the digital trunk: nReference=-1: Sets all the digital trunks in the system. 0≤nReference≤M-1: Sets the digital trunk designated by this parameter. Note: M is the total number of the digital trunks in the system.
E_RCV_Ss7Msu | 0-Reserved
E_RCV_Ss7SpyMsu | 0-Reserved
E_CHG_Mtp3State | DPC number: nReference=-1: Sets all the DPCs in the system. 0≤nReference≤M-1: Sets the DPC designated by this parameter.
E_SYS_TIMEOUT | Timer ID: nReference=-1: Sets all the timers in the system. 0≤nReference≤M-1: Sets the timer designated by this parameter
E_CHG_SpyState | Logical SpyCic number: nReference=-1: Sets all the SpyCics in the system. 0≤nReference≤M-1: Sets the SpyCic designated by this parameter
E_CHG_SpyHangupInfo | Logical SpyCic number: nReference=-1: Sets all monitored circuits in the system; 0≤nReference≤M-1: Sets the monitored circuits which are specified by this parameter.
E_CHG_CICRxPhoNumBuf E_CHG_CICState E_PROC_CICAutoDial | Virtual CIC number: nReference=-1: Sets the virtual CIC in the system. 0≤nReference≤M-1: Sets the virtual CIC designated by this parameter
Other Events | Logical channel number: nReference=-1: Sets all the channels (total is N) in the system. 0≤nReference≤N-1: Sets the channel designated by this parameter.

bEnable

The control sign of the event output. When wEvent=0xffff and nReference=-1, if bEnable=FALSE, the driver will by default not output any event; if bEnable=TRUE, the driver will output an default event specified by DefaultEventOutput. When wEvent≠0xffff, the value range of bEnable is as follows:

=TRUE: Throws out wEvent;

=FALSE: Not throws out wEvent.

pEventSet

Pointer which points to the struct object of EVENT_SET_INFO. It’s used for setting up the output conditions of the events. If the parameter wEvent=0xffff, this parameter can’t be NULL. The declaration of the struct EVENT_SET_INFO is:

typedef struct _EVENT_SET_INFO

{

DWORD dwWorkMode;

LPVOID lpHandlerParam;

DWORD dwOutCondition;

DWORD dwOutParamVal;

DWORD dwUser;

} EVENT_SET_INFO,*PEVENT_SET_INFO;

Below is the meaning of each parameter:

Parameter Name: dwWorkMode

Sets the working mode that the driver throws out the events. Only if wEvent=0xffff, this parameter is valid; If wEvent is other values, this parameter will be ignored. The range of values:

Value | Macro in event.h | Description
0 | NO_EVENT | The driver doesn’t output any events.
1 | EVENT_POLLING | The driver works under the event polling mode. The parameter dwOutCondition and dwOutParamVal are valid, the parameter lpHandlerParam and dwUser are invalid.
2 | EVENT_CALLBACK | The driver works under the event callback mode. lpHandlerParam and dwUser are valid.
3 | EVENT_MESSAGE | The driver works under the windows message mode. All the messages will be sent to the windows message queue.

Parameter Name: lpHandlerParam

Only when dwWorkMode=EVENT_CALLBACK or EVENT_MESSAGE, this parameter is valid.

If dwWorkMode equals to other values, this parameter will be ignored.

Ø dwWorkMode=EVENT_CALLBACK

lpHandlerParam is the pointer to the callback function. The callback function format is decided by the set value of the configuration item EventInterfaceType :

² EventInterfaceType=0:the format of lpHandlerParam :

int CALLBACK CallBackFun(WORD wEvent,int nReference,DWORD dwParam,DWORD dwUser);

The meanings of wEvent, nReference and dwParam are the same as the corresponding variables declared in the struct MESSAGE_INFO.

For more details, refer to function SsmWaitForEvent or SsmGetEvent. The parameter dwUser is the parameter dwUser which is passed from the application to the driver when invoking this callback function.

² EventInterfaceType=1:the format of lpHandlerParam :

int CALLBACK CallBackFunA(PSSM_EVENT pEvent):

pEvent which returns the event information is the pointer pointing to the struct object SSM_EVEN.

For more details, refer to the function SsmWaitForEventA or SsmGetEventA .

Note: When the callback function returns -1, all events are forbidden being thrown out. After that, if it is necessary to throw them out, you should call the function SsmSetEvent to reset them first.

Ø dwWorkMode=EVENT_MESSAGE

lpHandlerParam is the window handle which is used by the application to receive the driver events.

Parameter Name: dwUser

User-defined parameter which is valid only when dwWorkMode=EVENT_CALLBACK; If dwWorkMode equals to other values, this parameter will be ignored. The driver will save this parameter. When the driver throws out events, it will be transparently passed to the parameter having the same name in the callback function pointed by lpHandlerParam.

Parameter Name: dwOutCondition, dwOutParamVal

dwOutCondition sets the conditions on which the events are output. dwOutParamVal sets the types of the parameters of the output events. When the event is generated, the driver will assign the data types set by dwOutParamVal to the parameter dwParam in the struct MESSAGE_INFO or SSM_EVENT. dwOutCondition and dwOutParamVal are optional parameters. When using the default value of dwOutCondition, you can set pEventSet=NULL. But if the parameter wEvent is equal to one of the following values and pEventSet≠NULL, you have to set dwOutCondition each time before you invoke SsmSetEvent; otherwise, you shall meet unexpected consequence.

² wEvent = E_CHG_LineVoltage:

Only when the voltage change range on the analog phone line exceeds dwOutCondition (default value may be 5), will the driver throw out the event E_CHG_LineVoltage. dwOutParamVal is reserved but not used. When wEvent=0xffff and nReference=-1, dwOutCondition will be automatically set to 5.

² wEvent = E_PROC_PlayFile:

dwOutCondition sets the time interval (ms) that the driver throws out the event E_PROC_PlayFile (default value may be 1000). dwOutParamVal sets the types of the output parameters, the optional values are:

=0: Outputs the percentage of the played part.

=1: Outputs the time that finishes the play.

=2: Outputs the total number of played bytes.

=3: Outputs the total number of not-played bytes.

When wEvent=0xffff and nReference=-1, dwOutCondition will be automatically set to 1000 and dwOutParamVal set to 1.

² wEvent = E_PROC_PlayMem:

u dwOutParamVal=END_HALF_BUFFER:

When the play pointer in the driver gets across the middle position or the tail part of the buffer, the driver throws out the event E_PROC_PlayMem.

If the play pointer points to the front part of the buffer, the output value (dwParam) is -1; If it points to the rear part, the output value is -2.

u dwOutParamVal=END_BUFFER:

When the play pointer in the driver gets across the tail part of the buffer, the driver throws out the event E_PROC_PlayMem and outputs -2.

u dwOutParamVal=MEM_OFFSET:

After a certain time period of voice playback, the driver throws out the event E_PROC_PlayMem and outputs the play pointer (i.e., the offset in the buffer) in the driver. The time length (ms) is specified by dwOutCondition.

u dwOutParamVal=MEM_BYTES:

After playing a certain amount of voice-data bytes, the driver throws out the event E_PROC_PlayMem and outputs the play pointer (i.e., the offset in the buffer) in the driver. The amount of the bytes is specified by dwOutCondition (default value may be 64).

When wEvent=0xffff and nReference=-1, dwOutParamVal will be automatically set to MEM_OFFSET and dwOutCondition set to 64.

² wEvent = E_PROC_RecordFile:

dwOutCondition is set to be the time interval (ms) that the driver throws out the event E_PROC_RecordFile (default value may be 1000).

dwOutParamVal is set to be the types of output values, the optional values are:

=RECORD_TIME: Outputs the time (ms) spent on the finished recording;

=RECORD_BYTES: Outputs the total finished recorded bytes( bytes).

When wEvent=0xffff and nReference=-1, dwOutCondition will be automatically set to 1000 and dwOutParamVal set to RECORD_TIME.

² wEvent = E_PROC_RecordMem:

u dwOutParamVal=END_HALF_BUFFER:

When the record pointer gets across the middle position or the tail part of the recording buffer, the driver throws out the event E_PROC_RecordMem. If the record pointer points to the front part of the buffer, the output value is -1; If the pointer points to the rear part, the output value is -2.

u dwOutParamVal=END_BUFFER:

When the record pointer in the driver gets across the tail part of the buffer, the driver throws out the event of E_PROC_RecordMem and the output value is -2.

u dwOutParamVal=MEM_OFFSET:

After a certain time period of voice recording, the driver throws out the event E_PROC_RecordMem and outputs the record pointer (i.e., the offset in the buffer) in the driver. The time length (ms) is specified by dwOutCondition.

u dwOutParamVal=MEM_BYTES:

After recording a certain amount of voice-data bytes, the driver throws out the event of E_PROC_RecordMem and outputs record pointer (i.e., the offset in the buffer) in the driver. The bytes number is specified by dwOutCondition (default value may be 64).

When wEvent=0xffff and nReference=-1, dwOutParamVal will be automatically set to MEM_OFFSET and dwOutCondition set to 64.

² wEvent = E_OverallEnergy:

When the change range of the full-frequency energy exceeds the set value of dwOutCondition (default value may be 1000) the driver throws out the event E_OverallEnergy. dwOutParamVal is reserved and unused. When wEvent=0xffff and nReference=-1, dwOutCondition will be automatically set to 1000.

² wEvent = E_CHG_PeakFrq:

When the change range of the peak frequency exceeds the set value of dwOutCondition (default value may be 100), the driver throws out the event E_CHG_PeakFrq. dwOutParamVal is reserved and unused. When wEvent=0xffff and nReference=-1, dwOutCondition will be automatically set to 100.

² wEvent = Other events:

Both of dwOutParamVal and dwOutParamVal are reserved and unused. They can be set to be 0.

Return Value:

-1 | Failed
0 | Successful

Function Description:

If wEvent=0xffff, this function is used to set the event output mode for the driver. For more information about the output mode supported by the SynCTI driver, refer to ‘Set Driver Event Output Mode’ in Chapter 1.

If wEvent≠0xffff, this function is used to permit or forbid the driver to output one particular event. If there are some output parameters, they should be set. First set the output mode for the event. Then adjust the output rule for an undetermined event.

Notes:

l After the SynCTI driver is started, it automatically works under the polling mode. If the programming is done in the event polling or event callback mode, this function must be invoked to change the driver’s event output mode after driver initialization.

l If wEvent=0xffff, the application can call this function only once and the parameter pEventSet can’t be NULL otherwise the function returns failure.

l If wEvent≠0xffff, pEventSet can be NULL. If pEventSet is not NULL, its member variable dwWorkMode must be consistent with the previous set event output mode. At present, the driver does not support different modes to output multiple events.

Related Information:

Driver version | SynCTI Ver.4.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmWaitForEvent, SsmWaitForEventA, SsmGetEvent, SsmGetEventA, SsmPutUserEvent, SsmPutUserEventA

Sample Code: Refer to ‘Programming demo for event polling mode’ or ‘Programming demo for event callback mode’ in chapter 1.


2.2.3 Getting Programming Mode


2.2.3.1 SsmGetEventMode

Obtains the programming mode.

Format:

int SsmGetEventMode(WORD wEvent, int nReference, PWORD pwEnable, PEVENT_SET_INFO pEventSet)

Parameter Description:

wEvent | Event code: Regarding the value range, refer to the section MESSAGE_INFO in Chapter 1. Note that the value can not be 0xffff.
nReference | The reference value of the event: The physical meaning of nReference varies on the type of wEvent, just as the parameter nReference in the function SsmSetEvent. However, its value can not be -1.
pwEnable | Stores the flag to control the event output. Value range: =TRUE: Output wEvent; =FALSE: Not output wEvent
pEventSet | The point that points to the objects which have the EVENT_SET_INFO structure. It is used to save the event output condition set by the function SsmSetEvent. See SsmSetEvent for the EVENT_SET_INFO structure declaration.

Return Value:

-1 | Failed
0 | Successful

Function Description:

Obtains the driver event output mode set by the application.

Note:

l When this function is called to get the appplication’s event programming mode, an event code but 0xffff should be assigned to the parameter wEvent .

Related Information:

Driver version | SynCTI Ver.4.8.0.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSetEvent


2.2.4 Outputting Application’s Self-defined Events by Driver


2.2.4.1 SsmPutUserEvent

Refer to SsmPutUserEventA


2.2.4.2 SsmPutUserEventA

Appends the application defined events to the internal event queue of the driver.

Format:

int SsmPutUserEvent( WORD wEvent, int nReference, DWORD dwParam)

int SsmPutUserEventA(PSSM_EVENT pEvent)

Parameter Description:

wEvent | User-defined event code. Note: The user-defined event code should not be the same as the event code defined by the driver. Suggestion : Set the starting event code value to be 0xfffe and reduce it gradually.
nReference | Event output reference. It will be transparently passed back to the application via the internal event queue of the driver.
dwParam | Event output parameter. It will be transparently passed back to the application via the internal event queue of the driver.
pEvent | Pointer pointing to the struct object SSM_EVENT. It inputs the event information to the driver. The struct object pointed by pEvent will be transparently passed back to the application via the internal event queue of the driver.

Return Value:

-1 | Failed.
0 | Successful.

Function Description:

Appends the application defined events to the internal event queue of the driver. Function SsmPutUserEvent and SsmPutUserEventA have the same functions except for the different data structures of the event. SsmPutUserEventA is normally used for the D-channel event programming of the DST Series board.

The driver puts the events submitted by the application in a temporary buffer in advance and appends the events to the event output queue of the driver when the hardware interrupt occurs. The configuration item MaxUserEventSize is used to set the depth of the temporary buffer.

Note:

l This function can only be invoked under ‘event polling’ programming mode. For more information about event polling mode, refer to ‘Set Driver Event Output Mode’ in chapter 1.

l If the configuration item EventInterfaceType is set to be 0, only the function SsmPutUserEvent can be used; If it’s set to be 1, only the function SsmPutUserEventA can be used, otherwise the function returns failure.

l If the configuration MaxUserEventSize is set to be 0, the function returns failure immediately.

Related Information:

Driver version | SsmPutUserEvent requires SynCTI Ver. 4.0 or above; SsmPutUserEventA requires SynCTI Ver. 4.7.3.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmWaitForEvent, SsmWaitForEventA, SsmGetEvent, SsmGetEventA


2.3 Call State Machine Functions


2.3.1 Outgoing Call Functions (CTI Series)


2.3.1.1 Searching for Idle Channel


2.3.1.1.1 SsmSearchIdleCallOutCh

Searches for an idle channel in the channels which are able to make outgoing calls.

Format:

int SsmSearchIdleCallOutCh(WORD wSearchMode, DWORD dwPrecedence)

Parameter Description:

wSearchMode

Specify the searching mode based on the bits value:

Bit | Description
Bit0 | Whether to search among analog trunk channels. =1: Yes; =0: No
Bit1 | Whether to search among SS1 channels. =1: Yes; =0: No
Bit2 | Whether to search among TUP channels. =1: Yes; =0: No
Bit3 | Whether to search among ISDN channels (user side). =1: Yes; =0: No
Bit4 | Whether to search among ISDN channels (network side).=1: Yes; =0: No
Bit5 | Whether to search among ISUP channels. =1: Yes; =0: No
Bit6 | Whether to search among those TUP channels corresponding to the specified signaling link set. =1: Yes; =0: No
Bit7 | Whether to search among those ISUP channels corresponding to the specified signaling link set. =1: Yes; =0: No
Bit8 | Whether to search among SIP channels. =1: Yes; =0: No
Bit9 | Reserved
Bit10 | Whether to search among those SS7 channels corresponding to the specified PCM. =1: Yes; =0: No
Bit15~Bit11 | Reserved and should be set to 0.

dwPrecedence

Bit6 or Bit7 in wSearchMode (TUP or ISUP channel) set to 1: Select a signaling link set;

Bit10 in wSearchMode set to 1: Select a logical PCM number;

Other types of channels: Set to 0.

Return Value:

-1 | Failed. The failure reason can be acquired from the function SsmGetLastErrMsg.
³0 | The channel number which has been searched out.

Function Description:

Searches for an idle channel in the channels which are able to make outgoing calls. The driver maintains an idle channel queue.

Note:

l If it is an analog trunk channel, the channel state will remain idle after this function is invoked; if it is an ISDN, SS7, SS1 or SIP channel, the channel state will turn into ‘outgoing call locked’ after this function is invoked.

l To search channels in SS1, ISDN protocols, follow the time slots of E1 trunks in a 0, 1, 2, 3...31 sequence (except for TS0 and TS16);

l To search channels in SS7 protocol, follow the size of OPC and DPC configured by this E1;

l The party with a large point code controls even time slots. To search channels, follow the even time slots in a 0, 2, 4, …, 30, 31, 29, 27, …, 1 sequence (except for TS0, TS1 and TS16);

l The party with a small point code controls odd time slots. To search channels, follow the odd time slots in a 1, 3, 5, …, 31, 30, 28, 26, …, 0 sequence (except for TS0, TS1 and TS16).

Related Information:

Driver version | SynCTI Ver. 4.7.1.5 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmAutoDial, SsmChkAutoDial


2.3.1.2 Starting Outgoing Call


2.3.1.2.1 SsmAutoDial

Refer to SsmAutoDialEx


2.3.1.2.2 SsmAutoDialEx

Submits AutoDial to the driver to start an outgoing call. SsmAutoDialEx sets the address indicator in the calling line identification field in the TUP protocol (also can be set by the configuration item CallerAddrInd), normally applying to TUP channels.

Format:

int SsmAutoDial(int ch, LPSTR szPhoNum)

int SsmAutoDialEx(int ch, LPSTR szPhoNum, WORD wParam)

Parameter Description:

ch

Channel Number

szPhoNum

The pointer to the buffer storing the called party number with a maximum length of 50.

l The analog trunk channel: If the character in szPhoNum is neither standard DTMF character nor a designated flash character, it will be considered as a delay character. For more information about the flash character and delay character, refer to the function SsmTxDtmf.

l SS1 channel, TUP/ISUP channel and ISDN channel: the valid phone number must be digital characters between ‘0’ and ‘9’ and any non-digital character will be ignored by the driver.

l SIP channel: [“display-name” <][sip:/sips:][user@]host[:port][>]

a) display-name: local alias, with the default setting of NULL

b) sip:/sips: : sip is the default setting while sips specifies that the resource be contacted securely

c) user: user name, with the default setting of NULL

d) host: allowed to be host name, IPv4 address, registered SIP address or E164 number

e) port: with the default value of 5060

wParam

This parameter is only applicable to the TUP channel.

The high 4 bits should be set to be 0 and the low 4 bits (namely DCBA) are effective.

Bit(s) | Meaning | Value | Description
BA | Nature of address indicator of the calling line identity | 00 | Subscriber number
 |  | 01 | Spare, national number
 |  | 10 | National significant number
 |  | 11 | International number
C | Providing calling number indicator | 0 | providing calling number is unrestricted
 |  | 1 | Providing calling number is restricted
D | Calling number incomplete indicator | 0 | Calling number is not shown incomplete
 |  | 1 | Calling number is incomplete

Return Value:

-1 | Failed. The failure reason can be acquired from the function SsmGetLastErrMsg .
0 | Successful.

Function Description:

Submits AutoDial to the driver for an outgoing call.

After AutoDial has started, the channel state machine automatically originates an outgoing call connection.

For related information, refer to the channel state transfer introduction in this manual.

If there is any progress with the outgoing call, the driver throws out the event E_PROC_AutoDial to the application. The application may also inquire the call progress status via the function call of SsmChkAutoDial. Because the call progress must be represented by the channel state transfer, the application may inquire the channel state transfer information via the event E_CHG_ChState or function SsmGetChState in order to obtain the progress status of AutoDial.

Ø ISUP Channel

The driver originates an outgoing call with the message IAM. There are two methods to compose an IAM message.

(1) Automatically composed by the driver. Some fields of the IAM message can be customized by the following methods:

Field | Method
Nature of connection indicator [1] | Change the configuration item DefaultNatureOfConnectionInd .
Forward call indicator[1] | Change the configuration item DefaultIAM_ForwardCallInd .
Calling party category[1] | Change the configuration item DefaultIAM_CAT or invoke the function SsmSetISUPCAT .
Transmission medium requirement indicator [1] | Change the configuration item DefaultIAM_TransmissionMediumRequirment .
Called party number[2] | The first and second 8-bit group in the field can be set by the configuration item DefaultIAM_CalleeParam or the function SsmSetIsupFlag which has the parameter ISUP_PhoNumParam; The follow-up 8-bit group (i.e. the phone number) can be set by the parameter szPhoNum of the function SsmAutoDialEx.
Calling party number[3] | The first and second 8-bit group in the field can be set by the configuration item DefaultIAM_CallerParam or the function SsmSetIsupFlag which has the parameter ISUP_CallerParam; The follow-up 8-bit group(i.e the phone number) can be set by the configuration number CalloutCallerId or the function SsmSetTxCallerId. The configuration item SetSTSignal decides whether to transmit ST signal in the calling party number.
Original called party number[3] | The first and second 8-bit group can be set by the configuration item DefaultIAM_OriginalCalleeParam; The follow-up 8-bit group(i.e. the phone number) can be set by the function SsmSetTxOriginalCallerID.
User service information[3] | The configuration item bSubscriberSI decides whether to include this field, the configuration item SubscriberSI sets the value of this field.
Optional forward call indicator[3] | The configuration item bOptionalFCI decides whether to include this item, the configuration item OptionalFCI sets the value of this field.
User to user information[3] | Changes the configuration item Usr2UsrInfo or calls the function SsmSetIsupParameter.
Other optional parameters[3] | To set other parameters, call the function SsmSetIsupParameter.

Note: In the above table, ISUP_CallerParam and ISUP_ PhoNumParam are declared in the header file Shpa3api.h. [1] denotes essential length-fixed fields, [2] denotes essential length-unfixed fields, [3] denotes optional fields.

(2) The application itself creates an IAM message. Before invoking this function, the application itself may create an IAM message and submit the IAM message to the driver via the function call of SsmSetIsupUPPara. When the driver excites this function, it automatically covers the fields of SIO,DPC,OPC,SLC,CIC and the called party number.

Ø TUP Channel

The TUP channel may use the IAI message or IAM message as the initial address message to originate an outgoing call. Below are the functions and configuration items related with the IAM/IAI message:

Message Type | Related Function or Configuration Item | Description
IAM IAI | Configuration item: ConnectReqMsg | Decides to use the message IAM or IAI
 | Configuration item: CalloutIAM_CAT | Sets the Calling Party Category
 | Configuration item: CalloutIAM_MsgPntr | Sets the field of the message indicator
IAI | Function: SsmSetTxOriginalCallerID | Sets the original calling party address
 | Configuration item: OriginalCalleeAddrInd | Sets the original called party address
 | Configuration item: CalloutCallerId | Sets the calling party number
 | Function: SsmSetTxCallerId
 | Configuration item: CallingIndicatorBit | Sets the additional calling party information indicator and calling line identification indicator in the 8-bit group of the first indicator.
 | Configuration item: SetSTSignal | Sets whether the calling party number parameter ends with ST signal.
 | Configuration item: CallerAddrInd | Sets the address indicator in the calling line identification field

If, before the application calls SsmAutoDialEx , the function SsmSetTxOriginalCallerID is invoked to set the calling and called party address, the driver only uses the IAI message to originate an outgoing call. The address indicator in the field of the calling/called party address of the IAI message can be set via the configuration item OriginalCalleeAddrInd.

Ø ISDN Channel

For the ISDN protocol, this function will trigger the driver to use the SETUP message to originate the outgoing call. Below are the functions and configuration items related with the SETUP message.

Message Type | Related Function or Configuration Item | Description
SETUP | Configuration item: UserCalledNoSet, NetCalledNoSet | Sets the called party number type and the numbering plan
 | Configuration item: UserCallingNoSet, NetCallingNoSet | Sets the calling party number type and the numbering plan
 | Configuration item: UserNumIsFull, NetNumIsFull | Sets whether to include the parameter of "Called number complete" in SETUP message.
 | Configuration item: UserChIdentify, NetChIdentify | Sets the indication method for channel identification
 | Configuration item: UserChPreference, NetChPreference | Sets whether to need the preferred channel type
 | Configuration item: CalloutCallerId | Sets the calling party number (needs to be invoked before the call of this function)
 | Function: SsmSetTxCallerId
 | Configuration item:UserHighLayerCompatible, NetHighLayerCompatible | Sets whether to include the "high layer compatibility" field in the SETUP message
 | Configuration item:UserLowLayerCompatible, NetLowLayerCompatible | Sets whether to include the "low layer compatibility" field in the SETUP message
 | Function: SsmISDNSetTxSubAddr | Sets the calling party subaddress(needs to be invoked before the call of this function)
 | Function: SsmISDNSetDialSubAddr | Sets the called party subaddress(needs to be invoked before the call of this function)
 | Function: SsmSetTxOriginalCallerID | Sets the original calling party number
 | Function: SsmISDNSetCallerIdPresent | Sets the ‘CallerID Present’ field

Ø SS1 Channel

For SS1 channel, when the driver is executing Autodial, the application can partially control the outgoing call process via some functions or configuration items.

Related Function or Configuration Item | Description
Function: SsmSetKA Configuration Item: MfcKA | Sets the calling party category (i.e. KA signal)
Function: SsmSetKD Configuration Item: MfcKD | Sets the "Service nature of the original end" (i.e. KD signal)
Configuration Item: CalloutCallerId Function: SsmSetTxCallerId | Sets the calling party (original end) number.

Ø IP Channel

For IP channel, this function will trigger the driver to use a message specified by the protocol to start a call outbound. To be exact, INVITE message is used for SIP channel. Functions related to these messages are listed below.

Message Type | Related Function | Description
INVITE(SIP) | Function: SsmSetTxCallerId | Set the calling party number (should be invoked before the call of this function)

The function call result can be obtained via SsmChkAutoDial . In unusual cases when the IP channel fails to dial and the call of SsmChkAutoDial always returns 11, users can invoke SsmGetAutoDialFailureReason to get the exact reason why it fails.

Note:

l This function only supports TUP, ISUP, SS1, ISDN, IP and analog trunk channels;

l TUP channel: Maximum length of dial number is 30;

l ISUP channel: Maximum length of dial number is 49;

l SS1 channel: Maximum length of dial number is 50;

l ISDN channel: Maximum length of dial number is 20.

Related Information:

Driver version | SynCTI Ver. 3.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmAppendPhoNum, SsmChkAutoDial, SsmGetChState, SsmGetPendingReason


2.3.1.2.3 SsmAppendPhoNum

Appends the called party number to the AutoDial operation.

Format:

int SsmAppendPhoNum(int ch, LPSTR szPhoNum)

Parameter Description:

ch | Channel Number
szPhoNum | Pointer which points to the buffer storing phone number strings. For analog trunk channel, if the character in szPhoNum is neither standard DTMF character nor specified flash character, it will be regarded as the delay character; For SS1 outbound trunk channel, any non-number characters will be ignored by the driver. The maximum length of dial string is 50.

Return Value:

-1 | Failed. The failure reason can be acquired via the function SsmGetLastErrMsg. .
0 | Successful.

Function Description:

Appends the called party number to the AutoDial operation. For more detailed information, refer to the channel state machine.

Note:

l This function only supports TUP, ISUP, SS1, ISDN and analog trunk channels;

l TUP channel: Maximum length of appended called party number is 16;

l ISUP channel: Maximum length of appended called party number is 50;

l SS1 channel: Maximum length of appended called party number is 50;

l ISDN channel: Maximum length of appended called party number is 20.

Related Information:

Driver version | SynCTI Ver. 3.0or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmAutoDial, SsmAutoDialEx


2.3.1.2.4 SsmChkAutoDial

Inquire the execution status of the AutoDial operation.

Format:

int SsmChkAutoDial(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1: Call failed. Below are the meanings of other return values:

Return Value

Macro in shpa3api.h

Description

0

DIAL_STANDBY

Channel is idle and AutoDial is not operating.

1

DIAL_DIALING

Sending the called party number.

2

DIAL_ECHOTONE

Ringback.

² Analog Trunk Channel: After Autodial, ringback tone is detected on the line.

² SS1 channel: During outgoing call, if the driver receives a backward KB=1 or KB=6 signal from the remote PBX, the channel is idle.

² ISDN channel: Indicates the driver receives the ALERTING message from the remote PBX.

² TUP/ISUP channel: Indicates that the address complete message (ACM) has been received from the remote PBX.

3

DIAL_NO_DIALTONE

If no dialtone is detected on the line, AutoDial failed. It’s only applicable to the analog trunk channel.

4

DIAL_BUSYTONE

The called party is busy and Autodial failed.

For analogy trunk channel, it indicates that the busy tone has been detected on the line.

5

DIAL_ECHO_NOVOICE

After the Autodial, there is the ringback tone on the line and then the line keeps silence. The Autodial operation is finished. It’s only applicable to analog trunk channel.

6

DIAL_NOVOICE

After the Autodial, there is no tone signal on the line and the line keeps silence. The Autodial operation is finished. It’s only applicable to analog trunk channel.

7

DIAL_VOICE

The called party goes off-hook.

8

DIAL_VOICEF1

The called party goes off-hook (The answer signal with F1 frequency is detected) and the AutoDial is finished. It’s only applicable to analog trunk channel.

9

DIAL_VOICEF2

The called party goes off-hook (The answer signal with F2 frequency is detected) and the AutoDial is finished. It’s only applicable to analog trunk channel.

10

DIAL_NOANSWER

The called party doesn’t pick up the phone for a specified time interval and the Autodial fails. It is not applicable to SIP channels on VoIP boards.

11

DIAL_FAILURE

AutoDial fails. The failure reason can be acquired by the function SsmGetAutoDialFailureReason.

12

DIAL_INVALID_PHONUM

The called party number is unallocated. Autodial fails. It is not applicable to SIP channels on VoIP boards.

13

DIAL_SESSION_PROCEEDING

The SIP channel on a VoIP board receives 18X messages (except 180).

14

DIAL_ISDN_PROGRESS

The ISDN channel receives the PROGRESS message from the remote PBX. To get the details of this message, invoke the function SsmISDNGetProgressMsg.

Function Description:

Inquire the execution status of the AutoDial operation.

Note:

l The station channel, magnet channel and recording channel are not supported with this function.

l If the IP channel fails to dial and this function call always returns 11, users can invoke SsmGetAutoDialFailureReason to get the exact reason why it fails.

Related Information:

Driver version | SynCTI Ver. 3.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmAutoDial, SsmAutoDialEx


2.3.1.2.5 SsmGetAutoDialFailureReason

Obtains the failure reason for the outgoing call.

Format:

int SsmGetAutoDialFailureReason(int ch)

Parameter Description:

ch

Channel Number

Return Value:

Return Value | Macro | Description
-1 | -1 | Failed.
0 | ATDL_NULL | No outbound call operation.
1 | ATDL_Cancel | AutoDial is cancelled by the application
2 | ATDL_WaitDialAnsTimeout | Waiting for answer from called party is time out (for TUP protocol only)
3 | ATDL_WaitRemotePickupTimeout | Waiting for off-hook signal from called party is overtime
10 | ATDL_Mtp3Unusable | SS7signaling: Signaling is unusable.
11 | ATDL_RcvSSB | SS7 signaling: Receives SSB message from remote PBX
12 | ATDL_RcvSLB | SS7 signaling: Receives SLB message from remote PBX
13 | ATDL_RcvSTB | SS7 signaling: Receives STB message from remote PBX
14 | ATDL_RcvUNN | SS7 signaling: Receives UNN message from remote PBX
15 | ATDL_RcvSEC | SS7 signaling: Receives SEC message from remote PBX
16 | ATDL_RcvCGC | SS7 signaling: Receives CGC message from remote PBX
17 | ATDL_RcvNNC | SS7 signaling: Receives NNC message from remote PBX
18 | ATDL_RcvCFL | SS7 signaling: Receives CFL message from remote PBX
19 | ATDL_RcvLOS | SS7 signaling: Receives LOS message from remote PBX
20 | ATDL_RcvSST | SS7 signaling: Receives SST message from remote PBX
21 | ATDL_RcvACB | SS7 signaling: Receives ACB message from remote PBX
22 | ATDL_RcvDPN | SS7 signaling: Receives DPN message from remote PBX
23 | ATDL_RcvEUM | SS7 signaling: Receives EUM message from remote PBX
24 | ATDL_RcvADI | SS7 signaling: Receives ADI message from remote PBX
25 | ATDL_RcvBLO | SS7 signaling: Receives BLO message from remote PBX
26 | ATDL_DoubleOccupy | SS7 signaling: Collision is detected
27 | ATDL_CircuitReset | SS7 signaling: Receives the circuit/group reset signal from remote PBX
28 | ATDL_BlockedByRemote | SS7 signaling: The circuit is blocked by remote PBX
40 | ATDL_SS1WaitOccupyAckTimeout | SS1 signaling: Waiting for the occupy acknowledge is overtime
41 | ATDL_SS1RcvCAS_HANGUP | SS1 signaling: Receives the backward clear signal
42 | ATDL_SS1RcvA4 | SS1 signaling: Receives the A4 signal (Keys congestion)
43 | ATDL_SS1RcvA5 | SS1 signaling: Receives the A5 signal (Unallocated number)
44 | ATDL_SS1RcvUndefinedAx | SS1 signaling: Receives undefined backward A signal
45 | ATDL_SS1RcvUndefinedAxOnTxCallerId | SS1 signaling: When transmitting caller ID, receives undefined A signal
46 | ATDL_SS1WaitAxTimeout | SS1 signaling: Waiting for receiving backward A group signal is overtime
47 | ATDL_SS1WaitAxStopTimeout | SS1 signaling: Waiting for backward A group signal to be stopped is overtime
48 | ATDL_SS1WaitAxTimeoutOnTxCallerId | SS1 signaling: Waiting for A signal is overtime when transmitting callerID
49 | ATDL_SS1WaitAxStopTimeoutOnTxCallerId | SS1 signaling: Waiting for backward A signal to be stopped is overtime during transmission of Caller_Id.
50 | ATDL_SS1RcvKB2 | SS1 signaling: KB2 signal is received (subscriber ‘local busy’)
51 | ATDL_SS1RcvKB3 | SS1 signaling: KB3 is received (subscriber ‘toll busy’)
52 | ATDL_SS1RcvKB4 | SS1 signaling: KB4 is received (keys congestion signal)
53 | ATDL_SS1RcvKB5 | SS1 signaling: Receives KB5 signal (unallocated number)
54 | ATDL_SS1RcvUndefinedKB | SS1 signaling: Receives undefined KB signal
55 | ATDL_SS1WaitKBTimeout | SS1 signaling: Receiving backward KB signal is overtime
56 | ATDL_SS1WaitKBStopTimeout | SS1 signaling: Waiting for remote end to stop sending KB signal is overtime.
60 | ATDL_ISDNNETISBUS | ISDN: Network busy (no use any more)
61 | ATDL_ISDNEMPTYNO | ISDN: Unallocated number.
65 | ATDL_IllegalMessage | SS7 signaling: Receives the illegal message from remote PBX
66 | ATDL_RcvREL | ISUP:Receives Release message (REL) from remote PBX
67 | ATDL_RcvCBK | TUP: Receives CBK message from remote PBX
68 | ATDL_IPInvalidPhonum | IP: Invalid dailed number
69 | ATDL_IPRemoteBusy | IP: Remote end busy
70 | ATDL_IPBeenRefused | IP: Refused
71 | ATDL_IPDnsFail | IP: Invalid DNS
72 | ATDL_IPCodecUnSupport | IP: Unsupported CODEC
73 | ATDL_IPOutOfResources | IP: Out of resources
74 | ATDL_IPLocalNetworkErr | IP: Local network error
75 | ATDL_IPRemoteNetworkErr | IP: Remote network error
100+n |  | Other reasons, n is the ISDN cause code (refer to Appendix 1 ISDN Release Cause Information Element for details)
Other |  | Reserved.

Function Description:

Obtains the failure reason for the outgoing call.

Note:

l So far the SynCTI driver does not support macros ATDL_IPRemoteBusy, ATDL_IPDnsFail, ATDL_IPCodecUnSupport, ATDL_IPLocalNetworkErr and ATDL_IPRemoteNetworkErr.

Related Information:

Driver version | SynCTI Ver. 3.0or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmAutoDial , SsmAutoDialEx


2.3.1.2.6 SsmSetTxCallerId

Sets the local end number (i.e. the calling party number) for an outgoing call.

Format:

int SsmSetTxCallerId(int ch, LPSTR pszTxCallerId)

Parameter Description:

ch

Channel Number

pszTxCallerId

l For SIP channels, pszTxCallerId sets the ‘displayname’ part in a complete SIP URI, with the maximum size of 50. The format of a complete SIP URI is ”displayname” <sip:user@host:port>;

l For other channels, this parameter stores the calling party number in ASCII string format. To be exact, the maximum size for TUP channels is 15 characters, for ISDN channels is 20 characters and for other kinds of channels is 50 characters. Each character must be one of the digital characters ‘0’~'9', otherwise it will be ignored.

Return Value:

-1 | Failed
≥0 | The number of the CallerIDs which have been actually sent out

Function Description:

Sets the local end number (i.e. the calling party number) for an outgoing call.

During an outgoing call, if the remote PBX requires the local end to send out the caller ID, the driver will transmit the characters in pszTxCallerId to the remote PBX.

Note:

l This function must be called before the function SsmAutoDial or SsmAutoDialEx is invoked. Once the parameter value is set, it will be saved in the internal buffer area and used subsequently in the IAM message;

l The configuration item TxCallerId for SS1 channel can enable the same feature. Its default setting is an empty string;

l This function only supports SS1 channel, TUP channel, ISUP channel, ISDN channel and IP channel;

l Based on TUP and ISUP protocols, some PBXes require that the callerID sent by the calling party must include ST signal (Signal Termination), which can be set by the configuration item SetSTSignal;

l If the function call of SsmSetTxCallerId fails, the set calling party number will not be sent successfully. And the function SsmAutoDial will send a calling party number according to the definition of the configuration item CalloutCallerId in the configuration file shconfig.ini. If the configuration item CalloutCallerId does set a number, this number will be sent to the called party as the calling party number. If it does not set any number, the calling party number will be none.

Related Information:

Driver version | SynCTI Ver. 3.0or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetPhoNumLen, SsmAutoDial, SsmAutoDialEx


2.3.1.2.7 SsmGetTxCallerId

Obtains the calling party number which is set by the local end.

Format:

int SsmGetTxCallerId(int ch, LPSTR pszTxCallerId)

Parameter Description:

ch | Channel Number
pszTxCallerId | l Returns the character string set by SsmSetTxCallerId for SIP channel; l Returns the caller ID string for other channels.

Return Value:

-1 | Failed
≥0 | The total character number of pszTxCallerId

Function Description:

Obtains the calling party number which is set by the local end.

Note:

l This function only supports SS1 channel, TUP channel , ISUP channel, ISDN channel and IP channel.

Related Information:

Driver version | SynCTI Ver. 3.0or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSetTxCallerId


2.3.1.2.8 SsmSetTxOriginalCallerID

Sets the original CallerID or original CalleeID in the call setup message.

Format:

int SsmSetTxOriginalCallerID(int ch, BYTE* pszTxCallerId)

Parameter Description:

ch | Channel Number
pszTxCallerId | Pointer points to the string storing the original CalleeID (for ISUP or TUP protocol) or original callerID (for ISDN protocol). The maximum total character number is 16.

Return Value:

-1 | Failed
>=0 | The actual length of CallerID/CalleeID denoted by pszTxCallerId

Function Description:

During outgoing call, sets the original callerID (for ISDN protocol) or original CalleeID (for ISUP or TUP protocol) in the call setup message sent to the remote PBX.

Note:

l This function must be call before the function SsmAutoDial or SsmAutoDialEx are invoked. After the driver has finished establishing the outgoing call setup message, this buffer area will be cleared.

l For the TUP channel, if this function is called before SsmAutoDial or SsmAutoDialEx are invoked, the driver only uses IAI message to initiate the outgoing call. This function sets the original callee address of the original callee address field in the IAI message and the configuration item of OriginalCalleeAddrInd sets the original callee address indicator.

l This function only supports the TUP channel, ISUP channel and ISDN channel.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmAutoDial, SsmAutoDialEx


2.3.1.2.9 SsmSetTxRedirectingNum

Sets the redirecting number in the call setup message.

Format:

int SsmSetTxRedirectingNum(int ch, BYTE* pszTxredirectingNum)

Parameter Description:

ch | Channel Number
pszTxredirectingNum | Pointer points to the string storing the redirecting number. The maximum total character number is 16.

Return Value:

-1 | Failed
≥0 | The actual length of redirecting number denoted by pszTxredirectingNum

Function Description:

During outgoing call, sets the redirecting number in the call setup message sent to the remote PBX.

Note:

l This function must be invoked before the call of the function SsmAutoDial or SsmAutoDialEx.

l The values of the parameters once set will be saved in the interior buffer of the driver and will be used in subsequent IAM messages.

l The parameters of this function will go invalid when the program is restarted and the configuration file is reloaded.

l How to cancel: set the second parameter of this function with a null string, that is, SsmSetTxRedirectingNum(CurCh, (LPBYTE)"").

l For the ISUP channel, if this function is called before SsmAutoDial or SsmAutoDialEx, the driver only uses IAI message to initiate the outgoing call. This function only sets the redirecting number in the IAI message; other parameters like address indicator can be set by the configuration item DefaultIAM_RedirectingNumber.

l This function only supports the ISUP channel now.

Related Information:

Driver version | SynCTI Ver. 5.1.0.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmAutoDial, SsmAutoDialEx


2.3.1.2.10 SsmSetWaitAutoDialAnswerTime

Sets the maximum wait time for pickup by the callee.

Format:

BOOL SsmSetWaitAutoDialAnswerTime(WORD wSeconds)

Parameter Description:

wSeconds

Wait time (second)

Return Value:

FALSE | Failed
TRUE | Successful

Function Description:

Sets the maximum wait time for pickup by the callee in an outgoing call.

Note:

l The configuration item MaxWaitAutoDialAnswerTime may implement the same function.

l This function only supports the SS1 channel, TUP channel, ISUP channel, ISDN channel and analog trunk channel.

Related Information:

Driver version | SynCTI Ver. 3.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetWaitAutoDialAnswerTime


2.3.1.2.11 SsmSetWaitAutoDialAnswerTimeEx

Sets the maximum wait time for pickup by the callee.

Format:

Int WINAPI SsmSetWaitAutoDialAnswerTimeEx(int ch, int nSeconds)

Parameter Description:

ch | Channel number
nSeconds | Wait time (second)

Return Value:

-1 | failed
0 | successful

Function Description:

Sets the maximum wait time for pickup by the callee during an outgoing call.

Note:

l The parameter nSeconds must be larger than or equal to 0, otherwise the system will prompt error. When nSeconds=0, the configuration item MaxWaitAutoDialAnswerTime or the function SsmSetWaitAutoDialAnswerTime works; when nSeconds＞0, this function SsmSetWaitAutoDialAnswerTimeEx gets valid.

l This function supports the SS1 channel, TUP channel, ISUP channel, ISDN channel, IP channel and analog trunk channel, but it is valid only if invoked before the function SsmAutoDial .

Related Information:

Driver version | SynCTI Ver. 5.3.1.1 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related function: SsmSetWaitAutoDialAnswerTime


2.3.1.2.12 SsmGetWaitAutoDialAnswerTime

Obtains the preset maximum wait time for pickup by the callee

Format:

BOOL SsmGetWaitAutoDialAnswerTime(WORD* pwSeconds)

Parameter Description:

pwSeconds

Returns the wait time (second)

Return Value:

FALSE | Failed
TRUE | Successful

Function Description:

During outgoing call, obtains the preset maximum wait time for pickup by called party.

Note:

l This function only supports the TUP channel, ISUP channel and ISDN channel.

Related Information:

Driver version | SynCTI Ver. 3.0or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSetWaitAutoDialAnswerTime


2.3.1.2.13 SsmGetKB

Obtains the called party’s state.

Format:

int SsmGetKB(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1

Failed

³0

The detailed meanings of the called party’s state is related with the channel type and call direction:

Ø Outgoing call:

² SS1 Channel: Returns the value of the KB signal which is sent from the remote end to local end.

For detailed value and its meanings, refers to the description of function SsmSetKB.

² TUP Channel: Returns the message indicator field (it includes 8 bits) in the ACM message received from the remote PBX. For more information, refer to TUP protocol related documents.

² ISUP Channel: Returns the lower 8 bits of the backward call indicator field (it includes 2 bytes) in the ACM message received from the remote PBX, for more information, refer to ISUP protocol related documents.

² ISDN Channel: Not supported.

Ø Incoming call: Returns the parameter value of the KB signal when the application calls the function SsmSetKB, for more information, refer to the description of the function SsmSetKB.

Function Description:

Obtains the called party state.

Note:

l For outgoing call, it’s recommended to invoke this function when the channel transfers to the state of S_CALL_WAIT_REMOTE_PICKUP

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSetKB


2.3.1.3 SS1 Channel Functions


2.3.1.3.1 SsmSetKA

Sets the ‘Calling Party Category ’ signal during outgoing call.

Format:

int SsmSetKA(int ch, BYTE btSigKA)

Parameter Description:

ch

Channel Number

btSigKA

KA signal’s range of value: 1≤btSigKA≤10, see below for the details:

KA Code | KA signal’s content (including KOA)
 | Local office of step-by-step system |  | Crossbar and SPC local office (including quasi-electronic telephone switching system)
 | KA |  | KA |  | KOA
1 | Common | Period | Common | Period | Common | Period
2 |  | User table, immediate |  | User table, immediate |  | User table, immediate
3 |  | Printer, immediate |  | Printer, immediate |  | Printer, immediate
4 | Reserved |  | Reserved |  | Reserved
5 | Common, no charge |  | Common, no charge |  | Common, no charge
6 | Reserved |  | Reserved |  | Reserved
7 | Reserved |  | Reserved |  | Reserved
8 | Reserved |  | Priority, period |  | Priority, period
9 | suburb call with right automatically, toll without right automatically |  | Reserved |  | Reserved
10 | toll suburb call without right automatically |  | Priority, no charge |  | Priority, no charge
11 |  |  | Reserved
12
13 |  |  | Plan for test
14 |  |  | Reserved
15 |  |  | Reserved

Return Value:

-1 | Failed
0 | Successful

Function Description:

During outgoing call, sets the KA signal value (calling party category) of R2 signaling. For more information, refer to ‘China SS1 State Machine’ in Chapter 1.

Note:

l This function only supports the SS1 channel of the SHD Series board;

l This function needs to be called before function SsmAutoDial or SsmAutoDialEx;

l Configuration item MfcKA performs the same function.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetKA


2.3.1.3.2 SsmSetKD

During the outgoing call, sets the KD signal value.

Format:

int SsmSetKD(int ch, BYTE btSigKD)

Parameter Description:

ch

Channel Number

btSigKD

Code value of the KD signal and its range of value is listed below:

KD Code | Description
1 | Toll operator semi-auto call
2 | Toll auto call (phone communication or user fax, user data communication)
3 | Local call (user calls semi-auto operator and international semi-auto operator)
4 | Local user fax or user data communication and user with priority
5 | Semi-auto callerID verificationH
6 | Test call

Return Value:

-1 | Failed
0 | Successful

Function Description:

During outgoing call, sets the KD signal value (transmit end service nature). For more information, refer to ‘China SS1 State Machine’.

Note:

l This function only supports the SS1 channel of the SHD Series board;

l This function needs to be called before function SsmAutoDial or SsmAutoDialEx;

l Configuration item MfcKD performs the same function.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetKD


2.3.2 Incoming Call Functions


2.3.2.1 Obtaining Calling Party Information


2.3.2.1.1 SsmChkOpCallerId

Obtains whether the specified channel supports the operation of callerID information reception.

Format:

int SsmChkOpCallerId (int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Failed
0 | The specified channel doesn’t support the operation of callerID information reception
1 | The specified channel supports the operation of callerID information reception

Function Description:

Obtains whether the specified channel supports the callerID information reception.

Note:

l Station channel and magnet channel doesn’t support this operation.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetCallerId


2.3.2.1.2 SsmGetCallerId

Refer to SsmGetCallerIdEx


2.3.2.1.3 SsmGetCallerIdA

Refer to SsmGetCallerIdEx


2.3.2.1.4 SsmGetCallerIdEx

Obtains the callerID information of the incoming call. SsmGetCallerId and SsmGetCallerIdA obtain the callerID information stored in the basic buffer area; SsmGetCallerIdEx obtains the callerID information stored in the extension buffer area and it’s only applicable to analog trunk channel and analog trunk recording channel.

Format:

int SsmGetCallerId(int ch, LPSTR szCallerId)

int SsmGetCallerIdEx(int ch, LPSTR szCallerIdEx)

char* SsmGetCallerIdA(int ch)

Parameter Description:

ch

Channel Number

szCallerId

String pointer storing basic callerID information and it’s storage space, allocated by the application, is not less than 255 bytes.

szCallerIdEx

String pointer storing extentional callerID information and it’s storage space, allocated by the application, is not less than 255 bytes.

Note: For analog trunk channel and analog trunk recording channel, the original data of the callerID stored in szCallerIdEx is in FSK format, for more information, refer to ‘Caller ID on Analog Phone Line’ in Chapter 1.

Return Value:

Function Name | Return Value | Description
SsmGetCallerId SsmGetCallerIdEx | -1 | Failed
 | ≥0 | The length of the callerID information
SsmGetCallerIdA | NULL | Failed
 | Other | String pointer storing the callerID basic information in the driver

Function Description:

During incoming call, obtains the callerID information stored in the internal buffer area.

For SS1 channel, if the configuration item MfcR2ToRxCallerIdBuf is set to 1, SsmGetCallerIdEx may obtain the R2 signal which is sent from the remote PBX and stored in the callerID extension information buffer of the driver. For more information, refer to ‘ China SS1 State Machine ’ in Chapter 1.

Ø IP Channel

1) For SIP channel, the calling party number obtained by this function is SIP URI (the From field in SIP message), shown in the format: [sip:/sips:]user[@host[:port]].

Note:

l Station channel and magnet channel doesn’t support this operation.

Related Information:

Driver version | SynCTI Ver.4.0or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmClearCallerId, SsmClearCallerIdEx


2.3.2.1.5 SsmGetCallerName

Obtains the name string in the FSK caller information on the analog phone line.

Format:

int SsmGetCallerName(int ch, LPSTR pszCallerName)

Parameter Description:

ch | Channel Number
pszCallerName | Pointer which points to the buffer storing the name string. The buffer space is allocated by the application and no less than 50 characters.

Return Value:

-1 | Failed
≥0 | Returns the total number of characters in pszCallerName

Function Description:

Obtains the name string in the FSK caller information on the analog phone line. For more information, refer to ‘Caller ID on Analog Phone Line’.

Note:

l This function only supports the SHT Series analog trunk channel and ATP Series analog recording channel.

Related Information:

Driver version | SynCTI Ver. 3.0or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetCallerId, SsmGetCallerIdA, SsmGetCallerIdEx


2.3.2.1.6 SsmClearCallerId

Refer to SsmClearCallerIdEx


2.3.2.1.7 SsmClearCallerIdEx

Clears the buffer area storing callerID information in the driver.

Format:

int SsmClearCallerId (int ch)

int SsmClearCallerIdEx(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Failed
0 | Successful

Function Description:

Clears the buffer area storing callerID information in the driver. SsmClearCallerId clears the basic buffer area and SsmClearCallerIdEx clears the extension buffer area.

Note:

l This function supports all SHD, ATP, DTP, DST and SHN board channels and the SHT board analog trunk channels.

Related Information:

Driver version | SynCTI Ver. 3.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetCallerId, SsmGetCallerIdA, SsmGetCallerIdEx


2.3.2.1.8 SsmGetKA

During incoming call, obtains the calling party category.

Format:

int SsmGetKA(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1

Failed

³0

Returns the ‘calling party category’. The detailed meanings are associated with channel types.

² SS1 channel: If it’s an incoming call, the KA signal value is returned, for more information, refer to the description of function SsmSetKA. If it's an outgoing call, the returned value represents the ‘calling party category’ which is sent from the local end to the remote end during the call progress.

² ISUP channel: During the incoming call, the return value represents the parameter value of ‘calling party category’ in the IAM message sent from the remote PBX.

Return Value | Description
9 | National operator (for domestic use)
10 | Ordinary subscriber, it’s used for toll to toll and toll to local office calls
11 | Calling subscriber with priority
12 | Data call (voice with data)
13 | Test call
14 | Pay phone
15 | Ordinary calling subscriber, it’s used for local office to local office calls

² TUP Channel: During incoming call, the return value represents the parameter value of ‘calling party category’ in the IAI/IAM message sent from the remote PBX.

Function Description:

During incoming call, obtains the calling party category.

Note:

l This function only supports SS1 channel, TUP channel and ISUP channel;

l It’s recommended that the application invokes this function when the channel is transferred to the state of S_CALL_RINGING.

Related Information:

Driver version | SynCTI Ver. 4.7.1.5 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSetKA, SsmGetCallerId, SsmGetChState


2.3.2.1.9 SsmGetKD

During incoming call, obtains the service nature of the original end.

Format:

int SsmGetKD(int ch)

Parameter Description:

ch

Channel number

Return Value:

-1 | Failed
³0 | Returns the value of the KD signal sent from the calling party. For more detailed information, refer to the description of function SsmSetKD.

Function Description:

During incoming call, obtains the KD signal value from the calling party (i.e. the service nature of the original end)

Note:

l This function only supports SS1 channels of SHD Series boards and the called party’s channels in the SpyCic of DTP Series boards.

l It’s recommended that the application invokes this function when the channel is transferred to the state of S_CALL_RINGING.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetChState


2.3.2.2 Obtaining Called Party Information


2.3.2.2.1 SsmGetPhoNumStr

Refer to SsmGetPhoNumLen


2.3.2.2.2 SsmGetPhoNumStrA

Refer to SsmGetPhoNumLen


2.3.2.2.3 SsmGetPhoNumLen

During incoming call, obtains the called party’s phone number information. SsmGetPhoNumLen gets the length of the phone number; SsmGetPhoNumStr and SsmGetPhoNumStrA get detailed phone number.

Format:

int SsmGetPhoNumLen(int ch)

int SsmGetPhoNumStr(int ch, LPSTR pszPhoNum)

char* SsmGetPhoNumStrA(int ch)

Parameter Description:

ch | Channel Number
pszPhoNum | The pointer which points to the buffer storing the ASCII formatted phone number of the called party. It’s allocated by the application and no less than 50 characters.

Return Value:

Function Name | Return Value | Description
SsmGetPhoNumStr SsmGetPhoNumLen | -1 | Failed
 | ≥0 | The length of the called phone number.
SsmGetPhoNumStrA | NULL | Failed
 | Other | Returns the pointer which points to the buffer storing the called phone number in the driver.

Function Description:

During incoming call, the remote PBX sends the call setup message to the local end. Upon receiving the message, the driver separates the called phone number from the message and stores it in the buffer. This function is applicable to the called party’s phone number in the buffer.

Ø IP Channel

1) For SIP channel, the called party number obtained by this function is SIP URI (the To field in SIP message), shown in the format: [“displayname“] [sip:/sips:]user[@host[:port]].

Note:

l SsmGetPhoNumLen and SsmGetPhoNumStr are only applicable to incoming calls on the SS1, TUP, ISUP, ISDN or IP channel.

l SsmGetPhoNumStrA is only applicable to incoming calls on the SS1, TUP, ISUP or ISDN channel, not to those on the IP channel;

l Only when the channel is transferred to the state of S_CALL_RING can the CalleeID of this incoming call be obtained correctly by this function call. For more information, refer to the description on state machine of related channels in Chapter 1.

l The length of the calleeID buffer in the driver is 50 characters. If the length of the received CalleeID exceeds 50, the redundant number will be discarded.

Related Information:

Driver version | SynCTI Ver. 3.0or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Event: E_CHG_RxPhoNumBuf


2.3.2.3 Obtaining 1st Called Party Number Information


2.3.2.3.1 SsmGet1stPhoNumLen

Refer to SsmGet1stPhoNumStrA


2.3.2.3.2 SsmGet1stPhoNumStr

Refer to SsmGet1stPhoNumStrA


2.3.2.3.3 SsmGet1stPhoNumStrA

Obtains the redirecting number (ISDN channel), original called party number (TUP channel) or first called party number/redirecting number (ISUP channel) information in the call setup message. SsmGet1stPhoNumLen gets the length of the information, SsmGet1stPhoNumStr and SsmGet1stPhoNumStrA get the information itself.

Format:

int SsmGet1stPhoNumStr(int ch, LPSTR pszPhoNum)

char *SsmGet1stPhoNumStrA(int ch)

int SsmGet1stPhoNumLen(int ch)

Parameter Description:

ch | Channel Number
pszPhoNum | String pointer which points to the buffer area storing phone number string. It’s allocated by the application and no less than 50 characters.

Return Value:

Function Name | Return Value | Description
SsmGet1stPhoNumStr SsmGet1stPhoNumLen | -1 | Failed
 | ≥0 | The length of the phone number string
SsmGet1stPhoNumStrA | NULL | Failed
 | Other | Returns the pointer which points to the buffer storing the phone number in the driver.

Function Description:

During incoming call, obtains the called number information in the call setup message.

Ø ISDN Channel

Obtains the redirecting number in the SETUP message.

Ø TUP Channel

Obtains the original called party number in IAI message or IAM message.

Ø ISUP Channel

Obtains the 1st called party number or redirecting number information in the IAM message. For ISUP channel, this function either returns the redirecting number information in the IAM message or original called party number information. The configuration item SaveRGNTo1stPhoNumStr determines the type of the return value:

² SaveRGNTo1stPhoNumStr is set to be 0: If there exists original called number field in IAM message, it returns original called party number information, otherwise, it returns NULL;

² SaveRGNTo1stPhoNumStr is set to be 1: If there is only redirecting number field in the IAM message, this function returns redirecting number information. If there is only original called number field, it returns original called number information. If there are both redirecting number field and original called number field, it returns the information contained in the later field of the message . For example, if this two fields have a sequence of ‘redirecting number field | original called number’, it returns the original called number information; If the sequence is ‘original called number | redirecting number field’, it returns the redirecting number information.

If it’s needed to obtain the redirecting number or original called number information in the IAM message of ISUP channel, use the function SsmGetIsupParameter.

Note:

l The length of the buffer in the driver is 50 characters. If the length of the received CalleeID exceeds 50, the redundant number will be discarded.

Related Information:

Driver version | SynCTI Ver.3.0or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetChState


2.3.2.4 Setting Parameters for Incoming Call Progress


2.3.2.4.1 SsmEnableAutoSendKB

Sets the function of ‘auto-receive inbound call’

Format:

int SsmEnableAutoSendKB(int ch, BOOL bEnable)

Parameter Description:

ch | Channel Number
bEnable | =TRUE: Enable =FALSE: Disable

Return Value:

-1 | Failed
0 | Successful

Function Description:

Sets the function of ‘auto-answer incoming call’.

Note:

l This function is only applicable to SHD Series boards.

l For SS1 inbound trunk channel, the parameters set by this function can also be set by the configuration item AutoSendKB. For more information, refer to ‘China SS1 State Machine ’ in chapter 1.

l For ISUP/TUP channel, the parameters set by this function can also be set by the configuration item AutoSendACM. For more information, refer to ‘ISUP Channel State Machine’ or ‘TUP Channel State Machine’.

l For ISDN channel, the parameters set by this function can also be set by the configuration item UserSideAutoSendAck (user side) or NetSideAutoSendAck (network side). For more information, refer to ‘ISUP Channel State Machine’ in chapter 1.

Related Information:

Driver version | SynCTI Ver. 3.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSetKB, SsmGetAutoSendKBFlag


2.3.2.4.2 SsmGetAutoSendKBFlag

Obtains flags of the function ‘auto-receive incoming call’.

Format:

int SsmGetAutoSendKBFlag(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Failed
0 | Disable
1 | Enable

Function Description:

Obtains flags of the function ’auto-answer incoming call’.

Note:

l This function is only applicable to SHD Series boards.

Related Information:

Driver version | SynCTI Ver. 4.7.1.5or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmEnableAutoSendKB


2.3.2.4.3 SsmSetKB

During incoming call, sends backward answer message to the remote PBX and sets the called party’s state.

Format:

int SsmSetKB(int ch, BYTE btSigKB)

Parameter Description:

ch

Channel Number

btSigKB

The called party state indicator. The detailed setting method is related with the channel type.

Ø SS1 channel: btSigKB indicates the backward KB signal sent to remote PBX. Below are the KB values:

btSigKB | KB
 | Receive KD=1,2 or 6 | Receive KD=3 or 4
1 | Called subscriber free | Called subscriber free Circuit reset: independent control
2 | Called subscriber ‘local busy’ | Reserved
3 | Called subscriber ‘toll busy’ |
4 | Keys congestion | Called subscriber busy or keys congestion
5 | Unallocated called party number | Unallocated CalleeID
6 | Reserved | Called subscriber free Circuit reset: Calling party control

Ø TUP channel: This parameter represents the TUP messages sent by the driver:

btSigKB | Meanings | Message Sent by the Driver
1 | Called subscriber free, charge | ACM
2 | Called subscriber ‘local busy’ | SLB
3 | Called subscriber ‘toll busy’ | STB
4 | Keys congestion | SEC
5 | Unallocated CalleeID | UNN
6 | Reserved |
7 | Called subscriber free, no charge | ACM
8 | Request callerID | GRQ (The state will be transferred to ‘waiting GSM’)
9 | Switching Equipment Congestion signal | SEC
10 | Circuit Group Congestion signal | CGC
11 | Address incomplete signal | ADI
12 | Call failure signal | CFL
13 | Line out-of-service signal | LOS
14 | Send special information tone signal | SST
15 | Access barred signal | ACB
16 | Digital path not provided signal | DPN
17 | Busy | SSB

Ø ISUP channel: This parameter represents the ISUP messages sent by the driver:

btSigKB | Meanings | Driver Operation
1/6 | Called subscriber free, charge | Send ACM Message, accept incoming call
2 | Called subscriber busy | Send REL message, reject incoming call
3 | Incomplete address | Send REL message, reject incoming call
4 | Call rejection | Send REL message, reject incoming call
5 | No answer | Send REL message, reject incoming call
7 | Called subscriber free, no charge | Send ACM Message, accept incoming call
8 | Request callerID | Send INR message, the state is transferred to ‘waiting INF’.
9 | User absent | Send REL message, reject incoming call.

Ø ISDN channel: This parameter represents the ISDN messages sent by the driver:

btSigKB | Meanings | Driver Operation
1 | Called subscriber free | Send ALERT message
2 | Called subscriber busy | Send DISCONNECT message, reason=Called subscriber busy
4 | Call rejection | Send DISCONNECT message, reason=Call rejection
5 | No answer | Send DISCONNECT message, reason=No answer from Called party
Other | Reserved |

Return Value:

-1 | Failed (Note: For the ISUP channel, it returns -1 or 0 if the call is failed)
0 | Successful (Note: For the ISUP channel, it returns 1 if the call is successful)

Function Description:

During incoming call, after the driver finishes receiving the information such as calleeID based on the preset number receiving rule, if the application disables the feature ‘Auto-reception of incoming call’ via function SsmEnableAutoSendKB or configuration item AutoSendACM, the channel state will be transferred to S_CALL_PENDING and the driver gives the control right back to the application. The application then sends the backward answer message to the remote PBX and sets the called party’s state. The application may call this function to accept or reject the current incoming call.

For more information, refer to related part in Chapter 1 according to the channel type.

² SS1 channel: ‘China SS1 State Machine ’

² ISUP channel: ‘ISUP Channel State Machine’

² TUP channel: ’ TUP Channel State Machine’

² ISDN channel: ‘ISDN Channel State Machine’

Note:

l This function is only applicable to SHD Series board.

l For ISUP channels, if the parameter bigSigKB is set to be 1,6,or 7, the driver will send ACM message to the remote PBX. The methods to construct the ACM message: If, before this function is invoked, the function SsmSetIsupUPPara (with parameter C_ISUP_ACM) is called and a self-constructed ACM message is submitted to the driver, this ACM message will be used; otherwise, the driver automatically constructed ACM message will be used. For more information, refer to ‘ISUP Channel State Machine’ in Chapter 1.

l For ISDN channels, SsmSetCharge can be used to set a call is charged or free of charge.

Related Information:

Driver version | SynCTI Ver. 4.0or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmEnableAutoSendKB


2.3.3 Channel State Transition Events


2.3.3.1 SsmGetChState

Obtains the current state of the channel.

Format:

int SsmGetChState(int ch)

Parameter Description:

ch

Channel Number

Return Value:

If it returns -1, call failed. Other return values mean as follows:

Value | MACRO in shpa3api.h | State Description
0 | S_CALL_STANDBY | ‘idle’
 | S_FAX_Wait
1 | S_CALL_PICKUPED | ‘off-hook’
2 | S_CALL_RINGING | ‘ringing’
3 | S_CALL_TALKING | ‘talking’
4 | S_CALL_ANALOG_WAITDIALTONE | Analog trunk channel: outgoing call, ‘wait for dialing tone’
5 | S_CALL_ANALOG_TXPHONUM | Analog trunk channel: outgoing call, ‘dialing’
6 | S_CALL_ANALOG_WAITDIALRESULT | Analog trunk channel: outgoing call, ‘wait for dialing result’.
7 | S_CALL_PENDING | ‘pending’ . The pending cause can be got via function SsmGetPendingReason
8 | S_CALL_OFFLINE | ’off-line’
9 | S_CALL_WAIT_REMOTE_PICKUP | Outgoing call, ‘wait answer’, 'wait called subscriber pickup'
10 | S_CALL_ANALOG_CLEAR | Analog trunk channel: internal state
11 | S_CALL_UNAVAILABLE | ‘channel unusable’
12 | S_CALL_LOCKED | ‘outgoing call locked’
19 | S_CALL_RemoteBlock | ’blocked by remote’
20 | S_CALL_LocalBlock | ’blocked locally’
30 | S_CALL_Ss1InWaitPhoNum | SS1 Channel: ‘receive called subscriber number’
31 | S_CALL_Ss1InWaitFwdStop | SS1 Channel: ‘wait remote PBX to stop sending forward signal’
32 | S_CALL_Ss1InWaitCallerID | SS1 Channel: ‘receive Caller ID’
33 | S_CALL_Ss1InWaitKD | SS1 Channel: ‘receive KD signal’
34 | S_CALL_Ss1InWaitKDStop | SS1 Channel: ‘wait remote PBX to stop sending KD signal’
35 | S_CALL_SS1_SAYIDLE | SS1 Channel: ‘send idle signal to remote PBX’
36 | S_CALL_SS1WaitIdleCAS | SS1 Channel: ‘wait idle signal from remote PBX’
37 | S_CALL_SS1PhoNumHoldup | SS1 Channel: ‘phone number hold-up’
38 | S_CALL_Ss1InWaitStopSendA3p | SS1 Channel: ‘wait remote PBX to stop sending pulse-method based A3 signal’
40 | S_CALL_Ss1OutWaitBwdAck | SS1 Channel: ‘wait remote PBX to answer seizure confirmation signal’
41 | S_CALL_Ss1OutTxPhoNum | SS1 Channel: ‘send called subscriber number’
42 | S_CALL_Ss1OutWaitAppendPhoNum | SS1 Channel: ‘wait application to append phone number’
43 | S_CALL_Ss1OutTxCallerID | SS1 Channel: ‘send caller ID’
44 | S_CALL_Ss1OutWaitKB | SS1 Channel: ‘wait KB signal which is from remote PBX’
45 | S_CALL_Ss1OutDetectA3p | SS1 Channel: ‘wait A3 pulse signal which is from remote PBX’
50 | S_FAX_ROUND | FAX channel: ‘state transition is in progress’
51 | S_FAX_PhaseA | FAX channel: ’fax call setup’ (Phase A)
52 | S_FAX_PhaseB | FAX channel: ‘handling before fax message transmission’ (Phase B)
53 | S_FAX_SendDCS | FAX channel: ’send DCS signal to the receiver during transmission
54 | S_FAX_Train | FAX channel: ‘train before fax message transmission’
55 | S_FAX_PhaseC | FAX channel: ’in fax message transmission’ (Phase C)
56 | S_FAX_PhaseD | FAX channel: ‘handling after fax message transmission’ (Phase D)
57 | S_FAX_NextPage | FAX channel: ‘transmit next page’
58 | S_FAX_AllSent | FAX channel: ‘fax message transmission is completed’
59 | S_FAX_PhaseE | FAX channel: ‘fax call is released’ (Phase E)
60 | S_FAX_Reset | FAX channel: ‘reset MODEM’
61 | S_FAX_Init | FAX channel: ‘initialize MODEM’
62 | S_FAX_RcvDCS | FAX channel: Receiving fax, ‘receive DCS signal from sender’
63 | S_FAX_SendFTT | FAX channel: Receiving fax, ‘send FTT signal indicating training failure’
64 | S_FAX_SendCFR | FAX channel: Receiving fax, ‘send CFR signal confirming the request is acceptable’
65 | S_FAX_SendPPS | FAX channel: Fax transmission. Successive fax negotiation is undergone in the ECM mode.
66 | S_FAX_RcvPPR | FAX channel: Fax reception of the PPR signal after its transmission of the PPS signal.
67 | S_FAX_RepeatECMPage | FAX channel: Fax transmission. Fax data are resent in the ECM mode.
68 | S_FAX_CTC_CTR | FAX channel: Positive negotiation is undergone in the ECM mode after 4 times data resending.
69 | S_FAX_SendPPR | FAX channel: The sender is required to resend the fax data in the ECM mode.
70 | S_TUP_WaitPcmReset | TUP channel: ‘wait circuit group to reset’
71 | S_TUP_WaitSAM | TUP channel: ‘wait for subsequent address message of remote PBX’
72 | S_TUP_WaitGSM | TUP channel: ‘wait for GSM message from remote PBX’
73 | S_TUP_WaitCLF | TUP channel: 'wait for disconnect message from remote PBX'
74 | S_TUP_WaitPrefix | TUP channel: ‘inbound office prefix’
75 | S_TUP_WaitDialAnswer | TUP channel: ‘wait for message from remote PBX’
76 | S_TUP_WaitRLG | TUP channel: ’wait for release-guard signal from remote PBX’
77 | S_TUP_WaitSetCallerID | TUP channel: ‘wait for the application to set callerID’
81 | S_ISDN_OUT_WAIT_NET_RESPONSE | ISDN channel: ‘wait for network response’
82 | S_ISDN_OUT_PLS_APPEND_NO | ISDN channel: ‘wait for the application to append the number’
83 | S_ISDN_IN_CHK_CALL_IN | ISDN channel: ‘incoming call is detected’
84 | S_ISDN_IN_RCVING_NO | ISDN channel: ‘number is been receiving’
85 | S_ISDN_IN_WAIT_TALK | ISDN channel: ‘ready for talk’
86 | S_ISDN_OUT_WAIT_ALERT | ISDN channel: ‘wait for the alerting signal from remote end’
87 | S_ISDN_CALL_BEGIN | ISDN channel: ‘originate an outgoing call or detect an incoming call’
88 | S_ISDN_WAIT_HUANGUP | ISDN channel: ‘wait for hangup’
89 | S_ISDN_IN_CALL_PROCEEDING | ISDN channel: ‘call proceeding’
100 | S_CALL_SENDRING | Magnetic channel: ‘send ring’
110 | S_SPY_SS1RESET | SS1 channel: reset
111 | S_SPY_SS1WAITBWDACK | SS1 channel: waiting for the backward acknowledgement
112 | S_SPY_SS1WAITKB | SS1 channel: waiting for the KB signal
120 | S_ISUP_WaitSAM | ISUP channel: ‘wait for SAM message from remote PBX’
121 | S_ISUP_WaitRLC | ISUP channel: ‘wait for release complete signal from remote PBX’
122 | S_ISUP_WaitReset | ISUP channel: ‘wait for circuit to reset’
123 | S_ISUP_LocallyBlocked | ISUP channel: ‘locally blocked’
124 | S_ISUP_RemotelyBlocked | ISUP channel: ‘remotely blocked’
125 | S_ISUP_WaitDialAnswer | ISUP channel: ‘wait for message from remote PBX’
126 | S_ISUP_WaitINF | ISUP channel: ‘wait for INF message from remote PBX’
127 | S_ISUP_WaitSetCallerID | ISUP channel: ‘wait for the application to set caller ID’
128 | S_DTRC_ACTIVE | DTR channel: ‘monitored voice channel is in active state’
129 | S_ISUP_Suspend | ISUP channel: ‘suspended’
130 | S_CALL_EM_TXPHONUM | E/M channel: ‘dial’ or the voice alteration resource is used
131 | S_CALL_EM_WaitIdleCAS | E/M channel: ‘wait for the idle signal from remote end’
132 | S_CALL_VOIP_DIALING | IP channel: VoIP calling party is dialing
133 | S_CALL_VOIP_WAIT_CONNECTED | IP channel: VoIP called party picks up the phone and waits for the channel to enter ‘talking’ state
134 | S_CALL_VOIP_CHANNEL_UNUSABLE | IP channel: IP channel is unusable now
135 | S_CALL_DISCONECT | USB connection is disconnected
136 | S_CALL_SS1WaitFlashEnd | SS1 channel: ‘wait for the end of flash’
137 | S_CALL_FlashEnd | SS1 channel: ‘flash ends’
139 | S_CALL_SIGNAL_ERROR | DTR channel: ‘frame synchronization normal but signal incomplete’
140 | S_CALL_FRAME_ERROR | DTR channel: ‘frame synchronization abnormal but signal complete’
150 | S_CALL_VOIP_SESSION_PROCEEDING | IP channel: ‘In session’, it is a state when 183 received.
151 | S_CALL_VOIP_REG_ING | IP channel: registering a SIP channel
152 | S_CALL_VOIP_REG_FAILED | IP channel: fail to register a SIP channel
160 | S_IP_MEDIA_LOCK | MEDIA channel: locked
161 | S_IP_MEDIA_OPEN | MEDIA channel: unlocked
300 | S_FAX_EOR_ERR | FAX channel: Negative processing is done in the ECM mode after several times fax resending.
301 | S_FAX_RNR_RR | FAX channel: The fax receiver is busy in the ECM mode.
302 | S_FAX_RTN | FAX channel: Fax reception-receiving the message denial and retraining.
other |  | reserved

Function Description:

Obtains the current channel state

Note:

l In order to enhance the application’s operation efficiency, it’s recommended to use the event of E_CHG_ChState to obtain the information of channel state changes.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetChStateKeepTime, SsmGetPendingReason


2.3.3.2 SsmGetChStateKeepTime

Retrieves the duration while the channel keeps in the current state.

Format:

long SsmGetChStateKeepTime(int ch)

Parameter Description:

ch

Channel number

Return Value:

-1 | Failed
≥0 | The duration (ms) while the channel keeps in the current state

Function Description:

Retrieves the duration while the channel keeps in the current state.

More information can be obtained via the flexible implementation of this function:

l When the incoming call channel stays in the state S_CALL_RINGING, this function can be used to retrieve the ringing tone duration.

l When the current channel stays in the state S_CALL_TALKING, this function can be used to retrieve the call duration.

l When the outgoing call channel stays in the state S_CALL_WAIT_REMOTE_PICKUP, this function can be used to retrieve the time waiting for the called subscriber to pick up the phone.

Note:

l This function is not supported for VoIP boards.

Related Information:

Driver version | SynCTI Ver.3.0or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetChState


2.3.4 Obtaining Pending Reason


2.3.4.1 SsmGetPendingReason

The detailed cause for the channel enters the state of S_CALL_PENDING.

Format:

int SsmGetPendingReason(int ch)

Parameter Description:

ch

Channel

Return Value:

-1 represents a failed call, below are the meanings of other values.

Return Value | Macro | Applicable Channel Type | Description
0 | ANALOGOUT_NO_DIALTONE | Analog trunk channel | Outgoing call failed: no dial tone detected
1 | ANALOGOUT_BUSYTONE | Analog trunk channel | Outgoing call failed: busy tone detected
2 | ANALOGOUT_ECHO_NOVOICE | Analog trunk channel | Outgoing call: after the ringback tone detected, the phone line keeps silence. The driver can’t determine whether the called subscriber picks up the phone
3 | ANALOGOUT_NOANSWER | Analog trunk channel | Outgoing call: after the ringback tone detected, the called subscriber doesn’t answer during the time specified in the configuration item MaxWaitAutoDialAnswerTime
4 | ANALOGOUT_TALKING_REMOTE_HANGUPED | Analog trunk channel | The channel in the ‘connected’ state detects that the remote subscriber has hanged up.
5 | ANALOGOUT_NOVOICE | Analog trunk channel | Outgoing call: the autodial is finished and no ringback tone or other voice signals have been detected. The driver can’t determine whether the called subscriber has hanged up.
10 | PEND_WaitBckStpMsg | ISUP / TUP/ ISDN/ SS1 | Incoming call: if, after the driver has finished receiving the information such as calleeID based on the preset number receiving rule, the feature of ‘automatically receive incoming call’ is disabled, the application itself needs to decide whether to accept this call or not.
11 | SS1IN_BWD_KB5 | SS1 | Incoming call: after the KD signal from the remote PBX has been received, the application sets KB=5 (unallocated number) and waits for the release signal from the calling party.
12 | PEND_RemoteHangupOnTalking | ISUP / TUP/ SS1 | Incoming call: the remote end hangs up the phone while talking.
13 | PEND_AutoDialFailed | ISUP / TUP/ ISDN | Outgoing call failed. You can invoke the function SsmGetAutoDialFailureReason() to get the exact reason why this auto dial fails.
14 | PEND_SsxUnusable | ISUP / TUP | SS7 signaling is unavailable
15 | PEND_CircuitReset | ISUP / TUP | Generate the event of circuit reset
16 | PEND_PcmSyncLos | ISUP / TUP SS1 | The basic frame (0 timeslot) synchronization signal of the digital trunk is lost.
20 | SS1OUT_TALKING_REMOTE_HANGUPED | SS1 | Outgoing call: the remote end hangs up the phone while talking.
 | PEND_CalleeHangupOnTalking | ISUP / TUP
21 | SS1OUT_NOANSWER | SS1 | Outgoing call failed: the called subscriber doesn’t answer the call duiring the time specified by the configuration item MaxWaitAutoDialAnswerTime
22 | SS1OUT_NOBWDACK | SS1 | Outgoing call failed: wait for the ‘Seizure Ack’ signal from the remote PBX overtime
23 | SS1OUT_DIALING_BWD_HANGUP | SS1 | Outgoing call failed: remote PBX cancels the call.
24 | SS1OUT_BWD_A5 | SS1 | Outgoing call failed: receives the A5 signal (unallocated number signal) from the remote PBX
25 | SS1OUT_BWD_KB5 | SS1 | Outgoing call failed: receives the KB=5 (unallocated number signal) from the remote PBX.
26 | SS1OUT_BWD_KB2 | SS1 | Outgoing call failed: receives KB=2(Called subscriber ‘local busy’)from the remote PBX
27 | SS1OUT_BWD_KB3 | SS1 | Outgoing call failed: receives KB=3(Called subscriber ‘toll busy’)receives from the remote PBX
28 | SS1OUT_BWD_A4 | SS1 | Outgoing call failed: receives A4 signal (keys congestion) from remote PBX
29 | SS1OUT_BWD_KB4 | SS1 | Outgoing call failed: receives KB=4 signal (keys congestion) from remote PBX
30 | SS1OUT_TIMEOUT_BWD_A | SS1 | Outgoing call failed: the wait for backward group A signals from the remote PBX is time out.
31 | SS1OUT_TIMEOUT_BWD_A_STOP | SS1 | Outgoing call failed: the wait for the remote PBX to stop sending backward group A signals is time out.
32 | SS1OUT_TIMEOUT_BWD_KB | SS1 | Outgoing call failed: the wait for KB signal from the remote PBX is time out.
33 | SS1OUT_TIMEOUT_BWD_KB_STOP | SS1 | Outgoing call failed: the wait for the remote PBX to stop sending KB signal is time out.
34 | SS1OUT_TIMEOUT_CALLERID_BWD_A1 | SS1 | Outgoing call failed: when sending calling party number to the remote PBX, the wait for backward group A signal from the remote PBX is time out.
35 | SS1OUT_TIMEOUT_CALLERID_BWD_A1_STOP | SS1 | Outgoing call failed: when sending calling party number to the remote PBX, the wait for the remote PBX to stop sending backward group A signals is timeout and the autodial fails.
36 | SS1OUT_UNDEFINED_CALLERID_BWD_A | SS1 | Outgoing call failed: receive undefined backward group A signal when sending calling party number to the remote PBX,
37 | SS1OUT_UNDEFINED_BWD_A |  | Outgoing call failed: receive undefined backward group A signal
38 | SS1OUT_UNDEFINED_BWD_KB |  | Outgoing call failed: receive the undefined KB signal
41 | ISDN_CALLOVER | ISDN | The call is over and the remote end hangs up at first.
42 | ISDN_WAIT_RELEASE | ISDN | Receives the ‘disconnected’ message from the remote end and waits for the release of the local end.
43 | ISDN_HANGING | ISDN | The local end hangs up first and is being disconnected.
44 | ISDN_RELEASING | ISDN | Releasing the call
45 | ISDN_UNALLOCATED_NUMBER | ISDN | Unallocated number
46 | ISDN_NETWORK_BUSY | ISDN | Network busy
47 | ISDN_CIRCUIT_NOT_AVAILABLE | ISDN | Designated circuit is unavailable
48 | PEND_CalleeHangupOnWaitRemotePickUp | TUP | Outgoing call failed: receives the ‘disconnected‘ message from the remote PBX when waiting for the called subscriber to pick up.
49 | ISUP_HardCircuitBlock | ISUP | Receive the hardware blocking message from the remote PBX
50 | ISUP_RemoteSuspend | ISUP | Timer T6 overflows. For more information about the timer T6, refer to the ‘ISUP Channel State Machine’ in chapter 1.
51 | PEND_RcvHGBOrSGB | TUP | Receive the blocking message from the remote PBX(SGB/HGB)
52 | ISDN_NO_ANSWER | ISDN | No answer
53 | ISDN_CALL_REJ | ISDN | Call rejection
54 | PEND_RemoteHangupOnRinging | ISUP / TUP | Incoming call: when the channel is in the ‘ringing’ state, the remote PBX cancels the call
55 | ISDN_NO_ROUTE | ISDN | No route to destination, the cause may be ‘the mobile phone is not in the service area’
56 | ISDN_NO_ROUTE_TO_DEST | ISDN | No route to the destination, the cause may be ‘the mobile phone is power off’
57 | EM_USER_BUSY | E/M | User busy
58 | EM_CH_ERROR | E/M | Channel error
59 | EM_LOCAL_HANGUP | E/M | Local end hangs up first
60 | EM_LOCAL_NOANSWER | E/M | Local end no answer
61 | EM_REMOTE_HANGUP | E/M | Remote end hangs up first
62 | EM_REMOTE_NOANSWER | E/M | Remote end no answer
63 | PEND_RemoteHangupOnSuspend | ISUP | When the channel is in the suspended state, the remote end hangs up
64 | PEND_CalleeHangupOnSuspend | ISUP | When the channel is in the suspended state, the called party hangs up
65 | ISDN_NORMAL_UNSPEC | ISDN | The call is finished normally
66 | ISDN_USER_ABSENCE | ISDN | User absent
67 | ISDN_INVALID_NUMBER_FOEMAT | ISDN | Number format invalid
68 | ISDN_NO_CIRCUIT_AVAILABLE | ISDN | No circuit/channel available
69 | IP_REMOTE_CRASHED | SIP | Remote end crashes abnormally
70 | IP_REMOTE_CLOSED | SIP | Remote end sends the BYE or CANCEL message
71 | IP_DIAL_TIMEOUT | SIP | Call over the VoIP board is time-out
72 | IP_REMOTE_REJECTED | SIP | Call from the VoIP board is rejected by the remote end
other | Reserved |  |

Function Description:

The detailed cause for the channel to be transferred to the state of S_CALL_PENDING

Note:

Related Information:

Driver version | SynCTI Ver. 3.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function:


2.3.5 Channel Pickup Functions (CTI Series)


2.3.5.1 SsmPickup

Refer to SsmPickupANX


2.3.5.2 SsmPickupANX

Executes pickup operation on the channel. SsmPickupANX not only includes all the features of SsmPickup,

but also indicates the charging information of the called party in the answer message which is only applicable to the TUP channel and ISUP channel.

Format:

int SsmPickup(int ch)

int SsmPickupANX(int ch, int nANX)

Parameter Description:

ch | Channel Number
nANX | =0:No charging information =1:Charge =2:Free of charge

Return Value:

-1 | Failed
0 | Successful

Function Description:

Executes the pickup operation on the channel.

² ISUP channel:

For ISUP channel, when the application calls this function, if the channel is in the ‘ringing’ state, based on the settings in the configuration item DefaultCalledPickupMsg, the driver will send CON (address is complete and pickup) or ANM (answer) message in which the backward call indicator field can be set by the configuration item DefaultBackwardCallInd to the remote PBX; If the channel is in ‘idle’ or ‘blocked’ state, the driver will not send any messages to the remote PBX.

² ISDN channel:

For the ISDN channel, when the application calls this function, if the channel is in the ‘ringing’ state, the driver will send CONNECT message to the remote PBX , start the Timer T313 simultaneously and then transfer the channel state to be S_ISDN_IN_WAIT_TALK; If the channel is in the state of ‘idle’ or ‘blocked’ , the driver will not send any messages to the remote PBX.

² Analog Trunk Channel

For the incoming calls in the analog trunk channel, when the application calls this function, if the channel is in the state of S_CALL_RINGING and the ringing current stays at on state, in order to avoid the damage to the voice board caused by the on-line ringing current voltage, the driver will not send the pickup command to the hardware circuit. Only when the voltage of the ringing current turns to be off will the driver execute the pickup command and throw out the event E_SYS_ActualPickup to the application. The function SsmCheckActualPickup can be used to check whether the pickup command has been finished

² IP Channel

An idle IP channel will turn into the ‘Call Hold’ state after the call of this function. Then users can invoke SsmHangup to send the channel back to the ‘Idle” state or invoke dial functions to call out. If users don’t do any operation within 60s, the channel will go back to be idle automatically. This function call for a ringing IP channel just means the reception of an incoming call. When this function is called for an IP channel in other states, it will return error.

Note:

l SsmPickup is applicable to SS1 channel, TUP channel, ISUP channel, ISDN channel, IP channel, analog trunk channel and EM Control channel. SsmPickupANX is only applicable to TUP channel and ISUP channel.

l For analog trunk channel, after the application calls this function, the driver will reset the ringing current detector and also reset and start the tone detector.

Related Information:

Driver version | SsmPickup requires SynCTI Ver. 3.0 or above SsmPickupANX requires SynCTI Ver. 4.7.1.5 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmHangup, SsmHangupEx


2.3.6 Channel Hangup Functions (CTI Series)


2.3.6.1 SsmHangup

Refer to SsmHangupEx


2.3.6.2 SsmHangupEx

Sends hangup command to the channel. SsmHangupEx may also send the information such as the cause of hangup to the driver, which is only applicable to ISUP channel.

Format:

int SsmHangup(int ch)

int SsmHangupEx(int ch, UCHAR ucCauseVal)

Parameter Description:

ch | Channel Number
ucCauseVal | The cause of hangup release. For detailed values, refer to the description on ISUP protocol.

Return Value:

-1 | Fail to hang up the call. The failure reason can be acquired via function SsmGetLastErrMsg
0 | Successful to hang up the call.

Function Description:

Sends hangup command to the channel. The operation executed by the driver is determined by the channel type.

Ø ISUP Channel

This function will trigger the driver to send REL (release) message to the remote PBX and the REL message can be used to both reject the incoming call and cancel the outgoing call. If the application calls SsmHangupEx, the release cause in the message of REL is determined by the parameter of ucCauseVal; If SsmHangup is called, the release cause varies according to the channel state:

Channel State | Release Cause in REL Message
S_CALL_PICKUPED | Not send REL message
S_ISUP_WaitDialAnswer S_CALL_WAIT_REMOTE_PICKUP S_CALL_TALKING S_ISUP_WaitSetCallerID | C_ISUP_REL_NORMAL_REL
S_ISUP_Suspend | C_ISUP_REL_DENY
S_ISUP_WaitSAM S_ISUP_WaitINF S_CALL_RINGING S_CALL_PENDING (the hangup cause is PEND_WaitBckStpMsg) | Determined by the preset value of the configuration item DefaultHangupRELInd or function SsmSetIsupFlag (with parameter ISUP_REL_DENY_SetToOther)

Note: The macro used in the above table are declared in the header file shpa3api.h.

Ø TUP Channel

If the channel is in the state of S_CALL_RINGING, invoking of this function indicates that the application rejects the incoming call. The call rejection message could be CBK or CFL and which one to be used is determined by the configuration item HangupRingSendCBK .

Ø ISDN Channel

For the ISDN channel, after invoking this function:

² If the channel is in the state of S_CALL_PENDING, the driver will send ‘RELEASE’ message to the remote PBX.

² If the channel is in the state of S_ISDN_OUT_PLS_APPEND_NO, the current call will be hanged up ,the driver will send the ‘DISCONNECT’ message to the remote PBX, in which the hangup cause field will be set to be ‘unallocated number’.

² If the channel is in the state of S_CALL_TALKING, indicating the local end hangs up first, the driver sends ‘DISCONNECT’ message to the remote PBX , in which the hangup cause is set to be ‘the call is finished normally’.

² If the channel is in the state of S_CALL_RINGING, indicating the application rejects the current incoming call, the driver sends ‘DISCONNECT’ message to the remote PBX and the hangup cause in the message is set to be ‘call rejection’.

Ø IP Channel

² If this function is called for an IP channel which stays in the ‘Call Hold’ state, the channel will turn to be idle;

² If this function is called for a non-idle IP channel, the IP state machine will trigger different protocol commands according to the current state and terminate the IP session.

Note:

l The function SsmHangupEx is applicable to ISUP channel, TUP channel, ISDN channel, analog trunk channel and SS1 channel. The VoIP channel and the EM Control channel can only use the function SsmHangup.

l For the ISDN channel, before invoking this function, the application can set the hangup cause via calling the function SsmISDNSetHangupRzn.

Related Information:

Driver version | SynCTI Ver. 2.0 or above SsmHangupEx: SynCTI Ver. 4.7.1.5or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmPickup, SsmPickupANX


2.3.7 Setting Channel’s Call Direction


2.3.7.1 SsmSetAutoCallDirection

Sets the calling direction of the channel.

Format:

int SsmSetAutoCallDirection(int ch, BOOL bEnAutoCall, int nDirection)

Parameter Description:

ch | Channel Number
bEnAutoCall | Whether the calling is processed by the driver automatically. =TRUE: yes; =FALSE: no. If ‘FALSE’, nDirection will be ignored.
nDirection | Calling direction, it’s valid only when bEnAutoCall is set to be TRUE. Range of Value: =0: only incoming call can be carried =1: only outgoing call can be carried =2: both outgoing and incoming call can be carried (this value is invalid to SS1)

Return Value:

-1 | Failed, the failure reason can be acquired via the function SsmGetLastErrMsg
³0 | Successful

Function Description:

Sets the calling direction of the channel.

Note:

l This function only supports the SS1 and ISDN channels of SHD Series, and the SIP channel of SHN Series.

l Only when the channel is in the state of S_CALL_STANDBY can this function be called.

l This function has no effect on SS7 trunk channels. If the call direction of SS7 channel is needed to be set, it can be set via blocking functions. For more details, refer to the function SsmBlockLocalCh.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetChState, SsmGetAutoCallDirection


2.3.7.2 SsmGetAutoCallDirection

Obtains the channel calling direction.

Format:

int SsmGetAutoCallDirection(int ch, int* pnDirection)

Parameter Description:

ch | Channel Number
pnDirection | Returns the calling direction, it’s valid only when bEnAutoCall is set to be TRUE. The range of value: =0: Only incoming call can be carried. =1: Only outgoing call can be carried. =2: Both incoming and outgoing call can be carried. =3: Run in the monitoring mode and the signaling mode is ISDN or TUP.

Return Value:

-1 | Failed
0 | In this channel, the calling isn’t processed by the driver automatically.
1 | In this channel, the calling is processed by the driver automatically.

Function Description:

Obtains the channel calling direction.

Note:

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSetAutoCallDirection


2.3.8 Obtaining Release Reason


2.3.8.1 SsmGetReleaseReason

Obtains the release reason value in the release message sent from the remote PBX.

Format:

WORD SsmGetReleaseReason(int ch)

Parameter Description:

ch

Channel Number

Return Value:

0

Unknow reason

>0

The reason value in the release message, the detailed message type and meaning are related with the channel type.

Ø ISUP channel: Returns the release cause in REL message. For detailed information, refer to Appendix 1 ISDN Release Cause Information Element. The often used values are:

0x01: unallocated number

0x10: normal disconnection

0x11: user busy

0x12: no answer

0x15: rejected

0x1c: incomplete address

0x1f: normal

0x2a: switching device congested

0x14: subscriber absent

0x16: number changed

Ø ISDN channel: Returns the ‘cause information element’ field in the ISDN release message. For detailed information, refer to Appendix 1 ISDN Release Cause Information Element.

Function Description:

Obtains the release reason value in the release message sent from the remote PBX.

Note:

l Before processing the incoming call (i.e. when the driver receives a call setup message from the remote PBX), the driver sets the cause value to be 0.

l This function is only applicable to ISDN channel (including network side and user side) and ISUP channel.

Related Information:

Driver version | SynCTI Ver. 4.7.1.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function:


2.3.9 TUP Channel Functions


2.3.9.1 SsmSetCalleeHoldFlag

Sets the ‘caller holding’ feature for the TUP channel.

Format:

int SsmSetCalleeHoldFlag(int ch, BOOL bFlag)

Parameter Description:

ch | Channel Number
bFlag | =TRUE: Enable =FALSE: Diable

Return Value:

-1 | Failed. The failure reason can be acquired via the function SsmGetLastErrMsg
0 | Successful

Function Description:

Sets the ‘caller holding’ feature for the TUP channel. For more information, refer to ‘the feature of caller holding’ in chapter 1.

Note:

l This function is only applicable to the TUP channels of SHD Series board

l Only when the channel is in the state of S_CALL_TALKING, can this function be called.

l During the incoming call, before the driver transfers the channel to the state of S_CALL_TALKING, it automatically sets the ‘caller holding’ feature to be disabled.

Related Information:

Driver version | SynCTI Ver. 4.7 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function:


2.3.9.2 SsmGetTupFlag

Obtains the value of the specified parameter or field in the TUP message.

Format:

int SsmGetTupFlag(int ch,int nType,DWORD *pdwParaValue)

Parameter Description:

ch | Channel Number
nType | Select the type of the parameter or field. The range of value: =1(Tup_ANX): During an outgoing call, if the called subscriber accepts this call when the channel stays in the S_CALL_WAIT_REMOTE_PICKUP state, the remote PBX will send the Answer Signal to the local end and the driver will transfer the channel state to S_CALL_TALKING. At this point, the detailed answer message type can be obtained via the parameter pdwParaValue.
pdwParaValue | Return value of the parameter or field. Detailed meaning is related with nType. nType=Tup_ANX: 0x06:ANU Message (no charging information, Unqualified) 0x16:ANC Message (Charge) 0x26:ANN Message (no charge)

Return Value:

1 | Successfully obtains the message.
-1 | Failed, the failure reason can be acquired via the function SsmGetLastErrMsg

Function Description:

Obtains the value of the specified parameter or field in the TUP message.

Note:

l This function is only applicable to the TUP channels.

Related Information:

Driver version | SynCTI Ver. 4.7.1.9or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: None


2.3.9.3 SsmSetTupParameter

Sets the optional parameters of the Tup message in the outgoing call channel.

Format:

int SsmSetTupParameter (int nBCh, UCHAR ucMsgTypeCode, UCHAR ucParamTypeCode, WORD wLength, PUCHAR pucContent)

Parameter Description:

nBCh | Channel Number
ucMsgTypeCode | Message type. The range of value: 0x21: IAI message 0x11: IAM message Other: Reserved
ucParamTypeCode | Parameter type. The type value is related with the ucMsgTypeCode: ucMsgTypeCode = IAI message: 0x00: the nature indicator of the original called party address in IAI 0x01: Sets the calling party’s category field in the IAI message 0x02: Sets the address indicator in the calling line identification field in the IAI message ucMsgTypeCode = IAM message: 0x01: Sets the calling party’s category field in the IAM message other: reserved
wLength | The length of parameter’s content
pucContent | Pointer pointing to the buffer area storing the content of the parameter

Return Value:

-1 | Failure in parameter setting
0 | Successful

Function Description:

Sets the optional parameters of the TUP message in the outgoing call channel. This function is only effective to the nature indicator of the original called party address in IAI, the address indicator in the calling line identification field in IAI and the calling party’s category field in IAI/IAM . Relative configuration items: CalloutIAM_CAT.

Note:

The parameters set in this function will go invalid once the program is restarted and the configuration file is reloaded.

Related Information:

Driver Version | SynCTI Ver. 4.7.3.1 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function：None


2.3.9.4 SsmGetTupParameter

Obtains a specified field from the received IAM message.

Format:

int SsmGetTupParameter (int nBCh, UCHAR ucMsgTypeCode, UCHAR ucParamTypeCode,PUCHAR pucContent, WORD wNumberOfBytesToWrite, LPWORD lpNumberOfBytesWritten);

Parameter Description:

nBCh | Channel Number
ucMsgTypeCode | Message type. The range of value: 0x11: IAM message Other: Reserved
ucParamTypeCode | Parameter type. The type value is related with the ucMsgTypeCode: 0xE3: obtains the CIC field of the IAM message other: reserved
pucContent | Pointer pointing to the buffer area storing the content of the parameter
wNumberOfBytesToWrite | Size of the buffer area
lpNumberOfBytesWritten | Length of the actually returned data

Return Value:

-1 | Failed to obtain
0 | Successful to obtain

Function Description:

Obtains a specified field from the received IAM message. At present this function only supports to obtain the CIC field of the IAM message.

Related Information:

Driver Version | SynCTI Ver.5.3.1.2 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function：None


2.3.10 ISUP Channel Functions


2.3.10.1 SsmSetISUPCAT

Sets the calling party category in the ISUP IAM message.

Format:

int SsmSetISUPCAT(int nch, UCHAR ucCallerCAT)

Parameter Description:

nch | Channel Number
ucCallerCAT | Hexadecimal calling party category

Return Value: 0

Function Description:

Sets the calling party category in the ISUP IAM message. The parameters set by this function can also be set by the configuration item DefaultIAM_CAT.

Note:

l This function should be called before calling the function SsmAutoDial or SsmAutoDialEx.

l The parameters set in this function will go invalid once the program is restarted and the configuration file is reloaded.

Related Information:

Driver version | SynCTI Ver. 4.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function:


2.3.10.2 SsmSetIsupParameter

Sets the optional fields in the ISUP message sent from the local end to the remote PBX.

Format:

int SsmSetIsupParameter(int ch, UCHAR ucMsuType, UCHAR ucParamType, WORD wLength, PUCHAR pucContent)

Parameter Description:

ch | Channel Number
ucMsuType | Message type. The range of value: 0x01: IAM message 0X09: ANM message Other: Reserved
ucParamType | Parameter type. The type value is related with the usMsuType: ucMsuType= IAM message: used to set optional fields ucMsuType= ANM message: used to set other optional fields except the following one: ² Backward call indicator For the parameter type of each optional field, refer to Appendix 2 ISUP Parameters. ucMsuType=other: reserved
wLength | Parameter length (byte). If ucMsuType=IAM, wLength is set to be 0 means that IAM message no longer includes the optional fields designated by ucParamType
pucContent | The content of the parameter. If ucMsuType=IAM, pucContent is set to be NULL means that IAM message no longer includes the optional fields designated by ucParamType

Return Value:

-1 | Failed
0 | Successful

Function Description:

Sets the optional fields in the ISUP message sent from the local end to the remote PBX.

Note:

l If ucMsuType is set to be the IAM message, this function should be called before invoking the function SsmAutoDial. Once the parameter value is set, it will be saved in the internal buffer area and used in the continuing IAM message. For the user to user information field in the IAM message, it can also be set by the configuration item Usr2UsrInfo.

l The parameters set in this function will go invalid once the program is restarted and the configuration file is reloaded.

Related Information:

Driver version | SynCTI Ver. 4.7.2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetIsupParameter

Sample code:

The redirection information field is added in the IAM message. The parameter type of the redirection information field is 0x13, which contains 2 bytes. Below is the meaning of the first 8-bit group (namely HGFEDCBA, A is the lowest bit) of the redirection information field:

Bit | Meaning | Value | Description
CBA | Redirection indicator | 000 | No redirection
 |  | 001 | Call reroute
 |  | 010 | Call reroute, presentation or restriction of all the redirection information
 |  | 011 | In-call modification
 |  | 100 | In-call modification, presentation or restriction of all the redirection information
 |  | 110 | In-call modification, presentation or restriction of the redirection number
 |  | other | reserved
D | Reserved |  |
HGFE | Original redirection cause | 0000 | Unknown/unusable
 |  | 0001 | User busy
 |  | 0010 | No answer
 |  | 0011 | No condition
 |  | other | reserved

Below is the meaning of the second 8-bit group (namely PONMLKJI, I is the lowest bit):

Bit | Meaning | Value | Description
KJI | Redirection counter | 1~5 | The redirection times of the call is expressed by a binary number between 1 and 5.
L | Reserved |  | Needs to be set 0
PONM | Cause of redirection | 0000 | Unknown/unusable
 |  | 0001 | User busy
 |  | 0010 | No answer
 |  | 0011 | No condition
 |  | 0110 | Unavailable mobile user
 |  | other | Reserved

If the redirection information is set to be call forwarding on no answer, the related sample code is below:

UCHAR IsupParamRI[2];

IsupParamRI[0] = 0x03; //set the content of the redirection information

IsupParamRI[1] = 0x21;

SsmSetIsupParameter(ch, 0x01, 0x13, 2, IsupParamRI);

SsmAutoDial(ch,…);


2.3.10.3 SsmGetIsupParameter

Obtains the optional fields in the ISUP message sent from the remote PBX to the local end.

Format:

int SsmGetIsupParameter(int nBCh, UCHAR ucMsuType, UCHAR ucParamType, PUCHAR pucContent, WORD wBufSize, LPWORD lpNumberOfBytesWritten)

Parameter Description:

nBCh | Channel Number
ucMsuType | Message type. Range of value: 0x01: IAM message 0x06: ACM message Others: reserved
ucParamType | l Fields of IAM message: 0xE3: Obtain the CIC field of the IAM message 0xE7: Obtain the TMR field of the IAM message 0xE8: Obtain the calling party subaddress of the IAM message 0xE9: Obtain the called party subaddress of the IAM message l The type of the optional field. This value is related with ucMsuType, for more information, refer to Appendix 2 ISUP Parameters .
pucContent | The pointer which points to the buffer area storing the content of the optional fields. The buffer area for storage is allocated by the application and its length is recommended to be 272. Note: The returned information doesn’t include the code of the type (1 byte) and the length (1byte) of the optional field.
wBufSize | The length of pucContent (byte)
lpNumberOfBytesWritten | The actual length (Byte) of the data which is written into pucContent by the driver.

Return Value:

-1 | Failed.
0 | Successful.

Function Description:

Obtains the optional fields in the ISUP message sent from the remote PBX to the local end.

Note:

Related Information:

Driver version | SynCTI Ver. 4.7.2.0or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSetIsupParameter


2.3.10.4 SsmSetIsupFlag

Sets the parameters in the ISUP user part.

Format:

int SsmSetIsupFlag(int ch, int nType, DWORD dwValue, PVOID pV)

Parameter Description:

ch

Channel number

nType

Choose the type of the parameter, below are the available values:

ISUP_PhoNumParam=2: Sets the callee parameter of the called-subscriber number field in the IAM message, at this point, the parameter dwValue is the set value and the parameter pV is invalid.

ISUP_CallerParam=1: Sets the caller parameter of the calling-subscriber number field, at this point, the parameter dwValue is the set value and the parameter pV is invalid.

ISUP_REL_DENY_SetToOther=100: When, triggered by the application’s call of the function SsmHangup , the driver sends REL message to the remote PBX, the parameter dwValue may set the release reason value carried in the REL message and the parameter pV is invalid.

ISUP_PhoNumREL=3: Sends the disconnection message including the number redirection information to the remote PBX, at this point, the parameter pV is valid.

ISUP_IAM_TMR =4: Sets the TMR (Transmission Medium Requirement) parameter in the IAM message, at this point, the parameter dwValue is the set value and the parameter pV is invalid.

DefaultIAM_OriginalCalleeParam: The parameter of the original called party

dwValue

Sets the parameter value which is related with the value of nType

Value of nType | Value and meaning of dwValue
ISUP_PhoNumParam | Refer to the configuration item DefaultIAM_CalleeParam
ISUP_CallerParam | Refer to the configuration item DefaultIAM_CallerParam
ISUP_REL_DENY_SetToOther | Refer to the configuration item DefaultHangupRELInd
ISUP_IAM_TMR | Refer to the configuration item DefaultIAM_TransmissionMediumRequirment
DefaultIAM_OriginalCalleeParam | Parameter value of Original Called Party: Spare: 0x1000 Subscriber Number: 0x1001 Unknown: 0x1002 National Number: 0x1003 International Number: 0x1004
ISUP_PhoNumREL | Reserved, unused

pV

The meaning of pV is related with the value of nType:

Ø nType=ISUP_PhoNumREL:

pV is the pointer pointing to the struct object ISUP_RIREL, which is used to customize the parameters in the REL message. The struct ISUP_RIREL in Shpa3api.h is declared below:

typedef struct tag_ISUP_RIREL{

WORD wRIMsg;

WORD wRIPhoNumPara;

WORD wPhoNumLen;

UCHAR ucRIPhoNum[20];

}ISUP_RIREL,*PISUP_RIREL;

The parameter meanings in the above struct are:

wRIMsg: The ‘redirection information’ field consists of the bits PONMLKJIHGFEDCBA;

wRIPhoNumPara: The ‘redirection number’ field consists of the bits Bit15…Bit0;

wPhoNumLen: The character number of ucRIPhoNum

ucRIPhoNum: The string of the redirection phone number.

Ø nType=other: Reserved, unused.

Note: All the constants used in the table are declared in the header file Shpa3api.h.

Return Value:

-1 | Failed
1 | Successful

Function Description:

Sets the parameters in the ISUP user part.

Note:

l ISUP_IAM_TMR=4 is only supported by SynCTI Ver. 5.1.0.0 or above.

l When nType is set to ISUP_PhoNumREL, the operation of invoking SsmSetIsupFlag on the channel ch to set some user parameters only has an effect on the current call. Otherwise, the parameters set in this function will go invalid once the program is restarted and the configuration file is reloaded.

Related Information:

Driver version | SynCTI Ver. 4.7.1.5 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetIsupFlag


2.3.10.5 SsmGetIsupFlag

Obtains the parameters in the ISUP user part.

Format:

int SsmGetIsupFlag(int ch, int nType, DWORD *pd)

Parameter Description:

ch | Channel number
nType | Select the parameter type, for more details, refer to the function SsmSetIsupFlag.
*pd | Parameter value, for more details, refer to the function SsmSetIsupFlag.

Return Value:

-1 | Failed.
1 | Successful.

Function Description:

Obtains the parameters in the ISUP user part.

Note:

Related Information:

Driver version | SynCTI Ver. 4.7.1.5or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSetIsupFlag


2.3.10.6 SsmGetIsupUPPara

Obtains the original ISUP message saved in the driver.

Format:

int SsmGetIsupUPPara(int nBCh, WORD wMsuType, LPWORD pwMsuSize, PUCHAR pucRawMsu)

Parameter Description:

nBCh

Channel Number

wMsuType

Message Type

Value | Macro in shpa3api.h | Message Corresponding with parameter pucContent
0x01 | C_ISUP_IAM | Initial address message (IAM)
0x06 | C_ISUP_ACM | Address complete message (ACM)

pwMsuSize

Returns the actual length (bytes) of the message.

pucRawMsu

Pointer which points the buffer area storing the ISUP message. The buffer area is allocated by the application and its length must be greater than or equal to 281 bytes.

Return Value:

1 | Successful
-1 | Incorrect channel number
-2 | Call failed, the parameter wMsuType is out of bound

Function Description:

Obtains the original ISUP message saved in the driver. For more information, refer to ‘ISUP Channel State Machine’ in chapter 1.

Note:

l This function only supports ISUP channel.

l The ISUP message stored in the driver will be cleared up following the hangup of the ISUP call.

Related Information:

Driver version | SynCTI Ver. 4.7.1.5 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSetIsupUPPara


2.3.10.7 SsmSetIsupUPPara

Submits a self-constructed ISUP message to the driver.

Format:

int SsmSetIsupUPPara(int nBCh, WORD wMsuType, LPWORD pwMsuSize, PUCHAR pucRawMsu)

Parameter Description:

nBCh

Channel number

wMsuType

Message Type

Value | Macro in shpa3api.h | The Message Corresponding to Parameter pucContent
0x01 | C_ISUP_IAM | Initial address message(IAM)
0x06 | C_ISUP_ACM | Address complete message (ACM)

pwMsuSize

The length (bytes) of the ISUP message (including SIO field), maximum length can’t exceed 281 bytes

pucRawMsu

Pointer which points to the initial address of the message data

Return Value:

1 | Successful
-1 | Incorrect channel number
-2 | Failed, the parameter wMsuType is out of bound
-3 | Verification failed, the message content doesn’t qualify the ISUP protocol rules

Function Description:

Submits a self-constructed ISUP message to the driver.

Note:

l This function only supports ISUP channel.

l If wMsuType is C_ISUP_IAM, this function must be called before SsmAutoDial or SsmAutoDialEx is invoked.

l If wMsuType is C_ISUP_ACM, only when the channel is in the ‘pending’ state and the cause for pending is PEND_WaitBckStpMsg, can the ACM message submitted by the application be sent to the remote PBX. For more information, refer to ‘ISUP Channel State Machine’ in chapter 1.

l When the driver sends ISUP messages submitted by the application, it automatically covers the SIO,DPC,OPC,SLC and CIC fields. If wMsuType is C_ISUP_IAM, the driver covers the corresponding fields in pucRawMsu with the calleeID in SsmAutoDial or SsmAutoDialEx.

l The parameters set in this function is only valid in the current function call.

Related Information:

Driver version | SynCTI Ver. 4.7.1.5 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmAutoDial, SsmAutoDialEx, SsmGetIsupUPPara, SsmSendIsupMsg


2.3.10.8 SsmSendIsupMsg

Sends one ISUP message to the remote PBX.

Format:

int SsmSendIsupMsg(int nBCh, WORD wMsuType)

Parameter Description:

nBCh

Channel number

wMsuType

Message Type

Value | Macro in shpa3api.h | Message Type
0x06 | C_ISUP_ACM | Address Complete Message (ACM)

Return Value:

1 | Successful
-1 | Incorrect channel number
-2 | Failed, the parameter wMsuType is out of bounds
-3 | Failed in sending message

Function Description:

Sends one ISUP message to the remote PBX. The ISUP message must be called in advance so that the ISUP message can be submitted to the driver.

Note:

l This function only supports ISUP channel.

l Only when the channel is in the S_CALL_PENDING state and the cause for pending is PEND_WaitBckStpMsg, can this function be called.

Related Information:

Driver version | SynCTI Ver. 4.7.1.5 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSetIsupUPPara


2.3.10.9 SsmGetRedirectionInfReason

During incoming call, for ISUP channel, obtains the cause value of redirection from the received IAM message; for ISDN channel, obtains the cause value of redirection from the received Setup message.

Format:

int SsmGetRedirectionInfReason(int ch)

Parameter Description:

ch

Channel number

Return Value:

-1 | Failed
≥0 | Cause value of redirection 0: Unknown/unavailable 1: User busy 2: No answer 3: Unconditional 4: Redirect the call when notified 5: Immediately redirect the call 6: Mobile subscriber unreachable

Function Description:

During incoming call, for ISUP channel, obtains the cause value of redirection from the received IAM message; for ISDN channel, obtains the cause value of redirection from the received Setup message.

Note:

Related Information:

Driver version | SynCTI Ver. 5.3.0.3 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetIsupUPPara


2.3.10.10 SsmGetRedirectionInfNum

Obtains the redirection number from an ISDN channel.

Format:

int WINAPI SsmGetRedirectionInfNum(int ch, LPSTR szRedirectNum)

Parameter Description:

ch | The channel number
szRedirectNum | The pointer pointing to the buffer area storing the redirection number. The storage space, allocated by the application, should be not less than 32 bytes.

Return Value:

≥0 | Call successful. Return the length of the redirection number in byte
-1 | Call failed

Function Description:

Obtains the redirection number from an ISDN channel.

Note:

Related Information:

Driver version | SynCTI Ver. 5.3.0.3 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function:


2.3.10.11 SsmIsHaveCpg

Refer to SsmGetCpg


2.3.10.12 SsmGetCpg

SsmIsHaveCpg checks whether ACM message is followed by the CPG message. If yes, SsmGetCpg retrieves the original CPG message stored in the driver.

Format:

int SsmIsHaveCpg(int ch)

int SsmGetCpg(int ch, char* pszContent, int* piLength)

Parameter Description:

ch | Channel Number
pszContent | Returns the content of the CPG message. For detailed information about the CPG message, refer to related documents of ISUP protocol
piLength | Returns the length of the CPG message

Return Value:

-1 | Failed. The failure reason can be acquired via the function SsmGetLastErrMsg
0 | SsmIsHaveCpg: no CPG message SsmGetCpg: Successful
1 | SsmIsHaveCpg: CPG message exists. Only when SsmIsHaveCpg returns 1, calling SsmGetCpg is meaningful.

Function Description:

During outgoing call, after the remote PBX sends ACM message, it may continue sending the CPG message (call progress). When the driver has received the CPG message, it saves the message in the internal buffer area.

This function checks whether the ACM message is followed by the CPG message.

Note:

l Only when the channel is in the S_CALL_WAIT_REMOTE_PICKUP state, can this function be called.

l When the following events happen, the driver automatically cleans the CPG message in the internal buffer:

² The channel is transferred to the S_CALL_STANDBY state.

² Receives the ACM message from the remote PBX.

l This function only supports the ISUP channel.

Related Information:

Driver version | SynCTI Ver. 4.7.1.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Event: E_CHG_ChState, E_RCV_Ss7IsupCpg


2.3.10.13 SsmIsupGetUsr

Checks and obtains the USR message.

Format:

BOOL SsmIsupGetUsr(int *ch, PUCHAR pucData, PUCHAR ucLen)

Parameter Description:

ch | The pointer pointing to the number of the channel receiving messages
pucData | The buffer area storing the ‘user-to-user information’ in the received USR message, it occupies 130 bytes
ucLen | The length of pucData

Return Value:

0 | Obtains new data
Other | No new data has been received

Function Description:

Checks and obtains the USR message. After the execution of this function, the new message will be deleted from the system.

Note: none.

Related Information:

Driver Version | SynCTI Ver. 4.7.3.1 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Event: E_RCV_Ss7IsupUtuinf


2.3.10.14 SsmIsupSendUsr

Sends the USR message.

Format:

BOOL SsmIsupSendUsr(int ch, PUCHAR pucData, UCHAR ucLen)

Parameter Description:

ch | Channel Number
pucData | The data sent as the ‘user-to-user information’ in the received USR message
ucLen | The length of pucData, the defined valid value in the protocol is 2~130

Return Value:

1 | Successful
Other | Call failed

Function Description:

Sends USR message.

Note: None.

Related Information:

Driver Version | SynCTI Ver. 4.7.3.1 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Event:


2.3.11 ISDN Channel Function

The functions provided in this section are specially used for ISDN channel calls.


2.3.11.1 Setting Parameters for Setup Message


2.3.11.1.1 SsmISDNSetDialSubAddr

Refer to SsmISDNSetDialSubAddrEx


2.3.11.1.2 SsmISDNSetDialSubAddrEx

Sets the subaddress of the called party in the SETUP message, during an outgoing call.

Format:

int SsmISDNSetDialSubAddr(int ch, LPSTR lpSubAddress)

int WINAPI SsmISDNSetDialSubAddrEx(int ch, LPBYTE lpSubAddressEx, UCHAR ucSubAddressLen)

Parameter Description:

ch | Channel Number
lpSubAddress | The subaddress of the called party. It's comprised with characters ‘0’~'9', the maximum length is 20 bytes. The storage space is allocated by the application
lpSubAddressEx | The subaddress of the called party, including the subaddress type and the buffer area storing the subaddress messages
ucSubAddressLen | The total length of the subaddress type and the buffer area storing the subaddress messages

Return Value:

0 | Successful
-1 | Failed, invoking the function SsmGetLastErrMsg to retrieve the failure reason.

Function Description:

During outgoing call, sets the subaddress of the called party.

Note:

l This function must be called before SsmAutoDial is invoked.

Related Information:

Driver version | SynCTI Ver. 3.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmAutoDial


2.3.11.1.3 SsmISDNSetTxSubAddr

Refer to SsmISDNSetTxSubAddrEx


2.3.11.1.4 SsmISDNSetTxSubAddrEx

Sets the subaddress of the calling party in the SETUP message, during an outgoing call.

Format:

int SsmISDNSetTxSubAddr(int ch, LPSTR lpSubAddress)

int WINAPI SsmISDNSetTxSubAddrEx(int ch, LPBYTE lpSubAddressEx,UCHAR ucSubAddressLen)

Parameter Description:

ch | Channel Number
lpSubAddress | The subaddress of the calling party, comprised with characters ‘0’~'9', maximum length is 20 bytes, the storage space is allocated by the application.
lpSubAddressEx | The subaddress of the calling party, including the subaddress type and the buffer area storing the subaddress messages
ucSubAddressLen | The total length of the subaddress type and the buffer area storing the subaddress messages

Return Value:

0 | Successful
-1 | Failed, Calling the function SsmGetLastErrMsg to retrieve the failure reason.

Function Description:

During outgoing call, sets the subaddress of the calling party in the SETUP message.

Note:

l This function must be called before SsmAutoDial is called.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmAutoDial , SsmISDNGetTxCallerSubAddr


2.3.11.1.5 SsmISDNSetCallerIdPresent

Sets the ‘CallerID Present’ field in the signaling messages.

Format:

int SsmISDNSetCallerIdPresent(int ch, UCHAR ucPresentation)

Parameter Description:

ch | Channel Number
ucPresentation | =0: not allowed to present =1: allowed to present, provided by users =2: allowed to present, provided by network

Return Value:

0 | Call successful
-1 | Call failed. The failure reason can be obtained by the function SsmGetLastErrMsg.

Function Description:

Sets the ‘CallerID Present’ field in the signaling messages.

Note:

l The parameters set in this function will go invalid once the program is restarted and the configuration file is reloaded to initialize the link.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function:


2.3.11.2 Obtaining Incoming Call Information


2.3.11.2.1 Obtaining Subaddress Information


2.3.11.2.1.1 SsmISDNGetSubAddr

Obtains the subaddress information of the called party.

Format:

int SsmISDNGetSubAddr(int ch, LPSTR lpSubAddress)

Parameter Description:

ch | Channel Number
lpSubAddress | Buffer area storing the subaddress of the called party, storage area is allocated by the application, the length can’t be less than 21 bytes.

Return Value:

≥0 | The actual length (bytes) of the string in lpSubAddress
-1 | Failed, the failure reason can be obtained by the function SsmGetLastErrMsg.

Function Description:

During incoming call, the message from the remote PBX includes the subaddress information of the called party. This function retrieves the ASCII character formatted subaddress information of the called party from the message.

Note: None

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmISDNGetCallerSubAddr


2.3.11.2.1.2 SsmISDNGetCallerSubAddr

Obtains the information of the calling party subaddress.

Format:

int SsmISDNGetCallerSubAddr(int ch, LPSTR lpSubAddress)

Parameter Description:

ch | Channel Number
lpSubAddress | Buffer area storing the subaddress of the calling party, storage area is allocated by the application, the length can’t be less than 21 bytes.

Return Value:

≥0 | The length of the calling party subaddress
-1 | Call failed. The failure reason can be obtained by the function SsmGetLastErrMsg

Function Description:

During incoming call, the message from the remote PBX includes the information of the calling party subaddress. This function retrieves the ASCII character formatted subaddress information of the calling party from the message.

Note: None

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmISDNGetSubAddr


2.3.11.2.2 Obtaining User-defined Calling Party Number


2.3.11.2.2.1 SsmGetUserCallerId

Obtains user-defined calling party number.

Format:

int SsmGetUserCallerId(int ch, LPSTR szCallerId)

Parameter Description:

ch | Channel Number:
szCallerId | The buffer area storing the user-defined calling party number during incoming call. Maximum length is 21 bytes

Return Value:

-1 | Call failed, the failure reason can be obtained via the function call of SsmGetLastErrMsg
≥0 | Length of the user-defined calling party number

Function Description:

Obtains user-defined calling party number.

Note:

Related Information:

Driver Version | SynCTI Ver. 4.7.3.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function:


2.3.11.3 Setting Hangup Reason


2.3.11.3.1 SsmISDNSetHangupRzn

Sets the cause of hangup.

Format:

int SsmISDNSetHangupRzn(int ch, int nReason)

Parameter Description:

ch | Channel Number
nReason | Hangup cause, the range of value: 0: Normal hangup 1: Subscriber busy 2: Unallocated number 3: Reject the current call

Return Value:

0 | Successful
-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg

Function Description:

Sets the hangup cause.

Note:

l This function must be called before the function SsmHangup is invoked.

l The parameters set in this function will go invalid once the configuration file is reloaded.

Related Information:

Driver version | SynCTI Ver. 4.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetPendingReason


2.3.11.4 Other Functions


2.3.11.4.1 SsmISDNGetDisplayMsg

Obtains the display information of the ISDN channel.

Format:

int SsmISDNGetDisplayMsg(int ch, LPSTR lpDispMsg)

Parameter Description:

ch | Channel Number
lpDispMsg | The buffer area storing the display information. The maximum length is 100 bytes

Return Value:

≥0 | The length of the display information
-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg

Function Description:

Obtains the display information of the ISDN channel. The display information is the ASCII formatted string, which is normally sent from the network side to the user side. It may also include greetings or other supplementary information.

Note: None

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: None


2.3.11.4.2 SsmISDNGetTxCallerSubAddr

Obtains the subaddress information of the calling party configured at the local end.

Format:

int SsmISDNGetTxCallerSubAddr(int ch, LPSTR lpSubAddress)

Parameter Description:

ch | Channel Number
lpSubAddress | The buffer area storing the subaddress information of the calling party during outgoing call. Maximum length is 21 bytes.

Return Value:

≥0 | The length of the calling party subaddress.
-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg

Function Description:

Obtains the subaddress information of the calling party configured at the local end.

Note:

l This function is only applicable to the outgoing call.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmISDNGetSubAddr


2.3.11.4.3 SsmSetNumType

Sets the calling/called party number type for a specified channel.

Format:

int SsmSetNumType(int ch, int nNumClass, int nNumType)

Parameter Description:

ch | Channel Number
nNumClass | Calling/called Party Number: 1: Calling party number 2: Called party number
nNumType | Number Type: 0x00: Unknown 0x10: International number 0x20: National number 0x30: Specified network number 0x40: Specified number or subscriber number Others: Spare

Return Value:

-1 | Call failed
0 | Call successful

Function Description:

Sets the calling/called party number type for a specified channel.

Note:

l This function is only applicable to ISDN channels.

Related Information:

Driver version | SynCTI Ver. 5.0.2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetNumType, NetCallingNoSet


2.3.11.4.4 SsmGetNumType

Gets the calling/called party number type for a specified channel.

Format:

int SsmGetNumType(int ch, int nNumClass, int* pNumType)

Parameter Description:

ch | Channel Number
nNumClass | Calling/called Party Number: 1: Calling party number 2: Called party number
pNumType | Number Type: 0x00: Unknown 0x10: International number 0x20: National number 0x30: Specified network number 0x40: Specified number or subscriber number Others: Spare

Return Value:

-1 | Call failed
0 | Call successful

Function Description:

Gets the calling/called party number type for a specified channel.

Note:

l This function is only applicable to ISDN channels.

Related Information:

Driver version | SynCTI Ver. 5.0.0.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSetNumType, NetCallingNoSet


2.3.11.4.5 SsmSetCharge

Sets if a call is charged or free of charge.

Format:

int SsmSetCharge(int ch,int ChargeFlag)

Parameter Description:

ch | Channel number
ChargeFlag | 0: Free call; 1: Charge; Others: Reserved

Return Value:

-1 | Call failed
0 | Call successful

Function Description:

Sets if a call on the corresponding channel is charge or free of charge.

Note:

l This function only supports ISDN channels for some particular PBX models;

l It can be invoked in a state of ringback or talking for a call outbound;

l It can be invoked in a state of talking for a call inbound.

Related Information:

Driver version | SynCTI Ver. 5.0.0.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function:


2.4 Tone Generator Functions (CTI Series)


2.4.1 Setting Parameters for Tone Generator


2.4.1.1 SsmSetTxTonePara

Sets the frequency and volume of the tone generated by the tone generator.

Format:

int SsmSetTxTonePara(int ch, int nFreq1, int nVolume1, int nFreq2, int nVolume2)

Parameter Description:

ch | Channel Number
nFreq1 | Sets the 1st frequency (Hz) of the tone, range of value: 300~3400, the default value : 450
nVolume1 | Sets the 1st volume of the tone, range of value: -7~+6. Great than 0 means that volume is increased, less than 0 means the volume is decreased, -7 means to turn off the 1st tone. The default value is 0. The volume value multiplies 3 equals the decibel value.
nFreq2 | Sets the 2nd frequency (Hz) of the tone, range of value: 300~3400, with the default value of 0 which means that this frequency is not been used, only the single frequency tone is sent.
nVolume2 | Sets the 2nd volume of the tone, range of value: -7~+6. Great than 0 means that volume is increased, less than 0 means the volume is decreased, -7 means to turn off the 2nd tone. The default value is -7 (the 2nd tone is not bee used). The volume value multiplies 3 equals the decibel value.

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Sets the frequency and volume of the tone generated by the tone generator.

Note:

l The configuration items DefaultSendToneFrequence and DefaultSendToneVolume can achieve the same settings as described above. The default tone generator is a single frequency tone generator with 450Hz frequency.

Related Information:

Driver version | SynCTI Ver. 2.0.0.0or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSendTone


2.4.1.2 SsmQueryOpSendTone

Checks whether a tone generator exists on the channel.

Format:

int SsmQueryOpSendTone (int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Failed
0 | No
1 | Yes, it exists

Function Description:

Checks whether a tone generator exists on the channel.

Note:

Related Information:

Driver version | SynCTI Ver. 2.0.0.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function:


2.4.1.3 SsmGetTxTonePara

Obtains the frequency and volume of the tone generator.

Format:

int SsmGetTxTonePara(int ch, int* nFreq1, int* nVolume1, int* nFreq2, int* nVolume2)

Parameter Description:

ch | Channel number
nFreq1 | Returns the frequency (Hz) of the 1st tone.
nVolume1 | Returns the volume of the 1st tone, range of value: -7~+6. Great than 0 means that volume is increased, less than 0 means the volume is decreased, -7 means this frequency is not been used. The volume value multiplies 3 equals the decibel value.
nFreq2 | Returns the frequency (Hz) of the 2nd tone.
nVolume2 | Returns the volume of the 2nd tone, range of value: -7~+6. Great than 0 means that volume is increased, less than 0 means the volume is decreased, -7 means that this frequency is not been used. The volume value multiplies 3 equals the decibel value.

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Obtains the frequency and volume when the tone generator sends the tone.

Note:

Related Information:

Driver version | SynCTI Ver. 2.0.0.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSetTxTonePara


2.4.2 Sending Tones


2.4.2.1 SsmSendTone

Refer to SsmSendToneEx


2.4.2.2 SsmSendToneEx

Starts the tone generator, generates the tone on the line. SsmSendTone is used to send the tone with driver-predefined type. SsmSendToneEx specifies the signal duration at on or off.

Format:

int SsmSendTone(int ch, int nToneType)

int SsmSendToneEx(int ch, DWORD dwOnTime, DWORD dwOffTime)

Parameter Description:

ch | Channel Number
nToneType | Tone type, the range of value: 0: dial tone 1: busy tone 2: ringback tone 3: howler tone
dwOnTime | Signal duration (ms) at on state. Must be integral times of 8
dwOffTime | Signal duration (ms) at off state. Must be integral times of 8

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Generates single or dual tone on the specified channel.

Note:

l The frequency and volume value of the tone can be set via the function SsmSetTxTonePara or the configuration item DefaultSendToneFrequence and DefaultSendToneVolume.

l Once the tone generator is started, the specified tone will be continuously presented on the line until the application calls the function SsmStopSendTone.

Related Information:

Driver version | SynCTI Ver. 2.0.0.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmStopSendTone, SsmSetTxTonePara, SsmChkSendTone


2.4.2.3 SsmStopSendTone

Stops the tone generator.

Format:

int SsmStopSendTone(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Stops the tone generator.

Note:

Related Information:

Driver version | SynCTI Ver. 2.0.0.0or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSendTone, SsmSendToneEx


2.4.2.4 SsmChkSendTone

Checks whether the tone generator is started, and checks the type of the tone which is being sent.

Format:

int SsmChkSendTone(int ch, int* pnToneType)

Parameter Description:

ch | Channel Number
pnToneType | Returns the type of the tone which is being sent on the channel: 0: dial tone 1: busy tone 2: ringback tone 3: howler tone 4: self-defined tone (generated upon detecting SsmSendToneEx) 5: no tone

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | No tone is being sent on the channel
1 | The tone is being sent on the channel

Function Description:

Checks whether the tone generator is started, and checks the type of the tone which is being sent.

Note:

Related Information:

Driver version | SynCTI Ver. 2.0.0.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSendTone, SsmSendToneEx


2.5 Tone Detector Functions


2.5.1 Commonly Used Tone Detector Functions


2.5.1.1 Setting Working Status


2.5.1.1.1 SsmStartToneAnalyze

Starts the tone detector.

Format:

int SsmStartToneAnalyze(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Call successful

Function Description:

Starts the tone detector. For more information, refer to Tone Detector in chapter 1.

Note:

l By default this function is only applicable to analog trunk channels, magnet channels and recording channels.

l If tone analysis is required for digital boards, you should configure DefaultToneCheckState=1 under Section [BoardId=x] in the file ShConfg.ini, or set this function SsmStartToneAnalyze to start the tone detector.

Related Information:

Driver version | SynCTI Ver. 2.0.0.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmCloseToneAnalyze, SsmStart2ndToneAnalyzer


2.5.1.1.2 SsmCloseToneAnalyze

Stops the tone detector.

Format:

int SsmCloseToneAnalyze (int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Stops the tone detector. For more information, refer to Tone Detector in chapter 1.

Note:

Related Information:

Driver version | SynCTI Ver. 2.0.0.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmStartToneAnalyze


2.5.1.1.3 SsmQueryOpToneAnalyze

Checks whether the channel includes the tone detector.

Format:

int SsmQueryOpToneAnalyze(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | No
1 | Yes, it includes the tone detector

Function Description:

Checks whether the channel includes the tone detector.

Note:

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function:


2.5.1.2 Obtaining Detected Result


2.5.1.2.1 SsmGetToneAnalyzeResult

Obtains the detected result of the tone detector.

Format:

int SsmGetToneAnalyzeResult (int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Failed
0 | The tone is being analyzed
1 | Dial tone is detected
2 | Busy tone is detected
3 | Ringback tone is detected
4 | After the ringback tone is detected, the line keeps silent
5 | It’s detected that the line is silent
6 | The answer signal is detected. For analog phone lines, it usually represents whether the called subscriber answers the call (pick up the phone).
7 | The single frequency tone with F1 frequency is detected. The parameter F1 is set by the function SsmSetVoiceFxPara, which is often used to detect the fax tone of the fax machine.
8 | The single frequency tone with F2 frequency is detected. The parameter F2 is set by the function SsmSetVoiceFxPara, which is often used to detect the fax tone of the fax machine.
9 | The subscriber-defined tone type is detected.
n>9 | Some particular user-defined tones (e.g. SIT) are detected. For more information, see the section ‘Enhanced Tone Detector’.

Function Description:

Obtains the detected result of the tone detector.

Note:

l By default this function is only applicable to analog trunk channels, magnet channels and recording channels;

l For digital boards, if the tones need to be analyzed, the following configuration item in the section of [BoardId＝x] in the file ShConfg.ini needs to be configured. DefaultToneCheckState=1.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmClearToneAnalyzeResult


2.5.1.3 Clearing Detected Result


2.5.1.3.1 SsmClearToneAnalyzeResult

Clears the detected result of the tone detector.

Format:

int SsmClearToneAnalyzeResult (int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Failed
0 | Successful

Function Description:

Clears the detected result of the tone detector.

Note:

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetToneAnalyzeResult


2.5.2 FFT Functions


2.5.2.1 Setting Parameters


2.5.2.1.1 SsmSetPeakFrqDetectBW

Sets the bandwidth used to detect the peak frequency in the incoming call signal.

Format:

int SsmSetPeakFrqDetectBW(int ch, WORD nPeakBW)

Parameter Description:

ch | Channel Number
nPeakBW | Bandwidth (Hz) , range of value: 40~80, with the default value of 80Hz.

Return Value:

-1 | Failed
0 | Successful

Function Description:

Sets the bandwidth used to detect the peak frequency in the incoming call signal. For more information, refer to Tone Detector in chapter 1.

Note:

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmQueryOpPeakFrqDetect, SsmGetPeakFrqDetectBW


2.5.2.2 Obtaining Parameters


2.5.2.2.1 SsmQueryOpPeakFrqDetect

Checks whether the channel supports the operation of detecting the peak frequency.

Format:

int SsmQueryOpPeakFrqDetect (int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Failed
0 | Not supported
1 | Supported

Function Description:

Checks whether the channel supports the operation of detecting the peak frequency.

Note:

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function:


2.5.2.2.2 SsmGetPeakFrqDetectBW

Obtains the bandwidth parameter used to detect the peak frequency.

Format:

int SsmGetPeakFrqDetectBW(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Failed
³0 | The set value of the bandwidth

Function Description:

Obtains the bandwidth parameter used to detect the peak frequency.

Note:

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmQueryOpPeakFrqDetect, SsmSetPeakFrqDetectBW


2.5.2.3 Obtaining Detected Result


2.5.2.3.1 SsmGetPeakFrq

Obtains the peak frequency in the incoming call signal.

Format:

int SsmGetPeakFrq(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Failed
³0 | The peak frequency in the incoming call signal

Function Description:

Obtains the peak frequency in the incoming call signal. For more information, refer to ‘Tone Detector’ in chapter 1.

Note:

l The event of E_CHG_PeakFrq may implement the same feature.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmQueryOpPeakFrqDetect, SsmSetPeakFrqDetectBW


2.5.2.3.2 SsmGetPeakFrqEnergy

Obtains the energy value of the peak frequency in the incoming call signal.

Format:

long SsmGetPeakFrqEnergy(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Failed
³0 | The energy value of the peak frequency in the incoming call signal

Function Description:

Obtains the energy value of the peak frequency in the incoming call signal. For more information, refer to ‘Tone Detector’ in chapter 1.

Note:

l The event of E_CHG_PeakFrq may implement the same feature.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSetPeakFrqDetectBW, SsmGetPeakFrq


2.5.2.3.3 SsmGetOverallEnergy

Refer to SsmGetOverallEnergyAllCh


2.5.2.3.4 SsmGetOverallEnergyAllCh

Obtains the overall energy value of the incoming call signal after FFT transformation. SsmGetOverallEnergy operates on each channel, SsmGetOverallEnergyAllCh may simultaneously obtain the overall energy of multiple channels.

Format:

int SsmGetOverallEnergy(int ch)

int SsmGetOverallEnergyAllCh (int nBeginCh, int nChNum, PDWORD pdwEnergyTable)

Parameter Description:

ch | Channel Number
nBeginCh | Starting channel number
nChNum | Channel amount
PdwEnergyTable | Stores the energy value of the nChNum channels starting from nBeginCh which is allocated by the application

Return Value:

Function Name | Return Value | Description
SsmGetOverallEnergy | -1 | Call failed
 | ≥0 | Overall energy value
SsmGetOverallEnergyAllCh | -1 | Call failed
 | 0 | Successful

Function Description:

Obtains the overall energy value of the incoming call signal after FFT transformation.

Note:

l For more information about the conversion of the unit of overall energy to DB (decibel), refer to the ‘FFT component’ in ‘Tone Detector’ of Chapter 1.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetPeakFrqEnergy


2.5.3 Setting Parameters for Noise Filter


2.5.3.1 SsmSetMinVocDtrEnergy

Sets the threshold value for noise detection on the line.

Format:

int SsmSetMinVocDtrEnergy(int ch, DWORD dwMinVocDtrEnergy)

Parameter Description:

ch | Channel Number
dwMinVocDtrEnergy | Threshold value for noise detection, range of value: ³700, with the default value of 100000. For more information about the conversion of the unit of this parameter to DB (decibel), refer to the ‘FFT component’ in ‘Tone Detector’ of Chapter 1.

Return Value:

-1 | Call failed, the failure reason can be obtained by the functionSsmGetLastErrMsg
0 | Successful

Function Description:

Sets the threshold value for noise detection on the line. If the energy of the incoming call signal on the line is less than the set value of dwMinVocDtrEnergy, it will be regarded as noise by the driver.

Note:

l The configuration item MinimumVoiceDetermineEnergy may implement the same feature.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetMinVocDtrEnergy


2.5.3.2 SsmGetMinVocDtrEnergy

Obtains the threshold value of energy for the driver to determine whether the signal on the line is noise or voice.

Format:

int SsmGetMinVocDtrEnergy(int ch, PDWORD pdwMinVocDtrEnergy)

Parameter Description:

ch | Channel Number
pdwMinVocDtrEnergy | Returns the threshold value of energy which determines whether it’s noise or voice.

Return Value:

-1 | Failed
0 | Successful

Function Description:

Obtains the threshold value of energy for the driver to determine whether the signal on the line is noise or voice.

Note:

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSetMinVocDtrEnergy


2.5.4 Call Progress Tone Detector Functions


2.5.4.1 Setting Working Status of 2nd Call Progress Tone Detector


2.5.4.1.1 SsmStart2ndToneAnalyzer

Starts the 2nd call progress tone detector.

Format:

int SsmStart2ndToneAnalyzer(int ch,BOOL bEnable)

Parameter Description:

ch | Channel Number
bEnable | The 2nd tone detector enabling switch. = TRUE: Start; = FALSE: Stop

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Starts the 2nd call progress tone detector.

Note:

l The feature set by this function can also be set by the configuration item Enable2ndToneAnalyzer.

l Because the 2nd call progress tone detector occupies the FFT analyzer which is used by the function SsmSetVoiceFxPara, the driver no longer detects the special tones designated by the function SsmSetVoiceFxPara when the 2nd call progress tone detector is started.

l Only under the condition that the 1st call progress tone detector is turned on, it’s valid to turn on the 2nd call progress detector.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGet2ndToneAnalyzerState


2.5.4.1.2 SsmGet2ndToneAnalyzerState

Checks the working status of 2nd call progress tone detector.

Format:

int SsmGet2ndToneAnalyzerState(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Failed
0 | Started
1 | Stopped

Function Description:

Checks the working status of 2nd call progress tone detector.

Note:

l By default this function is only applicable to analog trunk channels, magnet channels and recording channels.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmStart2ndToneAnalyzer


2.5.4.2 Obtaining Result of 2nd Call Progress Tone Detector


2.5.4.2.1 SsmGet2ndToneAnalyzeResult

Obtains the result of the 2nd call progress tone detector.

Format:

int SsmGet2ndToneAnalyzeResult(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Failed
0 | Tone analysis is in progress
1 | Dial tone detected
2 | Busy tone detected
3 | Ringback tone detected
4 | line silence after ringback tone detected
5 | Silence detected
6 | Answer tone detected, which usually indicates for analog phone lines that the called party answers (picks up) the call.
7 | Single tone that represents the characteristic of F1 frequency detected. F1 whose parameters are set via the function SsmSetVoiceFxPara is often used to detect fax tone.
8 | Single tone that represents the characteristic of F2 frequency detected. F2 whose parameters are set via the function SsmSetVoiceFxPara is often used to detect fax tone.
9 | User-defined tone detected
>9 | Particular user-defined tone detected (e.g. SIT tone). For more information, refer to the section Enhanced Tone Detector in Chapter 1.

Function Description:

Obtains the result of the 2nd call progress tone detector.

Note:

l If the result of the second tone detector shows that this group of tones are the same in frequency as the firtst group of tones, only a detector for one of these two groups of tones actually works by default.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmClear2ndToneAnalyzeResult


2.5.4.2.2 SsmClear2ndToneAnalyzeResult

Clears the result of the 2nd call progress tone detector.

Format:

int SsmClear2ndToneAnalyzeResult(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Failed
0 | Successful

Function Description:

Clears the result of the 2nd call progress tone detector.

Note:

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGet2ndToneAnalyzeResult


2.5.4.3 Setting Parameters for Frequency Detector


2.5.4.3.1 SsmSetTonePara

Refer to SsmSet2ndTonePara


2.5.4.3.2 SsmSet2ndTonePara

Sets the operating parameters of the frequency detector in the call progress tone detector. SsmSetTonePara and SsmSet2ndTonePara are used to set the frequency parameters of the 1st and 2nd call progress tone detector respectively.

Format:

int SsmSetTonePara(int ch, WORD wF1, WORD wBw1, WORD wF2, WORD wBw2, DWORD dwMinEnrgRatio)

int SsmSet2ndTonePara(int ch, WORD wF1, WORD wBw1, WORD wF2, WORD wBw2, DWORD dwMinEnrgRatio)

Parameter Description:

ch | Channel Number
wF1 | The 1st center frequency (Hz), range of value: 300~3400
wBw1 | The bandwidth (Hz) of the 1st center frequency, range of value: 40~120
wF2 | The 2nd center frequency (Hz), range of value: 300~3400
wBw2 | The bandwidth (Hz) of the 2nd center frequency, range of value: 40~120
dwMinEnrgRatio | Determining threshold value percentage (%), range of value: 15~80

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Sets the operating parameters of the frequency detector in the call progress tone detector. For more information, refer to Call Progress Tone Detector in chapter 1.

Note:

l The configuration item TonePara may implement the same feature of the function SsmSetTonePara, with the default value of 450Hz;

l The configuration item 2ndTonePara may implement the same feature of the function SsmSet2ndTonePara.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetTonePara, SsmGet2ndTonePara


2.5.4.3.3 SsmGetTonePara

Refer to SsmGet2ndTonePara


2.5.4.3.4 SsmGet2ndTonePara

Obtains the operating parameters of the frequency detector in the call progress tone detector. SsmGetTonePara and SsmGet2ndTonePara are used to obtain the frequency parameters of the 1st and 2nd call progress tone detector respectively.

Format:

int SsmGetTonePara(int ch, PWORD pwF1, PWORD pwBw1, PWORD pwF2, PWORD pwBw2, PDWORD pdwMinEnrgRatio)

int SsmGet2ndTonePara(int ch, PWORD pwF1, PWORD pwBw1, PWORD pwF2, PWORD pwBw2, PDWORD pdwMinEnrgRatio)

Parameter Description:

ch | Channel Number
pwF1 | Returns the center frequency (Hz) of the 1st tone
pwBw1 | Returns the bandwidth (Hz) of the 1st tone
pwF2 | Returns the center frequency (Hz) of the 2nd tone
pwBw2 | Returns the bandwidth (Hz) of the 2nd tone
pdwMinEnrgRatio | Returns the preset threshold value percentage of the in-band energy in the overall energy which determines whether it’s a signal tone

Return Value:

-1 | Failed
0 | Successful

Function Description:

Obtains the operating parameters of the frequency detector in the call progress tone detector.

Note:

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSetTonePara, SsmSet2ndTonePara


2.5.4.4 Setting Parameters for Dial Tone Detector


2.5.4.4.1 SsmSetIsDialToneDtrTime

Refer to SsmSet2ndIsDialToneDtrTime


2.5.4.4.2 SsmSet2ndIsDialToneDtrTime

Sets the minimum duration of the dial tone detector. SsmSetIsDialToneDtrTime and SsmSet2ndIsDialToneDtrTime set the 1st and 2nd call progress tone detector respectively.

Format:

int SsmSetIsDialToneDtrTime(int ch, WORD wIsDialToneDtrTime)

int SsmSet2ndIsDialToneDtrTime(int ch, WORD wIsDialToneDtrTime)

Parameter Description:

ch | Channel Number
wIsDialToneDtrTime | The minimum duration (ms) of the dial tone, range of value: ≥1200ms

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Sets the minimum duration of the dial tone detector.

Note:

l The configuration item IsDialToneDetermineTime may implement the same feature of the function SsmSetIsDialToneDtrTime.

l The configuration item 2ndIsDialToneDetermineTime may implement the same feature of the function SsmSetIsDialToneDtrTime.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetIsDialToneDtrTime, SsmGet2ndIsDialToneDtrTime


2.5.4.4.3 SsmGetIsDialToneDtrTime

Refer to SsmGet2ndIsDialToneDtrTime


2.5.4.4.4 SsmGet2ndIsDialToneDtrTime

Obtains the minimum duration of the dial tone detector.

SsmGetIsDialToneDtrTime and SsmGet2ndIsDialToneDtrTime retrieves tones of the 1st and 2nd call progress tone detector respectively.

Format:

int SsmGetIsDialToneDtrTime(int ch, PWORD pwIsDialToneDtrTime)

int SsmGet2ndIsDialToneDtrTime(int ch, PWORD pwIsDialToneDtrTime)

Parameter Description:

ch | Channel Number
pwIsDialToneDtrTime | Returns the minimum duration (ms)

Return Value:

-1 | Failed
0 | Successful

Function Description:

Obtains the minimum duration of the dial tone detector.

Note:

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSetIsDialToneDtrTime, SsmSet2ndIsDialToneDtrTime


2.5.4.5 Setting Parameters for Ringback Tone Detector


2.5.4.5.1 SsmSetRingEchoTonePara

Refer to SsmSet2ndRingEchoTonePara


2.5.4.5.2 SsmSet2ndRingEchoTonePara

Sets the signal durations at on and off for the ringback tone detector. SsmSetRingEchoTonePara is applicable to the 1st call progress tone detector, SsmSet2ndRingEchoTonePara is applicable to applicable to the 2nd call progress tone detector.

Format:

int SsmSetRingEchoTonePara(int ch, WORD wTon, WORD wToff)

int SsmSet2ndRingEchoTonePara(int ch, WORD wTon, WORD wToff)

Parameter Description:

ch | Channel Number
wTon | The duration (ms) of the tone at on state, range of value: 500~2500
wToff | The duration (ms) of the tone at off state, range of value: 1500 ~ 6000

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Sets the signal durations respectively at on and off for the Ringback Tone Detector.

Note:

l The parameters set by SsmSetRingEchoTonePara can also be set by the configuration item RingEchoTonePara. Default value: The signal duration at on state is 1000ms, the signal duration at off state is 4000ms; The parameters set by SsmSet2ndRingEchoTonePara can also be set by the configuration item 2ndRingEchoTonePara. Default value: The signal duration at on state is 1000ms, the signal duration at off state is 4000ms.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetRingEchoTonePara, SsmGet2ndRingEchoTonePara


2.5.4.5.3 SsmGetRingEchoToneTime

Obtains the duration of ringback tone.

Format:

int SsmGetRingEchoToneTime(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Failed
≥0 | Duration time (ms)

Function Description:

Obtains the duration of ringback tone.

Note:

l This function is only applicable to the analog trunk channel.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function:


2.5.4.5.4 SsmGetRingEchoTonePara

Refer to SsmGet2ndRingEchoTonePara


2.5.4.5.5 SsmGet2ndRingEchoTonePara

Obtains the signal durations respectively at on and off for the ringback tone detector. SsmGetRingEchoTonePara and SsmGet2ndRingEchoTonePara are applicable to the 1st and 2nd call progress tone detector respectively.

Format:

int SsmGetRingEchoTonePara(int ch, PWORD pwTon, PWORD pwToff)

int SsmGet2ndRingEchoTonePara(int ch, PWORD pwTon, PWORD pwToff)

Parameter Description:

ch | Channel Number
pwTon | Returns the signal duration (ms) at on state
pwToff | Returns the signal duration (ms) at off state

Return Value:

-1 | Failed
0 | Successful

Function Description:

Obtains the signal durations respectively at on and off for the ringback tone detector.

Note:

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSetRingEchoTonePara, SsmSet2ndRingEchoTonePara


2.5.4.6 Setting Parameters for Busy Tone Detector


2.5.4.6.1 SsmSetBusyTonePeriodEx

Refer to SsmSet2ndBusyTonePeriod


2.5.4.6.2 SsmSetBusyTonePeriod

Refer to SsmSet2ndBusyTonePeriod


2.5.4.6.3 SsmSet2ndBusyTonePeriod

Sets the busy tone cycle of busy tone detector in the call progress tone detector. SsmSetBusyTonePeriod is applicable to the 1st call progress tone detector, SsmSet2ndBusyTonePeriod is applicable to the 2nd call progress tone detector, and SsmSetBusyTonePeriodEx is applicable to both 1st and 2nd call progress tone detector.

Format:

int SsmSetBusyTonePeriodEx(int ch, int nCptdNo, WORD wMax, PWORD pwPeriod)

int SsmSetBusyTonePeriod(int ch, WORD wPeriod)

int SsmSet2ndBusyTonePeriod(int ch, WORD wPeriod)

Parameter Description:

ch | Channel Number
nCptdNo | =1: Sets the 1st call progress tone detector =2: Sets the 2nd call progress tone detector
wMax | The number of the busy tone cycle, range of value: 1~4
pwPeriod | The pointer storing the parameter of busy tone cycle, it’s storage space is allocated by the application
wPeriod | Busy tone cycle (ms) , range of value: 200~2000. This parameter can be specified in the configuration file, with the default value of 700ms (350ms/ON,350ms/OFF)

Return Value:

-1 | Failed
0 | Successful

Function Description:

Sets the busy tone cycle of busy tone detector in the Call Progress Tone Detector. SsmSetBusyTonePeriodEx is a new version function with more features, it can set at most 4 different busy tone cycles. For more information, refer to ‘Busy Tone Detector’.

Note:

l The busy tone cycle may also be set via the configuration item BusyTonePeriod or 2ndBusyTonePeriod .

l It’s recommended to use the function SsmSetBusyTonePeriodEx.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetBusyTonePeriodEx, SsmGetBusyTonePeriod, SsmGet2ndBusyTonePeriod

Sample Code:

The application needs to simultaneously detect 4 types of busy tones (700ms, 800ms, 900ms and 1000ms period) in the 1st call progress tone detector and only detects the busy tone with 700ms period in the 2nd call progress tone detector, below is the implementing sample code:

WORD BusyTonePeriod[4] = {700,800,900,1000};

SsmSetBusyTonePeriodEx(ch, 1, 4, BusyTonePeriod);

SsmSet2ndBusyTonePeriod(ch, 700);


2.5.4.6.4 SsmSetIsBusyToneDtrCnt

Refer to SsmSet2ndIsBusyToneDtrCnt


2.5.4.6.5 SsmSet2ndIsBusyToneDtrCnt

Sets the minimum number of the busy tone cycles. SsmSetIsBusyToneDtrCnt is applicable to the 1st call progress tone detector, SsmSet2ndIsBusyToneDtrCnt is applicable to the 2nd call progress tone detector.

Format:

int SsmSetIsBusyToneDtrCnt(int ch, WORD wIsBusyToneDtrCnt)

int SsmSet2ndIsBusyToneDtrCnt(int ch, WORD wIsBusyToneDtrCnt)

Parameter Description:

ch | Channel Number
wIsBusyToneDtrCnt | The minimum number of the busy tone cycles, range of value: 1~50

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Sets the minimum number of the busy tone cycles. For more information, refer to Busy Tone Detector.

Note:

l The configuration item IsBusyToneDetermineCount, 2ndIsBusyToneDetermineCount implements the same feature.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetIsBusyToneDtrCnt, SsmGet2ndIsBusyToneDtrCnt


2.5.4.6.6 SsmGetBusyTonePeriodEx

Refer to SsmGet2ndBusyTonePeriod


2.5.4.6.7 SsmGetBusyTonePeriod

Refer to SsmGet2ndBusyTonePeriod


2.5.4.6.8 SsmGet2ndBusyTonePeriod

Obtains the set value, determining the busy tone cycle. SsmGetBusyTonePeriod is applicable to the 1st call progress tone detector, SsmGet2ndBusyTonePeriod is applicable to the 2nd call progress tone detector, and SsmGetBusyTonePeriodEx is applicable to both 1st and 2nd call progress tone detector.

Format:

int SsmGetBusyTonePeriodEx(int ch, int nCptdNo, PWORD pwPeriod)

int SsmGetBusyTonePeriod(int ch, PWORD pwBusyTonePeriod)

int SsmGet2ndBusyTonePeriod(int ch, PWORD pwBusyTonePeriod)

Parameter Description:

ch | Channel Number
nCptdNo | =1: sets the 1st call progress tone detector =2: sets the 2nd call progress tone detector
pwPeriod | Returns the pointer of the set value of busy tone cycle (ms), the storage space is allocated by the application, the size is 4 WORD
pwBusyTonePeriod | Returns the set value of busy tone cycle (ms)

Return Value:

-1 | Failed
0 | Successful
>0 | The preset number of busy tone cycles

Function Description:

Obtains the set value, determining the busy tone cycle. For more information, refer to ‘Busy Tone Detector’.

Note:

l It’s recommended to use the function SsmGetBusyTonePeriodEx.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSetBusyTonePeriodEx, SsmSetBusyTonePeriod, SsmSet2ndBusyTonePeriod


2.5.4.6.9 SsmGetIsBusyToneDtrCnt

Refer to SsmGet2ndIsBusyToneDtrCnt


2.5.4.6.10 SsmGet2ndIsBusyToneDtrCnt

Obtains the set value of the minimum number of busy tone cycles. SsmGetIsBusyToneDtrCnt is applicable to the 1st call progress tone detector, SsmGet2ndIsBusyToneDtrCnt is applicable to the 2nd call progress tone detector.

Format:

int SsmGetIsBusyToneDtrCnt(int ch, PWORD pwIsBusyToneDtrCnt)

int SsmGet2ndIsBusyToneDtrCnt(int ch, PWORD pwIsBusyToneDtrCnt)

Parameter Description:

ch | Channel Number
pwIsBusyToneDtrCnt | Returns the set value of the minimum number of busy tone cycles

Return Value:

-1 | Failed
0 | Successful

Function Description:

Obtains the set value of the minimum number of busy tone cycles.

Note:

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSetIsBusyToneDtrCnt, SsmSetIsBusyToneDtrCnt


2.5.4.7 Obtaining Detected result


2.5.4.7.1 SsmGetBusyToneLen

Refer to SsmGet2ndBusyToneLen


2.5.4.7.2 SsmGet2ndBusyToneLen

Obtains the duration time of busy tone. SsmGetBusyToneLen is applicable to the 1st call progress detector, SsmGet2ndBusyToneLen is applicable to the 2nd call progress tone detector.

Format:

int SsmGetBusyToneLen(int ch)

int SsmGet2ndBusyToneLen(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Failed
≥0 | The duration time (ms) of busy tone

Function Description:

Obtains the duration time of busy tone. For more information, refer to ‘Busy Tone Detector’.

Note:

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetBusyAMDToneCount


2.5.4.7.3 SsmGetBusyAMDToneCount

Refer to SsmGet2ndBusyAMDToneCount


2.5.4.7.4 SsmGet2ndBusyAMDToneCount

Obtains the number of busy tone cycles. SsmGetBusyAMDToneCount is applicable to the 1st call progress tone detector, SsmGet2ndBusyAMDToneCount is applicable to the 2nd call progress tone detector.

Format:

int SsmGetBusyAMDToneCount(int ch)

int SsmGet2ndBusyAMDToneCount(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Failed
≥0 | The number of continuous busy tone cycles

Function Description:

Obtains the number of busy tone cycles.

Note:

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetBusyToneLen


2.5.4.8 Obtaining Result Gained by Using Back-to-Back Busy Tone Detection


2.5.4.8.1 SsmGetBusyToneEx

Obtains the detected result of the busy tone detector by adopting the back-to-back busy tone detecting algorithm.

Format:

int SsmGetBusyToneEx(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Failed
0 | No busy tone detected
1 | Busy tone detected

Function Description:

Obtains the detected result of the busy tone detector by adopting the back-to-back busy tone detecting algorithm. For more information, refer to ‘busy tone detector’.

Note:

l Using the event of E_CHG_BusyToneEx may implement the same feature.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmClearToneAnalyzeResult


2.5.5 Fax Progress Tone Detector Functions


2.5.5.1 Setting Working Parameters


2.5.5.1.1 SsmSetVoiceFxPara

Sets operating parameters of the fax progress tone detector.

Format:

int SsmSetVoiceFxPara(int ch, WORD wSelFx, WORD wFx,WORD wFxBW, DWORD dwIsVocFxRatio, WORD wIsVocFxDtrTime)

Parameter Description:

ch | Channel Number
wSelFx | Selects the fax progress tone detector, range of value: 1: sets the parameter of 1st fax progress tone detector 2: sets the parameter of 2nd fax progress tone detector
wFx | Center frequency (Hz), range of value: 300~3400
wFxBW | Bandwidth (Hz), range of value: 40~120
dwIsVocFxRatio | The minimum threshold value percentage (%) of in-band energy in overall energy, range of value: 15~80
wIsVocFxDtrTime | The minimum duration time (ms) , range of value: ³64

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Sets operating parameters of the fax progress tone detector. For more information, refer to ‘Fax Progress Tone Detector’.

Note:

l The configuration item VoiceFreqF1Para and VoiceFreqF2Para may implement the same feature. Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetVocFxFlag, SsmGetVoiceFxPara


2.5.5.1.2 SsmGetVoiceFxPara

Obtains operating parameters of the fax progress tone detector.

Format:

int SsmGetVoiceFxPara(int ch, WORD wSelFx, PWORD pwFx, PWORD pwFxBW, PDWORD pdwIsVocFxRatio, PWORD pwIsVocFxDtrTime)

Parameter Description:

ch | Channel Number
wSelFx | Selects the fax progress tone detector, range of value: 1: sets the parameter of 1st fax progress tone detector 2: sets the parameter of 2nd fax progress tone detector
pwFx | Returns center frequency (Hz)
pwFxBW | Returns bandwidth (Hz)
pdwIsVocFxRatio | Returns the minimum threshold value percentage (%) of in-band energy in overall energy
wIsVocFxDtrTime | Returns the minimum duration (ms)

Return Value:

-1 | Failed
0 | Successful

Function Description:

Obtains operating parameters of the fax progress tone detector.

Note:

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSetVoiceFxPara


2.5.5.2 Obtaining Detected Result


2.5.5.2.1 SsmGetVocFxFlag

Obtains the detected result of the fax progress tone detector.

Format:

int SsmGetVocFxFlag(int ch, int nSelFx, BOOL bClear)

Parameter Description:

ch | Channel Number
nSelFx | Selects the frequency of voice to be detected: =1: selects F1; =2: selects F2
bClear | Indicates that whether the driver clears the detected result after reading the designated sign =TRUE: clear the detected result; =FALSE: not clear the detected result

Return Value:

-1 | Failed
0 | The single tone voice with specified frequency is not detected
1 | The single tone voice with specified frequency is detected

Function Description:

Obtains the detected result of the fax progress tone detector. For more information, refer to ‘Fax Progress Tone Detector’.

Note:

l It’s recommended to use the event of E_CHG_VocFxFlag to implement the same feature.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSetVoiceFxPara


2.5.6 AMD Function


2.5.6.1 Obtaining and Clearing Result Gained by AMD


2.5.6.1.1 SsmGetAMDResult

Obtains the result that detected by AMD.

Format:

int SsmGetAMDResult (int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Failed or in invalidating state
0 | human being detected then the detected task over
1 | signal tone detected then the detected task continue
2 | color-ring or indicated sounds detected then the detected task continue
3 | overtime then the detected task over
4 | The line keeps silent after detecting the color-ring or indicated sounds then the detected task continue
5 | The line keeps silent after detecting the dial tone then the detected task over
6 | busy tone detected then the detected task over
7 | fax detected then the detected task over

Function Description:

Obtains the result that detected by AMD.

Note:

l Suggest to use the event E_CHG_AMD to complete the function same as SsmGetAMDResult..

Related Information:

Driver version | SynCTI Ver. 5.0.3.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll


2.5.6.1.2 SsmClearAMDResult

Clear the result that detected by AMD.

Format:

int SsmClearAMDResult (int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Failed
0 | Successful

Function Description:

Clear the result that detected by AMD.

Note:

l Suggest to call this function before starting AMD.

Related Information:

Driver version | SynCTI Ver. 5.0.3.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll


2.5.6.1.3 SsmControlAMD

Manually control the turnon and turnoff of AMD detector.

Format:

int WINAPI SsmControlAMD(int ch,BOOL bStart)

Parameter Description:

ch | Channel Number
bStart | Decides whether to turn on the control switch of the AMD detector or not. TRUE： turn on FALSE：turn off

Return Value:

-1 | Failed
0 | Successful

Function Description:

Manually control the turnon and turnoff of AMD detector.

Note:

l The channel state also has an effect on the turnon and turnoff of AMD detector when using this function.

Related Information:

Driver Version | SynCTI Ver. 5.0.3.0 or above
Header | Shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll


2.6 DTMF Detector Functions

There exits internal buffer area in the driver to receive DTMF strings. The size of the buffer area may be specified in the configuration file and its default value is 200. The application needs to read the DTMF character in time before the buffer area overflows; Otherwise, if the driver receives a new character again, it causes the firstly received DTMF character lost.

For the station channel or recording channel, when pickup or hangup is detected, the driver automatically clear the DTMF-reception buffer area; For other type of channels, the driver automatically clear the buffer area upon receiving the hangup command.

All the functions in this section don’t support magnet channels.


2.6.1 Starting/Stopping DTMF Detector


2.6.1.1 SsmEnableRxDtmf

Start or stop the DTMF detector.

Format:

int SsmEnableRxDtmf(int ch, BOOL bRun)

Parameter Description:

ch | Channel Number
bRun | The control switch determining whether start or stop the DTMF detector TRUE: start FALSE: stop

Return Value:

-1 | Failed. The failure reason can be acquired via the function SsmGetLastErrMsg
0 | Successful

Function Description:

Start or stop the DTMF detector.

Note:

l The driver automatically enables or disables the DTMF detector according to the channel state transition. Only if you want to control the switch of the DTMF detector by yourself need this function be invoked. Note that in SS1 mode, only when the application controls the call process by itself can this function be invoked.

l This function is only applicable to SHT, SHD, DST and SHN series.

l The same purpose can be achieved by using the configuration item AlwaysEnableRxDtmf.

l This function gets valid when it is called by the application and will go invalid once the channel state changes.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSetRxDtmfHandler, SsmGetDtmfStr


2.6.2 Setting Callback Functions


2.6.2.1 SsmSetRxDtmfHandler

Sets the callback function when DTMF Detector outputs DTMF signals.

Format:

int SsmSetRxDtmfHandler(int ch, RXDTMFHANDLER pfnOnRcvDtmf, PVOID pV)

Parameter Description:

ch

Channel Number

pfnOnRcvDtmf

The pointer of the callback function. The type of the callback function is: RXDTMFHANDLER, it’s declared in shpa3api.h:

typedef void (*RXDTMFHANDLER) (int ch, char cDtmf, int nDTStatus, PVOID pV);

In the above format,

ch: Channel Number;

cDtmf: DTMF character (ASCII format)

nDTStatus: DTMF signal type, 0 means the DTMF signal disappears, 1 means the DTMF signal appears;

pV: The pointer of PVOID type. It’s usually used by the application to pass its data structure to the callback function. This pointer is transparently passed to the callback function by the application

pV

The pointer of PVOID type. The application passes needed object or data structure to the callback function via this parameter

Return Value:

-1 | Failed. The failure reason can be acquired via the function SsmGetLastErrMsg
0 | Successful

Function Description:

Sets the callback function when DTMF Detector outputs DTMF signals.

Note:

l Each time when DTMF detects a complete DTMF character, it invokes the callback function set by this function twice: one time is when the DTMF signal appears, another time is when the DTMF signal disappears. For more information, refer to DTMF Detector,

l The received DTMF character will still be put in the buffer area of the DTMF detector.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function:


2.6.3 Obtaining DTMF Digits


2.6.3.1 SsmClearRxDtmfBuf

Clears the internal buffer area for DTMF keypress number reception in the driver.

Format:

int SsmClearRxDtmfBuf(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Failed. The failure reason can be acquired via the function SsmGetLastErrMsg.
0 | Successful

Function Description:

Clears the internal DTMF reception buffer area in the driver.

Note:

l When the channel is transferred to the state of standby, the driver automatically clears the buffer area of the DTMF detector.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetDtmfStr


2.6.3.2 SsmGetDtmfStr

Refer to SsmGetDtmfStrA


2.6.3.3 SsmGetDtmfStrA

Obtains the DTMF characters saved in the buffer area of the DTMF detector.

Format:

int SsmGetDtmfStr(int ch, LPSTR pszDtmf)

char* SsmGetDtmfStrA(int ch)

Parameter Description:

ch | Channel Number
pszDtmf | The pointer storing the received DTMF string, the storage space is allocated by the application

Return Value:

Function Name | Return Value | Description
SsmGetDtmfStr | -1 | Failed
 | ≥0 | The character number in the DTMF detector
SsmGetDtmfStrA | NULL | Call failed
 | Other | Returns the pointer which points to the buffer area of the DTMF detector

Function Description:

Obtains the DTMF standard ASCII-formatted characters saved in the buffer area of the DTMF Detector. SsmGetDtmfStr and SsmGetDtmfStrA are the same in features except for the methods returning the buffer area of the DTMF detector.

Note:

l When this function is being called, the driver will not clear the buffer area of the DTMF detector.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | Shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetRxDtmfLen, SsmGet1stDtmf, SsmGet1stDtmfClr, SsmGetLastDtmf


2.6.3.4 SsmGetRxDtmfLen

Obtains the DTMF character number saved in the buffer area of the DTMF detector.

Format:

int SsmGetRxDtmfLen(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Failed. The failure reason can be acquired via the function SsmGetLastErrMsg
≥0 | The DTMF character number saved in the buffer area of the DTMF detector

Function Description:

Obtains the DTMF character number saved in the buffer area of the DTMF detector.

Note:

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetDtmfStr, SsmGetDtmfStrA


2.6.3.5 SsmGet1stDtmf

Refer to SsmGet1stDtmfClr


2.6.3.6 SsmGet1stDtmfClr

Obtains the firstly-received DTMF character in the buffer area of the DTMF detector.

Format:

int SsmGet1stDtmf(int ch, char* pcDtmf)

int SsmGet1stDtmfClr(int ch, char* pcDtmf)

Parameter Description:

ch | Channel Number
pcDtmf | The initial address of the buffer area which stores the DTMF characters

Return Value:

-1 | Failed. The failure reason can be acquired via the function SsmGetLastErrMsg
0 | The buffer area of the DTMF detector is empty
1 | There exists character in the buffer area of the DTMF detector

Function Description:

Obtains the firstly-received DTMF character in the buffer area of the DTMF detector. After SsmGet1stDtmf obtains the DTMF character, it still remains in the buffer area; SsmGet1stDtmfClr will then clear the obtained character from the buffer area.

Note:

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | Shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetDtmfStr, SsmGetDtmfStrA


2.6.3.7 SsmGetLastDtmf

Obtains the lastly-received DTMF character in the buffer area of the DTMF detector.

Format:

int SsmGetLastDtmf(int ch, char* pcDtmf)

Parameter Description:

ch | Channel Number
pcDtmf | The initial address of the buffer area storing the DTMF characters

Return Value:

-1 | Failed. The failure reason can be acquired via the function SsmGetLastErrMsg
0 | The buffer area of the DTMF detector is empty
1 | There exists character in the buffer area of the DTMF detector

Function Description:

Obtains the lastly-received DTMF character in the buffer area of the DTMF detector.

Note: None

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetRxDtmfLen, SsmGet1stDtmfClr, SsmGetLastDtmf, SsmGetDtmfStr, SsmGetDtmfStrA


2.6.4 Using WaitDtmf


2.6.4.1 SsmSetWaitDtmf

Refer to SsmSetWaitDtmfExA


2.6.4.2 SsmSetWaitDtmfEx

Refer to SsmSetWaitDtmfExA


2.6.4.3 SsmSetWaitDtmfExA

Starts WaitDtmf. The precision level of the maximum waiting time of SsmSetWaitDtmf is 1 second, while the precision level of the maximum waiting time of SsmSetWaitDtmfEx and SsmSetWaitDtmfExA is 1 millisecond; SsmSetWaitDtmfEx only supports one terminating character, while SsmSetWaitDtmfExA supports multiple terminating characters.

Format:

int SsmSetWaitDtmf(int ch, WORD wTimeOut1, WORD wMaxLen, char cEndChar, BOOL bWithEndChar)

int SsmSetWaitDtmfEx(int ch, WORD wTimeOut2, WORD wMaxLen, char cEndChar, BOOL bWithEndChar)

int SsmSetWaitDtmfExA(int ch, WORD wTimeOut2, WORD wMaxLen, char* szEndChar, BOOL bWithEndChar)

Parameter Description:

ch | Channel Number
wTimeOut1 | Maximum waiting time (s), with the value range of 1~524
wTimeOut2 | Maximum waiting time (ms)
wMaxLen | The maximum length of the DTMF waited to be received, range of value: 1~50
cEndChar | Terminating character. If the driver receives this character, WaitDtmf is finished
szEndChar | Terminating character set, at most 16 characters. If the driver receives any character in the set, WaitDtmf is finished
bWithEndChar | After WaitDtmf is finished, this parameter decides whether the string returned from the driver to the application includes the received terminating character.: =TRUE: include =FALSE: not include

Return Value:

-1 | Failed. The failure reason can be acquired via the function SsmGetLastErrMsg
0 | Successful

Function Description:

Submits a task of receiving a specific DTMF string, i.e. the WaitDtmf task. When this task is started

successfully, the driver will check the data already received in the DTMF reception buffer area and refuse any DTMF digit received after the task is started to enter this buffer area. This task will not be cancelled until one of the following conditions is met:

² The terminating character specified in the parameter of cEndChar or szEndChar is received.

² The number of the received DTMF equals the maximum length which is set in the parameter wMaxLen

² The waiting time exceeds the time specified in the parameter wTimeOut1 or wTimeOut2.

When WaitDtmf is finished, the driver throws out the event of E_PROC_WaitDTMF to the application. The execution result of WaitDtmf may be obtained by the function SsmChkWaitDtmf.

The function SsmCancelWaitDtmf may be used to cancel WaitDtmf.

Note:

l Each time when the driver receives one DTMF character on the designated channel, it automatically resets and restarts the timer.

l When this function is invoked, the previously received digits in the DTMF buffer area will not be cleared. That is, the DTMF digits remaining in the buffer area will affect this function’s execution result.

l If the WaitDtmf task is already started on a channel, the DTMF digits received afterwards will no longer be put into the DTMF reception buffer area and the event E_CHG_RcvDTMF will not be generated during the execution of this task.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmChkWaitDtmf, SsmCancelWaitDtmf


2.6.4.4 SsmCancelWaitDtmf

Cancels the task of WaitDtmf.

Format:

int SsmCancelWaitDtmf(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Error occurs
0 | Successful

Function Description:

Cancels the task of WaitDtmf.

Note:

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSetWaitDtmf, SsmSetWaitDtmfEx, SsmSetWaitDtmfExA, SsmChkWaitDtmf


2.6.4.5 SsmChkWaitDtmf

Checks the execution status of the WaitDtmf task.

Format:

int SsmChkWaitDtmf(int ch, LPSTR pszDtmf)

Parameter Description:

ch | Channel Number
pszDtmf | The pointer pointing to the buffer area which stores DTMF, the storage space is allocated by the application

Return Value:

-1 | Error occurs
0 | Currently receiving
1 | Receiving timeout and the task finished; or, no WaitDtmf task on the channel.
2 | The task is finished due to the reception of the designated terminating character.
3 | The task is finished due to the reception of the DTMF string with designated length.

Function Description:

Checks the execution status of the WaitDtmf task.

Note:

l The event of E_PROC_WaitDTMF provides the same feature.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Event: E_PROC_WaitDTMF


2.7 DTMF Generator Functions (CTI Series)


2.7.1 Setting Parameters for DTMF Generator


2.7.1.1 SsmSetTxDtmfPara

Sets the durations of the DTMF signal generated by the DTMF Generator respectively at on and off states.

Format:

int SsmSetTxDtmfPara(int ch, WORD wOnTime, WORD wOffTime)

Parameter Description:

ch | Channel Number
wOnTime | The duration (ms) of DTMF at on state, the range of value: ³40, must be integral times of 8
wOffTime | The duration (ms) of DTMF at off state, the range of value: ³40, must be integral times of 8

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Sets the durations of the DTMF signal generated by the DTMF Generator respectively at on and off states.

Note:

l The configuration item TxDtmfTimePara implements the same feature.

l For IP channel, this function call is valid only when DTMF signals are sent by in-band method.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetTxDtmfPara, SsmTxDtmf


2.7.1.2 SsmQueryTxDtmf

Checks whether the channel includes DTMF Generator.

Format:

int SsmQueryTxDtmf(int ch, LPSTR pszReserved)

Parameter Description:

ch | Channel Number
PszReserved | Reserved string pointer, it could be not used

Return Value:

-1 | Failed
0 | The designated channel doesn’t support the operation of sending the standard DTMF characters
1 | The designated channel supports the operation of sending the standard DTMF characters

Function Description:

Checks whether the channel includes DTMF Generator.

Note:

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function:


2.7.1.3 SsmGetTxDtmfPara

Obtains the duration of the DTMF signal generated by the DTMF Generator respectively at on and off states.

Format:

int SsmGetTxDtmfPara(int ch, PWORD pwOnTime, PWORD pwOffTime)

Parameter Description:

ch | Channel Number
pwOnTime | Returns the duration (ms) at on state
pwOffTime | Returns the duration (ms) at off state

Return Value:

-1 | Failed
=0 | Successful

Function Description:

Obtains the durations of the DTMF signal generated by the DTMF Generator respectively at on and off states.

Note:

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSetTxDtmfPara


2.7.2 Setting Working Status of DTMF Generator


2.7.2.1 SsmTxDtmf

Transmits DTMF string in the channel’s outgoing call direction.

Format:

int SsmTxDtmf(int ch, LPSTR pszDtmf)

Parameter Description:

ch

Channel Number

pszDtmf

l Pointer to the string, must be terminated with ‘0’. The number of characters can't exceed the set value in the configuration item TxDtmfBufSize. The character can be:

a) ‘0’~’9’,’*’,’#’,’A’,’B’,’C’,’D’ : Standard DTMF signal;

b) ‘!’: Generates one flash on the line, only applicable to the analog trunk channel;

c) Other characters: Keeps a period of silence on the line. The duration time is set by the configuration item DefaultTxDelayTime, with the default value of 2000ms.

l For IP channel, the meaning of this parameter varies on DTMF transmission modes as follows:

a) When DTMF signals are sent by in-band or RFC2833 method, only 15 standard DTMF digits ‘0’~’9’,’*’,’#’,’A’,’B’,’C’,’D’ are supported;

b) When DTMF signals are sent by out-of-band method, all characters in the ASCII character set can be used.

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Transmits DTMF string in the channel’s outgoing call direction.

After the driver copies the characters in the pszDtmf into the internal transmission buffer area of DTMF generator, it starts the DTMF transmission. When all the characters in the transmission buffer area have been sent out, the driver throws out the event of E_PROC_SendDTMF to the application. The function SsmChkTxDtmf can be used to query the transmission status, the function SsmStopTxDtmf can be used to terminate the transmission.

Note:

l The size of the transmission buffer area of the DTMF generator can be set by the configuration item TxDtmfBufSize and the default value is 50 characters.

l This function only supports SHT Series, SHD Series and SHN Series boards.

l For IP channel, you should pay attention to the following:

a) When DTMF signals are sent by out-of-band method, it is a synchronous function; otherwise it is an asynchronous function.

b) Only when DTMF signals are sent by in-band method can the function SsmStopTxDtmf be invoked to terminate the transmission.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmChkTxDtmf, SsmStopTxDtmf, SsmSetTxDtmfPara


2.7.2.2 SsmStopTxDtmf

Stops the transmission of DTMF generator.

Format:

int SsmStopTxDtmf(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Stops the transmission of DTMF generator.

Note:

l For IP channel, this function call is valid only when DTMF signals are sent by in-band method.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmTxDtmf


2.7.2.3 SsmChkTxDtmf

Checks the transmission status of the DTMF generator.

Format:

int SsmChkTxDtmf(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Error occurs
0 | The transmission of DTMF string is completed
1 | The transmission of DTMF string is in progress

Function Description:

Checks the transmission status of the DTMF generator.

Note:

l The event of E_PROC_SendDTMF may implement the same feature.

l For IP channel, this function call is valid only when DTMF signals are sent by in-band method.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmTxDtmf, SsmStopTxDtmf


2.8 Barge-in Detector Functions


2.8.1 Setting Parameters for Barge-in Detector


2.8.1.1 SsmSetBargeInSens

Sets the sensitivity level of the Barge-in detector.

Format:

int SsmSetBargeInSens(int ch, int nSens)

Parameter Description:

ch | Channel Number
nSens | Sensitivity level, range of value: 0~31, more sensitive with the larger value

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Sets the sensitivity level of the Barge-in detector. For more information, refer to Barge-in Detector.

Note:

l The configuration item BargeInSensitive may implement the same feature.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetBargeInSens, SsmSetIsBargeInDtrmTime, SsmSetNoSoundDtrmTime


2.8.1.2 SsmSetIsBargeInDtrmTime

Sets the minimum duration time of BargIn.

Format:

int SsmSetIsBargeInDtrmTime(int ch, WORD wMinKeepTime)

Parameter Description:

ch | Channel Number
wMinKeepTime | Minimum duration time (ms), range of value: ³16, must be integral times of 16ms

Return Value:

-1 | Not supported or parameter setting error
0 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
1 | Successful

Function Description:

Sets the minimum duration time of BargIn.

When the voice signal is detected in the incoming call and the duration time is greater than the set value of this function, the BargeIn detector determines and outputs the detected result of ‘BargeIn’ and throws out the event of E_SYS_BargeIn to the application. For more information, refer to ‘Barge-in Detector’.

Note:

l The configuration item BargeInDtrmTime may implement the same feature, with the default value of 32ms.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetIsBargeInDtrmTime, SsmSetBargeInSens, SsmSetNoSoundDtrmTime


2.8.1.3 SsmSetVoiceEnergyMinValue

Sets the threshold value for noise judgment.

Format:

int SsmSetVoiceEnergyMinValue(int ch, DWORD nVoiceEnergyMinValue)

Parameter Description:

ch | Channel Number
nVoiceEnergyMinValue | The threshold value for noise judgment, range of value: 0<nVoiceEnergyMinValue<=0x7fffffff

Return Value:

-1 | Call failed, the failure reason can be obtained from the function SsmGetLastErrMsg
0 | Successful

Function Description:

Sets the threshold value of Barge-in detector for noise judgment.

Note:

l The configuration item VoiceEnergyMinValue may implement the same feature, with the default value of 100000.

Related Information:

Driver version | SynCTI Ver. 5.1.0.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetVoiceEnergyMinValue


2.8.1.4 SsmSetNoSoundDtrmTime

Sets the minimum silence duration.

Format:

int SsmSetNoSoundDtrmTime(int ch, DWORD wMinKeepTime)

Parameter Description:

ch | Channel Number
wMinKeepTime | Minimum duration time (ms), range of value: ³16, must be integral times of 16ms

Return Value:

-1 | Call failed, the failure reason can be obtained from the function SsmGetLastErrMsg
0 | Successful

Function Description:

Sets the minimum silence duration.

When the voice signal disappears (i.e. keeps silence) and the duration time is larger than the set value of this function, the BargeIn detector determines and outputs the detected result of ‘No Sound’ and throws out the event of E_SYS_NoSound to the application. For more information, refer to ‘Barge in Detector’.

Note:

l The configuration item IsNoSoundDtrmTime may implement the same feature, the defaulted value is 5000ms.

Related Information:

Driver version | SynCTI Ver. 2.0 or higher
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetIsBargeInDtrmTime, SsmSetBargeInSens, SsmGetNoSoundDtrmTime


2.8.1.5 SsmGetBargeInSens

Obtains the sensitivity level of the Barge-in detector.

Format:

int SsmGetBargeInSens(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
³0 | The sensitivity level of the Barge In detector

Function Description:

Obtains the preset sensitivity level of the Barge In detector.

Note:

Related Information:

Driver version | SynCTI Ver. 2.0 or higher
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSetBargeInSens


2.8.1.6 SsmGetIsBargeInDtrmTime

Obtains the preset value of the minimum duration time of BargeIn.

Format:

int SsmGetIsBargeInDtrmTime(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Failed
³0 | Minimum duration time (ms)

Function Description:

Obtains the preset value of the minimum duration time of BargeIn.

Note:

Related Information:

Driver version | SynCTI Ver. 2.0 or higher
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSetIsBargeInDtrmTime


2.8.1.7 SsmGetVoiceEnergyMinValue

Gets the threshold value for noise judgment.

Format:

DWORD SsmGetVoiceEnergyMinValue(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Call failed, the failure reason can be obtained from the function SsmGetLastErrMsg
³0 | Successful, return the threshold value for noise judgment.

Function Description:

Gets the threshold value of Barge-in detector for noise judgment.

Note:

Related Information:

Driver version | SynCTI Ver. 5.1.0.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSetVoiceEnergyMinValue


2.8.1.8 SsmGetNoSoundDtrmTime

Obtains the preset value of the minimum duration time of silence.

Format:

int SsmGetNoSoundDtrmTime(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Failed
³0 | Minimum duration time (ms)

Function Description:

Obtains the preset value of the minimum duration time of silence.

Note:

Related Information:

Driver version | SynCTI Ver. 2.0 or higher
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSetNoSoundDtrmTime


2.8.2 Obtaining Detected Result of Barge-in Detector


2.8.2.1 SsmDetectBargeIn

Obtains the detected result of the Barge-in Detector.

Format:

int SsmDetectBargeIn(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Failed
0 | Bargein is not detected
1 | Bargein is detected

Function Description:

Obtains the detected result of the Bargein detector. For more information, refer to ‘Barge in Detector’ in chapter 1.

Note:

l It’s recommended to use the event of E_SYS_BargeIn to get the detected result.

Related Information:

Driver version | SynCTI Ver. 2.0 or higher
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmDetectNoSound


2.8.2.2 SsmDetectNoSound

Format:

int SsmDetectNoSound(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Failed
0 | ‘No Sound’ is not detected
1 | ‘No sound’ is detected

Function Description:

Obtains the detected result of Bargein.

Note:

l It’s recommended to use the event of E_SYS_NoSound to get the detected result.

Related Information:

Driver version | SynCTI Ver. 2.0 or higher
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmDetectBargeIn


2.8.2.3 SsmGetNoSoundTime

Obtains the duration time of silence.

Format:

int SsmGetNoSoundTime(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Failed
³0 | The duration time of silence (ms)

Function Description:

Obtains the duration time of silence. For more information, refer to ‘Barge in Detector’ in chapter 1.

Note:

Related Information:

Driver version | SynCTI Ver. 2.0 or higher
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmDetectNoSound


2.9 Voice Playing Functions


2.9.1 Setting Playing Data’s Destination


2.9.1.1 SsmSetPlayDest

Sets whether to send the voice playing data onto the TDM bus.

Format:

int SsmSetPlayDest(int ch, int nSelDest)

Parameter Description:

ch | Channel Number
nSelDest | The selection switch determining whether to send the voice playing data onto the TDM bus. For SHD and SHT series boards, this parameter controls the status of the switch K1-1 in both operation principle diagrams of SHD and SHT series boards. Value range: 0: Not onto the bus (switch off); 1: Onto the bus (switch on).

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Call successful

Function Description:

Sets whether to send the voice playing data onto the TDM bus. For more information, refer to ‘Operation Principle of SHD Series’ or ‘Operation Principle of SHT Series’ in Chapter 1.

Note:

l This function can only be used to play the background music for the conference room during teleconference.

l This function only supports SHT, SHD and SHN series boards.

Related Information:

Driver version | SynCTI Ver. 4.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function:


2.9.2 Setting Playing Volume


2.9.2.1 SsmSetPlayVolume

Refer to SsmSetPlayGain


2.9.2.2 SsmSetPlayGain

Sets the voice playing volume for SHD/SHT/SHN Series boards. SsmSetPlayGain achieves more accurate control than SsmSetPlayVolume.

Format:

int SsmSetPlayVolume(int ch, int nGain)

int SsmSetPlayGain(int ch, WORD wGainLevel)

Parameter Description:

ch | Channel Number
nGain | Volume gain, range of value: -7~+6. Greater than 0 denotes increasing, less than 0 denotes decreasing, -7 denotes completely turning off the audio output, with the default value of 0. The volume value multiplies 3 equals DB value.
wGainLevel | Volume gain expressed in hexadecimal form, lower 8 bits are valid, higher 8 bits are reserved and needs to be set 0. Range of value: wGainLevel=0: completely turns off the audio output; wGainLevel=1: decreases 16 times; wGainLevel=16: gain keeps unchanged (0DB); 32≤wGainLevel≤255: divides by 16 equals the gain amplification times; wGainLevel=255: 16 times amplification

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

The above 2 functions are used to set the gain of the volume adjustor A1 in SHD/SHT/ATP/SHN Series boards. For more information about the volume adjustor A1, refer to Operation Principle of SHD Series or Operation Principle of SHT Series.

Note:

l The configuration item DefaultPlayVolume may implement the same function as SsmSetPlayVolume.

Related Information:

Driver version | SynCTI Ver. 3.0or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function:


2.9.3 Setting Termination Condition of Voice Playing


2.9.3.1 SsmSetDtmfStopPlay

Sets whether the voice playing needs to be terminated because of the detection of DTMF character by the DTMF Detector.

Format:

int SsmSetDtmfStopPlay(int ch, BOOL bTerminatePlaybackOnDTMF)

Parameter Description:

ch | Channel Number
bTerminatePlaybackOnDTMF | Enabling indicator, range of value: TRUE: turn-on FALSE: turn-off

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Sets whether the voice playing needs to be terminated because of the detection of DTMF character by the DTMF Detector.

In the case that the parameter bTerminatePlaybackOnDTMF is set to be TRUE: When the voice is playing on the channel, if the DTMF Detector detects the DTMF character in the incoming call signals, which is included in the character set preset by the function SsmSetDTMFStopPlayCharSet or the configuration item DtmfStopPlayCharSet, the driver stops the voice playing immediately.

Note:

l The configuration item DefaultDtmfStopPlay may implement the same feature, the defaulted value of the configuration item means to turn off this feature.

l The indicator set by this function has effect on the loaded file to be played, single file, multiple files, single buffer, Pingpong buffer and multiple buffers.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSetDTMFStopPlayCharSet, SsmGetDtmfStopPlayFlag


2.9.3.2 SsmSetDTMFStopPlayCharSet

Sets the DTMF character set which is used to terminate the voice playing.

Format:

int SsmSetDTMFStopPlayCharSet(int ch, LPSTR lpstrDtmfCharSet)

Parameter Description:

ch | Channel Number
lpstrDtmfCharSet | Pointer pointing to the character set which is used to terminate the voice playing. The usable DTMF characters include: ‘0’, ‘1’, ‘2’, ‘3’, ‘4’, ‘5’, ‘6’, ‘7’, ‘8’, ‘9’, ‘*’, ‘#’, ‘a’, ‘b’, ‘c’, 'd'

Return Value:

-1 | Failed, the failure reason may be parameter errors or unsupported operation by the channel. The failure reason can be acquired via the function SsmGetLastErrMsg
0 | Failed, the failure reason is that the command can’ t be transferred to the board, the failure reason can be obtained by the function SsmGetLastErrMsg
1 | Successful

Function Description:

Sets the DTMF character set which is used to terminate the voice playing.

Note:

l The configuration item DtmfStopPlayCharSet may implement the same feature, the defaulted DTMF character set is a complete set.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSetDtmfStopPlay, SsmGetDTMFStopPlayCharSet


2.9.3.3 SsmGetDtmfStopPlayFlag

Obtains the indicator which denotes whether the voice playing is stopped because the DTMF Detector detects the DTMF character.

Format:

int SsmGetDtmfStopPlayFlag(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Failed
0 | The indicator is in the turn-off state
1 | The indicator is in the turn-on state

Function Description:

Obtains the indicator which denotes whether the voice playing is stopped because the DTMF Detector detects the DTMF character.

Note:

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSetDtmfStopPlay


2.9.3.4 SsmGetDTMFStopPlayCharSet

Obtains the DTMF character set which is used to terminate the voice playing.

Format:

int SsmGetDTMFStopPlayCharSet(int ch, LPSTR lpstrDtmfCharSet)

Parameter Description:

ch | Channel Number
lpstrDtmfCharSet | Returns the preset DTMF character set

Return Value:

-1 | Failed, the failure reason can be acquired via the function SsmGetLastErrMsg
≥0 | The length of the character set

Function Description:

Obtains the DTMF character set which is used to terminate the voice playing.

Note:

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSetDTMFStopPlayCharSet


2.9.3.5 SsmSetBargeinStopPlay

Sets whether the voice playing stops because the voice activities are detected by the Barge-in Detector.

Format:

int SsmSetBargeinStopPlay(int ch, BOOL bTerminatePlaybackOnBargein)

Parameter Description:

ch | Channel Number
bTerminatePlaybackOnBargein | Enabling indicator, range of value: TRUE: Turn-on FALSE: Turn-off

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Sets whether the voice playing stops because the voice activities are detected by the Barge-in Detector

In the case that the parameter bTerminatePlaybackOnBargein is set to be TRUE: When the voice is playing on the channel , if the Barge-in Detector detects voice activities in the incoming call signals, the driver terminates the voice playing.

Note:

l The configuration item DefaultBargeInStopPlay may complete the same feature, the defaulted value is turn-off.

l The indicator set by this function has effect on the loaded file to be played, single file, multiple files, single buffer, Pingpong buffer and multiple buffers.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetBargeinStopPlayFlag


2.9.3.6 SsmGetBargeinStopPlayFlag

Obtains the indicator which denotes whether the voice playing is stopped because the Barge-in Detector detects the voice activities.

Format:

int SsmGetBargeinStopPlayFlag(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Failed
0 | The indicator is in turn-off state
1 | The indicator is in turn-on state

Function Description:

Obtains the indicator which denotes whether the voice playing is stopped because the Barge-in Detector detects the voice activities.

Note:

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSetBargeinStopPlay


2.9.3.7 SsmSetHangupStopPlayFlag

Sets whether the voice playing stops because the driver detects the hangup of the remote end.

Format:

int SsmSetHangupStopPlayFlag(int ch, BOOL bHangupStopPlayFlag )

Parameter Description:

ch | Channel Number
bHangupStopPlayFlag | The indicator denoting whether the voice playing stops when the driver detects the hangup of the remote end: TRUE: turn-on FALSE: turn-off

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Sets whether the voice playing stops because the driver detects the hangup of the remote end on channel ch.

Note:

l The configuration item HangupStopPlay may implement the same feature, the defaulted value is turn-off.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function:


2.9.4 Functions for Playing in Single File Mode


2.9.4.1 SsmPlayFile

Plays a single file, starts the file playing.

Format:

int SsmPlayFile(int ch, LPSTR pszFileName, int nFormat, DWORD dwStartPos, DWORD dwLen)

Parameter Description:

ch

Channel Number

pszFileName

Voice file name. It could be either a standard wav file or a non-header file. If it’s a standard wav file, the voice encoding format is achieved from the file header, the parameter nFormat is ignored. If it’s a non-header file, the voice encoding format is designated by nFormat.

nFormat

Encoding format of the voice data, range of value and its meaning are listed below:

Value | Encoding format | Remarks
-2 | PCM16 |
1 | PCM8 |
6 | A-Law |
7 | m-Law |
17 | IMA ADPCM | The board is required to have the hardware decoding capability
23 | VOX |
49 | GSM |
85 | MP3 |
131 | G.729A |

Note: nFormat = -1 represents the default encoding format which is related to the item DefaultRecordFormat in ShConfig.ini. For more information about each specific model board, regarding whether it supports or what method it uses to support the above encoding format, refer to ‘Board Supported CODECs’ in chapter 1.

dwStartPos

The starting position counted from the actual voice data part in the file. For the standard wav file, the starting position 0 represents the position of the first voice data byte following the file header; For the non-header file, it’s counted from the head part of the file.

dwLen

The length of the voice data (bytes) to be played. If this parameter is larger than the length from dwStartPos to the tail part of the file, the later length is used to be the actual playing length.

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Plays a single file.

After invoking this function, the driver starts playing a file. When the following events happen, the file stops playing:

² When all the data in the file have been finished playing.

² The application invokes SsmStopPlayFile or SsmStopPlay;

² When DTMF, Barge in or remote end hangup has been detected. For more information, refer to Setting Termination Condition in chapter 1.

² For some models of SHD Series boards, the configuration item of LinkFromStopPlayAndTone is set to be 1 and some data is taken off from the bus. For more information, refer to ‘Operation Principle of SHD Series ’ in chapter 1.

After the file has been finished playing, the driver closes the played file and throws out the event of E_PROC_PlayEnd to the application. The function SsmCheckPlay may also be used to enquire the status of the file playing.

During the execution of file playing, the driver throws out the event of E_PROC_PlayFile to the application at every time interval. The function SsmSetEvent (with the parameter E_PROC_PlayFile) sets whether or not to throw out this event by the driver and the time interval of throwing out events. By default, every 1000ms the event is thrown out and the also the time length of played file is output.

During the execution of file playing, the application may call the below functions to pause the file playing or adjust the file playing position.

² SsmPausePlay

² SsmFastFwdPlay

² SsmFastBwdPlay

² SsmSetPlayTime

² SsmSetPlayPrct

The following functions can be called to obtain the related information:

² SsmGetDataBytesToPlay

² SsmGetPlayedTime

² SsmGetPlayedPercentage

Note:

l The file is opened with ‘shared read’ mode, so this function supports the feature of ‘record while play’;

l If this function is called on channel 0, for ATP/DST Series boards, the played voice is sent to the port of the on-board speaker, but not sent to the line; For SHT Series boards, the played voice is sent not only to the line but also to the port of the on-board speaker;

l Due to historical reasons, the coding value 65411 which ever represented G.729A is still valid in early versions and backward compatible. For G.729A recording in new versions, we suggest you use the coding value 131.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmStopPlayFile, SsmStopPlay, SsmCheckPlay, SsmPausePlay, SsmRestartPlay, SsmFastFwdPlay, SsmFastBwdPlay, SsmSetPlayTime, SsmSetPlayPrct, SsmGetDataBytesToPlay, SsmGetPlayedTime, SsmGetPlayedPercentage


2.9.4.2 SsmStopPlayFile

Stops the file playing.

Format:

int SsmStopPlayFile(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Stops the file playing started by the function call of SsmPlayFile.

Note:

l This function can be totally replaced by the function SsmStopPlay

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmPlayFile, SsmPausePlay, SsmRestartPlay, SsmFastFwdPlay, SsmFastBwdPlay, SsmSetPlayTime, SsmSetPlayPrct, SsmStopPlay


2.9.4.3 SsmPausePlay

Pauses (suspends) the file playing.

Format:

int SsmPausePlay(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Pauses (suspends) the file playing. When the file playing is paused, the application can only execute the below operations:

l Invokes the function SsmStopPlayFile or SsmStopPlay to stop the file playing.

l Invokes the function SsmRestartPlay to restart the file playing.

Note:

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmRestartPlay, SsmStopPlayFile, SsmStopPlay


2.9.4.4 SsmRestartPlay

Restarts the file playing which is paused by the function call of SsmPausePlay.

Format:

int SsmRestartPlay(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Restarts the file playing which is paused by the function call of SsmPausePlay.

Note:

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmPausePlay, SsmStopPlayFile, SsmStopPlay


2.9.4.5 SsmFastFwdPlay

Skips 1 second voice data and continues to play.

Format:

int SsmFastFwdPlay(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Starting from the current playing position, skips 1 second (configurable with the configuration item FastPlayTime) voice data, and then restarts the single file playing.

Note:

l If the remaining voice data is less than 1 second, the driver regards that the entire voice data has been finished playing and stops the current playing.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmFastBwdPlay, SsmStopPlayFile, SsmStopPlay


2.9.4.6 SsmFastBwdPlay

Skips back 1 second voice data and continues to play.

Format:

int SsmFastBwdPlay(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Starting from the current playing position, skips back 1 second (configurable with the configuration item FastPlayTime), and then continues the file playing.

Note:

l If the beginning of the file has been reached by skipping back, plays the file from the beginning.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmFastFwdPlay, SsmPausePlay, SsmStopPlayFile, SsmStopPlay


2.9.4.7 SsmSetPlayTime

Jumps to the specified time position in the file and continues to play.

Format:

int SsmSetPlayTime(int ch, DWORD dwTime)

Parameter Description:

ch | Channel Number
dwTime | Time based new playing position (ms)

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Jumps to the specified time position in the file and continues to play. The function SsmGetPlayingFileInfo may be used to obtain the file information such as the duration of the file.

Note:

l If the file offset corresponding to the parameter dwTime exceeds the length of the voice data, the driver regards that the entire voice data has been finished playing and stops the current playing.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetPlayingFileInfo, SsmSetPlayPrct, SsmStopPlayFile, SsmStopPlay


2.9.4.8 SsmSetPlayPrct

Jumps to the specified percentage position in the file and continues to play.

Format:

int SsmSetPlayPrct(int ch, DWORD dwPercentage)

Parameter Description:

ch | Channel Number
dwPercentage | The new playing starting position based on the specified file percentage, range of value: 0~100

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Jumps to the specified percentage position in the file and continues to play, the new position is specified with the percentage. The function SsmGetPlayingFileInfo is used to obtain the file duration.

Note:

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSetPlayTime, SsmStopPlayFile, SsmStopPlay


2.9.4.9 SsmGetDataBytesToPlay

Checks the bytes number of the voice data which has not been played.

Format:

int SsmGetDataBytesToPlay(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Failed
≥0 | The length (bytes) of the voice data which has not been played

Function Description:

Checks the bytes number of the voice data which has not been played.

Note:

l This function only supports the voice playing task started by the function SsmPlayFile.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetDataBytesPlayed, SsmGetPlayedTime, SsmGetPlayedPercentage


2.9.4.10 SsmGetDataBytesPlayed

Checks the length of the voice data which has been played.

Format:

int SsmGetDataBytesPlayed(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Failed
≥0 | The length (bytes) of voice data which has been played.

Function Description:

Checks the length of the voice data which has been played.

Note:

l This function only supports the voice playing task started by the function SsmPlayFile.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetDataBytesToPlay, SsmGetPlayedTime, SsmGetPlayedPercentage


2.9.4.11 SsmGetPlayedTimeEx

Obtains the playing duration starting from the 1st voice data byte in the file header to the current playing position in the file.

Format:

int SsmGetPlayedTimeEx(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
≥0 | Returns the playing duration (ms) starting from the 1st voice data byte in the file header to the current playing position in the file

Function Description:

Obtains the playing duration starting from the 1st voice data byte in the file header to the current playing position in the file.

For example, after starting file playing by calling the function SsmPlayFile(ch, ‘Voice.voc’, 7, 16000, ), if the driver initiates playing from the file offset 16000 and has played 10 seconds of voice data, this function is called and returns the value 10+2=12 seconds (the playing duration for 16000 bytes m-law format voice data is 2 seconds).

Note:

l This function is only applicable to the file playing which is started by the function call of SsmPlayFile.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetPlayedTime


2.9.4.12 SsmGetPlayingFileInfo

Obtains the related information of the playing file.

Format:

int SsmGetPlayingFileInfo(int ch , int *pnFormat , long *pnTime)

Parameter Description:

ch | Channel Number
pnFormat | Returns the voice encoding format of the playing file. For the code value of the voice CODEC format in the SynCTI driver platform, refer to SynCTI Supported CODECs in chapter 1
pnTime | Total time length (ms) of the voice data in the file

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

After the application calls the function of SsmPlayFile, this function is used to obtain the related information of the playing file.

Note:

l This function is only applicable to the playing task initiated by the function SsmPlayFile.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmPlayFile, SsmGetPlayedTime, SsmGetPlayedTimeEx, SsmGetPlayedPercentage


2.9.5 Functions for Playing in File List Mode


2.9.5.1 SsmClearFileList

Closes and clears all the voice files submitted to the driver.

Format:

int SsmClearFileList(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Closes and clears all the voice files submitted to the driver.

Note:

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmAddToFileList


2.9.5.2 SsmAddToFileList

Submits a voice file to be played to the driver.

Format:

int SsmAddToFileList(int ch, LPSTR pszFileName, int nFormat, DWORD dwStartPos, DWORD dwLen)

Parameter Description:

ch

Channel Number

pszFileName

Voice file name, it is either a standard wav file or a non-header file. If it’s a standard wav file, the voice encoding format is achieved from the file header, the parameter nFormat is ignored. If it’s a non-header file, the voice encoding format is designated by nFormat.

nFormat

Encoding format of the voice data, range of value and its meaning are listed below:

Value | Encoding format | Remark
-2 | PCM16 |
1 | PCM8 |
6 | A-Law |
7 | m-Law |
17 | IMA ADPCM | The board is required to have the hardware decoding capability
23 | VOX |

For more information about each specific model board, regarding whether it supports or what method it uses to support the above encoding format, refer to ‘Board Supported CODECs’ in chapter 1

dwStartPos

The starting position counted from the actual voice data part in the file. For the standard wav file, the starting position 0 represents the position of the first voice data byte following the file header; For the non-header file, it’s counted from the head part of the file

dwLen

The length of the voice data (bytes) to be played. If this parameter is larger than the actual length calculated from dwStartPos, the driver regards that the file will be played until the end of the file

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Submits a voice file to be played to the driver. After the file is submitted, the multi-file playing may be started by the function call of SsmPlayFileList.

Note:

l After this function is successfully executed, the submitted file is opened with ‘shared read’ mode. The file keeps open until the function SsmClearFileList is called to close it.

l This function can be invoked continuously to submit multiple files, but the total number can’t exceed the value set in the configuration item. All the files must have the same voice CODEC format.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmPlayFileList, SsmStopPlay, SsmClearFileList


2.9.5.3 SsmPlayFileList

Starts multi-file playing.

Format:

int SsmPlayFileList(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Starts multi-file playing. After the application calls this function, the driver starts one task of multi-file playing and initiates to play the first file. Each time when one file is finished playing, the driver throws out the event of E_PROC_PlayFile List to the application, and then starts to play the next file.

When the following events happen, the driver stops playing the file:

² When the entire data in the file have been finished playing.

² The application calls SsmStopPlayFileList or SsmStopPlay;

² DTMF, Barge in or remote hang-up is detected by the driver. For more information, refer to Setting Termination Condition in chapter 1.

² For some model boards of SHD Series, when the configuration item of LinkFromStopPlayAndTone is set to 1, data are taken off the bus. For more information, refer to Operation Principle of SHD Series in the current chapter.

After the file is finished playing, the driver throws out the event of E_PROC_PlayEnd to the application. The function of SsmCheckPlay may also be used to enquire the status of the file playing.

Note:

l Before invoking this function, you may call the function SsmAddToFileList to add files to the file list if it is empty.

l The driver won’t close the submitted file after the file playback task is terminated. In such case, you may call the function SsmClearFileList to clear the file list.

l If this function is invoked on Channel 0, for the ATP/DST Series boards, the played voice is sent directly to the port of the on-board speaker, but not sent to the line; for the SHT Series boards, the played voice is not only sent to the line, but also sent to the port of the on-board speaker.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmStopPlayFileList, SsmStopPlay, SsmCheckPlay, SsmAddToFileList, SsmClearFileList


2.9.5.4 SsmStopPlayFileList

Stops the multi-file playing.

Format:

int SsmStopPlayFileList(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Stops the task of multi-file playing, the task must be started by the function of SsmPlayFileList.

Note:

l This function can be completely replaced by the function of SsmStopPlay.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmPlayFileList, SsmClearFileList, SsmStopPlay


2.9.6 Functions for Playing in Single Buffer Mode


2.9.6.1 SsmPlayMem

Starts the task of single-buffer playing.

Format:

int SsmPlayMem(int ch, int nFormat, LPBYTE pBuf, DWORD dwBufSize, DWORD dwStartOffset, DWORD dwStopOffset)

Parameter Description:

ch

Channel Number

nFormat

Encoding format of the voice data, range of value and its meaning are listed below:

Value | Encoding format | Remarks
1 | PCM8 |
6 | A-Law |
7 | m-Law |
17 | IMA ADPCM | The board is required to have the hardware decoding capability
-2 | PCM16 |
85 | MP3 |

For more information about each specific model board, regarding whether it supports or what method it uses to support the above encoding format, refer to ‘Board Supported CODECs’ in chapter 1.

pBuf

The address of the buffer storing voice data

dwBufSize

The size (byte) of the buffer storing voice data, no less than 768 bytes

dwStartOffset

Starting position (byte) of voice playing (offset), it’s calculated from the initial address of the buffer

dwStopOffset

Starting position (byte) of voice playing (offset), it’s calculated from the initial address of the buffer. If this parameter is less than the buffer length, when the playing pointer in the driver reaches the position designated by dwStopOffset, the current voice playing is finished; Otherwise, the buffer is circularly played until the application calls SsmStopPlayMem to stop the voice playing.

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Starts the task of single-buffer playing.

After calling this function, the driver will start the task of single-buffer playing. Meanwhile, the driver maintains a playing pointer (offset) with the initial value equaling to dwStartOffset, which is used to read data from the submitted buffer. When the following events happen, the single-buffer playing stops:

² If dwStopOffset is less than the submitted buffer size, when the playing buffer in the driver reaches to the ending playing position which is specified by the parameter dwStopOffset, it means the specified data in the buffer have been finished playing.

² When the application calls SsmStopPlayMem or SsmStopPlay;

² When the driver detects DTMF, Barge in or remote hang-up. For more information, refer to Setting Termination Condition in Chapter 1.

² Some model boards of SHD Series set the configuration item LinkFromStopPlayAndTone to be 1, some data are taken from the bus. For more information, refer to Operation Principle of SHD Series in the current chapter.

After finishing the single-buffer playing, the driver throws out the event of E_PROC_PlayEnd to the application. The function SsmCheckPlay may also be used to enquire the status of single-buffer playing.

During the execution of single-buffer playing, each time when the preset condition is met, the driver outputs the event of E_PROC_PlayMem to the application. The output conditions of the event E_PROC_PlayMem can be set by the function SsmSetEvent, it can be set as one of the below three methods:

² The driver has finished the voice data playing with designated length

² The playing pointer in the driver has got across 1/2 part of the buffer.

² The playing pointer reaches to the terminating position of the buffer

For the settings of output conditions of the event of E_PROC_PlayMem, refer to MESSAGE_INFO in Chapter 1.

The function SsmSetStopPlayOffset may be used to reset the ending position of playing. The function SsmStopPlayMem or SsmStopPlay may be used to terminate the single-buffer playing, the function SsmGetPlayOffset may be used to obtain the playing pointer in the driver.

Note:

l If this function is invoked on the channel 0, for the ATP/DST Series boards, the played voice is sent directly to the port of the on-board speaker, but not sent to the line; For the SHT Series boards, the played voice is not only sent to the line, but also sent to the port of the on-board speaker.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmStopPlayMem, SsmStopPlay, SsmSetStopPlayOffset, SsmGetPlayOffset, SsmSetEvent


2.9.6.2 SsmStopPlayMem

Terminates the single-buffer playing initiated by the function SsmPlayMem.

Format:

int SsmStopPlayMem(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Terminates the single-buffer playing initiated by the function SsmPlayMem.

Note:

l After this function is successfully called, the driver will still throw out the event of E_PROC_PlayEnd;

l The function SsmStopPlay may implement the same features.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmPlayMem, SsmSetStopPlayOffset, SsmStopPlay


2.9.6.3 SsmSetStopPlayOffset

Resets the ending position of playing in the buffer.

Format:

int SsmSetStopPlayOffset(int ch, DWORD dwStopPlayOffset)

Parameter Description:

ch | Channel Number
dwStopPlayOffset | Ending offset of the buffer playing

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Resets the ending position of playing in the buffer.

Note:

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetPlayOffset


2.9.6.4 SsmGetPlayOffset

Obtains the playing pointer in the driver during the single-buffer playing.

Format:

int SsmGetPlayOffset(int ch, DWORD* pdwPlayOffset)

Parameter Description:

ch | Channel Number
pdwPlayOffset | Returns the playing pointer in the driver, an offset (bytes) based on the initial address of the buffer

Return Value:

-1 | Failed
0 | Successful

Function Description:

Obtains the playing pointer in the driver during the single-buffer playing.

Note:

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSetStopPlayOffset


2.9.7 Functions for Playing in Buffer List Mode


2.9.7.1 SsmAddToPlayMemList

Submits a memory buffer area to the driver.

Format:

int SsmAddToPlayMemList(LPBYTE pBuf, DWORD dwDataLen, int nFormat)

Parameter Description:

pBuf | Pointer pointing to the voice data buffer area. The memory buffer space is allocated by the application.
dwDataLen | The size (byte) of the voice data buffer area
nFormat | Voice encoding format. Range of value: 6:A-law 7:m-law 17:IMA ADPCM

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Submits a memory buffer to the driver. The voice data to be played is in the buffer area. The driver assigns a serial number to the each submitted buffer area. The firstly submitted buffer area is assigned with the serial number 0. According to this rule, the other submitted area will be assigned with one corresponding serial number.

This function may be continuously called multiple times, but the amount of function calls can’t exceed the set value in the configuration item MaxPlayMemList. The buffers are played in turn based on the submitting sequence of buffers.

Note:

l The submitted memory buffer areas by this function are not targeted at one specific channel, all the channels can use the submitted buffer area.

l The CODEC format for the voice files in all the submitted buffer areas must be the same.

l When the driver is executing this function, it only records the memory buffer information and doesn’t copy and buffer the data in the memory buffer area to the driver, so the application can release the submitted buffer area only when there are no channels executing the task of buffer list playing.

l If the data is in the ADPCM format, the frame structure needs to be paid attention to. The garbled frame data will cause noise.

Related Information:

Driver version | SynCTI Ver. 3.0or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmClearPlayMemList, SsmPlayMemList


2.9.7.2 SsmClearPlayMemList

Clears all the buffer areas submitted to the driver.

Format:

int SsmClearPlayMemList(void)

Parameter Description: None

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Clears all the buffer areas submitted to the driver.

Note:

l Before this function is called, it must be guaranteed that no channels are executing the task of buffer list playing.

Related Information:

Driver version | SynCTI Ver. 3.0or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmAddToPlayMemList


2.9.7.3 SsmPlayMemList

Starts the task of buffer list playing.

Format:

int SsmPlayMemList(int ch, PWORD pMemList, WORD wMemListLen)

Parameter Description:

ch | Channel Number
pMemList | Pointer to the array which stores the serial number of the buffer to be played. The serial number of the buffer must be submitted to the driver in advance by the function SsmAddToPlayMemList .
wMemListLen | Length of the array

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Starts the task of buffer list playing.

After calling this function, the driver starts a task of buffer list playing with a sequence designated in pMemList. When the following events happen, the task of buffer list playing will be stopped:

² The entire voice data in the buffer area designated in pMemList have been finished playing.

² The application calls SsmStopPlayMemList or SsmStopPlay.

² The driver detects DTMF, Barge in or remote hangup. For more details, refer to Setting Termination Condition in chapter 1.

² For some models of SHD Series boards, the configuration item of LinkFromStopPlayAndTone is set to be 1 and some data is taken off from the bus. For more information, refer to ‘Operation Principle of SHD Series ’ in chapter 1.

After the buffer list playing is stopped, the driver throws out the event of E_PROC_PlayEnd to the application.

The function SsmCheckPlay may also be used to enquire the status of buffer list playing.

Note:

l If the channel doesn’t support hardware decoding to the voice CODEC format designated to the buffer areas submitted to the driver via invoking the function SsmAddToPlayMemList, this function call will be failed. Whether the channel supports the hardware decoding to one type of CODEC format is determined by the model of the board where the channel is located. For more information, refer to the related information;

l If this function is called on channel 0, for ATP/DST Series boards, the played voice is sent to the port of the on-board speaker, but not sent to the line; For SHT Series boards, the played voice is sent not only to the line but also to the port of the on-board speaker.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmStopPlayMemList, SsmStopPlay, SsmCheckPlay, SsmAddToPlayMemList


2.9.7.4 SsmStopPlayMemList

Stops the buffer list playing initiated by the function SsmPlayMemList.

Format:

int SsmStopPlayMemList(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Stops the buffer list playing initiated by the function SsmPlayMemList.

Note:

l After this function succeeds, the driver will still throw out the event of E_PROC_PlayEnd to the application.

l This function may be replaced by the function SsmStopPlay .

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmPlayMemList, SsmStopPlay


2.9.8 Preload Voice Data Playing Functions (CTI Series)


2.9.8.1 Preload Voice Information Initialization Functions


2.9.8.1.1 SsmSetMaxIdxSeg

Sets the amount of the preload voice segments.

Format:

int SsmSetMaxIdxSeg(WORD wMaxIdxSeg)

Parameter Description:

wMaxIdxSeg

The maximum amount of the index segments

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Sets the amount of the preloaded voice segments. The configuration item MaxIndexSeg may implement the same feature.

Note:

l Before calling this function, if there are preloaded voice segments, they will be unloaded.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetTotalIndexSeg


2.9.8.1.2 SsmGetTotalIndexSeg

Obtains the total amount of the preload voice data segments.

Format:

int SsmGetTotalIndexSeg ()

Parameter Description:

ch

Channel Number

Return Value:

-1 | Failed
≥0 | Total amount of the index segments

Function Description:

Obtains the total amount of the preload voice data segments.

Note: None.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSetMaxIdxSeg


2.9.8.1.3 SsmLoadIndexData

Loads the designated voice data segment to the memory.

Format:

int SsmLoadIndexData(int nSegNo, LPSTR pAlias, int nCodec, LPSTR pVocFile, long lStartPos, long lLen)

Parameter Description:

nSegNo

The assigned number for the voice data segment, range of value: 0~N, N is the preset total amount of the voice data segments which can be obtained via the function SsmGetTotalIndexSeg

pAlias

The alias assigned to the voice segment, the length can’t exceed 20 characters. ‘0’ ~ ‘9’ can't be used as the first character of the string of the alias

nCodec

Encoding format of the voice data, range of value and its meaning are listed below:

Value | Encoding Format | Remark
1 | PCM_8 |
-2 | PCM_16 |
6 | A-Law |
7 | m-Law |
17 | IMA ADPCM | The board is required to have the hardware decoding capability
23 | VOX | The board is required to have the hardware decoding capability

For more information about each specific model board, regarding whether it supports or what method it uses to support the above coding format, refer to ‘Board Supported CODECs’ in chapter 1.

pVocFile

The file containing voice segments could be standard wav format file or non-header file without the file header. If it’s a standard wav file, the format specified by the parameter nCodec will be ignored; Otherwise, it will be regarded as non-header file, the CODEC format will be determined by the parameter nCodec

lStartPos

The starting position counted from the actual voice data part in the file. For the standard wav file, the starting position 0 represents the position of the first voice data byte following the file header; For the non-header file, it’s counted from the head part of the file.

lLen

The length (bytes) of the voice segment.

Note:

l If this parameter is larger than the data length from the position lStartPos to end of the file, then the latter is adopted as the actual load length.

l If lLen=-1, then data is loaded from the position lStartPos to end of the file.

The conversion between the byte length and time length of voice segments is determined by the CODEC format. For the related information, refer to ‘SynCTI Supported CODECs’ in chapter 1

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

This function loads the voice segment data from the specified file to the memory. The CODEC format of the voice segment data is determined according to the following rule:

Note:

l For each preload voice segment, this function needs to be called.

l The configuration item SegNo in ShIndex.ini may implement the same feature.

l The application needs to ensure that all the preload voice segments have the same CODEC format.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function:

SsmFreeIndexData


2.9.8.1.4 SsmFreeIndexData

Unloads the voice segment data which have been loaded to the memory.

Format:

int SsmFreeIndexData(int nSegNo)

Parameter Description:

nSegNo

The number assigned to the voice segment

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Unloads the voice segment data which have been loaded to the memory. After being unloaded, the segment number (nSegNo) it ever used can be reused for new voice segment data.

Note:

l When the driver uninstalls the function SsmCloseCti, it will automatically release all the resources occupied by preload voice segment data, such as the memory.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmLoadIndexData


2.9.8.1.5 SsmLoadChIndexData

Loads voice segment data from the specified file to the memory which has been assigned to the corresponding channel.

Format:

int WINAPI SsmLoadChIndexData(int ch, int nSegNo, LPSTR pAlias, int nCodec, LPSTR pVocFile, long lStartPos, long lLen)

Parameter Description:

ch | Channel number
nSegNo | The assigned number for voice segment data in the index file in memory
pAlias | The alias assigned to voice segment data in the index file in memory. Its length is not allowed to exceed 20 characters.
nCodec | CODECs for voice segment data, with the optional values of 6 (A-law), 7(μ-law) and 17(IMA ADPCM).
pVocFile | The file containing voice segment data
lStartPos | The start position of voice segment data in the voice file (excluding the file header)
lLen | The length (bytes) of the loaded voice segment data. If the length specified by this parameter is greater than the data length calculated from lStartPos to the end of the file, the latter is regarded as the actual length of the loaded voice segment data; if lLen=-1, that means voice segment data are just loaded from lStartPos to the end of the file.

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Call successful

Function Description:

This function is used to load a voice data segment from the specified file to the memory which has been assigned to the corresponding channel. The CODEC for the voice data segment is determined according to the following rule:

1. If pVocFile is a standard WAV file, the parameter nCodec will be ignored;

2. If pVocFile is not a standard WAV file, it will be regarded as a non-header file and the parameter nCodec is used to designate the codec for it.

Note:

l When the driver uninstalls the function SsmCloseCti, it will automatically release all the resources occupied by preload voice segment data, such as the memory.

Related Information:

Driver version | SynCTI Ver. 4.8.0.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmFreeChIndexData


2.9.8.1.6 SsmFreeChIndexData

Unloads the voice segment data which have been loaded to the memory.

Format:

int WINAPI SsmFreeChIndexData(int ch, int nSegNo)

Parameter Description:

ch | Channel number
nSegNo | The assigned number for voice segment data in the index file in memory

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Call successful

Function Description:

Unloads the voice segment data which have been loaded to the memory. After being unloaded, the segment number (nSegNo) it ever used can be reused for new voice segment data.

Note:

l When the driver uninstalls the function SsmCloseCti, it will automatically release all the resources occupied by preload voice segment data, such as the memory.

Related Information:

Driver version | SynCTI Ver. 4.8.0.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmLoadChIndexData


2.9.8.2 Functions to Play Preload Voice Segments


2.9.8.2.1 SsmPlayIndexString

Refer to SsmPlayIndexList


2.9.8.2.2 SsmPlayIndexList

Sequentially plays designated one or multiple preload voice segments.

Format:

int SsmPlayIndexList(int ch, WORD wIdxListLen, PWORD pwIdxList)

int SsmPlayIndexString(int ch, LPSTR pszIdxStr)

Parameter Description:

ch | Channel Number
wIdxListLen | The total amount of preload voice segments to be played, range of value: 1~N-1. N is set by the configuration item MaxPlayIndexList.
pwIdxList | The array stores the number of the preload voice segment. The voice segments must have the same voice CODEC format.
pszIdxStr | The string containing the information of preload voice segments which stores a sequence of the alias or number of voice segments to be played separated by ‘ ,’ . Each preload voice segment can be denoted by number or alias. Each number or alias is corresponding to a voice segment of memory. The corresponding relationship between number (or alias) and voice segment is decided by the function SsmStartCti based on ShIndex.ini, a configuration file of the form where lists voice files used for memory playback by index; also it can be loaded by the function SsmLoadIndexData and uninstalled by the function SsmFreeIndexData . The total amount of the preload voice segments specified in pszldxStr can exceed the set value in the configuration item MaxPlayIndexList. Note: All the voice segments designated in pszIdxStr must have the same CODEC format.

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

The preload voice segments are played according to the content designated in pwIdxList or pszIdxStr.

After this function is called, the driver will start playing the preload voice segment. When the following event happens, the driver stops playing the preload voice segment:

² The playing of all the data specified in the parameter pwIdxList or pszIdxStr is finished.

² The application calls the function SsmStopPlayIndex or SsmStopPlay.

² When DTMF, Barge in or remote end hangup has been detected. For more information, refer to Setting Termination Condition in chapter 1.

² For some models of SHD Series boards, the configuration item of LinkFromStopPlayAndTone is set to be 1 and some data is taken off from the bus. For more information, refer to ‘Operation Principle of SHD Series ’ in chapter 1.

After preload voice playing is stopped, the driver will throw out the event of E_PROC_PlayEnd to the application. The function SsmCheckPlay may also be used to check the finishing status of voice playing.

The application may invoke the function of SsmStopPlayIndex or SsmStopPlay to stop the voice playing at any moment.

Note:

l This function only supports the channels which have the hardware decoding capability to the CODEC format of the voice data segments designated by pwIdxList or pszIdxStr. Fore more information, refer to the function SsmLoadIndexData.

l If this function is called on channel 0, for ATP/DST Series boards, the played voice is sent to the port of the on-board speaker, but not sent to the line; For SHT Series boards, the played voice is sent not only to the line but also to the port of the on-board speaker.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmStopPlayIndex, SsmStopPlay, SsmCheckPlay, SsmLoadIndexData


2.9.8.2.3 SsmStopPlayIndex

Stops playing preload voice segments.

Format:

int SsmStopPlayIndex(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Stops playing preload voice segments. After stopping playing preload voice segments, the driver will set the cause of stopping playing to be CHKPLAY_APPLICATION_END and throw out the event of E_PROC_PlayEnd to the application.

Note:

l The task of playing voice segments must be started by the function SsmPlayIndexString or SsmPlayIndexList.

l This function can be completely substituted by the function SsmStopPlay.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmPlayIndexString, SsmPlayIndexList, SsmStopPlay


2.9.9 Functions for Playing in Pingpong Buffer Mode(CTI Series)


2.9.9.1 SsmPlayMemBlock

Submits a buffer area to the driver and starts the task of playing pingpong buffer.

Format:

int SsmPlayMemBlock(int ch, int nFormat, LPBYTE pBuf, DWORD dwBufSize, PLAYMEMBLOCKHANDLER pfnCallback, PVOID pV)

Parameter Description:

ch

Channel Number

nFormat

Voice data encoding format. Range of value:

1:PCM8

6:A-law

7:m-law

17:IMA ADPCM(The board needs to have the hardware decoding capability)

pBuf

The pointer points to the voice data buffer area

dwBufSize

The size (Bytes) of the voice data buffer. The minimum value of dwBufSize is determined by the following rules:

l If the configuration item RecordAndPlayUseAsIP is set 0 (default), dwBufSize should be not less than 768 bytes.

l If RecordAndPlayUseAsIP is set 1, for A-law and m-law, dwBufSize should be not less than 192 bytes (recommended value: under Windows operating system, not less than 192 bytes; under Linux, not less than 384 bytes);

For the format of IMA ADPCM, the size of the buffer should be not less than 768 bytes.

pfnCallback

Pointer of callback function. When the driver has finished playing a buffer area or the playing task in buffer was terminated, it automatically calls the callback function set by this parameter. NULL means not to set the callback function. The prototype of the callback function is declared in shpa3api.h:

typedef BOOL (*PLAYMEMBLOCKHANDLER) (int ch, int nEndReason, PUCHAR pucBuf, DWORD dwStopOffset, PVOID pV);

in which,ch: Channel Number;

nEndReason: The end reason, range of value:

1: Finished playing the buffer area;

2: The playing task is stopped because the DTMF key-press characters are detected.

3: The playing task is stopped because bargein is detected.

4: The playing task is stopped because remote end hangup is detected.

5: The playing task is stopped by the application.

pucBuf: The pointer pointing to the buffer area after the playing task is finished.

dwStopOffset: After the playing task is finished, the offset (bytes) of the driver’s playing pointer in the buffer area.

pV: The pointer which is passed by the application when it calls this function

pV

Pointer of PVOID type, it’s commonly used by the application to pass some necessary data such as data structure to the callback function. This pointer will be transparently passed to the callback function

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Submits a buffer area to the driver and starts the task of playing Pingpong buffer. For more information about Pingpong buffer mode, refer to Pingpong Buffer Mode in Chapter 1.

When it’s the first time calling this function, the driver starts the task of playing Pingpong buffers and plays the buffers according to their submission sequence. Each time when the driver finishes playing a buffer area, it switches to another buffer area and starts to play; At the same time, the driver invokes the callback function set by the application and passes the information of the buffer which has been finished playing to the application. In the callback function, the application may update the voice data in the buffer area, and then this function submits the buffer to the driver.

When the following event happens, the buffer-sequence playing will be stopped:

² The driver has finished playing all the buffers submitted.

² The application calls the function of SsmStopPlayMemBlock or SsmStopPlay;

² When DTMF, Barge in or remote end hangup has been detected. For more information, refer to Setting Termination Condition in chapter 1.

² For some models of SHD Series boards, the configuration item of LinkFromStopPlayAndTone is set to be 1 and some data is taken off from the bus. For more information, refer to ‘Operation Principle of SHD Series ’ in chapter 1.

The function may also be used to check the completion status of the task of buffer-sequence playing.

Note:

l If the channel doesn’t support hardware decoding to the encoding format designated by the parameter nFormat, this function call will be failed. It’s determined by the board model whether the on-board channel supports hardware decoding to one specified encoding format. For more details, refer to the related information in Chapter 1.

l In the callback function, the code execution time for the application to complete the voice data updating and submission needs to be minimized and it can’t be larger than the driver’s interruption time (8ms); otherwise the driver may work incorrectly.

l The application may invoke the function SsmStopPlayMemBlock or SsmStopPlay to stop the double-buffer voice playing, but these two functions can’t be called in the callback function.

l After the Pingpong-buffer voice playing stops, the driver will throw out the event of E_PROC_PlayEnd to the application.

l If this function is called on Channel 0, for ATP/DST Series boards, the played voice is sent to the port of the on-board speaker, but not sent to the line; For SHT Series boards, the played voice is sent not only to the line but also to the port of the on-board speaker.

l It is not allowed to simultaneously submit more than two buffer areas to the driver.

l It is not allowed to use the timer to invoke the function SsmPlayMemBlock.

Sample Code:

......//initialize and fill in the buffer areas szPlayBuf1, szPlayBuf2
BOOL PlayStart(int nCh)
{
if(SsmPlayMemBlock(nCh, 6, szPlayBuf1, dwBufSize, PlayCallBack, NULL) != 0)//submit the buffer area szPlayBuf1 to the driver and start the playing in pingpong buffer mode
{
SsmGetLastErrMsg(szErrMsg);
cout<<szErrMsg<<endl;
return FALSE;
}
if(SsmPlayMemBlock(nCh, 6, szPlayBuf2, dwBufSize, PlayCallBack, NULL) != 0)//submit the buffer area szPlayBuf2 to the driver
{
SsmGetLastErrMsg(szErrMsg);
cout<<szErrMsg<<endl;
return FALSE;
}
return TRUE;
}
BOOL PlayCallBack(int ch, int nEndReason, PUCHAR pucBuf, DWORD dwStopOffset, PVOID pV)
{
int nResult = 0;
if(pucBuf == szPlayBuf1)
{
......//refill in the buffer area szPlayBuf1
nResult = SsmPlayMemBlock(ch, 6, szPlayBuf1, dwBufSize, PlayCallBack, pV);)//submit the buffer area szPlayBuf1 to the driver
}
else if(pucBuf == szPlayBuf2)
{
......//refill in the buffer area szPlayBuf2
nResult = SsmPlayMemBlock(ch, 6, szPlayBuf2, dwBufSize, PlayCallBack, pV);//submit the buffer area szPlayBuf2 to the driver
}
return nResult;
}

Related Information:

Driver version | SynCTI Ver. 3.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmStopPlayMemBlock, SsmStopPlay, SsmPlayMem, SsmPlayMemList


2.9.9.2 SsmStopPlayMemBlock

Stops the Pingpong-buffer voice playing originated by SsmPlayMemBlock.

Format:

int SsmStopPlayMemBlock(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Stops the Pingpong-buffer voice playing originated by SsmPlayMemBlock.

Note:

l This function can’t be called in the callback function which is set during the function call of SsmPlayMemBlock.

l This function can be completely substituted by the function SsmStopPlay.

Related Information:

Driver version | SynCTI Ver. 3.0or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmPlayMemBlock, SsmStopPlay


2.9.10 General Functions to Stop Voice Playing


2.9.10.1 SsmStopPlay

Stops the voice playing originated by any modes.

Format:

int SsmStopPlay(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Stops the voice playing originated by any modes.

Note:

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function:

SsmStopPlayFile, SsmStopPlayFileList, SsmStopPlayMem, SsmStopPlayMemList, SsmStopPlayIndex, SsmStopPlayMemBlock


2.9.11 Obtaining Relative Information about Voice Playing


2.9.11.1 SsmQueryPlayFormat

Checks whether the channel supports the designated format of voice playing.

Format:

int SsmQueryPlayFormat (int ch, int nFormat)

Parameter Description:

ch | Channel Number
nFormat | Voice playing format, for the range of value and more detailed information, refer to SynCTI Supported CODECs in Chapter 1

Return Value:

0 | Not supported
1 | Supported with hardware decoding
2 | Supported with software decoding

Function Description:

Checks whether the channel supports the designated format of voice playing.

Note:

l This function supports channels of any type.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function:


2.9.11.2 SsmGetPlayType

Queries the type of the current executing task of voice playing on a channel.

Format:

int SsmGetPlayType(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Call failed
0 | No voice playing
1 | Playing single file
2 | Playing single file, but the file playing is suspended by the application
3 | Playing the file list
4 | Playing preload voice
5 | Playing single buffer
6 | Playing buffer list
7 | Transmitting FSK data (Note: Transmitting FSK data will occupy the resource of voice playing)
8 | Currently using the voice-playing to enable the voice exchange between channels without interboard bus
9 | Playing Pingpong buffer

Function Description:

Queries the type of the current executing task of voice playing on a channel.

Note:

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function:


2.9.11.3 SsmCheckPlay

Obtains the finishing status of the voice playing.

Format:

int SsmCheckPlay(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Call failed
0 | Voice is currently being played
1 | Voice playing is ended: All the voice data have been finished playing.
2 | The voice playing task is stopped because DTMF characters are detected. For more information, refer to Setting Termination Condition in Chapter 1.
3 | The voice playing task is stopped because bargein is detected. For more information, refer to Setting Termination Condition in Chapter 1.
4 | The voice playing task is stopped because remote end hangup is detected. For more information, refer to Setting Termination Condition in Chapter 1.
5 | The voice playing is terminated by the application
6 | The voice playing is suspended by the function SsmPausePlay which is invoked by the application. The voice playing task must be initiated by the function SsmPlayFile
7 | The voice playing is terminated due to the off-bus operation on the channel. For more information, refer to Setting Termination Condition in Chapter 1.
8 | The voice playing is terminated due to the network disconnection. When the application calls the function SsmPlayFile to play voice files in other computers located in the network, if the driver can’t read the file because of the reasons such as network disconnection, the return value is 8.

Function Description:

Obtains the finishing status of the voice playing.

Note:

l The voice playing may be started by whichever of the following functions: SsmPlayFile, SsmPlayFileList, SsmPlayMemList, SsmPlayIndexList, SsmPlayIndexString, SsmPlayMem, and SsmPlayMemBlock.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Functions: SsmPlayFile, SsmPlayFileList, SsmPlayMemList, SsmPlayIndexList, SsmPlayIndexString, SsmPlayMem, SsmPlayMemBlock

Related Events: E_PROC_PlayEnd, E_PROC_PlayFile, E_PROC_PlayFileList, E_PROC_PlayMem


2.9.11.4 SsmGetPlayedPercentage

Obtains the percentage of the played data length to the total data length.

Format:

int SsmGetPlayedPercentage(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Call failed
≥0 | The percentage of the played bytes to the total bytes

Function Description:

Obtains the percentage of the played data length to the total data length.

Note:

l This function supports the voice playing started by the function SsmPlayIndexList, SsmPlayIndexString, SsmPlayFile, SsmPlayFileList, or SsmPlayMemList.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetPlayedTime


2.9.11.5 SsmGetPlayedTime

Obtains the duration of the current voice playing.

Format:

int SsmGetPlayedTime(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
≥0 | The duration (ms) of the voice playing

Function Description:

Obtains the duration of the current voice playing.

Note:

l This function supports the voice playing started by the function SsmPlayFile, SsmPlayFileList, SsmPlayMemList, SsmPlayIndexList, SsmPlayIndexString, and SsmPlayMem.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetPlayedPercentage, SsmGetDataBytesToPlay, SsmGetPlayedTimeEx, SsmGetPlayingFileInfo


2.10 Voice Recording Functions


2.10.1 Setting Recording Parameters


2.10.1.1 Setting Signal Source and Its Volume


2.10.1.1.1 SsmSetRecVolume

Sets the gain of the volume adjuster for the incoming signal entering the recording mixer.

Format:

int SsmSetRecVolume(int ch, int nVolume)

Parameter Description:

ch | Channel Number
nVolume | Recording volume, range of value: -7~+6, -7 means turnoff, the other values represents the volume gain (multiplied by 3 equals dB value), The value larger than 0 means volume increasing, smaller than 0 means volume decreasing

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Sets the gain of the volume adjuster A3 for the incoming signal entering the recording mixer M3. For more details about M3 and A3, refer to the corresponding principle diagram of the board in Chapter 1.

Note:

l The same features may be achieved through the configuration item of DefaultRecordVolume, with the default value of 0.

l The parameters set by this function are valid to the recording functions of all types.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSetRecMixer, SsmSetRecBack


2.10.1.1.2 SsmSetRecMixer

Sets the gain of the volume adjuster A2 for the incoming signal entering the recording mixer M3.

Format:

int SsmSetRecMixer(int ch, BOOL bEnRecMixer, int nMixerVolume)

Parameter Description:

ch

Channel Number

bEnRecMixer

=FALSE: turns off the volume adjuster A2, the incoming signal of the current channel is the only data source for the recording operation;

=TRUE: turns on the volume adjuster A2, the data source for the recording operation includes not only the incoming signal of the current channel but also some other sources

nMixerVolume

The volume gain of other recording signal sources, it’s valid only when the switch of bEnRecMixer is turned on. The range of value: -7~+6, in which,

-7: turns off A2, it sets the value of bEnRecMixer to be False.

-6~6: volume gain (multiplied by 3 equals the dB value), larger than 0 means volume increasing, smaller than 0 means volume decreasing

Return Value:

-1 | Call failed
0 | Successful

Function Description:

Sets the gain of the volume adjuster A2 for the other signal sources entering the recording mixer M3. For more detailed information about M3 and A2, refer to the principle diagram of the board in Chapter 1.

Note:

l The configuration item DefaultRecordMixerVolume may implement the same features, A2 is turned off by default.

l The parameters set by this function are valid to the recording functions of all types.

l This function doesn’t support DST Series boards.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSetRecVolume, SsmSetRecBack, SsmGetRecMixerState, SsmQueryOpRecMixer


2.10.1.1.3 SsmQueryOpRecMixer

Queries whether the channel is supported to set the gain of volume adjuster A2.

Format:

int SsmQueryOpRecMixer(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Not supported
1 | Supported

Function Description:

Queries whether the channel is supported to set the gain of volume adjuster A2.

Note:

l This function doesn’t support DST Series boards.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSetRecMixer


2.10.1.1.4 SsmGetRecMixerState

Obtains the settings of the gain parameter of the volume adjuster A2.

Format:

int SsmGetRecMixerState(int ch, int* pnEnRecMixer, int* pnMixerVolume)

Parameter Description:

ch | Channel Number
pnEnRecMixer | The pointer storing the switching status of the recording mixer.
pnMixerVolume | Stores the volume of the voice signal from another channel apart from the volume of the incoming voice signal of the current channel entering the recording mixer. The obtained volume value multiplied with 3 equals its dB value

Return Value:

-1 | Failed
0 | Successful

Function Description:

Obtains the settings of the gain parameter of the volume adjuster A2.

Obtains the status of the recording mixer on the specified channel. If the switching status of the recording mixer is turned on, the parameter pnEnRecMixer is set 1, otherwise, it is set 0. The parameter pnMixerVolume is used to return the volume of the voice signal from another channel apart from the volume of the incoming voice signal of the current channel entering the recording mixer.

Note:

l The settings of the recording-mixer switch are effective to both file-recording and buffer-recording functions.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSetRecMixer, SsmQueryOpRecMixer


2.10.1.1.5 DTRSetMixerVolum

Sets the gain of the volume adjuster A4-1, A4-2 of the incoming/outgoing voice signal on DST Series boards.

Format:

int DTRSetMixerVolume(int ch, int nGroup, int nInboundGain, int nOutboundGain)

Parameter Description:

ch

Channel number

nGroup

Chooses B channel. The digital phone operates in 2B+D mode. Because the current driver can’t process the two B channels simultaneously, this parameter must be set 0

nInboundGain

The gain of the volume adjuster for incoming signals ( i.e. volume adjuster A4-1 in Operation Principle of DST Series of Chapter 1),

range of value: -7~+6, the negative value means volume decreasing, the positive value means the volume increasing , -7 means close, this parameter multiplied by 3 equals dB value

nOutboundGain

The gain of the volume adjuster for outgoing signals ( i.e. volume adjuster A4-2 in Operation Principle of DST Series of Chapter 1),

range of value: -7~+6, the negative value means volume decreasing, the positive value means the volume increasing , -7 means close, this parameter multiplied by 3 equals dB value

Return Value:

-1 | Failed
0 | Successful

Function Description:

Sets the gain of the volume adjuster A4-1, A4-2 of the incoming/outgoing voice signal on DST Series boards.

Fore more detailed information about A4-1, A4-2, refer to Operation Principle of DST Series in Chapter 1.

Note:

l This function only supports DST Series boards.

Related Information:

Driver version | SynCTI Ver. 4.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSetRecVolume, DTRGetMixerVolume


2.10.1.1.6 DTRGetMixerVolume

Obtains the gain parameters of the volume adjuster A4-1, A4-2 of the incoming/outgoing voice signal on DST Series boards.

Format:

int DTRGetMixerVolume(int ch, int nGroup, int* pnInboundGain, int* pnOutboundGain)

Parameter Description:

ch

Channel number

nGroup

Chooses B channel, it must be set 0

pnInboundGain

Returns the gain parameters of the volume adjuster for incoming signals ( i.e. volume adjuster A4-1 in Operation Principle of DST Series of Chapter 1),

range of value: -6~+6, the negative value means volume decreasing, the positive value means the volume increasing , this parameter multiplied by 3 equals dB value

pnOutboundGain

Returns the gain parameters of the volume adjuster for outgoing signals ( i.e. volume adjuster A4-2) in Operation Principle of DST Series of Chapter 1),

range of value: -6~+6, the negative value means volume decreasing, the positive value means the volume increasing , this parameter multiplied by 3 equals dB value

Return Value:

-1 | Failed
0 | Successful

Function Description:

Obtains the gain parameters of the volume adjuster A4-1, A4-2 of the incoming/outgoing voice signal on DST Series boards. Fore more detailed information about A4-1, A4-2, refer to Operation Principle of DST Series in Chapter 1.

Note:

l This function only supports DST Series boards.

Related Information:

Driver version | SynCTI Ver. 4.0or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: DTRSetMixerVolume


2.10.1.1.7 SsmSetRecBack

Sets whether to receive the output of the bus mixer or the play data as input signals of the recording mixer.

Format:

int SsmSetRecBack(int ch, int nSelector)

Parameter Description:

ch | Channel Number
nSelector | Sets the status of the switch k6-2 and k6-1, below are the values: 0: k6-2 switched off, k6-1 switched off 1: k6-2 switched on, k6-1 switched on 2: k6-2 switched off, k6-1 switched on 3: k6-2 switched on, k6-1 switched off The default value is 1, i.e. both k6-2 and k6-1 switched on. For more information about these two switches, refer to Operation Principle of SHD Series in Chapter 2

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Sets whether to receive the output of the bus mixer or the play data as input signals of the recording mixer.

Note:

l This function only supports SHD and SHN Series boards.

Related Information:

Driver version | SynCTI Ver. 4.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSetRecVolume, SsmSetRecMixer


2.10.1.1.8 SsmSetNoModuleChBusRec

Uses the non-module channels of ATP Series boards as recording channels.

Format:

int SsmSetNoModuleChBusRec(int ch, int nUsedAsResourceRecCh)

Parameter Description:

ch | Channel Number
nUsedAsResourceRecCh | 1: enables this feature 0: disables this feature

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Uses the non-module channels of ATP Series boards as recording channels. For more information, refer to ‘special application of non-module channel’ in Operation Principle of ATP Series of Chapter 1.

Note:

l Before the recording is started, the function SsmSetRecVolume needs to be invoked or the configuration item DefaultRecordVolume needs to be set in order to turn off the volume adjuster of incoming voice signals.

l The signal source for recording only comes from the TDM bus.

l The configuration item NoModuleChBusRec may implement the same features.

l This function only supports ATP Series boards.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSetRecVolume


2.10.1.2 Setting Termination Condition of Voice Recording


2.10.1.2.1 SsmSetDTMFStopRecCharSet

Sets whether the recording stops when the DTMF Detector detects DTMF character.

Format:

int SsmSetDTMFStopRecCharSet(int ch, LPSTR lpstrDtmfCharSet)

Parameter Description:

ch | Channel number
lpstrDtmfCharSet | Pointer which points to the ASCII-formatted DTMF character set used to stop the recording. The DTMF character set includes ‘0’, ’1’, ’2’, ’3’, ’4’, ’5’, ’6’, ’7’, ’8’, ’9’, ’*’, ’#’, ’a’, ’b’, ’c’, ’d’, it can also be set NULL to indicate that this feature is disabled.

Return Value:

-1 | Call failed. The failure reason can be acquired via the function SsmGetLastErrMsg
0 | Successful

Function Description:

Sets whether the recording stops when the DTMF Detector detects DTMF character.

If lpstrDtmfCharSet isn’t empty, when the channel is recording, on the condition that DTMF Detector detects the DTMF character in the incoming voice signal, and also the detected DTMF character is included in the DTMF character set which is designated by the parameter lpstrDtmfCharSet, the driver will stop the recording immediately.

Note:

l The configuration item DtmfStopRecCharSet may also implement the same features.

l All the recording started by the file recording function, buffer recording function or Pingpong-buffer recording function supports this feature.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSetHangupStopRecFlag, SsmGetDTMFStopRecCharSet


2.10.1.2.2 SsmGetDTMFStopRecCharSet

Checks whether the recording is stopped because DTMF Detector detects the DTMF character.

Format:

int SsmGetDTMFStopRecCharSet(int ch, LPSTR lpstrDtmfCharSet)

Parameter Description:

ch | Channel number
lpstrDtmfCharSet | Returns ASCII formatted DTMF character set

Return Value:

-1 | Call failed. The failure reason can be acquired via the function SsmGetLastErrMsg
0 | This feature has been turned off
>0 | The character number in the preset DTMF character set

Function Description:

Checks whether the recording is stopped because DTMF Detector detects the DTMF character.

Note:

Related Information:

Driver version | SynCTI Ver. 3.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSetDTMFStopRecCharSet


2.10.1.2.3 SsmSetHangupStopRecFlag

Sets whether the recording is stopped when the driver state machine detects remote end hangup.

Format:

int SsmSetHangupStopRecFlag(int ch, BOOL bHangupStopRecFlag )

Parameter Description:

ch | Channel number
bHangupStopRecFlag | The flag denotes whether to stop the voice recording when the driver detects remote end hangup. Range of value: TRUE: turn on this feature FALSE: turn off this feature

Return Value:

-1 | Call failed. The failure reason can be acquired via the function SsmGetLastErrMsg
0 | Successful

Function Description:

Sets whether the recording is stopped when the driver state machine detects remote end hangup.

Note:

l The configuration item HangupStopRec may implement the same features. When the driver starts, this feature is turned off.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSetDTMFStopRecCharSet


2.10.1.3 Setting Prerecord Feature (REC Series)


2.10.1.3.1 SsmSetPrerecord

Sets the prerecord feature.

Format:

int SsmSetPrerecord(int ch, BOOL bEnable, int nMode, WORD wInsertTime, int nFormat)

Parameter Description:

ch

Channel Number

bEnable

TRUE: turn on the prerecord feature

FALSE: turn off the prerecord feature

Note: the corresponding configuration item to this parameter is PrerecordEnable

nMode

Sets the operating mode of the prerecord feature:

0: When Barge-in Detector detects Barge in, it starts to write the recording data to the internal buffer

1: When the analog recording channel detects pick-up on the line, it starts to write the recording data to the internal buffer

Note: the corresponding configuration item to this parameter is PrerecordMode

nInsertTime

After the prerecord feature is enabled, when the application starts the task of file -recording, this parameter sets the time length (ms) that the driver takes to write the prerecord data to the file.

Note: the corresponding configuration item to this parameter is PrerecordInsertTime

nFormat

Sets the encoding format for recording, range of value:

1: PCM8

6: A-law

7: μ-law

17: IMA ADPCM(Note: the board needs to have hardware encoder)

49: GSM 6.10

85: MP3

Note: the corresponding configuration item to this parameter is PrerecordCodec

Return Value:

-1 | Call failed
0 | Successful

Function Description:

Sets the prerecord feature. For more details about the prerecord feature, refer to Setting Prerecord Feature in Chapter 1.

Note:

l This function is only applicable to ATP Series boards;

l Prerecord feature only supports file-recording functions.

Related Information:

Driver version | SynCTI Ver. 2.1 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetPrerecordState


2.10.1.3.2 SsmGetPrerecordState

Obtains the settings of prerecord feature.

Format:

int SsmGetPrerecordState (int ch , int* pnMode, PWORD pwInsertTime, int* pnFormat)

Parameter Description:

ch | Channel Number
pnMode | Returns the operating mode of prerecord
pnInsertTime | Returns the time length (ms) that the driver takes to write the prerecord data to the file
pnFormat | Returns the voice encoding format for prerecord

Return Value:

-1 | Call failed
0 | The prerecord feature is disabled
1 | The prerecord feature is enable. Only when the return value is 1, return values of parameters of this function are valid

Function Description:

Obtains the settings of prerecord feature.

Note:

For the meanings of related parameters, refer to the function SsmSetPrerecord.

Related Information:

Driver version | SynCTI Ver. 2.1or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSetPrerecord


2.10.1.4 Setting Tail-truncation Feature


2.10.1.4.1 SsmSetTruncateTail

Sets the operating parameters of tail-truncation for file recording.

Format:

int SsmSetTruncateTail(int ch, DWORD dwTime)

Parameter Description:

ch | Channel Number
dwTime | Sets the length (ms) of the recording data which needs to be truncated. 0 means to turn off this feature. For SynCTI Ver. 3.4.x, when the tail-truncation is implemented, the time length of tail-truncation is the duration of DTMF character which stops the file recording; For Ver. 3.5 and later version, if dwTime is greater than duration of the DTMF character which stops the file recording, the time length of the truncated data is dwTime; Otherwise, it’s the actual duration of the DTMF character. This parameter may also be set by the configuration item TruncateTailOnRecordToFile

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Sets the operating parameters of tail-truncation for file recording. For more information about recording file tail-truncation, refer to Setting Tail-Truncation Feature in Chapter 1.

When the file recording is initiated, if both the feature of recording file tail-truncation and the feature of file recording termination by DTMF character are enabled, in case that the DTMF character detected by the DTMF Detector is included in the character set configured by the function SsmSetDTMFStopRecCharSet or the configuration item DtmfStopRecCharSet, the driver stops the file recording immediately and deletes a section of voice data in the tail part of the file. The length of the deleted voice data is set by this function.

Note:

l If the file recording is terminated normally, i.e. it finishes the voice data recording with the designated length, the driver will not do the tail-truncation operation;

l The recording file tail-truncation feature only supports file recording functions.

Related Information:

Driver version | SynCTI Ver. 3.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmRecToFile, SsmRecToFileA, SsmRecToFileB, SsmRecToFileEx, SsmGetTruncateTailTime


2.10.1.4.2 SsmGetTruncateTailTime

Obtains the operating parameters of the recording file tail truncation.

Format:

long SsmGetTruncateTailTime(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | This feature is not enabled
>0 | Returns the time length (ms) of the tail truncation

Function Description:

Obtains the operating parameters of the recording file tail truncation.

Note:

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSetTruncateTail


2.10.1.5 Setting AGC Feature


2.10.1.5.1 SsmSetRecAGC

Enables or disables the AGC feature.

Format:

int SsmSetRecAGC(int ch, int nAGCSwitch)

Parameter Description:

ch | Channel number
nAGCSwitch | Automatic gain control switch for recording (AGC). For DST series B-type digital station tap boards, Bit0, Bit1 and Bit2 are valid. Bit0=0, the AGC downlink is disabled; Bit0=1, the AGC downlink is enabled. Bit1=0, the AGC uplink is disabled; Bit1=1, the AGC uplink is enabled. Bit2=0, DC-isolated is disabled; Bit2=1, DC-isolated is enabled. For other boards, Bit0 is valid. Bit0=0, the AGC is disabled; Bit0=1, the AGC is enabled.

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Enables or disables the AGC (Automatic Gain Control) feature. If the AGC is enabled, the driver automatically adjusts the voice signal based on the amplitude of the input signal. It increases the small signal gain and decreases the large signal gain.

Note:

l The recording AGC switch is valid to recording operations of any type;

l The configuration item AutoRecAgcSwitch can be used to achieve the same purpose, with the default value of 0.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetRecAGCSwitch


2.10.1.5.2 SsmGetRecAGCSwitch

Obtains the working status of the recording AGC.

Format:

int SsmGetRecAGCSwitch(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Call failed
>0 | For DST series B-type digital station tap boards, Bit0, Bit1 and Bit2 are valid. Bit0=0, the AGC downlink is disabled; Bit0=1, the AGC downlink is enabled. Bit1=0, the AGC uplink is disabled; Bit1=1, the AGC uplink is enabled. Bit2=0, DC-isolated is disabled; Bit2=1, DC-isolated is enabled. For other boards, Bit0 is valid. Bit0=0, the AGC is disabled; Bit0=1, the AGC is enabled.

Function Description:

Obtains the working status of the recording AGC module on the designated channel.

Note:

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSetRecAGC


2.10.2 Obtaining Recording Operation Information


2.10.2.1 SsmQueryRecFormat

Enquires whether the channel supports the designated recording format.

Format:

int SsmQueryRecFormat (int ch, int nFormat)

Parameter Description:

ch | Channel Number
nFormat | Recording format

Return Value:

0 | Not supported
1 | Supported with hardware encoding
2 | Supported with software encoding

Function Description:

Enquires whether the channel supports the designated recording format.

Note:

l This function supports boards and channels of all types.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function:


2.10.2.2 SsmGetRecType

Obtains the type of the currently executing recording task.

Format:

int SsmGetRecType(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Call failed
0 | No recording on the channel
1 | Currently executing file recording
2 | The recording in file mode has been suspended
3 | Currently executing recording in buffer mode
4 | Currently executing recording in Pingpong buffer mode

Function Description:

Obtains the type of the currently executing recording task.

Note:

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function:


2.10.2.3 SsmGetRecTime

Obtains the duration of the recording task.

Format:

int SsmGetRecTime(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Call failed
≥0 | the duration of the recording task, calculated by millisecond (ms)

Function Description:

Obtains the duration of the recording task.

Note:

l This function only supports recording in file mode and buffer mode.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmRecToFile, SsmRecToFileA, SsmRecToFileB, SsmRecToFileEx , SsmRecToMem


2.10.2.4 SsmCheckRecord

Enquires the finishing status of recording.

Format:

int SsmCheckRecord (int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Call failed
0 | Recording in process
1 | The recording is terminated by the application
2 | Recording is terminated upon detection of DTMF characters
3 | Recording is terminated upon detection of remote hangup
4 | Recording is terminated spontaneously
5 | File recording is suspended
6 | File recording is terminated upon the failure in writing into the file
7 | Recording is terminated becaused of the unsupport of system, eg. in a case when incoming and outgoing calls are recorded separately on a same link at the same time (only for DTP-120C/PCIe, DTP-120C/PCIe+ and DTP-120C/PCI, DTP-120C/PCI+ boards)

Function Description:

Enquires the finishing status of recording.

Note:

l This function is applicable to recording tasks initiated by any modes such as SsmRecToFile, SsmRecToFileA, SsmRecToFileB, SsmRecToFileEx, SsmRecToMem, and SsmRecordMemBlock.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function:

SsmRecToFile, SsmRecToFileA, SsmRecToFileB, SsmRecToFileEx, SsmRecToMem, SsmRecordMemBlock


2.10.3 Functions for Recording in File Mode


2.10.3.1 SsmRecToFile

Refer to SpyRecToFile


2.10.3.2 SsmRecToFileA

Refer to SpyRecToFile


2.10.3.3 SsmRecToFileB

Refer to SpyRecToFile


2.10.3.4 SsmRecToFileEx

Refer to SpyRecToFile


2.10.3.5 SpyRecToFile

Initiates the file recording task on the designated channel.

SsmRecToFileA not only has all the features of SsmRecToFile, but also provides the capability of achieving the recording data stream buffered in the driver by invoking the callback function.

SsmRecToFileEx not only has all the features of SsmRecToFile, but also provides the capability of using the Bargin signal which is output from the Barge-in Detector to trigger the recording data to be written into the file.

SpyRecToFile initiates the file recording task based on the circuit number which is only applicable to DTP Series boards.

Format:

int SsmRecToFile(int ch, LPSTR pszFileName, int nFormat, DWORD dwStartPos, DWORD dwBytes, DWORD dwTime, int nMask)

int SsmRecToFileA(int ch, LPSTR pszFileName, int nFormat, DWORD dwStartPos, DWORD dwBytes, DWORD dwTime, int nMask, LPRECTOMEM pfnCallbackA)

int SsmRecToFileB(int ch,LPSTR pszFileName,int nFormat,DWORD dwStartPos,DWORD dwBytes,DWORD dwTime,int nMask,LPRECTOMEMB pfnCallbackB, PVOID pVoid);

int SsmRecToFileEx(int ch, LPSTR pszFileName, int nFormat, DWORD dwStartPos, DWORD dwBytes, DWORD dwTime, int nMask, BOOL bSaveToFileOnBargin, DWORD dwRollbackTime)

int SpyRecToFile( int nCic, WORD wDirection, LPSTR pszFileName, int nFormat, DWORD dwStartPos, DWORD dwBytes, DWORD dwTime, int nMask )

Parameter Description:

ch

Channel Number

pszFileName

The name of the file storing the voice data

If the file declared by the parameter pszFileName doesn’t exist, the driver automatically creates a new file based on the following rules:

² If pszFileName has a file extension of ‘.wav’, the driver will consider that the application wants to record a standard WAV file and create a standard WAV file;

² If the file extension is not ‘.wav’, the driver will determine the file to be a non-header file. All the data in the file are voice data and have no file header.

nFormat

Encoding format of the voice data, range of value are listed below:

Value | CODEC | SsmRecToFile | SsmRecToFileA SsmRecToFileB | SsmRecToFileEx | SpyRecToFile
-2 | PCM16 | ☆ | ☆ | — | ☆
1 | PCM8 | ☆ | ☆ | — | ☆
6 | A-Law | Ö | Ö | Ö | Ö
7 | m-Law | Ö | Ö | Ö | Ö
17 | IMA ADPCM | Ö | Ö | Ö | Ö
23 | VOX | Ö | Ö | — | Ö
49 | GSM | ◇ | ◇ | — | ◇
85 | MP3 | ◇ | ◇ | — | ◇
131 | G.729A | Ö | Ö | — | Ö

Legend: ☆ Using software encoder, implemented by driver’s encoding in software

Ö Using hardware encoder, requiring that the device has encoders on itself. Fore more information, refer to ‘SynCTI Supported CODECs’in Chapter 1.

★ Software encoding, implemented by the external ACM program.

— Not supported

◇ Using hardware encoder if the device itself has encoders; otherwise,using software encoder via the external ACM program.

The actual encoding format for recording is determined by the following rules:

If the file declared by the parameter pszFileName has already existed and it’s a standard wav formatted file, the encoding format will be the encoding format designated in the head of the wav file, the parameter nFormat will be ignored;

If the existing file is not a standard wav file, or the file is a new created file, the encoding format is determined by nFormat.

Note: nFormat = -1 represents the default encoding format which is related to the item DefaultRecordFormat in ShConfig.ini. If the pre-recording feature is enabled, nFormat must be the same as the voice encoding format which is set in the prerecording settings, otherwise, this function returns failure.

dwStartPos

The starting offset when the first recording data is being written into the file. If the target file has the file header of wav, dwStartPos is calculated from the first position of the voice data area, the length of the file header is not included.

² In case the file exists: If dwStartPos is less than or equals to the length of the voice data in the file, the data is written into the file starting from the position designated by this parameter; If dwStartPos is bigger than the length of the voice data in the file, the recording data is written into the file starting from the file tail.

² If it’s a new created file: This parameter will be ignored. If it’s a standard wav file, the recording data is written immediately following the file header; If not, the recording data is written starting from the file header

dwBytes

Sets the length (bytes) of the voice data to be recorded.

When the total number of bytes which have been recorded are bigger than the value set by this parameter, the recording is finished. The purpose of continuous recording may reached via setting this parameter to be a large number (e.g. 0xffffffff ).

It’s determined by the parameter nMask that whether this parameter is effective or not.

Note: If frame-structured encoding format (e.g. IMA ADPCM, GSM, MP3, G.729A etc. ) is used, and also the length of dwBytes is not integral times of the length of the frame, the driver will automatically adjust the length of dwBytes to be integral times of the length of the frame to ensure the integrity of the frame structure

dwTime

Sets the total time length (ms) of the voice data to be recorded.

When the time length of recording exceeds the time length set by this parameter, the recording is finished. The purpose of continuous recording may reached via setting this parameter to be a large number (e.g. 0xffffffff ).

It’s determined by the parameter nMask that whether this parameter is effective or not.

Note: If frame-structured encoding format (e.g. IMA ADPCM, GSM, MP3, G.729A etc. ) is used, and also the length of dwTime is not integral times of the length of the frame, the driver will automatically adjust the length of dwTime to be integral times of the length of the frame to ensure the integrity of the frame structure

nMask

Sets the method used to terminate the recording. Range of value:

0: use the parameter dwBytes as the condition of stopping recording.

1: use the parameter dwTime as the condition of stopping recording

pfnCallbackA

pfnCallbackB

Sets the callback function pointer. If pfnCallbackA or pfnCallbackB is NULL, the feature of NULL, SsmRecToFileA or SsmRecToFileB is completely the same as the feature of SsmRecToFile; If they are not NULL, once 16384 bytes recording data have been accumulated in the buffer of the driver and also they are written into the file once for all, the callback function set by this parameter will be invoked to pass the buffered voice data stream to the application simultaneously. The function SsmSetFlag (along with the parameter F_RECTOFILEA_CALLBACKTIME) may be used to set the time interval of callback.

The prototype of the callback function pfnCallbackA:

void CALLBACK RecFileCallback(int ch, LPBYTE lpData, DWORD dwDataLen);

The prototype of the callback function pfnCallbackB:

void CALLBACK RecFileCallback (int ch, LPBYTE lpData, DWORD dwDataLen, PVOID pVoid);

in the above prototypes,

ch: Voice channel number

lpData: The address of the buffer area of recording data in the driver

dwDataLen: The length (bytes) of the recording data

pVoid: The passed-in pointer when SsmRecToFileB is called

pVoid

The pointer of PVOID type, it’s used to transparently pass the object pointer of the application to the callback function pfnCallbackB

bSaveToFileOnBargin

Whether to enable the feature that the output of Barge-in Detector is used to trigger the writing of the recording data into the file. Range of value:

TRUE: enable

FALSE: disabled

If this parameter is False, the parameter dwRollbackTime will be ignored. The features of the function SsmRecToFileEx and SsmRecToFile are completely the same

dwRollbackTime

This parameter determines the time length (ms) of the voice data before the generation of the Barge-in signal to be saved in the file, with the maximum value of 2000ms. This parameter is valid only when the parameter bSaveToFileOnBargin is set TRUE.

Because it takes certain time for Barge-in Detector to detect Barge-in, in order to ensure the integrity of the recorded voice data, this parameter needs to be set appropriately. It’s recommended that this parameter should be slightly bigger than the value set by the function SsmSetIsBargeInDtrmTime or the configuration item BargeInDtrmTime

nCic

The logical number of SpyCic. For more information, refer to ‘DTP Series’

wDirection

Sets the recording signal source, range of value:

0: Only to record the voice of the calling party. The driver automatically invokes the function SsmRecToFile on the calling party’s channel bounded with nCic, hence the related output messages are also returned on the calling party’s channel;

1: Only to record the voice of the called party. The driver automatically invokes the function SsmRecToFile on the called party’s channel bounded with nCic, hence the related output messages are also returned on the called party’s channel;

2: Mixedly records both of the calling and called party’s voice. The driver automatically invokes the function SsmRecToFile on the called party’s channel bounded with nCic, hence the related output messages are also returned on the called party’s channel

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Initiates the file recording on the designated channel.

The function SsmRecToFileA and SsmRecToFileB not only have all the features of the function SsmRecToFile, but also open the recording data stream saved in the internal buffer area of the driver to the application through the method of the callback function. If the parameter pfnCallbackA (or pfnCallbackB) is NULL, the features of the function SsmRecToFileA (or SsmRecToFileB) and the function SsmRecToFile are completely the same.

After the function SsmRecToFileEx initiates the file recording, the driver only buffers the recording data in the internal recording buffer area instead of writing the data into the file. Only when Barge-in Detector detects Barge- in, will the driver start to write the recoding data saved in the internal buffer into the file. If there is no Bargin detected until the current recording stops, no data will be written into the recording file.

After the application invokes the file recording function, the driver will start a task of file recording. When the following events happen, the file recording stops:

² The file recording stops spontaneously, i.e. the length of the voice data recorded by the driver reaches to the parameter dwBytes or the length specified by the parameter dwTime;

² It’s failed when the driver writes the voice data into the file;

² The application calls SsmStopRecToFile;

² The driver detects DTMF or remote end hangup, for more information, refer to Setting Termination Condition in Chapter 1.

When the file recording is terminated, the driver will automatically close the file and throws out the event E_PROC_RecordEnd to the application. If the feature of the tail-truncation of the recording file is enabled, the driver will automatically discard a section of data at the file tail. For more information about the tail-truncation feature of the recording file, refer to Setting Tail-Truncation Feature in Chapter.

During the execution of the file recording, the driver throws out the event of E_PROC_RecordFile to the application in each interval of 1000ms. Whether to throw out the event and the condition for throwing out the event can be set by the function SsmSetEvent (with the parameter E_PROC_RecordFile). This event is thrown out every 1000ms by default. The function SsmChkRecToFile or SsmCheckRecord may also be used to enquire the finishing status of the file recording.

When the file-recording is being executed, the application may:

² Invoke the function SsmPauseRecToFile to pause the file recording;

² Invoke the function SsmStopRecToFile to stop the file recording;

² Invoke the function SsmChkRecToFile or SsmCheckRecord to enquire the finishing status of the file recording;

² Invoke the function SsmGetRecTime to obtain the duration of file recording;

² Invoke the function SsmGetDataBytesToRecord to obtain the unfinished bytes of the data to be recorded.

Note:

l For more information about choosing the recording signal source and setting the volume, refer to ‘Setting Recording Signal Source’ in Chapter 1;

l If the feature of prerecord is enabled, the driver will firstly write the prerecord data saved in the internal buffer area into the file based on the parameter settings of prerecord, and then it starts to execute the normal file recording, writes the subsequent data into the file. For more information about the feature of prerecording, refer to ‘Setting Prerecord Feature’ in Chapter 1;

l If the parameter nFormat is GSM or MP3, the configuration item GsmCodecEnable must be set to be not 0, and ensure the corresponding drivers of CODEC (ACM) have been installed in the Windows system;

l The function SpyRecToFile starts the file recording based on the circuit number. It’s only applicable to DTP Series boards. The function SpyRecToFile is based on the circuit number. It throws out messages which are based on the calling or called party’s channel bounded with nCic during the call progress to the application. The function SpyGetCallInCh and SpyGetCallOutCh obtain the channel number of the calling and called parties during the current call respectively. The function SpyStopRecToFile is used to terminate the file recording initiated by the function SpyRecToFile;

l Due to historical reasons, the coding value 65411 which ever represented G.729A is still valid in early versions and backward compatible. For G.729A recording in new versions, we suggest you use the coding value 131.

Related Information:

Driver version | SsmRecToFileB requires the version of SynCTI to be Ver. 4.7.2.0 or above; Other functions require SynCTI Ver. 2.0 or above.
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmStopRecToFile, SsmChkRecToFile, SsmGetRecTime, SsmPauseRecToFile, SsmRestartRecToFile, SsmGetDataBytesToRecord, SsmSetDTMFStopRecCharSet, SsmSetHangupStopRecFlag, SsmSetRecVolume, SsmSetRecMixer, SsmSetRecBack, SsmSetRecAGC


2.10.3.6 SsmStopRecToFile

Refer to SpyStopRecToFile


2.10.3.7 SpyStopRecToFile

Terminates the file recording. The function SpyStopRecToFile is used to terminate the file recording initiated by the function SpyRecToFile.

Format:

int SsmStopRecToFile(int ch)

int SpyStopRecToFile(int nCic)

Parameter Description:

ch | Channel Number
nCic | Monitored circuit number

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

The function SsmStopRecToFile terminates the file recording initiated by SsmRecToFile, SsmRecToFileA, SsmRecToFileB or SsmRecToFileEx. The function SpyStopRecToFile is used to terminate the file recording initiated by the function call of SpyRecToFile.

Note:

l After this function is invoked, the driver will also throw out the event of E_PROC_RecordEnd.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function:

SsmRecToFile, SsmRecToFileA, SsmRecToFileB, SsmRecToFileEx, SsmSetDTMFStopRecCharSet, SsmSetHangupStopRecFlag, SsmSetRecVolume, SsmSetRecMixer, SsmSetRecBack


2.10.3.8 SsmPauseRecToFile

Suspends the file recording.

Format:

int SsmPauseRecToFile(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Suspends the file recording initiated by the function SsmRecToFile, SsmRecToFileA, SsmRecToFileB or SsmRecToFileEx. If the file recording is in the suspended state, it can only be restarted by the function SsmRestartRecToFile or terminated by the function SsmStopRecToFile.

Note:

l This function only supports the tasks initiated by SsmRecToFile, SsmRecToFileA, SsmRecToFileB, or SsmRecToFileEx

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmRestartRecToFile, SsmStopRecToFile


2.10.3.9 SsmRestartRecToFile

Restarts the file recording.

Format:

int SsmRestartRecToFile(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Restarts the file recording suspended by the function SsmPauseRecToFile .

Note:

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmPauseRecToFile


2.10.3.10 SsmChkRecToFile

Enquires the finishing status of the file recording.

Format:

int SsmChkRecToFile(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | The file recording stops normally
1 | The file recording is under progress
2 | The file recording is suspended

Function Description:

Enquires the finishing status of the file recording.

Note:

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmRecToFile, SsmRecToFileA, SsmRecToFileB, SsmRecToFileEx


2.10.3.11 SsmGetDataBytesToRecord

Obtains the bytes number of the unfinished recording data.

Format:

int SsmGetDataBytesToRecord(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Call failed
≥0 | The bytes number of the unfinished recording voice data

Function Description:

Obtains the bytes number of the unfinished recording data after the file recording is initiated.

Note:

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetRecTime


2.10.4 Functions for Recording in Buffer Mode


2.10.4.1 SsmRecToMem

Starts the recording in buffer mode.

Format:

int SsmRecToMem(int ch, int nFormat, LPBYTE pBuf, DWORD dwBufSize, DWORD dwStartOffset)

Parameter Description:

ch

Channel Number

nFormat

Encoding format of the recording data. Range of value:

Value | Encoding Format | Remarks
1 | PCM8 |
6 | A-Law |
7 | m-Law |
17 | IMA ADPCM | Hardware decoding capability is required for the board
23 | VOX | Hardware decoding capability is required for the board
49 | GSM |
85 | MP3 | Hardware decoding capability is required for the board
131 | G.729A | Hardware decoding capability is required for the board

In order to know whether the channel supports the hardware encoder, refer to SynCTI Supported CODECs in Chapter 1

pBuf

The first address pointer to the recording buffer area, it’s allocated by the application

dwBufSize

The size (bytes) of the recording buffer area

dwStartOffset

The offset of the starting position of recording in the recording buffer area. Range of value: 0~dwBufSize-1

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Starts the buffer recording task.

After this function is called, the driver initiates a buffer recording task, writes the recording data into pBuf starting from the offset designated by the parameter dwStartOffset, and at the same time maintains a recording pointer (offset) with an initial value equal to dwStartOffset which is used to write data into the submitted buffer area. When the buffer is full, the driver automatically does circular writing starting from the buffer head.

When the following events happen, the buffer recording stops:

² The application calls SsmStopRecToMem;

² The driver detects DTMF or remote end hangup. For more detailed information, refer to Setting Termination Condition in Chapter 1.

The function of SsmCheckRecord may be used to enquire the finishing status of the buffer recording.

During the execution of the buffer recording, once the preset condition is satisfied, the driver throws out the event of E_PROC_RecordMem to the application. The output conditions of the event of E_PROC_RecordMem may be set by the function SsmSetEvent (with the parameter E_PROC_RecordMem). Below are three optional conditions:

² The driver finishes recording the voice data with designated time length;

² The recording pointer in the driver gets across the dwBufSize /2 position of the buffer area;

² The recording pointer in the driver reaches to the end of the buffer.

The function SsmStopRecToMem may be used to stop the buffer recording. The function SsmGetRecOffset may be used to obtain the recording pointer in the driver.

Note:

l For more information about setting the volume and selecting the recording signal source, refer to Setting Recording Signal Source in Chapter 1;

l Due to historical reasons, the coding value 65411 which ever represented G.729A is still valid in early versions and backward compatible. For G.729A recording in new versions, we suggest you use the coding value 131.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmStopRecToMem, SsmGetRecOffset, SsmSetDTMFStopRecCharSet, SsmSetHangupStopRecFlag, SsmSetRecVolume, SsmSetRecMixer, SsmSetRecBack


2.10.4.2 SsmStopRecToMem

Terminates the buffer recording.

Format:

int SsmStopRecToMem(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Terminates the buffer recording.

Note:

l When the recording is terminated, the driver will throw out the event of E_PROC_RecordEnd.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmRecToMem


2.10.4.3 SsmGetRecOffset

Obtains the recording pointer in the driver during the buffer recording process.

Format:

int SsmGetRecOffset(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Call failed
≥0 | Recording pointer in the driver, its value (bytes) is the offset to the first address of the buffer area submitted by the function SsmRecToMem

Function Description:

Obtains the recording pointer in the driver during the buffer recording process.

Note:

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmRecToMem


2.10.5 Functions for Recording in Pingpong Buffer Mode (CTI Series)


2.10.5.1 SsmRecordMemBlock

Submits a buffer area to the driver and initiates a Pingpong buffer recording.

Format:

int SsmRecordMemBlock(int ch, int nFormat, LPBYTE pBuf, DWORD dwBufSize, RECORDMEMBLOCKHANDLER pfnCallback, PVOID pV)

Parameter Description:

ch

Channel Number

nFormat

Encoding format of the recording data. Range of value:

Value | Encoding Format | Remarks
1 | PCM8 |
6 | A-Law |
7 | m-Law |
17 | IMA ADPCM | Hardware decoding capability is required for the board
23 | VOX | Hardware decoding capability is required for the board
49 | GSM |
85 | MP3 | Hardware decoding capability is required for the board
131 | G.729A | Hardware decoding capability is required for the board

In order to know whether the channel supports the hardware encoder, refer to SynCTI Supported CODECs in Chapter 1

pBuf

Pointer to the recording buffer area

dwBufSize

The recording buffer size (bytes). The minimum value of dwBufSize is determined according to the following rules:

If the configuration item RecordAndPlayUseAsIP is set 0 (default), dwBufSize should be no less than 768 bytes.

If the configuration item RecordAndPlayUseAsIP is set 1, for A-law and m-law, dwBufSize should be no less than 192 bytes (recommended value: under Windows operating system, no less than 192 bytes; under Linux, no less than 384 bytes); For the format of IMA ADPCM, the buffer size should be no less than 768 bytes.

For GSM recording in software (the configuration item GsmCodecEnable set to 1), the buffer size, i.e. dwBufSize, should be no less than 65*32=2080 bytes.

For GSM recording in hardware, the buffer size, i.e. dwBufSize, should be no less than 65*4=260 bytes.

pfnCallback

Callback function pointer. NULL means that there is no callback function. If this parameter is not NULL, when the driver finishes recording a buffer area or the playing task in buffer was terminated, it automatically calls the callback function set by this parameter. The prototype of the callback function is declared in shpa3api.h:

typedef BOOL (WINAPI * RECORDMEMBLOCKHANDLER)

(int ch, int nEndReason, PUCHAR pucBuf, DWORD dwStopOffset, PVOID pVoid);

See below for details.

ch: Channel Number;

nEndReason: The cause of termination, range of value:

1: The recording is terminated by the application.

2: The recording is terminated upon detection of DTMF.

3: The recording is terminated upon detection of remote end hangup.

4: The buffer recording is completed

pucBuf: The buffer area pointer when the recording is finished.

dwStopOffset: When the buffer area is finished playing, the offset (bytes) of recording pointer in the buffer area in the driver. If the return value is 0xffffffff, it is invalid.

pVoid: The pointer passed by the application when it invokes the double-buffer recording function.

pVoid

The pointer of PVOID type, normally it’s used by the application to pass its data structure to the callback function. This pointer will be transparently passed to the callback function by the driver

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Submits a buffer area to the driver and initiates a Pingpong buffer recording. For more information about Pingpong buffer recording, refer to Pingpong Buffer Mode in Chapter 1.

When the following events happen, the Pingpong buffer recording is terminated:

² The driver has finished recording of all the submitted buffer areas;

² The application calls the function SsmStopRecordMemBlock;

² The driver detects DTMF or remote end hangup. For more information, refer to Setting Termination Condition in Chapter 1.

The function SsmCheckRecord may be used to enquire the finishing status of the Pingpong buffer recording.

Note:

l For more information about setting the volume and selecting the recording signal source, refer to Setting Recording Signal Source in Chapter 1.

l The application may invoke the function SsmStopRecordMemBlock at any moment to terminate the Pingpong buffer recording. This function can’t be invoked in the callback function.

l In the callback function, the code execution time of the application should be as short as possible, it can’t be larger than the driver’s interruption time (8ms), and otherwise it may cause driver error.

l When the Pingpong buffer recording is terminated, the driver will throw out the event of E_PROC_RecordEnd to the application.

l It is not allowed to simultaneously submit more than two buffer areas to the driver.

l It is not allowed to use the timer to invoke the function SsmRecordMemBlock.

l Due to historical reasons, the coding value 65411 which ever represented G.729A is still valid in early versions and backward compatible. For G.729A recording in new versions, we suggest you use the coding value 131.

Sample Code:

......//initialize
the buffer areas szRecBuf1, szRecBuf2
BOOL RecStart(int nCh)
{
if(SsmRecordMemBlock(nCh, 6, szRecBuf1, dwBufSize, RecordMemBlockHandler, NULL)
!= 0)//submit the buffer area szRecBuf1 to the driver and start the recording
in pingpong buffer mode
{
SsmGetLastErrMsg(szErrMsg);
cout<<szErrMsg<<endl;
return FALSE;
}
if(SsmRecordMemBlock(nCh, 6, szRecBuf2, dwBufSize, RecordMemBlockHandler, NULL)
!= 0)//submit the buffer area szRecBuf2 to the driver
{
SsmGetLastErrMsg(szErrMsg);
cout<<szErrMsg<<endl;
return FALSE;
}
return TRUE;
}
BOOL RecordMemBlockHandler(int ch, int nEndReason, PUCHAR pucBuf, DWORD
dwStopOffset, PVOID pV)
{
int
nResult = 0;
if(pucBuf
== szRecBuf1)
{
......//save
the data within szRecBuf1
nResult = SsmRecordMemBlock(ch, 6, szRecBuf1, dwBufSize, RecordMemBlockHandler,
pV);)//submit the buffer area szRecBuf1 to the driver
}
else if(pucBuf == szRecBuf2)
{
......//save
the data within szRecBuf2
nResult = SsmRecordMemBlock(ch, 6, szRecBuf2, dwBufSize, RecordMemBlockHandler,
pV);// submit the buffer area szRecBuf2 to the driver
}
return nResult;
}

Related Information:

Driver version | SynCTI Ver. 3.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmStopRecordMemBlock, SsmRecToMem


2.10.5.2 SsmStopRecordMemBlock

Terminates the Pingpong buffer recording.

Format:

int SsmStopRecordMemBlock (int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Terminates the Pingpong buffer recording.

Note:

l This function can’t be called in the callback function which is set by SsmRecordMemBlock;

l When the recording is terminated, the driver throws out the event E_PROC_RecordEnd.

Related Information:

Driver version | SynCTI Ver. 3.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmRecordMemBlock


2.11 TDM Functions


2.11.1 Functions for Two-way Connection (CTI Series)


2.11.1.1 Establishing Two-way Connection


2.11.1.1.1 SsmTalkWith

Refer to SsmTalkWithEx


2.11.1.1.2 SsmTalkWithEx

Establishes the two-way connection between two channels. The function SsmTalkWithEx is able to set the volume on the two voice exchanging channels.

Format:

int SsmTalkWith(int ch1,int ch2)

int SsmTalkWithEx(int ch1, int nVlm1, int ch2, int nVlm2)

Parameter Description:

ch1 | Channel Number1
ch2 | Channel Number2
nVlm1 | The volume of ch1, range of value: -7~+6. If negative, means volume decreasing; If positive, means volume increasing. The default value is 0. This value multiplied by 3 equals to the dB value.
nVlm2 | The volume of ch2, range of value: -7~+6, . If negative, means volume decreasing; If positive, means volume increasing. The default value is 0. This value multiplied by 3 equals to the dB value.

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Establishes the two-way connection between the designated channel ch1 and ch2, i.e. ch1 can listen from ch2, ch2 can also listen from ch1. If the incoming call signal from ch1 or ch2 has not been put onto the TDM bus, the driver will automatically arrange a time slot and put the incoming call signal onto this time slot.

Note:

l This function is only applicable to SHT/SHD/SHN Series boards, the parameters nVlm1 and nVlm2 are used to set volume adjusters A4-1…A4-6 in ‘Operation Principle of SHT Series’ or ‘Operation Principle of SHD Series’ or ‘Operation Principle of SHN Series’ in Chapter 1. The gains of A4-1…A4-6 can also be set by the configuration item DefaultSpeakVolume, with the default value of 0DB;

l If the model name of the board doesn’t include ‘-CT’, ch1 and ch2 must be on the same board, otherwise, this function will fail;

l For disconnection, use the function SsmStopTalkWith and make sure that the operations connect and disconnect appear at the same time, corresponding to each other.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmStopTalkWith, SsmListenTo, SsmListenToEx, SsmLinkFrom, SsmLinkFromEx


2.11.1.2 Tearing off Two-way Connection


2.11.1.2.1 SsmStopTalkWith

Tears off the two-way connection between two channels.

Format:

int SsmStopTalkWith(int ch1,int ch2)

Parameter Description:

ch1 | Listener/talker channel number
ch2 | Talker/listener channel number

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Tears off the two-way connection between ch1 and ch2.

Note:

l This function is only applicable to SHT/SHD/SHN Series boards

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmTalkWith, SsmTalkWithEx


2.11.2 Functions for One-way Connection


2.11.2.1 Establishing One-way Connection


2.11.2.1.1 SsmListenTo

Refer to SsmLinkFromAllCh


2.11.2.1.2 SsmListenToEx

Refer to SsmLinkFromAllCh


2.11.2.1.3 SsmLinkFrom

Refer to SsmLinkFromAllCh


2.11.2.1.4 SsmLinkFromEx

Refer to SsmLinkFromAllCh


2.11.2.1.5 SsmLinkFromAllCh

Establishes the one-way connection from the talker channel to the listener channel. Using the function SsmListenTo and SsmListenToEx to establish the one-way connection between two channels, and one channel can listen to only one channel. Using the function SsmLinkFrom and SsmLinkFromEx to establish the one-way connection between two channels, and one channel can listen to multiple channels. The function SsmListenToEx and SsmLinkFromEx may also set the volume of the one-way connection. The function SsmLinkFromAllCh may establish the one-way connection from one talker channel to multiple listener channels.

Format:

int SsmListenTo(int nSourceCh, int nListeningCh)

int SsmListenToEx(int nSourceCh, int nVolume, int nListeningCh)

int SsmLinkFrom(int nSourceCh, int nListeningCh)

int SsmLinkFromEx(int nSourceCh, int nVolume, int nListeningCh)

int SsmLinkFromAllCh(int nSourceCh, int nVolume, int* pnListenerTable,int nListenerNum)

Parameter Description:

nSourceCh

Talker channel number

nListeningCh

Listener channel number

Note: if nListeningCh is the channel 0 of ATP or DST Series boards, the voice of the talker will be sent to the on-board speaker port

nVolume

The volume of the talker, range of value: -7~+6, positive means increasing; negative means decreasing, with the default value of 0. This value multiplied by 3 equals to the dB value.

nVolume is used to set the volume of incoming signals which pass the TDM bus and go down to the off-bus mixer M2 of another channel. The gains of A4-1…A4-6 may also be set by the configuration item DefaultSpeakVolume, with the default value of 0DB.

pnListenerTable

The pointer pointing to the table of listener channels, the storage space is allocated by the application. The listener channels must be stored consecutively

nListenerNum

The number of listener channels in pnListenerTable

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Establishes the one-way connection from the talker channel to the listener channel, i.e. nListeningCh listens to the voice from nSourceCh , but nSourceCh is not able to hear the voice from nListeningCh.

Apart from having all the features of the function SsmListenTo, the function SsmListenToEx may also set the volume during connection. During the one-way connection established by the function SsmListenTo and SsmListenToEx, one channel can only listen to one at the same moment. For the connection established by the function SsmListenTo and SsmListenToEx, it needs to be torn off by the function SsmStopListenTo, and also, the operations of establishing/ tearing off the connection must be in pairs, one to one.

Apart from having all the features of the function SsmListenTo, the function SsmLinkFromEx may also set the volume during connection. For the one-way connection established by the function SsmLinkFrom and SsmLinkFromEx, it needs to be torn off by the function SsmStopListenTo, and also, the operations of establishing/ tearing off the connection must be in pairs, one to one.

SsmLinkFromAllCh may create the one-way connection from one talker channel to multiple listener channels all in once, which is the same as calling SsmLinkFromEx on multiple listener channels continuously. For the one-way connection established by the function SsmLinkFromAllCh, it needs to be torn off by the function SsmUnLinkFromAllCh, and also, the operations of establishing/ tearing off the connection must be in pairs, one to one.

The function SsmLinkFrom, SsmLinkFromEx and SsmLinkFromAllCh allow one channel to listen to the voices from multiple talker channels. The voices from the talker channels are sent to the conference mixer of the listener channel, the mixed voice is sent to the listener as the outgoing call signal.

Note:

l If the model name of the board doesn’t include ‘-CT’, channel nSourceCh and nListeningCh must be on the same board, otherwise the function will fail;

l For the SHT/SHD/SHN Series boards, because the off-bus mixer M2 has 6 input signal sources A4-1~A4-6, each channel may at most listen the voices from 6 channels simultaneously, i.e. one channel may invoke the function SsmLinkFrom and SsmLinkFromEx at most 6 times. For more information, refer to ‘Operation Principle of SHT Series’ or ‘Operation Principle of SHD Series’ or ‘Operation Principle of SHN Series’ in Chapter 1.

Related Information:

Driver version | SynCTI Ver. 3.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SmStopListenTo, SsmStopLinkFrom, SsmUnLinkFromAllCh, SsmTalkWith, SsmTalkWithEx

Sample code:

This sample code implements the following features:

ü Channel 0 listens the voice from channel 5;

ü Channel 1 listens the voice from channel 6 (the volume is increased by 6 units);

ü Channel 2 wants to listen the voices from channel 9, channel 10, and channel 11 simultaneously;

ü Channel 3 wants to listen to channel 9 (normal volume), channel 10 ( the volume is decreased by 1 unit),

and channel 11 (the volume is increased by 2 units) simultaneously ;

ü The voice from channel 4 needs to be listened simultaneously by channel 12, 13 and 14 (defaulted volume).

Code Implementation:

SsmListenTo( 5,0); // Establishes connection for the listener channel 0

SsmListenToEx( 6,6,1); // Establishes connection for the listener channel 1

SsmLinkFrom( 9,2); // Establishes connection for the listener channel 2

SsmLinkFrom(10,2);

SsmLinkFrom(11,2);

SsmLinkFromEx( 9, 0,3); // Establishes connection for the listener channel 3

SsmLinkFromEx(10,-1,3);

SsmLinkFromEx(11, 2,3);

int ListenerChList[3]={12,13,14}; // Establishes the one-way connections from the talker channel 4 to the listener

// channel 12,13 and 14

SsmLinkFromAllCh(4,0,ListenerChList,3);

...... // Other operations of the application

SmStopListenTo( 5,0); // Tears off the connection for the listener channel 0

SmStopListenTo( 6,1); // Tears off the connection for the listener channel 0

SsmStopLinkFrom( 9,2); // Tears off the connection for the listener channel 1

SsmStopLinkFrom(10,2);

SsmStopLinkFrom(11,2);

SsmStopLinkFrom( 9,3); // Tears off the connection for the listener channel 2

SsmStopLinkFrom(10,3);

SsmStopLinkFrom(11,3);

SsmLinkFromAllCh(4,ListenerChList,3);// Tears off the one-way connection from channel 4 to listener channel 12, 13 and 14.


2.11.2.2 Tearing off One-way Connection


2.11.2.2.1 SsmStopListenTo

Refer to SsmUnLinkFromAllCh


2.11.2.2.2 SsmStopLinkFrom

Refer to SsmUnLinkFromAllCh


2.11.2.2.3 SsmUnLinkFromAllCh

Tears off the one-way connection from the talker channel to the listener channel. The function SsmStopListenTo is used tear off the one-way connection established by the function SsmListenTo or SsmListenToEx, the function SsmStopLinkFrom is used to tear off the one-way connection established by SsmLinkFrom or SsmLinkFromEx, the function SsmUnLinkFromAllCh is used to tear off the one-way connection established by SsmLinkFromAllCh.

Format:

int SsmStopListenTo(int nSourceCh,int nListeningCh)

int SsmStopLinkFrom(int nSourceCh,int nListeningCh)

int SsmUnLinkFromAllCh (int nSourceCh, int* pnListenerTable,int nListenerNum)

Parameter Description:

nSourceCh | Talker channel number
nListeningCh | Listener channel number
pnListenerTable | The pointer pointing to the table of listener channels, the storage space is allocated by the application. The listener channels must be stored consecutively
nListenerNum | The number of the listener channels in the table of pnListenerTable

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Tears off the one-way connection from the talker channel to the listener channel.

Note:

l The functions of establishing/tearing off one-way connection must be in pairs.

Related Information:

Driver version | SynCTI Ver. 3.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmListenTo, SsmListenToEx, SsmLinkFrom, SsmLinkFromEx, SsmLinkFromAllCh


2.11.3 Obtaining Bus Information


2.11.3.1 SsmGetChBusInfo

Gets bus information for Channel ch.

Format:

int WINAPI SsmGetChBusInfo(int ch, PBUS_OP* p)

Parameter Description:

ch | Channel number
p | Bus structure pointer

Return Value:

-1 | The channel not connected via bus
>=0 | The number of the channel connected to Channel ch via bus

Function Description:

Obtains the relative bus parameters for Channel ch.

Bus Structure

{ BOOL bEnHwOpBus; Bus switch

BOOL bEnHwOpSetLinkFromVlm; Volume control switch for bus connection

int nST; Bit stream used by defualt for bus connection

int nTs; Time slot specified by default for bus connection

int nToBusCh; Total number of time slots used by default for bus connection

int nPlayST; Bit stream used by default for the recording module to put voices onto bus

int nPlayTs; Time slot connected by default for the recording module to put voices onto bus

int nPlayToBusCh; Total number of time slots used by default for the recording module to put voices onto bus

int nSpeakerVlm; Volume

int nTotListener; Total number of listeners in the teleconference

int * pnListenerCh; Total number of participants in the teleconference

int nFromSpeaker; Total number of speakers in the teleconference

int nDefaultSpeakerVlm; } Volume for bus connection

This bus structure is defined by the driver itself and some of the parameters are senseless to the application layer. Therefore users may not pay much attention to it.

Note:

l The function declaration can be found in the file STBUS.h.

Related Information:

Driver version | SynCTI Ver.3.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function:


2.11.4 Advanced Functions for Bus Operation (CTI Series)


2.11.4.1 Forcibly Tearing off All Bus Connections to Channel


2.11.4.1.1 SsmClearChBusLink

Tears off all the TDM bus connections established on the channel, recovers the channel to be in the TDM bus connection state when the driver finishes the initialization.

Format:

int SsmClearChBusLink(int nCh)

Parameter Description:

nCh

The monitor channel number

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Tears off all the TDM bus connections which are established on the channel nCh by invoking any of the functions such as below:

Ø SsmListenTo, SsmListenToEx, SsmLinkFrom, SsmLinkFromEx, SsmLinkFromAllCh

Ø SsmTalkWith, SsmTalkWithEx

Ø SsmLinkFromBus, SsmLinkFromBusEx

Recovers the channel to be in the TDM bus connection state when the driver finishes the initialization.

Note:

l If the channel has entered a conference room, its TDM bus connections will also be torn off forcibly.

Related Information:

Driver version | SynCTI Ver.4.5.6.2 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function:


2.11.4.2 One-way Connection from Channel to Bus Time Slot


2.11.4.2.1 SsmLinkToBus

Changes the bus time slot to which the output signal of the onto-bus mixer is transmitted

Format:

int SsmLinkToBus(int ch, int ts)

Parameter Description:

ch | Channel Number
ts | The number of the usable TDM-bus common time slot, range of value: N~4095, N is twice of the total amount of the channels in the system. For more information about the number of the usable common time slot, refer to ‘TDM Capability’ in Chapter 1

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

During the board initialization, the output signal of the onto-bus mixer on channel ch has already been connected with one common time slot (suppose it is ts0). This function reconnects output signals with time slots.

Call the function SsmUnLinkToBus to tear down the connection.

Note:

l The time slot ts must be an unused common time slot;

l This function must be used with SsmUnLinkToBus, otherwise, it may cause garbled signals;

l This function is a bottom function which is only applicable to the situation where Synway boards are interoperated with third party boards.

l The configuration item EnableCommonTimeSlot can be used to open all the common time slots on the TDM bus.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmUnLinkToBus, SsmLinkFromBus, SsmLinkFromBusEx


2.11.4.2.2 SsmUnLinkToBus

Recovers the output signals of the onto-bus mixer to be connected with the defaulted bus time slot.

Format:

int SsmUnLinkToBus(int ch, int ts)

Parameter Description:

ch | Channel Number
ts | The number of the time slot

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Tears down the one-way connection from the channel ch to the bus time slot ts, and recovers the output signals of the onto-bus mixer to be connected with the defaulted bus time slot.

Note:

l This function must be called along with SsmLinkToBus in pairs, otherwise, it may cause garbled signals.

l This function is a bottom function which is only applicable to the situation that Synway’s boards needs to interoperate with 3rd party’s boards.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmLinkToBus


2.11.4.3 One-way Connection from Bus Time Slot to Channel


2.11.4.3.1 SsmLinkFromBus

Refer to SsmLinkFromBusEx


2.11.4.3.2 SsmLinkFromBusEx

Establishes the one-way connection from the bus time slot to the listener channel. Apart from having all the features of the function SsmLinkFromBus, SsmLinkFromBusEx can also set the volume.

Format:

int SsmLinkFromBus(int ts, int ch)

int SsmLinkFromBusEx(int ts, int ch, int nVolume)

Parameter Description:

ch | Channel Number
ts | The number of the time slot
nVolume | The volume of the voice data on the time slot ts when it is transmitting to channel ch, range of value: -6~+6, the negative value means volume decreasing, the positive value means the volume increasing , this parameter multiplied by 3 equals dB value

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Establishes the one-way connection from the bus time slot ts to the listener channel ch.

Note:

l The function SsmLinkFromBus or SsmLinkFromBusEx must be called along with SsmUnLinkFromBus in pairs, otherwise, it may cause garbled signals.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmLinkToBus, SsmUnLinkFromBus


2.11.4.3.3 SsmUnLinkFromBus

Tears down the one-way connection from the bus time slot to the listener channel.

Format:

int SsmUnLinkFromBus(int ts, int ch)

Parameter Description:

ch | Channel Number
ts | Time slot number

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Tears off the one-way connection from the time slot ts to the listener channel ch.

Note:

l The function SsmLinkFromBus or SsmLinkFromBusEx must be called along with SsmUnLinkFromBus in pairs, otherwise, it may cause garbled signals.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmLinkFromBus, SsmLinkFromBusEx


2.11.4.3.4 SsmListenToPlay

Enables a channel to monitor another recording channel.

Format:

int WINAPI SsmListenToPlay(int ch1, int vlm, int ch2)

Parameter Description:

ch1 | The monitor channel number
ch2 | The number of the monitored channel which is required to be a recording channel
vlm | The volume of voices played on the monitored channel

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Enable Channel ch1 to monitor Channel ch2.

Note:

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmUnListenToPlay


2.11.4.3.5 SsmUnListenToPlay

Stops the monitoring of a recording channel.

Format:

int WINAPI SsmUnListenToPlay(int ch1, int ch2)

Parameter Description:

ch1 | The monitor channel number
ch2 | The number of the monitored channel which is required to be a recording channel

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Stops Channel ch1 from monitoring Channel ch2.

Note:

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmListenToPlay


2.12 On-board Audio Power Amplifier Functions


2.12.1 SsmQueryOpPowerAmp

Enquires whether the channel is equipped with on-board audio amplifier circuit.

Format:

int SsmQueryOpPowerAmp(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Call failed
0 | Not equipped with on-board audio amplifier circuit
1 | Equipped with on-board audio amplifier circuit

Function Description:

Enquires whether the channel is equipped with on-board audio amplifier circuit. For detailed information about the on-board audio power amplifier, see the operation principle of the corresponding board.

Note:

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSetPowerAmpVlm, SetVolume


2.12.2 SsmSetPowerAmpVlm

Refer to SetVolume


2.12.3 SetVolume

Sets the gain of the on-board audio power amplifier. SetVolume is an early version function. SsmSetPowerAmpVlm is recommended to be used.

Format:

void SsmSetPowerAmpVlm(int ch, int nGain)

void SetVolume(DWORD dwBoardId, DWORD nGain)

Parameter Description:

ch | Channel Number. Note: the internal number of the board corresponding to channel number ch must be 0, otherwise, the function will fail
dwBoardId | The board ID number
nGain | The gain of the power amplifier, range of value: 0~7, in which: 7: 0DB 6~1: -6×nGain DB 0: Completely turned off Default value is 3(-18DB)

Return Value: None

Function Description:

Sets the gain of the on-board audio power amplifier. For detailed information about the on-board audio power amplifier, see the operation principle of the corresponding board.

Note:

l The channel 0 of only ATP Series, SHT Series or DST Series boards is equipped with the on-board audio power amplifier.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmQueryOpPowerAmp


2.13 On-board Speaker Functions


2.13.1 SsmSetLine0OutTo

Turns on/ turns off the internal on-board speaker of the USB recording box/ voice box.

Format:

int SsmSetLine0OutTo(BOOL bEnable)

Parameter Description:

bEnable

=FALSE: sends the voice to the on-board speaker to be played;

=TRUE: sends the voice to the on-board speaker jack, the voice is played by the external speaker

Return Value:

-1 | Call failed
0 | Successful

Function Description:

Turns on or turns off the internal on-board speaker of the USB recording box/voice box. For more information, refer to ‘Operation Principle of ATP Series’ or ‘Operation Principle of SHT Series’.

Note:

l This function is only applicable to ATP Series USB recording box and SHT Series USB box.

l The configuration item USBLine0Output may also complete the same features.

Related Information:

Driver version | SynCTI Ver. 4.7.1.7 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSetPowerAmpVlm


2.14 Echo Canceller Functions (CTI Series)


2.14.1 Setting Operating Status of Echo Canceller


2.14.1.1 SsmQueryOpEchoCanceller

Checks whether the channel supports echo cancellation.

Format:

int SsmQueryOpEchoCanceller(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Call failed
0 | Not supported
1 | Supported

Function Description:

Checks whether the channel supports echo cancellation.

Note:

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function:


2.14.1.2 SsmSetEchoCanceller

Sets the operating mode of the echo canceller.

Format:

int SsmSetEchoCanceller(int ch, BOOL bEnable)

Parameter Description:

ch | Channel Number
bEnable | TRUE: enabled FALSE: disabled

Return Value:

-1 | Call failed
0 | Successful

Function Description:

Sets the operating mode of the echo canceller.

Note:

l The configuration item EnableEchoCancellor may complete the same features, with the default value of enabled.

l For more information, refer to Echo Canceller in Chapter 1.

l This function only supports SHD, SHT Series boards.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetEchoCancellerState


2.14.1.3 SsmGetEchoCancellerState

Obtains the operating mode of the echo canceller.

Format:

int SsmGetEchoCancellerState(int ch)

Parameter Description:

ch

Channel number

Return Value:

-1 | Call failed
0 | Turned off
1 | Turned on

Function Description:

Obtains the operating mode of the echo canceller.

Note:

l This function only supports SHD Series and SHT Series boards.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSetEchoCanceller


2.14.2 Setting Parameters of Echo Canceller


2.14.2.1 SsmSetEchoCancelDelaySize

Sets the filtering delay parameter of the echo canceller.

Format:

int SsmSetEchoCancelDelaySize(int ch,WORD wSize)

Parameter Description:

ch | Channel number
wSize | The filtering delay parameter, range of value: 0~31

Return Value:

-1 | Call failed
0 | Successful

Function Description:

Sets the filtering delay parameter of the echo canceller.

Note:

l This function only supports SHD Series and SHT Series boards;

l The configuration item EchoCancelDelaySize may also complete the same features.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetEchoCancelDelaySize


2.14.2.2 SsmGetEchoCancelDelaySize

Obtains the filtering delay parameter of the echo canceller.

Format:

int SsmGetEchoCancelDelaySize(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Call failed
³0 | The filtering delay parameter

Function Description:

Obtains the filtering delay parameter of the echo canceller.

Note:

l This function only supports SHD Series and SHT Series boards.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSetEchoCancelDelaySize


2.15 Teleconferencing Functions (CTI Series)


2.15.1 Initializing Conference Room


2.15.1.1 SsmCreateConfGroup

Creates a conference room.

Format:

int SsmCreateConfGroup(int nMaxMember, int nMaxSpeaker, int nMaxSpeaking, int nMaxSilenceTime)

Parameter Description:

nMaxMember | The maximum channel number in a conference room, range of value: -1: Use the parameter specified in the configuration item ConfDefaultMaxGroupMember 3~N: N is the total channel number in the application
nMaxSpeaker | Sets the maximum number of conference channels which have speaking rights. All of the speaking modes such as the organizer, chairman and dynamic speaker have speaking rights. It’s determined by the set value of the configuration item BackgroundVoicePriority whether the speaking mode of background music has the speaking right. The range of value: -1: Use the parameter designated by the configuration item ConfDefaultMaxGroupSpeaker ≥1: The total number of conference channels
nMaxSpeaking | The number of the permitted maximum concurrent speaking members, range of value: -1: Use the parameter designated by the configuration item ConfDefaultMaxGroupSpeaking ; 1~6: The set value
nMaxSilenceTime | Maximum silence time. Range of value: -1: Use the parameter designated by the configuration item ConfDefaultMaxSilenceTime ³1: The set value (seconds) For more information, refer to ‘ Distributed Teleconferencing System ’. Note: Now this parameter has been invalid. Just set it to -1.

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
≥0 | The ID number of the newly-created conference room

Function Description:

Creates a conference room.

Note: None

Related Information:

Driver version | SynCTI Ver. 3.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmFreeConfGroup , SsmJoinConfGroup , SsmGetConfGrpInfo , SsmGetConfGrpCfgInfo


2.15.1.2 SsmFreeConfGroup

Cancels a conference room.

Format:

int SsmFreeConfGroup(int nGrpId)

Parameter Description:

nGrpId

The ID number of the conference room

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Cancels a conference room, frees the allocated resources for the conference room.

Note:

l If there are still channels which don’t leave the conference room, the driver will automatically invoke the function SsmExitConfGroup to drive it out of the conference room.

Related Information:

Driver version | SynCTI Ver. 3.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmCreateConfGroup


2.15.2 Setting Conference Member’s Behavior


2.15.2.1 SsmJoinConfGroup

Adds the channel into the conference room.

Format:

int SsmJoinConfGroup(int nGrpId, int ch, WORD wJoinMode, int nMixerVolume, BOOL bCreateAlways, BOOL bExitGrpAlways)

Parameter Description:

nGrpId

Conference number

ch

Channel Number

wJoinMode

The speaking mode of the channel, range of value:

0: Organizer;

1: Dynamic Speaker;

2: Listener;

3: Background Music;

In this mode, that if the channel can hear voices from other channels is determined by the configuration item PlayVoiceIsListen: when PlayVoiceIsListen＝0, the channel can speak, but not hear sounds from other channels, usually for playing music to a conference; when PlayVoiceIsListen＝1, the channel can not only speak but also hear sounds from other channels (default setting).

4: Chairman;

5: Dynamic Speaker ONLY

For more information about the speaking mode and conference scheduling, refer to ‘ Distributed Teleconferencing System ’

nMixerVolume

The volume of the current channel’s incoming call signal before it enters the off-bus mixer M2 of other conference member, range of value: -6~+6. Values greater than 0 mean volume increasing, while values less than 0 mean volume decreasing. This parameter multiplied by 3 equals dB value. This volume is just the volume of speaking heard by other members in the conference.

bCreateAlways

When this function is called, if the conference room designated by the parameter nGrpId is not created, this parameter indicates whether to automatically create a new conference room by the driver using nGrpId as the conference ID.

TRUE: yes

FALSE: no, call failed

bExitGrpAlways

If this channel has already joined in the other conference room, this parameter indicates whether to automatically delete this channel from that conference room by the driver

TRUE: yes

FALSE: no, call failed

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Adds the channel into the conference room.

Note: none

Related Information:

Driver version | SynCTI Ver. 3.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmExitConfGroup , SsmSetListenVlmInConf


2.15.2.2 SsmExitConfGroup

Deletes the channel from the conference room.

Format:

int SsmExitConfGroup(int ch, BOOL bFreeGrpAlways)

Parameter Description:

ch | Channel Number
bFreeGrpAlways | If there only exists this channel in the conference room, this parameter indicates whether to automatically cancel the conference room by the driver: TRUE: Cancel; FALSE: Not cancel

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Deletes the channel from the conference room.

Related Information:

Driver version | SynCTI Ver. 3.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmJoinConfGroup


2.15.2.3 SsmSetListenVlmInConf

Sets the volume adjuster which is used for off-bus signals before they are sent to M2 (off-bus mixer).

Format:

int SsmSetListenVlmInConf(int ch, int nVlm)

Parameter Description:

ch | Channel number
nVlm | Volume of the voice when it’s taken off the bus, with the value range of about -7~6.

Return Value:

0 | Successful
-1 | Call failed

Function Description:

Sets the volume adjuster which is used for off-bus signals before they are sent to M2 (off-bus mixer), i.e. sets the volume adjuster A4-1…A4-6 in ‘ Operation Principle of SHT Series ’ or ‘ Operation Principle of SHD Series ’ or ‘ Operation Principle of SHN Series ’ in Chapter 1. This function can adjust only the volume heard by the current channel, but not by other members in the conference.

Note: none

Related Information:

Driver version | SynCTI Ver. 3.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmJoinConfGroup


2.15.2.4 SsmSetContactInConf

Masks a channel from hearing another channel in a teleconference.

Format:

int SsmSetContactInConf(int nGrpID, int chFrom, int chTo, BOOL bFlag)

Parameter Description:

nGrpID | Conference number
chFrom | Number of the channel where voices come from
chTo | Number of the channel where voices go to
bFlag | TRUE: Channel chTo is masked from hearing voices on Channel chFrom in a teleconference; FALSE: Channel chTo is required to hear voices on Channel chFrom in a teleconference.

Return Value:

-1 | This function unsupported
0 | Function call failed
1 | Function call successful

Function Description:

Masks a channel from hearing another channel in a teleconference.

Note:

l A channel only can be masked from hearing voices on another one channel. For example, when Channel A is masked from hearing Channel B, it can’t be masked from Channel C any more unless its masking from Channel B is stopped first.

Related Information:

Driver version | SynCTI Ver. 3.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: None


2.15.3 Obtaining Conference Room Information


2.15.3.1 SsmGetConfCfgInfo

Obtains the configuration parameters of the distributed teleconferencing.

Format:

int SsmGetConfCfgInfo(PWORD pwMaxMember, PWORD pwMaxSpeaker, PWORD pwMaxSpeaking, PWORD pwMaxSilenceTime)

Parameter Description:

pwMaxMember | Returns the set value of the configuration item ConfDefaultMaxGroupMember
pwMaxSpeaker | Returns the set value of the configuration item ConfDefaultMaxGroupSpeaker
pwMaxSpeaking | Returns the set value of the configuration item ConfDefaultMaxGroupSpeaking
pwMaxSilenceTime | Returns the set value of the configuration item ConfDefaultMaxSilenceTime

Return Value:

-1 | Call failed
≥0 | Returns the set value of the configuration item ConfMaxGroup

Function Description:

Obtains the configuration parameters of the distributed teleconferencing.

Note: none

Related Information:

Driver version | SynCTI Ver. 3.0or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetConfGrpInfo


2.15.3.2 SsmGetTotalConfGroup

Obtains the actual number of the conference rooms.

Format:

int SsmGetTotalConfGroup()

Parameter Description: none

Return Value:

-1 | Call failed
≥0 | The actual number of the conference rooms

Function Description:

Obtains the actual number of the conference rooms.

Note: none

Related Information:

Driver version | SynCTI Ver. 3.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetConfGrpId


2.15.3.3 SsmGetConfGrpCfgInfo

Obtains the set values of the operational parameters of the conference room.

Format:

int SsmGetConfGrpCfgInfo(int nGrpId, PWORD pwMaxMember, PWORD pwMaxSpeaker, PWORD pwMaxSpeaking, PWORD pwMaxSilenceTime)

Parameter Description:

nGrpId | Conference room ID
pwMaxMember | Returns the total number of the conference channels
pwMaxSpeaker | Returns the total number of the conference channels which have speaking rights
pwMaxSpeaking | Returns the total number of conference channels which are permitted to speak concurrently
pwMaxSilenceTime | Returns the maximum silence time (seconds) of the conference channel

Return Value:

-1 | Call failed
0 | Successful

Function Description:

Obtains the set values of the operational parameters of the conference room, i.e. the set values when the application creates the conference room by invoking the function SsmCreateConfGroup .

Note: none

Related Information:

Driver version | SynCTI Ver. 3.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetConfCfgInfo


2.15.3.4 SsmGetConfGrpInfo

Obtains the statistic information of the conference room.

Format:

int SsmGetConfGrpInfo(int nGrpId, PWORD pwTotalMember, PWORD pwTotalSpeaker, PWORD pwTotalSpeaking)

Parameter Description:

nGrpId | Conference room number
pwTotalMember | Returns the actual number of the channels joining in the conference
pwTotalSpeaker | Returns the actual number of the channels with speaking rights in the conference room
pwTotalSpeaking | Returns the actual number of the conference channels currently using the conference mixer

Return Value:

-1 | Call failed
0 | Successful

Function Description:

Obtains the statistic information of the conference room.

Note: none

Related Information:

Driver version | SynCTI Ver. 3.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetConfCfgInfo


2.15.3.5 SsmGetConfGrpId

Obtains the ID list for all the conference rooms.

Format:

int SsmGetConfGrpId(int* pnGrpId)

Parameter Description:

pnGrpId

Returns the pointer pointing to the array containing all the conference room IDs

Return Value:

-1 | Call failed
0 | Successful

Function Description:

Obtains the ID list for all the conference rooms.

Note: none

Related Information:

Driver version | SynCTI Ver. 3.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmValidateGrpId


2.15.3.6 SsmValidateGrpId

Enquires whether the conference room has been created.

Format:

int SsmValidateGrpId(int nGrpId)

Parameter Description:

nGrpId

Conference room number

Return Value:

1 | The conference room is already created
0 | Not created

Function Description:

Enquires whether the conference room is created.

Note: None

Related Information:

Driver version | SynCTI Ver. 3.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetConfGrpId


2.15.4 Obtaining Conference Member Information


2.15.4.1 SsmGetConfGrpMmbrId

Obtains the channel numbers of the channels which have joined in the conference room.

Format:

int SsmGetConfGrpMmbrId(int nGrpId, int* pnMmbrId)

Parameter Description:

nGrpId | Conference room ID
pnMmbrId | Returns the pointer pointing to an array containing the conference channel numbers

Return Value:

-1 | Call failed
0 | Successful

Function Description:

Obtains the channel numbers of the channels which have joined in the conference room.

Note: none

Related Information:

Driver version | SynCTI Ver. 3.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetConfGrpMmbrInfo


2.15.4.2 SsmGetConfGrpMmbrInfo

Obtains the detailed information about the conference channel in the conference room.

Format:

int SsmGetConfGrpMmbrInfo(int nGrpId, int nMmbrId, int* pnAppCh, PWORD pwJoinMode, PWORD pwIsSpeaking, PDWORD pdwSilenceTime)

Parameter Description:

nGrpId | Conference room number
nMmbrId | Conference channel number
pnAppCh | Returns the logical channel number corresponding to the conference channel number
pwJoinMode | Returns the speaking mode of the conference channel
pwIsSpeaking | Returns whether the conference channel is speaking
pdwSilenceTime | Returns the silence time (seconds) of the conference channel

Return Value:

-1 | Call failed
0 | Successful

Function Description:

Based on the conference room number and conference channel number, obtains the detailed information about the conference channel in the conference room.

Note: none

Related Information:

Driver version | SynCTI Ver. 3.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetConfChInfo


2.15.4.3 SsmGetConfChInfo

Enquires whether the channel has joined in one certain conference room.

Format:

int SsmGetConfChInfo(int ch, int* pnGrpId, int* pnMmbrId, PWORD pwJoinMode, PWORD pwIsSpeaking, PDWORD pdwSilenceTime)

Parameter Description:

ch | Channel Number
pnGrpId | Returns the conference room number
pnMmbrId | Returns the member ID of Channel ch in the conference room
pwJoinMode | Returns the speaking mode of Channel ch when it joins in the conference room
pwIsSpeaking | Returns the sign indicating whether Channel ch is speaking or not. pwIsSpeaking=1: Speaking; pwIsSpeaking=0: Not speaking.
pdwSilenceTime | Returns the silence time (seconds) of Channel ch

Return Value:

-1 | Call failed
0 | Successful

Function Description:

Enquires whether the channel has joined in one certain conference room.

Note: none

Related Information:

Driver version | SynCTI Ver. 3.0or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetConfGrpMmbrInfo


2.16 FSK Transceiver Functions (CTI Series)


2.16.1 FSK Transmitter


2.16.1.1 SsmSetFskPara

Sets the operational parameters of the FSK Transmitter.

Format:

int SsmSetFskPara(int nFreq0, int nFreq1, int nBaudrate, int nMdlAmp)

Parameter Description:

nFreq0 | The carrier frequency (Hz) of bit 0, range of value: 300~3400. This parameter may also be set by the configuration item FreqBit0 . The default value is 2200Hz
nFreq1 | The carrier frequency (Hz) of bit 1, range of value: 300~3400. This parameter may also be set by the configuration item FreqBit1 . The default value is 1200Hz
nBaudrate | Baud rate (bps), range of value: 300~2400. This parameter may also be set by the configuration item Baudrate , with the default value of 1200bps
nMdlAmp | Modulation Amplitude, range of value: 0~255. This parameter may also be set by the configuration item MdlAmp , with the default value of 128

Return Value:

-1 | Call failed
0 | Successful

Function Description:

Sets the operational parameters of the FSK Transmitter.

Note:

l If Synway boards are used at the reception end, normally the defaulted values of the corresponding configuration items can be used with no need for further configuration.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetFskPara


2.16.1.2 SsmGetFskPara

Obtains the operational parameters of the FSK Transmitter.

Format:

int SsmGetFskPara(int *nFreqBit0, int *nFreqBit1, int *nBaudrate, int *nMdlAmp)

Parameter Description:

nFreqBit0 | Returns the carrier frequency (Hz) of bit 0
nFreqBit1 | Returns the carrier frequency (Hz) of bit 1
nBaudrate | Returns the baud rate (bps) of the binary code stream
nMdlAmp | Returns the amplitude of the modulated signal

Return Value:

-1 | Call failed
0 | Successful

Function Description:

Obtains the operational parameters of the FSK Transmitter.

Note:

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSetFskPara


2.16.1.3 SsmTransFskData

Converts the data to be BFSK-formatted binary data stream.

Format:

int SsmTransFskData(unsigned char* pSrc, int nSrcLen,int nSyncLen,int nSyncOffLen,unsigned char* pStream)

Parameter Description:

pSrc | Pointer pointing to the buffer area storing the data
nSrcLen | The data length (bytes) in pSrc
nSyncLen | The bit number of the synchronization code, normally its integral times of 8. It’s determined based on the real needs and recommended to be set 96
nSyncOffLen | The bit number of the identification code, normally its integral times of 8. It’s determined based on the real needs and recommended to be set 32
pStream | Pointer pointing to the buffer area storing the converted BFSK data stream. Its space is allocated by the application, it’s size can be calculated by the following formula: (nSyncLen + nSyncOffLen + nSrcLen×10 ) / 8 + 1

Return Value:

-1 | Call failed
≥0 | The actual bit number in pStream

Function Description:

Converts the data to be BFSK-formatted binary data stream. For more information about the format of the BFSK data stream, refer to ‘ FSK Transceiver ’ in Chapter 1.

Note:

l In some protocols the flag code is called ‘synchronization end character’, and it is together with the syn code called ‘synchronization indicator string’ which verifies the synchronization has been established. In this function, we use nSyncLen to represent the syn code and nSyncOffLen to indicate the flag code.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmStartSendFSK


2.16.1.4 SsmStartSendFSK

Starts the FSK transmitter.

Format:

int SsmStartSendFSK(int ch, LPSTR pStream, DWORD dwMaxBit)

Parameter Description:

ch | Channel Number
pStream | The pointer pointing to the buffer area storing the BFSK data stream. For more information, refer to ‘ FSK Transceiver ’
dwMaxBit | The total valid bit number in pStream, it could be any length

Return Value:

-1 | Call failed
0 | Successful

Function Description:

Starts the FSK transmitter.

The operating parameters of the FSK transmitter may be configured by the function SsmSetFskPara or the configuration items FreqBit0 , FreqBit1 , Baudrate , or MdlAmp .

After the FSK transmitter is started, the application may stop it anytime via invoking the function SsmStopSendFsk . When the driver has finished transmitting all the bits in pStream, it will throw out the event E_PROC_SendFSK to the application. The application may also enquire the transmitting status of the FSK transmitter via invoking the function SsmCheckSendFsk .

Note:

l Before the FSK transmitter has finished transmitting all the data, the voice playing can’ t be started, and also the DTMF generator and tone generator can’t be used.

l Before the FSK transmitter is started, in order to ensure the data integrity, if the feature of echo cancellation is enabled, it needs to be disabled.

l This function can be called only after the original data has been converted to BFSK data stream via the function call of SsmTransFskData .

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmCheckSendFsk , SsmStopSendFsk , SsmTransFskData

Sample code:

char Data[]=‘12345’; //The string ‘12345’ needs to be transmitted

unsigned char Stream[256]; // Stores the converted BFSK bit stream

int nMaxBit = SsmTransFskData( (unsigned char*)Data, 5,96, 32, Stream);

SsmStartSendFSK(ch, (PCHAR)Stream, nMaxBit);


2.16.1.5 SsmCheckSendFsk

Enquires the transmitting status of the FSK transmitter.

Format:

int SsmCheckSendFsk(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Call failed
0 | Finished
1 | Not finished

Function Description:

Enquires the transmitting status of the FSK transmitter.

Note:

l If the application uses the event based programming mode, it’s recommended to use the event E_PROC_SendFSK .

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmStartSendFSK


2.16.1.6 SsmStopSendFsk

Stops the FSK transmitter.

Format:

int SsmStopSendFsk(int ch)

Parameter Description:

ch

Channel number

Return Value:

-1 | Call failed
0 | Successful

Function Description:

Stops the FSK transmitter.

Note:

l After the driver has executed this function, it throws out the event E_PROC_SendFSK to the application.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmStartSendFSK


2.16.2 FSK Receiver


2.16.2.1 SsmStartRcvFSK

Starts the FSK receiver.

Format:

int SsmStartRcvFSK(int ch, WORD wTimeOut, WORD wMaxLen, UCHAR ucEndCode, WORD wEndCodeCount)

Parameter Description:

ch | Channel Number
wTimeOut | Timer interval (ms)
wMaxLen | The maximum length (bytes) of the FSK data, range of value: 1~260
ucEndCode | The character indicating the end of the FSK data package
wEndCodeCount | The minimum times that ucEndCode continuously appears, range of value: 0~10

Return Value:

-1 | Call failed, the failure reason can be acquired via the function SsmGetLastErrMsg
0 | Successful

Function Description:

Starts the FSK receiver and begins to receive FSK data.

After the FSK receiver is started, the driver will start a timer and decide whether to stop receiving data based on the following rules:

² If the ending character set by the parameter ucEndCode is detected in the FSK data, and also the times that this character continuously appears is bigger than or equal to wEndCodeCount, the current task of FSK data receiving will be terminated, and the driver will also throw out the event E_PROC_RcvFSK (dwParam is set to be 2) to the application;

² If the length (total byte number) of the FSK data is larger or equal to wMaxLen, the current task of FSK data receiving will be stopped, and the driver will also throw out the event E_PROC_RcvFSK (dwParam is set to be 3) to the application;

² If the BFSK signal disappears on the line, and the time it keeps disappearing exceeds 100ms, the current task of FSK data receiving will be stopped, and the driver will throw out the event E_PROC_RcvFSK (dwParam is set to be 1) to the application.

² If the timer overflows, the current task of FSK data receiving will be stopped, and the driver will throw out the event E_PROC_RcvFSK (dwParam is set to be 1) to the application.

Note:

l The baud rate of the FSK receiver on Synway boards is 1200bps, the carrier frequency of bit 0 is 2200Hz, and the carrier frequency of bit 1 is 1200Hz. All of them can’t be changed via any functions or configuration items.

Related Information:

Driver version | SynCTI Ver. 3.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetRcvFSK , SsmStopRcvFSK , SsmStartRcvFSK_II

Sample code:

……

SsmStartRcvFSK (0, 10000, 260, ‘#’, 1); //Starts the FSK receiver

MESSAGE_INFO Event;

If ( SsmWaitForEvent (64, &Event) == 0 ) //Waits the event happening

{

switch(Event.EventCode)

{

case E_PROC_RcvFSK: //Stops the FSK receiver

if(Event.dwParam == 2) // Completes receiving FSK data ended with ending character ‘#’

{

unsigned char DataBuf[260];

SsmGetRcvFSK(Event.nReference, DataBuf); //Gets the data

…… //Processes the code

}

……

break;

……

}

}


2.16.2.2 SsmStartRcvFSK_II

Starts to receive FSK data.

Format:

int WINAPI SsmStartRcvFSK_II(int ch, WORD wTimeOut, WORD wMaxLen, PUCHAR pucMarkCodeBuf, UCHAR ucMarkCodeCount)

Parameter Description:

ch | Channel number
wTimeOut | Duration of the timer (ms)
wMaxLen | The maximum length of the FSK data: 1~260 (byte)
pucMarkCodeBuf | The buffer area storing identification codes, at most 10 different identification codes can be set
ucMarkCodeCount | The number of identification codes in pucMarkCodeBuf, range of value: 0~10. If this parameter is set to 0, the parameter pucMarkCodeBuf will be ignored

Return Value:

-1 | Call failed. The failure reason can be acquired via the function SsmGetLastErrMsg
0 | FSK receiver is started successfully

Function Description:

Starts the FSK receiver to begin the task of FSK data receiving.

This function supports two receiving mode: Length Mode and Frame Mode. Frame Mode means the FSK data to be transmitted has a fixed frame structure. The driver needs to perform the frame alignment and extraction according to the frame identification code; Length Mode means the driver only examines the length of the data to be received. When the length of the received FSK data becomes larger than wmMaxLen, the task of data receiving is terminated. If ucMarkCodeCount is larger than 0, the driver will use Frame Mode as the first choice to receive data. Otherwise, it will use Length Mode where the parameter wMaxLen is valid for receiving.

The frame is composed of four fields: identification code, data length, data body and check byte.

Identification Code

Data Length

Data Body

Check Byte

Identification Code: The beginning of the frame, occupying 1 byte and used for frame alignment. Its value can be determined by the application itself;

Data Length: The length of the data body, occupying 1 byte;

Data Body: The data to be transmitted, the maximum length can’t exceed 255 bytes;

Check Byte: It occupies 1 byte. Note that the check byte is generated by the application, so the driver doesn’t check the data integrity.

The execution rules of the FSK data receiver:

² Starts a timer and waits for the arrival of FSK data.

² Identification Code Mode: After the FSK data has arrived, the driver searches the identification code set by the parameter pucMarkCodeBuf in the first 10 bytes of the received data. If the identification code is found, it means the driver has finished the frame alignment successfully. After the driver has received a frame of data, the current task of data receiving is terminated and the driver throws out the event E_PROC_RcvFSK (dwParam is set to 4) to the application. If the identification code can’t be found, the data receiving will turn to follow the length mode.

² Length Mode: When the FSK data length exceeds the set value of the parameter wMaxLen, the current task of data receiving will be stopped and the driver will throw out the event E_PROC_RcvFSK (dwParam is set to 3) to the application.

² If the BFSK signal disappears on the line and does not reappear within 100ms, the current task of FSK data receiving will be stopped and the driver will throw out the event E_PROC_RcvFSK (dwParam is set to 1 if the length of the received FSK data is less than wMaxLen, otherwise it is set to 3) to the application.

² If the timer overflows, the current task of FSK data receiving will be stopped and the driver will throw out the event E_PROC_RcvFSK (dwParam is set to 1) to the application.

Note:

l The baud rate of the FSK receiver on Synway boards is 1200bps, the carrier frequency of Bit 0 is 2200Hz and that of Bit 1 is 1200Hz. Neither of them can be changed by modifying functions or configuration items.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetRcvFSK , SsmStopRcvFSK , SsmStartRcvFSK

Sample code:

……

SsmStartRcvFSK_II (0, 10000, 1, ‘#’, 1); //Start FSK receiver

MESSAGE_INFO Event;

If ( SsmWaitForEvent (64, &Event) == 0 ) //Wait for an event to be triggered

{

switch(Event.EventCode)

{

case E_PROC_RcvFSK: //FSK receiver is terminated

if(Event.dwParam == 4) //A frame of FSK data are received

{

unsigned char DataBuf[260];

SsmGetRcvFSK(Event.nReference, DataBuf); //Take the data

…… //Process the data

}

else

{

…… //Process the failure in receiving

}

break;

……

}

}


2.16.2.3 SsmStartRcvFSK_III

Starts to receive FSK data.

Format:

int WINAPI SsmStartRcvFSK_III(int ch,WORD wTimeOut,WORD wMaxLen,PUCHAR pucMarkCodeBuf, UCHAR ucMarkCodeCount)

Parameter Description:

ch | Channel number
wTimeOut | Duration of the timer (ms)
wMaxLen | The maximum length of the FSK data: 1~1024 (byte)
pucMarkCodeBuf | The buffer area storing identification codes, at most 10 different identification codes can be set
ucMarkCodeCount | The number of identification codes in pucMarkCodeBuf, range of value: 0~10. If this parameter is set to 0, the parameter pucMarkCodeBuf will be ignored; if this parameter is set to 5, the former 5 identification codes in pucMarkCodeBuf will be effective.

Return Value:

-1 | Call failed. The failure reason can be acquired via the function SsmGetLastErrMsg
0 | FSK receiver is started successfully

Function Description:

Starts the FSK receiver to begin the task of FSK data receiving.

This function supports two receiving mode: Length Mode and Frame Mode. Frame Mode means the FSK data to be transmitted has a fixed frame structure. The driver needs to perform the frame alignment and extraction according to the frame identification code; Length Mode means the driver only examines the length of the data to be received. When the length of the received FSK data becomes larger than wmMaxLen, the task of data receiving is terminated. If ucMarkCodeCount is larger than 0, the driver will use Frame Mode as the first choice to receive data. Otherwise, it will use Length Mode where the parameter wMaxLen is valid for receiving.

The frame is composed of four fields: identification code, data length, data body and check byte.

Identification Code

Data Length

Data Body

Check Byte

Identification Code: The beginning of the frame, occupying 1 byte and used for frame alignment. Its value can be determined by the application itself;

Data Length: The length of the data body, occupying 2 bytes;

Data Body: The data to be transmitted, the maximum length can’t exceed 1020 bytes;

Check Byte: It occupies 1 byte. Note that the check byte is generated by the application, so the driver doesn’t check the data integrity.

The execution rules of the FSK data receiver:

² Starts a timer and waits for the arrival of FSK data.

² Identification Code Mode: After the FSK data has arrived, the driver searches the identification code set by the parameter pucMarkCodeBuf in the first 10 bytes of the received data. If the identification code is found, it means the driver has finished the frame alignment successfully. After the driver has received a frame of data, the current task of data receiving is terminated and the driver throws out the event E_PROC_RcvFSK (dwParam is set to 4) to the application. If the identification code can’t be found, the data receiving will turn to follow the length mode.

² Length Mode: When the FSK data length exceeds the set value of the parameter wMaxLen, the current task of data receiving will be stopped and the driver will throw out the event E_PROC_RcvFSK (dwParam is set to 3) to the application.

² If the BFSK signal disappears on the line and does not reappear within 100ms, the current task of FSK data receiving will be stopped and the driver will throw out the event E_PROC_RcvFSK (dwParam is set to 1 if the length of the received FSK data is less than wMaxLen, otherwise it is set to 3) to the application.

² If the timer overflows, the current task of FSK data receiving will be stopped and the driver will throw out the event E_PROC_RcvFSK (dwParam is set to 1) to the application.

Note:

l The baud rate of the FSK receiver on Synway boards is 1200bps, the carrier frequency of Bit 0 is 2200Hz and that of Bit 1 is 1200Hz. Neither of them can be changed by modifying functions or configuration items.

l The date length occupies 2 bytes in the frame structure: the first byte indicates the length of high bits and the second one represents the length of low bits.

For example,

sz[5] = {0xFF 0x0 0x3 0x1 0x2 0x3} is a correct FSK datum, in which

sz[0] = 0xFF is the start flag;

sz[1] = 0x0, sz[2] = 0x3 indicate the length is 3 bytes;

0x1 0x2 0x3 at the end is the data body.

Related Information:

Driver version | SynCTI Ver. 5.0.1.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetRcvFSK , SsmStopRcvFSK , SsmStartRcvFSK , SsmStartRcvFSK_II

Sample code:

……

SsmStartRcvFSK_III (0, 10000, 1, ‘#’, 1); //Start FSK receiver

MESSAGE_INFO Event;

If ( SsmWaitForEvent (64, &Event) == 0 ) //Wait for an event to be triggered

{

switch(Event.EventCode)

{

case E_PROC_RcvFSK: //FSK receiver is terminated

if(Event.dwParam == 4) //A frame of FSK data are received

{

unsigned char DataBuf[260];

SsmGetRcvFSK(Event.nReference, DataBuf); //Take the data

…… //Process the data

}

else

{

…… //Process the failure in receiving

}

break;

……

}

}


2.16.2.4 SsmCheckRcvFSK

Enquires the receiving status of the FSK data

Format:

int SsmCheckRcvFSK(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Call failed
0 | FSK receiver has not finished the current task of data receiving yet
1 | Terminated because the timer is overtime
2 | Terminated due to the reception of ending character
3 | Terminated due to the reception of the data with designated length
4 | Terminated due to the reception of the data with designated format
5 | Terminated because the application makes the function call of SsmStopRcvFSK

Function Description:

Enquires the receiving status of the FSK data, the receiving task is initiated by the function SsmStartRcvFSK or SsmStartRcvFSK_II .

Note:

l If the application’s programming mode is based on event, it’s recommended to use the event E_PROC_RcvFSK .

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetRcvFSK


2.16.2.5 SsmStopRcvFSK

Cancels the task of FSK data receiving.

Format:

int SsmStopRcvFSK(int ch)

Parameter Description:

ch

Channel number

Return Value:

-1 | Call failed
0 | Successful

Function Description:

Cancels the task of FSK data receiving. This function may cancel the data receiving task started by the function SsmStartRcvFSK or SsmStartRcvFSK_II .

Note:

l After the driver finishes executing this function, it will throw out the event E_PROC_RcvFSK to the application.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetRcvFSK , SsmCheckRcvFSK


2.16.2.6 SsmClearRcvFSKBuf

Clears the buffer area for FSK data receiving in the driver.

Format:

int SsmClearRcvFSKBuf(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Error occurs, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Clears the buffer area for FSK data receiving in the driver.

Note:

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetRcvFSK


2.16.2.7 SsmGetRcvFSK

Gets the FSK data stored in the buffer area in the driver.

Format:

int SsmGetRcvFSK(int ch, PUCHAR pucBuf)

Parameter Description:

ch | Channel Number
pucBuf | Buffer area pointer, the storage space is allocated by the application, its size should be not less than 260 bytes

Return Value:

-1 | Call failed
≥0 | The length (bytes) of the received FSK data (not includes the ending character)

Function Description:

Gets the FSK data stored in the buffer area in the driver.

Note:

l Each time when the application calls the function SsmStartRcvFSK or starts the task of data receiving, the driver will automatically clear the buffer area storing the FSK data in the driver.

Related Information:

Driver version | SynCTI Ver. 3.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmCheckRcvFSK , SsmClearRcvFSKBuf


2.17 Voltage Detector Functions


2.17.1 Ignoring Result of Voltage Detector


2.17.1.1 SsmSetIgnoreLineVoltage

Sets whether to ignore the result of the voltage detector on analog phone lines.

Format:

int SsmSetIgnoreLineVoltage(int ch, BOOL bIgnore)

Parameter Description:

ch | Channel Number
bIgnore | =FALSE: not to ignore =TRUE: ignored

Return Value:

-1 | Operation failed
0 | Operation is successful

Function Description:

Sets whether to ignore the result of the voltage detector on analog phone lines. If the result of the voltage detector is ignored, the recording channel will always keep ‘off-hook’ state. For more information, refer to ‘Change in Analog Phone Line Voltage’ in Chapter 1.

Note:

l This function is only applicable to recording channels (including analog trunk recording module and microphone module) of ATP Series boards;

l The parameter set by this function may also be set by the configuration item IgnoreLineVoltage, with the default value of ‘not to ignore’.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetIgnoreLineVoltage


2.17.1.2 SsmGetIgnoreLineVoltage

Enquires whether the result of the line voltage detection of the channel is ignored

Format:

int SsmGetIgnoreLineVoltage(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Call failed
0 | Not to ignore
1 | Ignored

Function Description:

Enquires whether the result of the line voltage detection of the channel is ignored

Note:

l This function is only applicable to recording channels (including analog trunk recording module and microphone module) of ATP Series boards.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSetIgnoreLineVoltage


2.17.2 Setting Threshold Voltage to Detect Pickup and Hangup Behaviors


2.17.2.1 SsmSetDtrmLineVoltage

Sets the threshold voltage to detect the pickup and hangup behaviors on the analog trunk recording channel.

Format:

int SsmSetDtrmLineVoltage(int ch, WORD wDtrmValtage)

Parameter Description:

ch | Channel Number
wDtrmValtage | Determinant voltage (Volt), range of value:5~48

Return Value:

-1 | Call failed
0 | Successful

Function Description:

Sets the threshold voltage to detect the pickup and hangup behaviors on the analog trunk recording channel.

For more details, refer to ‘Change in Analog Phone Line Voltage’ in Chapter 1.

Note:

l This function is only applicable to recording channels (including analog trunk recording module and microphone module) of ATP Series boards.

l The parameter set by this function may also be set by the configuration item IsHangupDtrmVoltage, with the default value of 26V.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetDtrmLineVoltage


2.17.2.2 SsmGetDtrmLineVoltage

Obtains the threshold voltage determining the pickup/hangup on the analog trunk recording channel.

Format:

int SsmGetDtrmLineVoltage(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Call failed
³0 | Returns the threshold voltage (Volt) used to detect the pickup/hangup on the channel

Function Description:

Obtains the threshold voltage determining the pickup/hangup on the analog trunk recording channel.

Note:

l This function is only applicable to recording channels (including analog trunk recording module and microphone module) of ATP Series boards.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSetDtrmLineVoltage


2.17.3 Obtaining Result of Voltage Detector


2.17.3.1 SsmGetLineVoltage

Obtains the voltage value on the line.

Format:

int SsmGetLineVoltage(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Call failed
³0 | Returns the voltage value (Volt) on the line

Function Description:

Obtains the voltage value on the line. The line voltage value may also be obtained via the event E_CHG_LineVoltage. For more details, refer to Change in Analog Phone Line Voltage in Chapter 1.

Note:

l This function is only applicable to the recording channel of ATP Series boards and the analog trunk channel of SHT Series boards;

l It’s normal that the voltage value on the analog trunk may vary in the range of 1V-2V.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function:


2.17.4 Polarity Reversal Detector Functions


2.17.4.1 SsmQueryOpPolarRvrs

Queries a specified channel to make sure if it supports the detection of polarity reversal.

Format:

int WINAPI SsmQueryOpPolarRvrs(int ch)

Parameter Description:

ch

Channel number

Return Value:

-1 | Call failed
0 | The specified channel does not support the detection of polarity reversal
1 | The specified channel supports the detection of polarity reversal

Function Description:

Queries a specified channel to make sure if it supports the detection of polarity reversal. For more information, refer to ‘ Change in Analog Phone Line Voltage ’ in Chapter 1.

Note:

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function:


2.17.4.2 SsmGetPolarRvrsCount

The accumulated count of polarity reversing on the channel after pickup.

Format:

int SsmGetPolarRvrsCount(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Call failed
³0 | The count of polarity reversing

Function Description:

The accumulated count of polarity reversing on the channel after pickup. For more details, refer to ‘Change in Analog Phone Line Voltage’ in Chapter 1.

Note:

l This function is only applicable to the channels featured with polarity reversal detection;

l The same features can also be implemented by using the event E_CHG_PolarRvrsCount.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Event:E_CHG_PolarRvrsCount


2.17.5 Ringing Current Detector Functions


2.17.5.1 SsmGetRingCount

Obtains the count of the detected ringing current signals.

Format:

int SsmGetRingCount(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Call failed
≥0 | Count of ringing

Function Description:

Obtains the count of the detected ringing current signals. For more details, refer to ‘Change in Analog Phone Line Voltage’ in Chapter 1.

Note:

l The event E_CHG_RingCount may also implement the same features. It’s recommended to use this event to increase the portability of the application;

l This function is only applicable to the analog trunk recording channel of ATP Series boards and the analog trunk channel of SHT Series boards.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmClearRingCount, SsmGetChState


2.17.5.2 SsmGetCallBackRingCount

Obtains the count of the detected ringback current signals.

Format:

int SsmGetCallBackRingCount(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Call failed
≥0 | Count of ringing

Function Description:

Obtains the count of the detected ringback current signals.

Note:

l The event E_CHG_CallBackRingCount can be used to reach the same purpose. It’s recommended to use this event to increase the portability of the application;

l This function is only applicable to the analog trunk recording channel of ATP Series boards and the analog trunk channel of SHT Series boards.

Related Information:

Driver version | SynCTI Ver. 5.3.0.4 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmClearRingCount , SsmGetChState


2.17.5.3 SsmClearRingCount

Clears the count of the ringing current signals stored in the driver.

Format:

int SsmClearRingCount (int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Call failed
0 | Successful

Function Description:

Clears the count of the ringing current signals stored in the driver. For more details, refer to ‘Change in Analog Phone Line Voltage’ in Chapter 1.

Note:

l This function is only applicable to the analog trunk recording channel of ATP Series boards and the analog trunk channel of SHT Series boards.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetRingCount


2.17.5.4 SsmGetRingFlag

Gets the ring flag.

Format:

int SsmGetRingFlag (int ch)

Parameter Description:

ch

Channel number

Return Value:

0 | Not ringing
1 | Ringing

Function Description:

Clears the ring flag. For more information, refer to ‘Change in Analog Phone Line Voltage’ in Chapter 1.

Note:

l This function is only applicable to the analog trunk recording channel of ATP Series boards and the analog trunk channel of SHT Series boards.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function:


2.18 Digital Trunk Functions


2.18.1 SsmGetMaxPcm

Obtains the total amount of the digital trunks in the application.

Format:

int SsmGetMaxPcm()

Parameter Description:

Return Value:

-1 | Call failed
³0 | The total amount of the digital trunks in the system, it’s decided by the configuration item TotalPcm in the configuration section [PcmInfo]

Function Description:

Obtains the total amount of the digital trunks in the application.

Note:

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetPcmInfo


2.18.2 SsmGetPcmInfo

Obtains the operating parameters of the digital trunk interface unit (LIU).

Format:

int SsmGetPcmInfo(int nPcmNo, int* pnSSxMode, int* pnBoardId, int* pnBoardPcmNo, int* pnUsePcmTS16, PDWORD pdwRcvrMode, PDWORD pdwEnableAutoCall, PDWORD pdwAutoCallDirection)

Parameter Description:

nPcmNo | The logical number of the digital trunk, range of value: 0~N-1, N is the set value of the configuration item TotalPcm in the configuration section [PcmInfo], it can be obtained via the function call of SsmGetMaxPcm
pnBoardId | The ID of the board on which the digital trunk is located
pnBoardPcmNo | The internal number of the digital trunk on the board
pnSSxMode | Returns the signaling mode adopted by the PCM 0: ISDN(User side) 1: SS1 2: ISDN(Network side) 7: SS7
pnUsePcmTS16 | Returns whether the 16th time slot of the PCM is used as voice channel. 1: Yes 0: No
PdwRcvrMod *red+u e | Returns the operating mode of the Digital Trunk Interface Unit (LIU), it includes 32 bits, each bit is defined as follows: Bit1,Bit0: clock setting, range of value: 00: line-synchronization mode, master clock 01: Free-run mode, master clock 10: slave clock 11: reserved Bit2: type of connection line: 0:120 ohm twisted pair cable 1:75 ohm coaxial cable Bit3: whether the LIU needs to perform the jitter-cancellation to 16th time slot 0: not to perform the jitter-cancellation (default) 1: perform the jitter-cancellation for a duration of 14ms Bit4: sets the voice channel’s feature of Alternate Digit Inversion (ADI) 0: turned off (default) 1: turned on Bit6,Bit5: sets the gain of the input-equalizer of LIU 00: automatically controlled by LIU (default) 01: 0 DB 10:12 DB 11: 6 DB Bit7: reserved Bit15~Bit8: sets the control word of LIU for jitter-cancellation Bit31~Bit16: reserved
pdwEnableAutoCall | Returns the auto-connection control word (32 bits) for the 32 time slots. The highest bit (bit31) corresponds to time slot 0; the lowest bit (bit0) corresponds to time slot 31. If the bit value equals 1, auto-connection is allowed; if 0, auto-connection is forbidden
pdwAutoCallDirection | Returns the auto-connection direction of the 32 time slots. Each bit corresponds to one time slot, the highest bit (bit31) corresponds to time slot 0, and the lowest bit (bit0) corresponds to time slot 31. If bit value equals 0, indicates that only incoming call is permitted, if 1, only outgoing call is allowed

Return Value:

-1 | Call failed
0 | Successful

Function Description:

Obtains the operating parameters of the digital trunk interface unit (LIU).

Note:

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetPcmLinkStatus


2.18.3 SsmGetPcmLinkStatus

Obtains the synchronization status of the digital trunk.

Format:

int SsmGetPcmLinkStatus(int nPcmNo, PWORD pwPcmLinkStatus)

Parameter Description:

nPcmNo

The logical number of the digital trunk, range of value: 0~N-1. N is the set value of the configuration item TotalPcm in the section of [PcmInfo], it can be obtained by the function SsmGetMaxPcm

pwPcmLinkStatus

Returns the synchronization status of the digital trunk. It includes 16 bits and bit 0 is the lowest valid bit. If the bit value is equal to 0, it indicates that the operating status is normal; If the bit value is equal to 1:

For board models: SHD-30A-CT/PCI/SS1, SHD-30A-CT/PCI/ISDN, SHD-30A-CT/PCI/SS7, SHD-60A-CT/PCI/SS1, SHD-60A-CT/PCI/ISDN, SHD-60A-CT/PCI/SS7, SHD-120A-CT/PCI/SS1, SHD-120A-CT/PCI/ISDN, SHD-120A-CT/PCI/SS7, SHD-30B-CT/PCI/SS7/FAX, SHD-60B-CT/PCI/SS7/FAX, SHD-30A-CT/cPCI/SS7, SHD-60A-CT/cPCI/SS7, SHD-120A-CT/cPCI/SS7, SHD-30B-CT/cPCI/SS7/FAX, SHD-60B-CT/cPCI/SS7/FAX

bit0=1: basic frame synchronization loss

bit1=1: the duration of the basic frame synchronization loss is larger than 100ms

bit2=1: multi-frame synchronization loss (SS1 only)

bit3=1: CRC multi-frame synchronization loss

bit4=1: remote alarm indication

bit5=1: alarm indication signal

bit6=1: all-ones alarm signal of time slot 16 (SS1 only)

bit7=1: signal loss

bit8=1: auxiliary alarm (SS1 only)

bit9=1: alarm signal of multi-frame asychronization (SS1 only)

Other bits: reserved, all remain 0

For board models: SHD-60B-CT/PCI/FJ, DTP-30C/PCI, DTP-30C/PCI+, DTP-60C/PCI, DTP-60C/PCI+, DTP-120C/PCI, DTP-120C/PCI+, DTP-30C/PCIe, DTP-30C/PCIe+, DTP-60C/PCIe, DTP-60C/PCIe+, DTP-120C/PCIe, DTP-120C/PCIe+, SHD-120D-CT/PCI, SHD-120D-CT/PCI/EC, SHD-120D-CT/PCI/CAS, SHD-240D-CT/PCI , SHD-240D-CT/PCI/EC, SHD-240D-CT/PCI/CAS, SHD-30E-CT/PCI, SHD-30E-CT/PCI/FAX, SHD-30E-CT/PCI/EC, SHD-60E-CT/PCI, SHD-60E-CT/PCI/FAX, SHD-60E-CT/PCI/EC, SHD-120E-CT/PCI, SHD-120E-CT/PCI/FAX, SHD-120E-CT/PCI/EC, SHD-240E-CT/PCI, SHD-240E-CT/PCI/FAX, SHD-240E-CT/PCI/EC, SHD-30E-CT/PCIe, SHD-30E-CT/PCIe/FAX, SHD-30E-CT/PCIe/EC, SHD-60E-CT/PCIe, SHD-60E-CT/PCIe/FAX, SHD-60E-CT/PCIe/EC, SHD-120E-CT/PCIe, SHD-120E-CT/PCIe/FAX, SHD-120E-CT/PCIe/EC, SHD-240E-CT/PCIe, SHD-240E-CT/PCIe/FAX, SHD-240E-CT/PCIe/EC

bit0=1: FAS re-synchronization (E1 only)

bit1=1: frame loss

bit2=1: CAS re-synchronization (SS1and E1)

bit3=1: CRC re-synchronization (E1 only)

bit4=1: remote alarm indication

bit5=1: alarm indication signal

bit6=1: all-ones alarm signal of time slot 16 (SS1 only)

bit7=1: signal loss

bit9=1: MF alarm from the remote end (SS1 and E1)

bit10=1: open circuit

bit11=1: short circuit

Other bits: reserved, all remain 0

For board models: SHD-480A-CT/cPCI, SHD-480S-CT/cPCI, SHD-240S-CT/cPCI, SHD-240A-CT/cPCI

bit1=1: FAS synchronization active

bit2=1: CAS MF synchronization active

bit3=1: CRC4 MF synchronization active

bit8=1: synchronization loss

bit9=1: carrier loss

bit10=1: remote alarm

Other bits: reserved, all remain 0

For board models: SHD-30C-CT/PCI, SHD-60C-CT/PCI, SHD-30C-CT/PCI/FAX, SHD-60C-CT/PCI/FAX, SHD-30B-CT/PCI/FJ

bit1=1: asynchronization time more than 120ms

Other bits: reserved, all remain 0

Return Value:

-1 | Call failed
0 | Successful

Function Description:

Obtains the synchronization status of the digital trunk.

Note:

l For SS1, only part of the exchanges supports multi-frame CRC check, so, it doesn’t always mean the line synchronization fails when the CRC multi-frame synchronization loss occur.

l For SS7, ISDN signaling, Time Slot 16 is always used to transmit the Common Channel Signaling (CCS), which is irrelative to multi-frame and CRC multi-frame verification. Consequently, only if the basic frame synchronization information is correct (both bit0 and bit1 is 0), it can be used normally. In addition, because both SS7and ISDN signaling are digital signaling, and they have the capability of fault tolerance, it’s allowed that the basic frame synchronization has jitter in a small range. Hence, if the line synchronization status returned by this function is used for alarm signal, normally the bit value change of bit0 from 0 to 1 is regarded as the alarm condition.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetPcmInfo


2.18.4 SsmPcmTsToCh

Enquires the corresponding channel number based on the PCM logical number and the time slot number.

Format:

int SsmPcmTsToCh(int nLocalPcmNo, int nTs)

Parameter Description:

nLocalPcmNo | The logical number of the digital trunk. For more information about digital trunk, refer to Basic Concepts in Chapter 1.
nTs | Time slot number, range of value : 1~31

Return Value:

-1 | Call failed
≥0 | The logical number of the corresponding channel

Function Description:

Enquires the corresponding channel number based on the PCM logical number and time slot number.

Note:

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmChToPcmTs


2.18.5 SsmChToPcmTs

Enquires the corresponding PCM logical number and time slot number according to the channel number.

Format:

int SsmChToPcmTs(int ch, int* pnLocalPcmNo, int* pnTs)

Parameter Description:

ch | Channel Number
pnLocalPcmNo | The logical number of the PCM on which the channel ch is located
pnTs | The number of the time slot on which the channel is located

Return Value:

-1 | Call failed
≥0 | Returns the value in the parameter pnLocalPcmNo

Function Description:

Enquires the corresponding PCM logical number and time slot number according to the channel number.

Note:

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmPcmTsToCh


2.18.6 SsmSetPcmClockMode

Sets the clock mode of the digital trunk.

Format:

int SsmSetPcmClockMode(int nPcmNo, int nClockMode)

Parameter Description:

nPcmNo | The logical number of the digital trunk, range of value: 0~N-1 (N is the set value of the configuration item TotalPcm, it can be obtained by the function call SsmGetMaxPcm)
nClockMode | Clock mode, range of value: 0: master clock, line-synchronization mode (the board must be the master board) 1: master clock, free-run mode (the board must be the master board) 2: slave clock

Return Value:

-1 | Call failed
0 | Successful

Function Description:

Sets the clock mode of the digital trunk. For more information, refer to ‘System Clock Configuration’.

Note:

l This function is only applicable to SHD, DTP Series;

l The configuration item PcmClockMode may implement the same features.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetPcmInfo


2.18.7 SsmGetInboundLinkSet

During incoming call, retrieves the information of the link set which is used by TUP/ISUP messages from the remote PBX.

Format:

int SsmGetInboundLinkSet(int ch, LPWORD pwLinkSetNo, LPSTR pszOpc, LPSTR pszDpc)

Parameter Description:

ch | Channel number
pwLinkSetNo | Link set number
pszOpc | OPC
pszDpc | DPC

Return Value:

1 | Successful
-1 | Call failed

Function Description:

During incoming call, retrieves the information of the link set which is used by TUP/ISUP messages from the remote PBX, including the link set number, DPC and OPC.

Note:

l This function is only applicable to TUP/ISUP channels.

Related Information:

Driver version | SynCTI Ver. 4.7.1.2 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function:


2.18.8 SsmGetCbChStatus

Retrieves the connection state of the large-capacity channel bank.

Format:

int WINAPI SsmGetCbChStatus(int ch, PWORD pwCBLinkStatus)

Parameter Description:

ch | Channel number
pwCBLinkStatus | Connection state of the channel bank

Return Value:

0 | Call successful
-1 | Call failed

Function Description:

Retrieves the connection state of a line between a large-capacity channel bank and an on-board channel. pwCBLinkStatus=0 means the line is connected, while pwCBLinkStatus=1 means the line is disconnected.

Note:

l This function is used only to detect the connection state of a large-capacity channel bank.

l The same feature can be implemented by using the event E_CHG_CbChStatus.

Related Information:

Driver version | SynCTI Ver. 5.0.3.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function:

Related Event: E_CHG_CbChStatus


2.18.9 SsmSetPcmPowerDown

Sets the working mode of the digital trunk.

Format:

int WINAPI SsmSetPcmPowerDown(int nPcmNo, int nPowerMode)

Parameter Description:

nPcmNo | The logical number of the digital trunk, range of value: 0~N-1 (N is the set value of the configuration item TotalPcm, it can be obtained by the function call of SsmGetMaxPcm)
nPowerMode | Working mode, range of value: 0: normal working mode 1: idle mode (It is similar to the state that the PCM is unconnected)

Return Value:

-1 | Call failed
0 | Successful

Function Description:

Sets the working mode for the specified PCM. It can be set to normal working mode or idle mode.

Note:

l This function is only applicable to SHD Series D-type and E-type boards.

Related Information:

Driver version | SynCTI Ver. 5.3.0.1 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll


2.19 Functions for SHT Series Boards (CTI Series)


2.19.1 Setting Operating Mode of Composite Module


2.19.1.1 SsmSetUnimoduleState

Sets whether to enable the direct connection between the analog trunk channel and station channel on the composite module.

Format:

int SsmSetUnimoduleState(int ch,int nState)

Parameter Description:

ch | The number of the analog trunk channel on the composite module
nState | =0: connect the analog trunk channel directly with the station channel =1: There is no connection between the analog trunk channel and the station channel, they are equivalently two independently controlled channels

Return Value:

-1 | Failed
0 | Successful

Function Description:

Sets whether to enable the direct connection between the analog trunk channel and station channel on the composite module.

Note:

l The configuration item UnimoduleState may implement the same features

Related Information:

Driver version | SynCTI Ver. 3.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function:


2.19.2 Functions for Analog Trunk Channel


2.19.2.1 Generating Flash Signal on Analog Phone Line


2.19.2.1.1 SsmTxFlash

Generates a flash signal on the analog trunk (equivalent to a rapid clap on the hook switch).

Format:

int SsmTxFlash(int ch, WORD time)

Parameter Description:

ch | Channel Number
time | Sets the duration (ms) of the flash, range of value: 32~1000, usually it’s set to 500ms

Return Value:

-1 | Call failed. The failure reason can be acquired via the function SsmGetLastErrMsg
0 | Successful

Function Description:

Generates a flash signal on the analog trunk (equivalent to a rapid clap on the hook switch).

When the application finishes an operation of flash, it throws out the event of E_PROC_SendFlash to the application. The operation status may be obtained by the function of SsmChkTxFlash .

Note:

l This function only supports analog trunk channels on SHT Series boards.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmChkTxFlash


2.19.2.1.2 SsmSetTxFlashCharTime

Sets the duration of the flash signal generated on the analog trunk via the function call of SsmTxDtmf.

Format:

int SsmSetTxFlashCharTime(int ch,WORD time)

Parameter Description:

ch | Channel Number
Time | The duration (ms) of the flash signal, range of value: 32~1000, with the default value of 500

Return Value:

0 | Successful
-1 | Call failed. The failure reason can be acquired via the function SsmGetLastErrMsg

Function Description:

The function call of SsmTxDtmf by using the parameter of the character ‘!’ may also generate a flash signal on the analog trunk. This function sets the duration of the flash signal generated by using the character ‘!’.

Note:

l The configuration item DefaultTxFlashTime may complete the same features, with the default value of 500ms.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetTxFlashCharTime , SsmTxDtmf


2.19.2.1.3 SsmGetTxFlashCharTime

Obtains the duration of the flash signal generated on the analog trunk via the function call of SsmTxDtmf.

Format:

int SsmGetTxFlashCharTime(int ch,WORD time)

Parameter Description:

ch

Channel Number

Return Value:

>0 | The duration of the flash signal, calculated by millisecond (ms).
-1 | Call failed. The failure reason can be acquired via the function SsmGetLastErrMsg

Function Description:

Obtains the duration of the flash signal generated on the analog trunk by the function call of SsmTxDtmf.

Note: none

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSetTxFlashCharTime


2.19.2.1.4 SsmChkTxFlash

Enquires whether the operation of generating the flash signal on the analog trunk has been completed.

Format:

int SsmChkTxFlash(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Error occurs
0 | The operation of generating the flash signal has been completed
1 | The operation of generating the flash signal is under progress

Function Description:

Enquires whether the operation of generating the flash signal on the analog trunk has been completed.

Note:

l Only the analog trunk channel supports the generation of the flash signal.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmTxFlash


2.19.2.1.5 SsmTxFlashEx

Generates a flash signal on the analog trunk (equivalent to a rapid clap on the hook switch) and sets the current channel state upon this flash.

Format:

int WINAPI SsmTxFlashEx(int ch, WORD time, int nChState, BOOL bIgnoreDlTn)

Parameter Description:

ch | Channel number
time | The duration (ms) of the flash signal, range of value: 32~1000, with the default value of 500.
nChState | The channel state after the flash, range of value: S_CALL_PICKUPED(1), S_CALL_TALKING(3)
bIgnoreDlTn | Determines whether to ignored the dial tone after the flash, range of value: FALSE (not ignore), TRUE(ignore).

Return Value:

-1 | Call failed. The failure reason can be acquired via the function SsmGetLastErrMsg .
0 | Call successful

Function Description:

Generates on the specifed channel a flash signal (equivalent to a rapid clap on the hook switch) , whose duration is set by the parameter ‘time’. And sets the current channel state upon this flash.

Note:

l This function only supports analog trunk channels on the SHT Series boards.

Related Information:

Driver version | SynCTI Ver. 4.8.0.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmTxFlash , SsmChkTxFlash


2.19.2.2 Forced Transition of Channel State


2.19.2.2.1 SsmSetChState

Forces the state of the analog trunk channel to be transferred to the talking state.

Format:

int SsmSetChState (int ch, int nState)

Parameter Description:

ch | Channel Number
nState | The new state of the channel, it must be set to 3

Return Value:

-1 | Call failed
0 | Successful

Function Description:

When the analog trunk channel accidentally enters the pending state, this function may force the state of the analog trunk channel to be transferred to the talking state.

Note:

l This function is only applicable to the analog trunk channels of SHT Series boards. This function is used only in some special applications. For example, when the application discovers that the channel enters the pending state abnormally, it wants to get the channel back to the talking state.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function:


2.19.2.3 Detecting Remote Pick-up During Outgoing Call


2.19.2.3.1 SsmStartPickupAnalyze

Starts the ‘Enhanced Remote Pickup Detector’.

Format:

int SsmStartPickupAnalyze(int ch)

Parameter Description:

ch

Channel number

Return Value:

-1 | Failed
0 | Successful

Function Description:

Starts the ‘Enhanced Remote Pickup Detector’. For more information, refer to ‘ Enhanced Remote Pickup Detector ’

Note:

l This function is only applicable to analog trunk channels of SHT Series boards.

Related Information:

Driver version | SynCTI Ver. 3.5.2.4 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetPickup


2.19.2.3.2 SsmSetCalleeHookDetectP

Sets the operating parameters of the ‘Enhanced Remote Pickup Detector’ on the analog trunk channel.

Format:

int SsmSetCalleeHookDetectP(int ch, WORD wMulti, WORD wValidTime)

Parameter Description:

ch | Channel number
wMulti | Sensitivity, for more information, refer to the description of the configuration item HookEngyConfigMulti
wValidTime | Minimum duration, for more information, refer to the description of the configuration item HookValidEngyCnt

Return Value:

-1 | Call failed
0 | Successful

Function Description:

Sets the operating parameters of the ‘Enhanced Remote Pickup Detector’ on the analog trunk channel. For more information, refer to ‘ Enhanced Remote Pickup Detector ’.

Note:

l This function is only applicable to the analog trunk channels of SHT Series boards.

Related Information:

Driver version | SynCTI Ver. 3.5.2.4 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmStartPickupAnalyze


2.19.2.3.3 SsmGetPickup

Enquires the detected result of the ‘Enhanced Remote Pickup Detector’ on the analog trunk channel.

Format:

int SsmGetPickup (int ch)

Parameter Description:

ch

Channel number

Return Value:

-1 | Failed
0 | The called party didn’t pick up
1 | The called party has picked up

Function Description:

Enquires the detected result of the ‘Enhanced Remote Pickup Detector’ on the analog trunk channel. For more information, refer to ‘ Enhanced Remote Pickup Detector ’ .

Note:

l The same features can be implemented by the event of E_SYS_RemotePickup (recommended);

l This function is only applicable to the analog trunk channels of SHT Series boards.

Related Information:

Driver version | SynCTI Ver. 3.5.2.4 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmStartPickupAnalyze , SsmSetCalleeHookDetectP


2.19.2.4 Checking Pickup Status


2.19.2.4.1 SsmCheckActualPickup

Enquires whether the operation of pickup has been completed.

Format:

int SsmCheckActualPickup(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Failed
0 | The specified channel is in the actual hangup state
1 | The specified channel is in the actual pickup state

Function Description:

Enquires whether the operation of pickup has been completed. For more information, refer to the description of the function SsmPickup .

Note:

l This function is only applicable to the analog trunk channels of SHT Series boards.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmPickup


2.19.2.5 Checking Analog-trunk-to-recording Channel


2.19.2.5.1 SsmGetIsAnalogToRec

Checks whether this channel is a recording channel transformed from the analog trunk channel.

Format:

int WINAPI SsmGetIsAnalogToRec(int ch);

Parameter Description:

ch

Channel Number

Return Value:

-1 | Failed
0 | The specified channel is neither an analog trunk channel nor a recording channel transformed from the analog trunk channel
1 | The specified channel is a recording channel transformed from the analog trunk channel

Function Description:

Checks whether this channel is a recording channel transformed from the analog trunk channel. For more information, refer to the configuration item SetAnalogChToRecCh .

Note:

l This function is only applicable to analog trunk channels of SHT Series boards.

Related Information:

Driver version | SynCTI Ver. 5.3.1.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Configuration Item: SetAnalogChToRecCh


2.19.3 Functions for Station Channel


2.19.3.1 Sending Ringing Signals to Phone


2.19.3.1.1 SsmStartRing

Refer to SsmStartRingWithCIDStr


2.19.3.1.2 SsmStartRingWithCIDStr

Sends ringing signals to the phone. SsmStartRing only generates the ringing signals, SsmStartRingWithCIDStr may also send the caller ID information to the phone.

Format:

int SsmStartRing(int ch)

int SsmStartRingWithCIDStr(int ch, LPSTR pCIDBuf, DWORD dwCIDLen, DWORD dwDelayTime)

Parameter Description:

ch | Channel Number
pCIDBuf | The first address of the buffer area storing the caller ID information. e.g. ‘0018657188861158’
dwCIDLen | The number of characters of the caller ID in pCIDBuf , range of value: 1~20
dwDelayTime | The time interval (ms) starting from the negative edge of the first ringing signal to the 1st FSk data emerging on the line, range of value: 500~1500 Note: The FSK modulated caller ID is transmitted between the 1st and 2nd ringing signal

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Sends ringing signals to the phone.

The function SsmStopRing may be used to stop sending ringing signal to the phone at anytime.

Note:

l This function is only applicable to station channels of SHT Series boards, the function of SsmStartRing is applicable to both the station channel and magnet channel, the function of SsmStartRingWithCIDStr is only applicable to the station channel;

l If the function SsmStartRingWithCIDStr is called, during the function execution, none of the voice playing functions can be invoked.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmStopRing


2.19.3.1.3 fPcm_ConvertFskCID

Converts the caller ID information using FSK modulation to audio signals fit for the transmission on the analog phone line.

Format:

DWORD fPcm_ConvertFskCID(LPSTR pFskStream, int nFskLen, LPSTR pszCIDNumber, LPSTR pszTime, LPSTR pszName, int nMode)

Parameter Description:

pFskStream | The first address of the buffer area storing the modulated FSK bit stream, outputs the value of the parameter, the application allocates the storage space which should be not less than 500 bytes
nFskLen | The size of the buffer area (bytes) pointed by pFskStream
pszCIDNumber | The first address of the buffer area storing the caller ID, the character number should be in the range of 4~14
pszTime | The first address of the buffer area storing the time information, its length is 8 bytes, the format is ‘MMDDhhmm’, MM is the month of the year, DD is the day of the month, hh is the hour of the day, mm is the minute of the hour. e.g., ‘12041224’ denotes 12:24, 4th, December. If pszTime is NULL, the driver will use the system time as the time information
pszName | The first address of the buffer area storing the additional information, the length is 4~14 bytes, it can be null Note: most of the phones can’t display the additional information
nMode | The frame format of the FSK calling ID, 0 denotes the multi-frame, 1 denotes the single-frame

Return Value:

0 | Call failed
>0 | The total bit number after modulation

Function Description:

Converts the caller ID information using FSK modulation to audio signals fit for the transmission on the analog phone line.

Note:

Related Information:

Driver version | SynCTI Ver.4.5.2.5 or above
Header | ShPcmApi.h
Library | ShPcmHandle.lib
DLL | ShPcmHandle.dll

Related Function:


2.19.3.1.4 SsmStopRing

Stops sending ringing signals to magnet channels or station channels.

Format:

int SsmStopRing(int ch)

Parameter Description:

ch

Channel number

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Stops sending ringing signals to magnet channels or station channels. The operation of ringing signal transmission may be initiated by the function SsmStartRing or SsmStartRingWithCIDStr .

Note:

l This function is only applicable to the station channels and magnet channels of SHT Series boards;

l After this function is invoked, the counter of ringing signals in the driver will be set to 0.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmStartRing , SsmStartRingWithCIDStr


2.19.3.1.5 SsmCheckSendRing

Obtains the operating status of the ringing current generator of station channels and magnet channels.

Format:

int SsmCheckSendRing(int ch,int * pnCnt)

Parameter Description:

ch | Channel Number
pnCnt | Returns the value of the ringing tone counter in the driver

Return Value:

-1 | Call failed
0 | No ringing tone signal transmission on the channel
1 | The ringing tone signal is being transmitted on the channel

Function Description:

Obtains the operating status of the ringing current generator of station channels and magnet channels.

Note:

l This function is only applicable to the station channels and magnet channels of SHT Series boards.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmStartRing , SsmStartRingWithCIDStr


2.19.3.1.6 SsmSetRingPeriod

Sets the on and off durations for the ringing current generator on station channels.

Format:

int WINAPI SsmSetRingPeriod(int ch,WORD wHigh,WORD wLow)

Parameter Description:

ch | Channel Number
wHigh | The on duration of a ringing signal, calculated by ms, with the minimum value of 16ms
wLow | The off duration of a ringing signal, calculated by ms, with the minimum value of 16ms

Return Value:

-1 | Call failed
0 | Call successful

Function Description:

Sets the on and off durations for the ringing current generator on station channels.

Note:

l This function is only applicable to the station channels of SHT Series boards.

Related Information:

Driver version | SynCTI Ver. 5.1.0.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmStartRing , SsmStartRingWithCIDStr


2.19.3.2 Auto Sending Dial Tone upon Detection of Phone Pickup


2.19.3.2.1 SsmSetASDT

Sets whether the driver automatically sends the dial tone signal when it’s detected that the phone connected with the station channel has been picked up.

Format:

int SsmSetASDT(int ch, BOOL bEnAutoSendDialTone)

Parameter Description:

ch | Channel number
bEnAutoSendDialTone |  | =TRUE: Turned on =FALSE: Turned off

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Sets whether the driver automatically sends the dial tone signal when it’s detected that the phone connected with the station channel has been picked up.

Note:

l This function is only applicable to station channels of SHT Series boards.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetASDT


2.19.3.2.2 SsmGetASDT

Obtains the sign indicating whether the driver automatically sends the dial tone signal when it’s detected that the phone connected with the station channel has been picked up.

Format:

int SsmGetASDT(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Call failed
0 | ‘Turned off’ state
1 | ‘Turned on’ state

Function Description:

Obtains the sign indicating whether the driver automatically sends the dial tone signal when it’s detected that the phone connected with the station channel has been picked up.

Note:

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSetASDT


2.19.3.3 Detecting Flash Signal


2.19.3.3.1 SsmSetLocalFlashTime

Sets the maximum duration determining the flash signal.

Format:

int SsmSetLocalFlashTime(int nFlashTime)

Parameter Description:

nFlashTime

Maximum duration (ms) of the flash signal, range of value: 32~2000

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Sets the maximum duration determining the flash signal. For more information, refer to ‘ Flash Signal Detection ’.

Note:

l This function is only applicable to station channels.

l The configuration item MaxLocalFlashTime may also complete the same features, with the default value of 700ms.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function:


2.19.3.3.2 SsmGetFlashCount

Obtains the value of the flash signal counter in the driver on the station or recording channel.

Format:

int SsmGetFlashCount(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Call failed
³0 | The value of the flash signal counter

Function Description:

Obtains the value of the flash signal counter in the driver on the station or recording channel.

Note:

l This function is only applicable to station and recording channels;

l When the station channel enters the pickup or hangup state, the driver will reset the flash signal counter to 0.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmClearFlashCount


2.19.3.3.3 SsmClearFlashCount

Resets the flash signal counter on the designated station or recording channel to 0.

Format:

int SsmClearFlashCount (int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Call failed
0 | Successful

Function Description:

Resets the flash signal counter on the designated station or recording channel to 0.

Note:

l This function is only applicable to station and recording channels;

l When the station channel enters the pickup or hangup state, the driver will automatically reset the flash signal counter to 0.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetFlashCount


2.19.3.4 Pickup/Hangup Detection


2.19.3.4.1 SsmGetHookState

Obtains the on-/off-hook state of the station channel or the EM Control channel.

Format:

int SsmGetHookState(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Call failed
0 | On-hook state
1 | Off-hook state

Function Description:

Obtains the on-/off-hook state of the station channel or the EM Control channel. The same features can also be implemented by using the event of E_CHG_HookState .

Note:

l This function is only applicable to station channels and EM Control channels of SHT Series boards;

l When the station channel enters the ‘off-hook’ state or ‘on-hook’ state, the driver will reset the flash signal counter in the driver to 0.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Event: E_CHG_HookState


2.19.3.5 Generating Polarity Reversal Signals on Phone Line


2.19.3.5.1 SsmSetPolarState

Sets the polarity of the feed voltage of the analog phone line connected with the station channel.

Format:

int SsmSetPolarState(int ch, int nPolar)

Parameter Description:

ch | Channel number
nPolar | The polarity of the channel to be set, range of value: 0 or 1

Return Value:

-1 | Call failed
0 | Successful

Function Description:

Sets the polarity of the feed voltage of the analog phone line connected with the station channel. The current voltage polarity of the channel may be obtained by the function SsmGetPolarState . For more information, refer to

‘ Generating Polarity Reversal Signal on Phone Line ’ in Chapter 1.

Note:

l Only when the configuration item UserSendPolar is set to 1, can this function be called;

l This function is only applicable to station channels of SHT Series boards.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetPolarState

Sample Code:

int v = SsmGetPolarState(ch);

SsmSetPolarState(ch, ~v);


2.19.3.5.2 SsmGetPolarState

Obtains the polarity of the feed voltage of the analog phone line connected with the station channel.

Format:

int SsmGetPolarState(int ch)

Parameter Description:

ch

Channel number

Return Value:

-1 | Call failed
0,1 | Returns the current polarity

Function Description:

Obtains the polarity of the feed voltage of the analog phone line connected with the station channel.

Note:

l This function is only applicable to station channels of SHT Series boards.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSetPolarState


2.19.4 Remote Pickup Detector Functions (SHT Series Only)


2.19.4.1 Functions for Ordinary Remote Pickup Detector


2.19.4.1.1 Setting Parameters


2.19.4.1.1.1 SsmSetVoiceOnDetermineTime

Sets the minimum duration of voice activities.

Format:

int SsmSetVoiceOnDetermineTime(int ch, WORD wIsVocDtrTime)

Parameter Description:

ch | Channel Number
wIsVocDtrTime | Minimum duration (ms), range of value: 16ms~1024ms

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Sets the minimum duration of voice activities. Only when there are continuous voice activities appearing on the line, and also the duration is larger than the preset value of the parameter wIsVocDtrTime, will the driver confirm that there are real voice activities. For more information, refer to ‘ Ordinary Remote Pickup Detector ’.

Note:

l The configuration item VoiceOnDetermineTime may implement the same features;

l This function is only applicable to the analog trunk channels of SHT Series boards.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetVoiceOnDetermineTime


2.19.4.1.2 Obtaining Parameters


2.19.4.1.2.1 SsmGetVoiceOnDetermineTime

Obtains the minimum duration of the voice activities.

Format:

int SsmGetVoiceOnDetermineTime(int ch, PWORD pwIsVocDtrTime)

Parameter Description:

ch | Channel Number
pwIsVocDtrTime | Returns the minimum duration (ms)

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Successful

Function Description:

Obtains the minimum duration which determines whether there is voice signal on the line.

Note:

l This function is only applicable to the analog trunk channels of SHT Series boards.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSetVoiceOnDetermineTime


2.20 Advanced Programming API for SHD Series (CTI Series)


2.20.1 Channel Blocking Control (CTI Series)


2.20.1.1 Functions for Blocking Local End


2.20.1.1.1 Blocking Single Channel


2.20.1.1.1.1 SsmBlockLocalCh

Blocks the local channel in order to prohibit the channel from making outgoing calls, but still allows the local channel to process incoming calls (TUP channel), or both incoming and outgoing calls are prohibited (ISDN channel) .

Format:

int SsmBlockLocalCh(int ch)

Parameter Description:

ch

Channel number to be input

Return Value:

-1 | Call failed
0 | Successful

Function Description:

Blocks the local channel in order to prohibit the channel from making outgoing calls, but still allows the local channel to process incoming calls (ISUP channel), or both incoming and outgoing calls are prohibited (ISDN channel) .For more information about channel blocking, refer to ‘ Channel Blocked and Unblocked ’.

This function is applicable to TUP and ISDN channels and has an effect on the TUP Channel State Machine . For more detailed description about the TUP and ISDN channel state machine, refer to TUP Channel State Machine and ISDN Channel State Machine in Chapter 1 (The event triggered by this function is named as ‘Blocking’ in the state machine).

Note:

l This function is only applicable to TUP and ISDN channels;

l This function can be invoked at anytime Attention that an immediate AutoDial failure will be caused if this function is called while the task of AutoDial is being executed on TUP channels; however, such failure won’t occur if this function is called while the task of AutoDial is being executed on ISDN channels.

Related Information:

Driver version | SynCTI Ver. 3.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmUnblockLocalCh , SsmBlockLocalPCM , SsmQueryLocalChBlockState ,

SsmBlockRemoteCh , SsmBlockRemotePCM


2.20.1.1.1.2 SsmUnblockLocalCh

Unblocks the local channel.

Format:

int SsmUnblockLocalCh(int ch)

Parameter Description:

ch

Channel number to be input

Return Value:

-1 | Call failed
0 | Successful

Function Description:

This function unblocks the local channels including the channel blocked by the function call of SsmBlockLocalCh or SsmBlockLocalPCM .

Note:

l This function is only applicable to the TUP and ISDN channels.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmBlockLocalCh , SsmUnblockLocalPCM , SsmQueryLocalChBlockState


2.20.1.1.1.3 SsmQueryLocalChBlockState

Obtains the blocking status (blocked/unblocked) of the local channel.

Format:

int SsmQueryLocalChBlockState(int ch, PDWORD pdwBlockState)

Parameter Description:

ch

Channel Number

pdwBlockState

Returns the blocking status of the local channel. Bit 1 means blocked, 0 means unblocked. Below is the list of meanings of each bit:

Bit 0 | Blocked because the application invokes the function SsmBlockLocalCh
Bit 1 | Blocked because the remote circuit blocking message (BLO) is received
Bit 2 | Blocked because the remote circuit group blocking message (SGB) is received
Bit 3 | Blocked because the remote circuit group blocking message (HGB) is received
Bit 4 | Blocked because the remote circuit group blocking message (MGB) is received
Bit 5 | Blocked because the application invokes the function SsmBlockLocalPCM
Bit31~Bit6 | Reserved

Return Value:

-1 | Call failed
0 | Successful

Function Description:

Obtains whether the channel is locally blocked and also retrieves the detailed blocking reason.

Note:

l This function is only applicable to the TUP channels.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmBlockLocalCh , SsmBlockLocalPCM


2.20.1.1.2 Blocking Whole Digital Trunk


2.20.1.1.2.1 SsmBlockLocalPCM

Blocks the local circuit group (the whole digital trunk).

Format:

int SsmBlockLocalPCM(int nLocalPcmNo)

Parameter Description:

nLocalPcmNo

The logical number of the PCM

Return Value:

-1 | Call failed
0 | Successful

Function Description:

This function blocks the whole digital trunk, and the consequence is that all the local channels included in the digital trunk are forbidden to make outgoing calls but still able to process incoming calls. The execution effect of this function call is equivalent to calling the function of SsmBlockLocalCh on all the channels of this PCM simultaneously . For more information about this function, refer to the description of the function SsmBlockLocalCh.

Note:

l This function is only applicable to the TUP channels.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmUnblockLocalPCM , SsmQueryLocalPCMBlockState , SsmBlockLocalCh


2.20.1.1.2.2 SsmUnblockLocalPCM

Unblocks the whole local digital trunk.

Format:

int SsmUnblockLocalPCM(int nLocalPcmNo)

Parameter Description:

nLocalPcmNo

The logical number of the PCM

Return Value:

-1 | Call failed
0 | Successful

Function Description:

This function unblocks the blocking on the digital trunk which is caused by the function call of SsmBlockLocalPCM . The execution effect is equivalent to calling the function of SsmUnblockLocalCh . Therefore for more information about this function, refer to the description of the function SsmUnblockLocalCh.

Note:

l This function is only applicable to the TUP channels.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmBlockLocalPCM , SsmQueryLocalPCMBlockState , SsmUnblockLocalCh


2.20.1.1.2.3 SsmQueryLocalPCMBlockState

Obtains the local blocking state of the digital trunk.

Format:

int SsmQueryLocalPCMBlockState(int nLocalPcmNo, PDWORD pdwBlockState)

Parameter Description:

nLocalPcmNo

PCM Logical Number

pdwBlockState

Returns the channel local blocking state. The bit value equals to 1 means ‘blocked’ and equals to 0 means ‘unblocked’. Below are the meanings of the bits:

Bit1~Bit0 | Reserved
Bit 2 | Blocked because of the reception of the circuit group blocking message SGB from the remote PBX.
Bit 3 | Blocked because of the reception of the circuit group blocking message HGB from the remote PBX.
Bit 4 | Blocked because of the reception of the circuit group blocking message MGB from the remote PBX.
Bit 5 | Blocked since the application invokes the function SsmBlockLocalPCM
Bit31~Bit6 | Reserved

Return Value:

-1 | Failed
0 | Successful

Function Description:

Obtains the local blocking state of the digital trunk

Note:

l This function is only applicable to the TUP channels.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmBlockLocalCh , SsmBlockLocalPCM


2.20.1.2 Functions for Blocking Remote End


2.20.1.2.1 Blocking Single Channel


2.20.1.2.1.1 SsmQueryOpBlockRemoteCh

Enquires whether the channel supports the blocking of the remote end.

Format:

int SsmQueryOpBlockRemoteCh(int ch)

Parameter Description:

ch

Channel number

Return Value:

-1 | Call failed
0 | The specified channel doesn’t support the remote blocking
1 | The specified channel supports the remote blocking

Function Description:

Enquires whether the channel supports remote blocking.

Note:

l Only the TUP channel and ISUP channel support to block the remote channel.

Related Information:

Driver version | SynCTI Ver. 3.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function:


2.20.1.2.1.2 SsmBlockRemoteCh

Blocks the remote channel.

Format:

int SsmBlockRemoteCh(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Call failed
0 | Successful

Function Description:

Blocks the remote channel in order to prevent the remote PBX from initiating call towards the local end on the remote channel, but the local end can still send the outgoing call towards the remote PBX. The remote channel means the circuit in the remote PBX which has the same CIC number as in the local channel. When the remote channel enters the blocking state, its outgoing call is forbidden, and the local channel is ensured to have no incoming call. The feature of blocking remote channel is normally used for system maintenance.

The following message processing procedure is used for blocking the remote channel:

(1) The driver sends the circuit blocking message BLO to the remote PBX;

(2) After the remote PBX receives the BLO message, it answers with the blocking acknowledgement message BLA;

(3) After receiving the BLA message from the remote PBX, the driver will throw out the event of E_CHG_RemoteChBlock to the application. After the above steps are completed, the remote channel blocking is finished.

The function SsmGetRemoteChBlockStatus could be used to check whether the remote channel blocking is finished.

Note:

l Only TUP channels and ISUP channels support the remote channel blocking.

Related Information:

Driver version | SynCTI Ver. 3.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmUnblockRemoteCh , SsmGetRemoteChBlockStatus


2.20.1.2.1.3 SsmUnblockRemoteCh

Unblocks the remote channel blocking.

Format:

int SsmUnblockRemoteCh(int ch)

Parameter Description:

ch

Channel number

Return Value:

-1 | Call failed
0 | Successful

Function Description:

Unblocks the remote channel blocking in order to resume the call towards the local end on the remote channel. The following message processing procedure is used for unblocking the remote channel:

(1) The driver sends the circuit unblocking message UBL to the remote PBX;

(2) After the remote PBX receives the UBL message, it answers with the unblocking acknowledgement message UBA;

(3) After receiving the UBA message from the remote PBX, the driver will throw out the event of E_CHG_RemoteChBlock to the application. After the above steps are completed, the remote channel unblocking is finished.

The function SsmGetRemoteChBlockStatus could be used to check whether the remote channel unblocking is finished.

Note:

l Only TUP channels and ISUP channels support the remote channel unblocking.

Related Information:

Driver version | SynCTI Ver. 3.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmBlockRemoteCh , SsmGetRemoteChBlockStatus , SsmBlockRemotePCM


2.20.1.2.1.4 SsmGetRemoteChBlockStatus

Enquires whether the channel on the remote PBX is blocked by the local end.

Format:

int SsmGetRemoteChBlockStatus(int ch)

Parameter Description:

ch

Channel number

Return Value:

-1 | Call failed
0 | Not blocked by the local end, or the blocking caused by the local end has been successfully unblocked
1 | The remote end is blocked successfully
2 | The circuit blocking message has been sent, waiting for the blocking acknowledgement message from the remote PBX
3 | The circuit unblocking message has been sent, waiting for the unblocking acknowledgement message from the remote PBX

Function Description:

Enquires whether the channel on the remote PBX is blocked by the local end. The return value can be used to check the executing status of the function SsmBlockRemoteCh or SsmUnblockRemoteCh .

Note:

l Only TUP channels and ISUP channels support to check the remote channel blocking status

Related Information:

Driver version | SynCTI Ver. 3.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmBlockRemoteCh , SsmUnblockRemoteCh


2.20.1.2.2 Blocking Whole Digital Trunk


2.20.1.2.2.1 SsmBlockRemotePCM

Blocks the remote circuit group.

Format:

int SsmBlockRemotePCM(int nLocalPcmNo, DWORD dwBlockMode)

Parameter Description:

nLocalPcmNo | PCM logical number
dwBlockMode | Choose the circuit group blocking message sent to the remote PBX. Range of value: TUP protocol: 1: send the maintenance oriented group blocking message for (MGB); 2: send the hardware failure oriented group blocking message for hardware failure (HGB); 3: send the software generated group blocking message (SGB). ISUP protocol: 0: send the maintenance oriented group blocking message (CGB); 1: send the hardware failure oriented group blocking message (CGB)

Return Value:

-1 | Call failed
0 | Successful

Function Description:

Uses the circuit group blocking message to block the whole digital trunk of the remote PBX, consequently, all the channels included in this PCM of the remote PBX are not able to initiate outgoing calls, and only the incoming calls can be processed. The execution effect of this function call is equivalent to calling the function of SsmBlockRemoteCh on all the channels of this PCM simultaneously.

The following message processing procedure is used for blocking the remote circuit group:

(1) According to the settings of the parameter dwBlockMode, the driver sends the specified group blocking message towards the remote PBX;

(2) After the remote PBX receives the group blocking message, it will answer with the message of group blocking acknowledgement (for the TUP protocol, the corresponding blocking acknowledgement messages for the group blocking messages of MGB, HGB and SGB are MBA, HBA and SBA respectively; for the ISUP protocol, the corresponding blocking acknowledgement message for the group blocking message of CGB is CGBA);

(3) After receiving the group blocking acknowledgement message, the driver will send the event of E_CHG_RemotePCMBlock to the application. After the above steps are completed, the remote channel unblocking is finished.

The function SsmGetRemotePCMBlockStatus could be used to check whether the remote circuit group blocking is finished.

Note:

l This function only supports the TUP protocol and ISUP protocol;

l According to the definition of the TUP protocol and ISUP protocol, the circuit group blocking message is only effective after its transmitted twice. Therefore the driver will send the circuit group blocking message to the remote PBX twice continuously, but the application will only need to call this function once.

Related Information:

Driver version | SynCTI Ver. 3.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmUnblockRemotePCM , SsmGetRemotePCMBlockStatus

Related Event: E_CHG_RemotePCMBlock


2.20.1.2.2.2 SsmUnblockRemotePCM

Unblocks the remote circuit group.

Format:

int SsmUnblockRemotePCM(int nLocalPcmNo, DWORD dwUnblockMode)

Parameter Description:

nLocalPcmNo | PCM logic number
dwBlockMode | Selects the circuit group unblocking message sent to the remote PBX. Range of value: TUP protocol: 1: transmit MGU to unblock the circuit group blocking caused by the message of MGB; 2: transmit HGU to unblock the circuit group blocking caused by the message of HGB; 3: transmit SGU to unblock the circuit group blocking caused by the message of SGB. ISUP protocol: 0: transmit the maintenance oriented circuit group unblocking message CGU; 1: transmit the hardware failure oriented circuit group unblocking message CGU

Return Value:

-1 | Call failed
0 | Successful

Function Description:

Unblocks the whole digital trunk of the remote PBX, consequently, all the channels included in this PCM of the remote PBX are enabled to initiate outgoing calls. The execution effect of this function call is equivalent to calling the function of SsmUnBlockRemoteCh on all the channels of this digital trunk simultaneously.

The following message processing procedure is used for unblocking the remote circuit group:

(1) According to the settings of the parameter dwBlockMode, the driver sends the specified group unblocking message towards the remote PBX;

(2) After the remote PBX receives the group unblocking message, it will answer with the message of group unblocking acknowledgement (for the TUP protocol, the corresponding unblocking acknowledgement messages for the group unblocking messages of MGU, HGU and SGU are MUA, HUA and SUA respectively; for the ISUP protocol, the corresponding unblocking acknowledgement messages for the group blocking messages of CGU is CGUA);

(3) After receiving the group unblocking acknowledgement message, the driver will send the event of E_CHG_RemotePCMBlock to the application. After the above steps are completed, the remote channel unblocking is finished.

The function SsmGetRemotePCMBlockStatus could be used to check whether the remote circuit group unblocking is finished.

Note:

l This function only supports the TUP protocol and ISUP protocol;

l According to the definition of the TUP protocol and ISUP protocol, the circuit group unblocking message is only effective after its transmitted twice. Therefore the driver will send the circuit group unblocking message to the remote PBX twice continuously, but the application will only need to call this function once.

Related Information:

Driver version | SynCTI Ver. 3.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmBlockRemotePCM , SsmGetRemotePCMBlockStatus

Related Event: E_CHG_RemotePCMBlock


2.20.1.2.2.3 SsmGetRemotePCMBlockStatus

Obtains the blocking status of the circuit group.

Format:

int SsmGetRemotePCMBlockStatus(int nLocalPcmNo, DWORD dwBlockMode)

Parameter Description:

nLocalPcmNo | PCM Logical number
dwBlockMode | Selects the circuit group blocking type to be enquired, the range of value: TUP protocol: 1: maintenance oriented circuit group blocking status; 2: hardware failure oriented circuit group blocking status; 3: circuit group blocking status generated by software. ISUP protocol: 0: maintenance oriented circuit group blocking status; 1: hardware failure oriented circuit group blocking status.

Return Value:

-1 | Call failed
0 | The remote circuit group is not blocked, or the remote circuit group is unblocked successfully
1 | The remote circuit group is blocked successfully
2 | The circuit group blocking message has been sent already, waiting for the acknowledgement message from the remote PBX
3 | The circuit group unblocking message has been sent already, waiting for the acknowledgement message from the remote PBX

Function Description:

Obtains the blocking status of the circuit group. The return value may be used to check the executing status of the function SsmBlockRemotePCM or SsmUnblockRemotePCM.

Note:

l This function only supports the TUP protocol and ISUP protocol.

Related Information:

Driver version | SynCTI Ver. 3.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmBlockRemotePCM , SsmUnblockRemotePCM


2.20.2 SS7-MTP3 Based API


2.20.2.1 SsmSendSs7Msu

Sends a message (MSU) to the remote signaling point.

Format:

int SsmSendSs7Msu(WORD wMsuLength, PUCHAR pucMsuBuf)

Parameter Description:

wMsuLength | The length (bytes) of the transmitted MSU, the maximum length can’t exceed 273
pucMsuBuf | The first address pointer storing the MSU data. The first byte of pucMsuBuf (i.e. pucMsuBuf[0]) must be the SIO field

Return Value:

0 | Successful
-1 | Failed. Below are the possible failure reasons: ² Interruption of MTP3 Service ² The system doesn’t support SS7 signaling ² The API of the system is not open yet

Function Description:

Sends a message (MSU) to the remote signaling point.

Note: none

Related Information:

Driver version | SynCTI Ver. 3.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetSs7Msu


2.20.2.2 SsmGetSs7Msu

Enquires whether there exist MSU messages in the MSU receiving buffer area of the driver.

Format:

int SsmGetSs7Msu(PUCHAR* ppucMsuBuf)

Parameter Description:

ppucMsuBuf

Returns the first address pointer pointing to the buffer area in the driver storing MSU data. The first byte of the MSU message is SIO filed. (Note: the pointer of ppucMsgBuf should be claimed before it’s invoked, and its length can’t be specified)

Return Value:

0 | The receiving buffer area of MSU messages in the driver is NULL
>0 | The length (bytes) of the current MSU
-1 | Failed. The failure reason may be: ² The system doesn’t support SS7 signaling; ² The API of the system is not open yet

Function Description:

Enquires whether there exist MSU messages in the MSU receiving buffer area in the driver. If there exist MSU messages, takes out the earliest received message.

Each time when the driver receives a MSU message, it will store it in the MSU receiving buffer area in the driver, and then throw out the message of E_RCV_Ss7Msu to the application.

Note:

l The way to output SS7 MSU can be set by the configuration item GetMsuOnAutoHandle.

l When the MSU receiving buffer area is full, the subsequently arrived MSU messages will be discarded. Hence the application needs to take out the message as soon as possible and process it.

Related Information:

Driver version | SynCTI Ver. 3.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSendSs7Msu

Related Event:E_RCV_Ss7Msu


2.20.2.3 SsmGetMtp3State

Refer to SsmGetMtp3StateEx


2.20.2.4 SsmGetMtp3StateEx

Obtains whether the service from the original signaling point to the destination signaling point is open.

Format:

int SsmGetMtp3State()

int SsmGetMtp3StateEx(int nDpcNo)

Parameter Description:

nDpcNo

The number of the destination signaling point. The corresponding relation between the number and the code of the destination signaling point is specified in the SS7 server configuration program

Return Value:

1 | The service is available
0 | The service is interrupted
-1 | Call failed

Function Description:

Obtains whether the service from the original signaling point to the destination signaling point is open. Only when the service is open, the application is able to call the function of SsmSendSs7Msu and send message to the DPC.

SsmGetMtp3StateEx supports the application environment with multiple destination signaling points, and that SsmGetMtp3State is an old version function, it’s only applicable to the application environment with a direct connection to a single destination signaling point which is equivalent to calling the function SsmGetMtp3StateEx when nDpcNo is set 0.

Note:

l Because the SS7 signaling has the auto resume feature, when this function is used as the alarm source of the SS7 signaling monitoring, the alarm signal should be sent out after the service interruption is detected and has been sustained a certain period of time;

l When the SS7 server detects that the state of the link to the destination signaling point is changed, after saving the service state of this signaling point, it throws out the event of E_CHG_Mtp3State to the driver.

Related Information:

Driver version | SynCTI Ver. 3.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetMtp2Status

Related Event: E_CHG_Mtp3State


2.20.2.5 SsmGetMtp2Status

Obtains the operating status of the 64kbps signaling link in the SS7 signaling link set.

Format:

int SsmGetMtp2Status(int nLinkNum)

Parameter Description:

nLinkNum

The number of the signaling link which is specified in the SS7 server configuration program

Return Value:

0 | The DSP software is uploaded but not started to run
1 | Service is interrupted
2 | Initial framing
3 | Framed/ready
4 | Framed/not ready
5 | Service is open
6 | Processor failure
-1 | Call failed

Function Description:

This function obtains the operating status of the signaling link in the SS7 signaling. Only when the status value equals to 5 (service is open), can this signaling link be used.

Note:

l This function returns the information of the MTP2 layer. The information is normally displayed for monitoring and maintenance.

Related Information:

Driver version | SynCTI Ver. 3.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetMtp3State, SsmGetMtp3StateEx


2.20.2.6 SsmSendSs7MsuEx

Packs the message header according to the channel number (ch) and leaves the message content to be configured by the application itself.

Format:

int WINAPI SsmSendSs7MsuEx(int ch, int nNewStep, WORD wMsuLength, PUCHAR pucMsuBuf)

Parameter Description:

ch | Channel number
nNewStep | Obligate
wMsuLength | Length of the message content, which is calculated from the message type but excludes the message header
pucMsuBuf | Length of the message

Return Value:

-1 | Call failed: Wrong parameter
0 | Call failed: Fail to send
1 | Call successful

Function Description:

This function is used to pack the message header according to the channel number (ch) and leave the message content to be configured by the application itself.


2.20.2.7 SsmGetMaxSs7link

Gets the total number of configured SS7 links in the system.

Format:

int WINAPI SsmGetMaxSs7link( )

Parameter Description:

Return Value:

-1 | Call failed
≥0 | The total number of configured SS7 links in the system

Function Description:

Gets the total number of configured SS7 links in the system.

Note: None

Related Information:

Driver version | SynCTI Ver. 5.1.0.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function:


2.20.2.8 SsmGetSs7Mtp2Msu

Gets MSU messages at MTP2 layer on a specified SS7 link.

Format:

int WINAPI SsmGetSs7Mtp2Msu(int ss7link, PUCHAR pucPara, PUCHAR* ppucMsuBuf)

Parameter Description:

ss7link | SS7 link number
pucPara | Obligate
ppucMsuBuf | The first address pointer pointing to the buffer area within the driver which stores MSU messages. The first byte of an MSU message is the SIO field (Note that ppucMsgBuf should be declared before invoking).

Return Value:

-1 | Call failed. The failure reason may be: 1) SS7 signalling unsupported by the system; 2) API functions for the system not opened yet.
0 | The buffer area within the driver to receive MSU messages is empty.
>0 | The current length of MSU message, calculated by byte.

Function Description:

Queries if the buffer area for MTP2 MSU reception in the driver has received any MSU message; if has, take out the first received message.

Note:

l The way to handle SS7 MTP2 MSU messages can be determined by setting the configuration item AppHandleMtp2Msu;

l If the MSU reception buffer area in the driver is full, the subsequently received MSU messages will be discarded. Therefore, the application should guarantee to take out and handle the received messages as soon as possible.

Related Information:

Driver version | SynCTI Ver. 5.1.0.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSendSs7Mtp2Msu


2.20.2.9 SsmSendSs7Mtp2Msu

Sends MSU messages at MTP2 layer on a specified SS7 link.

Format:

int WINAPI SsmSendSs7Mtp2Msu(int ss7link, WORD wMsuLength, PUCHAR pucMsuBuf)

Parameter Description:

ss7link | SS7 link number
wMsuLength | The length (size) of the sent MSU which must be less than or equal to 273 bytes.
pucMsuBuf | The first address pointer pointing to MSU messages. The first byte of an MSU message is the SIO field.

Return Value:

-1 | Call failed
0 | Call successful

Function Description:

Sends MSU messages at MTP2 layer on a specified SS7 link.

Note:

l The way to handle SS7 MTP2 MSU messages can be determined by setting the configuration item AppHandleMtp2Msu.

Related Information:

Driver version | SynCTI Ver. 5.1.0.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetSs7Mtp2Msu


2.20.3 Advanced Functions for ISDN


2.20.3.1 SsmGetIsdnMsu

Takes out an ISDN message from the buffer area in the driver.

Format:

int SsmGetIsdnMsu(int nPcmId, PUCHAR pucMsuBuf)

Parameter Description:

nPcmId | The logical number of the digital trunk
pucMsuBuf | Returns the ISDN message. The storage space of pucMsuBuf is allocated by the application, its size can’t be less than 256 bytes

Return Value:

0 | There are no messages in the buffer area
>0 | The actual length (bytes) of the message in pucMsuBuf
-1 | Call failed

Function Description:

Takes out an ISDN message from the buffer area in the driver.

Note:

l When the configuration item AutoHandleIsdn is set to 1, messages are processed by the driver; when it is set to 0, messages are processed by the application program.

l In real practice, this function call gets valid only when the configuration item AutoHandleIsdn is set to 0.

Related Information:

Driver version | SynCTI Ver. 4.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmCheckIsdnMsu


2.20.3.2 SsmSendIsdnMsu

Sends an ISDN message.

Format:

int SsmSendIsdnMsu(int nPcmId, int nMsgLen, PUCHAR pucMsuBuf)

Parameter Description:

nPcmId | The logical number of the digital trunk
nMsgLen | The actual length (bytes) of the message in pucMsuBuf
pucMsuBuf | The buffer area for ISDN messages

Return Value:

0 | Successful
-1 | Call failed

Function Description:

Sends an ISDN message on TS16 of the designated digital trunk.

Note:

l When the configuration item AutoHandleIsdn is set to 1, messages are processed by the driver; when it is set to 0, messages are processed by the application program.

l In real practice, this function call gets valid only when the configuration item AutoHandleIsdn is set to 0.

Related Information:

Driver version | SynCTI Ver. 4.0or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetIsdnMsu


2.20.3.3 SsmCheckIsdnMsu

Checks whether there exist ISDN messages in the internal buffer area of the driver.

Format:

int SsmCheckIsdnMsu(int nPcmId)

Parameter Description:

nPcmId

The logical number of the digital trunk

Return Value:

-1 | error
≥0 | The number of ISDN messages

Function Description:

Checks whether there exist ISDN messages in the internal buffer area of the driver.

Note:

l When the configuration item AutoHandleIsdn is set to 1, messages are processed by the driver; when it is set to 0, messages are processed by the application program.

l In real practice, this function call gets valid only when the configuration item AutoHandleIsdn is set to 0.

Related Information:

Driver version | SynCTI Ver. 4.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetIsdnMsu


2.20.3.4 SsmISDNGetStatus

Obtains the operating status of the HDLC link in ISDN protocol.

Format:

int SsmISDNGetStatus(int nPcmNo, int *pL3Start, int *pL2DStatus, int *pL2D_L3Atom, int * pL3_L2DAtom, int *pRef_ind)

Parameter Description:

nPcmNo | The logical number of the local digital trunk
pL3Start | Returns the pointer to the information indicating whether L3 in ISDN protocol is started. The return value equals to 1 means that it’s started, equals to 0 means that it’s not started
pL2Dstatus | Returns the pointer to the state of L2 in ISDN protocol. For L2, there are 8 states as follows: State 1 TEI unassigned State 2 Assign awaiting TEI State 3 Establish awaiting TEI State 4 TEI assigned State 5 Awaiting establishment State 6 Awaiting release State 7 Multiple frame established State 8 Timer recovery (See Q921 for detailed information)
pL2D_L3Atom | Returns the pointer which points to the received message primitives from L2 to L3 in ISDN protocol. (See Q921 for detailed information)
pL3_L2DAtom | Returns the pointer which points to the already sent message primitives from L3 to L2 in ISDN protocol. (See Q921 for detailed information)
pRef_ind | Returns the pointer to the inside indicator value in ISDN protocol (the fixed value is 0xfe)

Return Value:

0 | Successful
-1 | Call failed

Function Description:

Obtains the operating status of the HDLC link in ISDN protocol.

Note:

l This function is normally called in the response code of the event of E_CHG_ISDNStatus.

Related Information:

Driver version | SynCTI Ver. 3.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll


2.20.3.5 SsmGetUserInfo

Obtains the content of the User-User message unit.

Format:

int WINAPI SsmGetUserInfo( int ch, PUCHAR pUUI)

Parameter Description:

ch | The channel number
pUUI | The pointer pointing to the buffer area storing content of User-User message units. The storage space, not less than 131 bytes, is allocated by the application.

Return Value:

≥0 | Call successful. Returns the length of content of the User-User message unit.
-1 | Call failed.

Function Description:

Obtains the content of the User-User message unit.

Note:

Related Information:

Driver version | SynCTI Ver. 5.1.0.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Event: none


2.20.3.6 SsmISDNGetProgressMsg

Obtains the content of the PROGRESS message.

Format:

int WINAPI SsmISDNGetProgressMsg(int ch, BYTE* pbMsg)

Parameter Description:

ch | The channel number
pbMsg | The pointer pointing to the buffer area storing the PROGRESS message. The storage space, allocated by the application, should be not less than 300 bytes.

Return Value:

≥0 | Call successful. Returns the length of the PROGRESS message in byte.
-1 | Call failed.

Function Description:

Obtains the content of the PROGRESS message.

Note:

Related Information:

Driver version | SynCTI Ver. 5.2.0.1 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function:


2.20.4 Advanced Functions for China SS1


2.20.4.1 Controlling ABCD Signaling Codes


2.20.4.1.1 SsmGetCAS

Obtains the state of the ABCD signaling at the receiving end on the channel.

Format:

int SsmGetCAS(int ch)

Parameter Description:

ch

Channel number

Return Value:

-1 | Call failed
³0 | The higher 4 bits of the return value are 0, the lower 4 bits are the received CAS signaling bits at the local end: bit3 bit2 bit1 bit0 A B C D

Function Description:

Obtains the current value of the ABCD signaling sent by the remote PBX.

Note:

l The ABCD signaling is transmitted on TS 16 of E1;

l The features of this function may also be implemented by the event of E_RCV_CAS . The event of E_RCV_CAS is recommended to be used.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSendCAS


2.20.4.1.2 SsmSendCAS

Sets the state of the ABCD signaling at the transmitting end on the channel.

Format:

int SsmSendCAS(int ch, BYTE btCas)

Parameter Description:

ch | Channel number
btCas | Transmit the CAS signaling value, the higher 4 bits are 0, the lower 4 bits are the new state of the ABCD signaling bits: bit3 bit2 bit1 bit0 A B C D

Return Value:

-1 | Call failed
0 | Successful

Function Description:

Sets the state of the ABCD signaling at the local end.

Note:

l The ABCD signaling is transmitted on TS 16 of E1;

l If the channel is configured to be automatic call connection, calling this function will return -1.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetSendingCAS, SsmGetCAS


2.20.4.1.3 SsmGetSendingCAS

Obtains the state of the ABCD signaling at the transmitting end on the channel.

Format:

int SsmGetSendingCAS(int ch)

Parameter Description:

ch

Channel number

Return Value:

-1 | Call failed
³0 | The lowest 4 bits of the return value are the ABCD signaling bits of the transmit end: bit3 bit2 bit1 bit0 A B C D Other bits are reserved.

Function Description:

Obtains the state of the ABCD signaling at the transmitting end on the channel.

Note:

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetCAS, SsmSendCAS


2.20.4.1.4 SsmSetSendCASFlag

Sets if the channel is allowed to send CAS signals.

Format:

int WINAPI SsmSetSendCASFlag(int ch, int nCASFlag)

Parameter Description:

ch | Channel number
nCASFlag | indicates if the channel is allowed to send CAS signals. 0: allowed 1: not allowed

Return Value:

-1 | Call failed
=0 | Call successful

Function Description:

Sets if the channel is allowed to send CAS signals.

Note: None

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetSendCASFlag, SsmSendCAS


2.20.4.1.5 SsmGetSendCASFlag

Obtains the flag that tells if the channel is allowed to send CAS signals.

Format:

int WINAPI SsmGetSendCASFlag(int ch, int* pCASFlag)

Parameter Description:

ch | Channel number
pCASFlag | a pointer used to obtain the flag that tells if the channel is allowed to send CAS signals

Return Value:

-1 | Call failed
=0 | Call successful

Function Description:

Obtains the flag that tells if the channel is allowed to send CAS signals.

Note: None

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetCAS, SsmSetSendCASFlag


2.20.4.2 Controlling R2 Signal Transceiver


2.20.4.2.1 SsmSetRxR2Mode

Sets the R2 signal receiver.

Format:

int SsmSetRxR2Mode(int ch, int nMode, BOOL bEnable)

Parameter Description:

ch | Channel Number
nMode | The operating mode of the R2 signal transceiver: =0: Receives the backward R2 signal =1: Receives the forward R2 signal
bEnable | The operating status of the R2 signal transceiver: =TRUE: turned on =FALSE: turned off

Return Value:

-1 | Call failed
0 | Successful

Function Description:

Sets the R2 signal receiver.

Note:

l If the channel is configured to be automatic call connection, calling this function will return -1;

l The R2 signal transceiver and the DTMF detector can’t work simultaneously. Hence when the R2 signal transceiver is used, the DTMF detector must be turned off. After the MFC process is terminated, the DTMF detector needs to be started via the function call of SsmEnableRxDtmf.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetR2


2.20.4.2.2 SsmGetR2

Obtains the detected result of the R2 signal receiver.

Format:

int SsmGetR2(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Call failed
0 | R2 signal is not detected on the line
1~15 | R2 signal is detected on the line. For the forward R2 signal, the range of the return value is: 1~15; For the backward R2 signal, the range of the return value is: 1~6

Function Description:

Obtains the detected result of the R2 signal receiver.

Note:

l If the channel is configured to be automatic call connection, calling this function will return -1;

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSetRxR2Mode, SsmSendR2, SsmSendR2Ex


2.20.4.2.3 SsmSendR2

Generates an R2 signal on the channel.

Format:

int SsmSendR2(int ch, int nMode, BYTE btR2)

Parameter Description:

ch | Channel Number
nMode | The operating mode of the R2 signal generator: =0: generates the backward R2 signal; =1: generates the forward R2 signal
btR2 | The code value of the R2 signal: l For the forward R2 signal, range of value: 1~15; l For the backward R2 signal, range of value: 1~6

Return Value:

-1 | Call failed
0 | Successful

Function Description:

Generates an R2 signal on the channel which continues until the application calls the function SsmStopSendR2.

Note:

l If the channel is configured to be automatic call connection, calling this function will return -1.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmStopSendR2, SsmGetSendingR2, SsmGetR2, SsmSendR2Ex


2.20.4.2.4 SsmSendR2Ex

Generates an R2 signal which lasts for a specified period of time on the channel.

Format:

int SsmSendR2Ex(int ch, int nMode, BYTE btR2, DWORD dwKeepTime)

Parameter Description:

ch | Channel Number
nMode | The operating mode of the R2 signal generator: =0: generates the backward R2 signal; =1: generates the forward R2 signal
btR2 | The code value of the R2 signal: l For the forward R2 signal, range of value: 1~15; l For the backward R2 signal, range of value: 1~6
dwKeepTime | The R2 signal duration, calculated by millisecond(ms)

Return Value:

-1 | Call failed
0 | Successful

Function Description:

Generates an R2 signal on the channel which lasts for the time specified by dwKeepTime. The function SsmStopSendR2 can be called to stop the R2 signal.

Note:

l If the channel is configured to be automatic call connection, calling this function will return -1.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmStopSendR2 ， SsmGetSendingR2 ， SsmGetR2 ， SsmSendR2


2.20.4.2.5 SsmStopSendR2

Stops generating an R2 signal on the channel.

Format:

int SsmStopSendR2(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Call failed
0 | Successful

Function Description:

Stops generating an R2 signal on the channel.

Note:

l If the channel is configured to be automatic call connection, calling this function will return -1.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSendR2, SsmSendR2Ex


2.20.4.2.6 SsmGetSendingR2

Obtains the operating mode of the R2 signal generator on the channel.

Format:

int SsmGetSendingR2(int ch, int* pnMode, BYTE* pbtR2)

Parameter Description:

ch | Channel Number
pnMode | Returns the operating mode of the R2 signal generator: =0: generates the backward R2 signal; =1: generates the forward R2 signal
pbtR2 | Returns the code value of the R2 signal: For the forward R2 signal, range of value: 1~15; For the backward R2 signal, range of value: 1~6

Return Value:

-1 | Call failed
0 | Successful

Function Description:

Obtains the operating mode of the R2 signal generator on the channel.

Note:

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSendR2, SsmSendR2Ex


2.21 Functions for SHV Series Boards (CTI Series)


2.21.1 SsmGetMaxVCh

Obtains the total number of the voice-alteration channels in the application.

Format:

int SsmGetMaxVCh()

Parameter Description: none

Return Value:

-1 | Call failed
≥0 | The total number of the voice-alteration channels

Function Description:

Obtains the total number of the voice-alteration channels in the application.

Note:

Related Information:

Driver version | SynCTI Ver. 4.7.2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetMaxFreeVCh


2.21.2 SsmGetMaxFreeVCh

Obtains the total number of the free voice-alteration channels.

Format:

int SsmGetMaxFreeVCh()

Parameter Description: none

Return Value:

-1 | Call failed
≥0 | The total number of the free voice-alteration channels

Function Description:

Obtains the total number of the free voice-alteration channels.

Note:

Related Information:

Driver version | SynCTI Ver. 4.7.2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetMaxVCh


2.21.3 SsmBindVCh

Binds the voice channel to the voice-alteration channel.

Format:

int SsmBindVCh(int iCh)

Parameter Description: none

iCh

Voice channel number

Return Value:

0 | Successful
-1 | Call failed: iCh is out of range
-2 | Call failed: iCh doesn’t support the bus exchange
-3 | Call failed: There is no free voice-alteration channel
-4 | Call failed: iCh is already bound to a voice-alteration channel
-5 | Call failed: The driver hasn’t been loaded

Function Description:

Binds the voice channel to the voice-alteration channel.

When the driver invokes this function, it will automatically allocate a free voice-alteration channel and bind it to

the vioce channel iCh. The incoming call signal on the channel iCh will enter the voice-alteration channel and be altered at first, then the altered voice signal will be sent to the bus.

Note:

l After the driver is successfully loaded, the application may invoke this function at anytime.

Related Information:

Driver version | SynCTI Ver. 4.7.2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmUnBindVCh, SsmSetVoiceEffect

Sample Code:

Example 1: There is two-way connection between channel 1 and channel 2, the voice from channel 1 needs to be altered, the voice from channel 2 doesn’t need to be altered, below is the implementing code:

…… // The code used to initiate the call

SsmBindVCh(1); // Bind the channel 1 to a voice-alteration channel

SsmSetVoiceEffect(1,180); // Set the voice alteration effect

SsmTalkWith(1,2); // Establish two-way connection between channel 1 and channel 2

…… // Calling

SsmUnBindVCh(1); // The call is completed, unbind the channel 1 to the voice-alteration channel

SsmStopTalkWith(1,2); // Disconnect the two-way connection

Example 2: Channel 1, channel 2 and channel 3 enter a conference room, channel 1 and channel 2 require the voice alteration. Below is the implementing code:

int GroupID = SsmCreateConfGroup(…); // Create a conference room

……

SsmBindVCh(1);

SsmJoinConfGroup(GroupID,1,…); //Channel 1 enters the conference room

SsmBindVCh(2);

SsmJoinConfGroup(GroupID,2,…); //Channel 2 enters the conference room

SsmJoinConfGroup(GroupID,3,…); //Channel 3 enters the conference room

……


2.21.4 SsmUnBindVCh

Unbinds the voice channel to the voice-alteration channel.

Format:

int SsmUnBindVCh(int iCh)

Parameter Description:

iCh

Voice channel number

Return Value:

0 | Successful
-1 | Call failed: iCh is out of range
-2 | Call failed: iCh doesn’t support bus exchange
-3 | Call failed: iCh isn’t bound to anyone of the voice alteration channels
-4 | Call failed: the driver is not loaded yet

Function Description:

Unbinds the voice channel to the voice-alteration channel. When the voice-alteration channel is unbound, it will be automatically reclaimed and enter the idle queue.

Note:

l If the voice channel doesn’t need voice alteration anymore, it needs to be unbound to the voice alteration channel.

Related Information:

Driver version | SynCTI Ver. 4.7.2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmBindVCh


2.21.5 SsmSetVoiceEffect

Sets the voice-alteration effect.

Format:

int SsmSetVoiceEffect(int iCh, int iValue)

Parameter Description:

iCh | Voice channel number
iValue | Voice alteration effect, range of value: 70~220, 128 means the original voice (unchanged), greater than 128 means the female voice effect, less than 128 means the male voice effect

Return Value:

0 | Successful
-1 | Call failed: iCh is out of range
-2 | Call failed: iCh isn’t bound to anyone of the voice alteration channels
-3 | Call failed: iValue is out of range
-4 | Call failed: the driver is not loaded

Function Description:

Sets the voice-alteration effect.

Note:

l Only when the voice channel has bound to a voice alteration channel, can this function be called;

l It’s difficult to describe the voice alteration effect in details, set iValue based on the actual testing effect.

Related Information:

Driver version | SynCTI Ver. 4.7.2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmBindVCh, SsmGetVoiceEffect


2.21.6 SsmGetVoiceEffect

Obtains the voice-alteration effect.

Format:

int SsmGetVoiceEffect(int iCh)

Parameter Description:

iCh

Voice channel number

Return Value:

>0 | Successful, returns the voice-alteration effect, refer to the description of the function SsmSetVoiceEffect for the detailed values
-1 | Call failed: iCh is out of range
-2 | Call failed: iCh is not bound to anyone of the voice-alteration channels
-3 | Call failed: the driver isn’t loaded yet

Function Description:

Obtains the voice-alteration effect.

Note:

Related Information:

Driver version | SynCTI Ver. 4.7.2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSetVoiceEffect


2.22 Functions for SHN Series Boards (CTI Series)


2.22.1 Setting Special Programming Interfaces for SIP Channel


2.22.1.1 SsmIpGetSessionCodecType

Obtains the CODEC actually used by a designated channel in an ongoing call.

Format:

int SsmIpGetSessionCodecType (int ch)

Parameter Description:

ch

Channel number

Return Value:

-1 | Call failed
6 | A-Law format is used by the designated channel in the ongoing call
7 | µ-Law format is used by the designated channel in the ongoing call
131 | G.729A format is used by the designated channel in the ongoing call

Function Description:

Obtains the CODEC actually used by a designated channel in an ongoing call.

Note:

l This function can be invoked only when the channel stays in the ‘Talking’ state.

l It is called SsmIpGetUsingCodecType in SynCTI 5.1.0.0 and below versions.

Related Information:

Driver version | SynCTI Ver. 5.0.0.0 or above
Header | Shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll


2.22.1.2 SsmIpSetForwardNum

Sets a forward number for a designated channel.

Format:

int SsmIpSetForwardNum(int ch, LPSTR pszForwardNum)

Parameter Description:

ch | Channel number
pszForwardNum | Forward number. It being with a NULL string means the previously set forward number is cancelled.

Return Value:

-1 | Call failed
0 | Call successful

Function Description:

Sets a forward number for a designated channel. Then any call to the designated channel will be forwarded unconditionally to the number set by this function.

Note:

l If a forward number has been set for a specified channel before, it can be cancelled by invoking this function again to set pszForwardNum with a null string.

Related Information:

Driver version | SynCTI Ver. 5.0.0.0 or above
Header | Shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll


2.22.1.3 SsmIpInitiateTransfer

Sets a transfer number for a designated channel.

Format:

int SsmIpInitiateTransfer(int ch, LPSTR pszTransferTo)

Parameter Description:

ch | Channel number
pszTransferTo | Transfer number

Return Value:

-1 | Call failed
0 | Call successful

Function Description:

Sets a transfer number for a designated channel. Then a call involving the designated channel will be transferred to the number set by this function.

Note:

l This function can be invoked only when the channel stays in the ‘Talking’ state.

Related Information:

Driver version | SynCTI Ver. 5.0.0.0 or above
Header | Shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll


2.22.1.4 SsmIpGetMessageField

Obtains a series of field values in messages related to the call establishment of a designated channel.

Format:

int SsmIpGetMessageField(int ch, int type, LPSTR szBuffer, int *pSize)

Parameter Description:

ch | Channel number
Type | Field type to be obtained
SzBuffer | Buffer used to store the obtained field content
PSize | A pointer pointing to the value which indicates the size of the user-provided buffer. If this function call is successful, the value it points to is the size of valid data obtained; if this function call is failed, the value it points to is the buffer size actually needed.

Return Value:

-1 | Call failed
0 | Call successful

Function Description:

Obtains a series of field values in messages related to the call establishment of a designated channel.

The value of the parameter ‘Type’ is as follows.

l TYPE_MESSAGE_CONTACT

Obtains the content of the ‘Contact’ field in the ‘INVITE’ or ‘REINVITE’ message. It only works for the called party. If there are multiple ‘Contact’ fields in the message body, the value it returns will be shown in the following format.

Contact0

\0

Contact1

\0

…

Contactn

\0

\0

Note:

l This function can be invoked only when the channel stays in the ‘Talking’ state.

Related Information:

Driver version | SynCTI Ver. 5.0.0.0 or above
Header | Shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll


2.22.1.5 SsmSipBoardRegister

A board which supports the SIP protocol sends the Register request to SIP Server.

Format:

int SsmSipBoardRegister(int nBId, LPSTR szRegSrvAddr, LPSTR szUserName, LPSTR szPasswd, LPSTR szRealm, int nExpires)

Parameter Description:

nBId | Board ID
szRegSrvAddr | IP address of SIP Server
szUserName | Username registered for the corresponding board
szPasswd | Password registered for the corresponding board (only useful when the registration on SIP Server needs to be authenticated)
szRealm | Alias of SIP Server
nExpires | Valid expiration time of the registration

Return Value:

-1 | Registration failed, all channels on the corresponding board go into the ‘UNUSABLE’ state.
0 | Registration successful

Function Description:

A board which supports the SIP protocol sends the Register request to SIP Server.

Note:

l If there are channels on the board not staying in ‘IDLE’ or ‘UNUSABLE’ state, this operation is refused.

l If the board has been registered: only the update of the registered messages can be sent (only allowed to update ‘Expires’). That is,

(1)RegSrvAddr and UserName must keep consistent with the registered ServerAddress and UserName;

(2)When the registration is authenticated, UserName and Passwd must conform to the registered UserName and Passwd;

(3)Expires=0 indicates the cancellation of the existing registration. Any uncompleted registration cannot be cancelled;

(4) After the registration is cancelled, ‘Identity’ is updated to ‘sip:Username@IPAdress’. Also the IP address can be used to make a call.

l A board which is unregistered or whose registration has been cancelled can send the Register request to any Server. (However, if registration failed, all channels on the board will go into the state of ‘UNUSABLE’.)

l If the parameter RegSrvAddr is filled with an inexistent Server IP, the Synway SipStack has a process of ‘Resend Overtime’. Any new Register request is not allowed to be sent before the time is over.

Related Information:

Driver version | SynCTI Ver. 5.1.0.0 or above
Header | Shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll


2.22.1.6 SsmSipChRegister

An SIP channel sends the Register request to SIP Server.

Format:

int SsmSipChRegister(int nCh, LPSTR szRegSrvAddr, LPSTR szUserName, LPSTR szPasswd, LPSTR szRealm, int nExpires)

Parameter Description:

nCh | Channel number
szRegSrvAddr | IP address of SIP Sever
szUserName | Username registered for the SIP channel
szPasswd | Password registered for the SIP channel (only useful when the registration on SIP Server needs to be authenticated)
szRealm | Alias of SIP Server
nExpires | Valid expiration time of the registration

Return Value:

-1 | Registration failed, the SIP channel will go into the ‘UNUSABLE’ state.
0 | Registration successful

Function Description:

An SIP channel sends the Register request to SIP Server.

Note:

l If the SIP channel does not stay in ‘IDLE’ or ‘UNUSABLE’ state, this operation is refused.

l If the SIP channel has been registered: only the update of the registered messages can be sent (only allowed to update ‘Expires’). That is,

(1)RegSrvAddr and UserName must keep consistent with the registered ServerAddress and UserName;

(2)When the registration is authenticated, UserName and Passwd must conform to the registered UserName and Passwd;

(3)Expires=0 indicates the cancellation of the existing registration. Any uncompleted registration cannot be cancelled;

(4) After the registration is cancelled, ‘Identity’ becomes that of the corresponding board.

l An SIP channel which is unregistered or whose registration has been cancelled can send the Register request to any Server. (However, if registration failed, it will go into the state of ‘UNUSABLE’.)

l If the parameter RegSrvAddr is filled with an inexistent Server IP, the Synway SipStack has a process of ‘Resend Overtime’. Any new Register request is not allowed to be sent before the time is over.

Related Information:

Driver version | SynCTI Ver. 5.1.0.0 or above
Header | Shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll


2.22.1.7 SsmSipMultiChRegister

Multiple SIP channels send the Register requests to the SIP Server.

Format:

int SsmSipMultiChRegister(int nChFrom, int nChTo, LPCSTR szRegSrvAddr, LPCSTR szUserName, LPCSTR szPasswd, LPCSTR szRealm, int nExpires)

Parameter Description:

nChFrom | The start channel number
nChTo | The end channel number
szRegSrvAddr | The IP address of the SIP Sever
szUserName | The username registered for the SIP channel
szPasswd | The password registered for the SIP channel (only useful when the registration on the SIP Server needs to be authenticated)
szRealm | The alias of the SIP Server
nExpires | The valid expiration time of the registration

Return Value:

-1 | Registration failed, the SIP channel will go into the ‘UNUSABLE’ state.
0 | Registration successful

Function Description:

Multiple SIP channels send the Register requests to the SIP Server.

Note:

l If the SIP channel does not stay in ‘IDLE’ or ‘UNUSABLE’ state, this operation is refused.

l If the SIP channel has been registered: only the update of the registered messages can be sent (only allowed to update ‘Expires’). That is,

(1) RegSrvAddr and UserName must keep consistent with the registered ServerAddress and UserName;

(2) When the registration is authenticated, UserName and Passwd must conform to the registered UserName and Passwd;

(3) Expires=0 indicates the cancellation of the existing registration. Any uncompleted registration cannot be cancelled;

(4) After the registration is cancelled, ‘Identity’ becomes that of the corresponding board.

l An SIP channel which is unregistered or whose registration has been cancelled can send the Register request to any Server. (However, if registration failed, it will go into the state of ‘UNUSABLE’.)

l If the parameter RegSrvAddr is filled with an inexistent Server IP, the Synway SipStack will have a process of ‘Resend Overtime’. Any new Register request is not allowed to be sent before the time is over.

Related Information:

Driver version | SynCTI Ver. 5.2.0.1 or above
Header | Shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll


2.22.1.8 SsmSipSetTxUserName

Sets the local UserName for an outgoing call.

Format:

int SsmSipSetTxUserName(int ch, LPSTR pszUserName)

Parameter Description:

ch | Channel number
pszUserName | pszUserName sets the ‘UserName’ part in a complete SIP URI, with the maximum size of 50. The format of a complete SIP URI is ”displayname” <sip:user@host:port>.

Return Value:

-1 | Call failed
0 | The size of UserName is 0, invalid
>0 | Size of UserName

Function Description:

Sets the local UserName for an outgoing call in case of non registration.

Note:

l This function is valid only in case of non registration;

l This function is valid only if it is set before starting a call.

Related Information:

Driver version | SynCTI Ver. 5.1.0.0 or above
Header | Shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll


2.22.1.9 SsmSetIpFlag

Sets some parameters for VoIP boards.

Format:

int SsmSetIpFlag(int ch,int Type,LPSTR pszBuffer)

Parameter Description:

ch | Channel number
Type | The type to be modified
pszBuffer | The value that has been modified

Return Value:

-1 | Call failed
0 | The size of pszBuffer is 0, invalid
>0 | Size of pszBuffer

Function Description:

Sets some parameters for VoIP boards.

Note:

l When this function is used to set outgoing calls with the parameter Type = 1, the IP address in the from field of Invite is valid only in case of non registration.

l This function is invalid if the value of Type is not equal to 1.

Related Information:

Driver version | SynCTI Ver. 5.1.0.0 or above
Header | Shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll


2.22.1.10 SsmSipGetReferStatus

Gets the call state of the third party after the call has been transferred.

Format:

int SsmSipGetReferStatus(int ch)

Parameter Description:

ch

Channel number

Return Value:

-1 | Fail to get the call state.
40 | The channel is in the state of ‘UNUSABLE’.
1 | The thrid party that the call is forwarded to is in the state of ‘Trying’. That is, the subscription is pending.
2 | In the state of 180 RingBack
3 | In the state of 200 OK or 3XX
4 | In the state of 4XX, 5XX or 6XX which indicates the failure

Function Description:

Gets the call state of the third party when the board invokes the function SsmIpInitiateTransfer to transfer the call to the third party.

Note:

l This function becomes usable only after the call has been transferred by invoking SsmIpInitiateTransfer .

Related Information:

Driver version | SynCTI Ver. 5.1.0.0 or above
Header | Shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll


2.22.1.11 SsmSipGetBoardRegStatus

Queries the registration status of the board.

Format:

int SsmSipGetBoardRegStatus(int nBId, LPSTR pszRegFailInfo)

Parameter Description:

nBId | The ID number of the board that is to be queried of the registration status
pszRegFailInfo | The information returned upon registration failure

Return Value:

-1 | Registration failed or this is not a VoIP board
≥1 | Registration successful

Function Description:

Gets the status returned at the last time the board sends the Registration request. The parameter pszRegFailInfo returns the reason for the failure of registration. It returns no information in case of successful registration. If this parameter is set to NULL, it will not return the reason for the failure of registration.

Note:

l In SIP protocol, there are no signaling messages that can query the registration status in real time; this function can only obtain the status returned by the last time sent Registration request.

l To improve the validity of the registration status obtained by this function, you may shorten the period of the registration validity. For example, if the registration validity is 300 (s), what obtained by this function in the worst situation is the registration status 5 minutes ago.

Related Information:

Driver version | SynCTI Ver. 5.1.0.0 or above
Header | Shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll


2.22.1.12 SsmSipGetChRegStatus

Queries the registration status of the channel.

Format:

int SsmSipGetChRegStatus(int nChId, LPSTR pszRegFailInfo)

Parameter Description:

nChId | The ID number of the channel that is to be queried of the registration status
pszRegFailInfo | The information returned upon registration failure

Return Value:

-1 | Registration failed or this is not an IP channel
≥1 | Registration successful

Function Description:

Gets the status returned at the last time the channel sends the Registration request. The parameter pszRegFailInfo returns the reason for the failure of registration. It returns no information in case of successful registration. If this parameter is set to NULL, it will not return the reason for the failure of registration.

Note:

l In SIP protocol, there are no signaling messages that can query the registration status in real time; this function can only obtain the status returned by the last time sent Registration request.

l To improve the validity of the registration status obtained by this function, you may shorten the period of the registration validity. For example, if the registration validity is 300 (s), what obtained by this function in the worst situation is the registration status 5 minutes ago.

Related Information:

Driver version | SynCTI Ver. 5.1.0.0 or above
Header | Shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll


2.22.2 Setting Special API functions for VoIP Resource Boards


2.22.2.1 SsmLockMediaCh

Locks the media channel. If a media channel is idle, lock it and obtain available resources on the channel.

Format:

int SsmLockMediaCh(int ch)

Parameter Description:

ch

Media channel number

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
> 0 | Call successful

Function Description:

If a media channel is idle, lock it and obtain available resources on the channel. To be exact, obtain only the local RTP address and port.

Note:

l This channel must be idle. It will go into the state S_IP_MEDIA_LOCK (with the corresponding value of 160) after this function being called successfully. This function is special to VoIP resource boards.

Related Information:

Driver version | SynCTI Ver. 5.2.0.0 or above
Header | Shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll


2.22.2.2 SsmGetMediaChParam

Obtains the media parameters. If the media channel is unlocked, obtain the current media parameters; if it is locked, obtain the locked parameters.

Format:

int SsmGetMediaChParam(int ch, struct MediaParam *mParam)

Parameter Description:

ch | Media channel number
mParam | The pointer pointing to the MediaParam structure

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Call successful

Function Description:

Obtains media parameters of the specified media channel. If the media channel is locked, obtain only the local IP address and port, other parameters remaining empty or 0.

If the media channel is unlocked, obtain the following parameters: local IP address, local port, remote IP address, remote port, codec, transmit and receive modes.

If the media channel is neither locked nor unlocked, the return value will be -1.

Note:

l This function is special to VoIP resource boards.

Related Information:

Driver version | SynCTI Ver. 5.2.0.0 or above
Header | Shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll


2.22.2.3 SsmOpenMediaCh

Opens the media channel.

Format:

int SsmOpenMediaCh(int ch, struct MediaParam *mParam)

Parameter Description:

ch | Media channel number
mParam | The pointer pointing to the MediaParam structure

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Call successful

Function Description:

Creates an RTP Session on the specified media channel to transmit and receive voice data. Parameters include transmit and receive modes, local RTP port and address, remote RTP port and address, load type and etc. Sets the channel state to be S_IP_MEDIA_OPEN at the same time.

Note:

l This function is special to VoIP resource boards.

Related Information:

Driver version | SynCTI Ver. 5.2.0.0 or above
Header | Shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll


2.22.2.4 SsmCloseMediaCh

Closes the media channel.

Format:

int SsmCloseMediaCh(int ch)

Parameter Description:

ch

Media channel number

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Call successful

Function Description:

Closes the media channel. That is, sets the channel state to be locked.

Note:

l This function can be invoked successfully only to those opened channels. Closing a voice channel does not mean leaving it idle. This function is special to VoIP resource boards.

Related Information:

Driver version | SynCTI Ver. 5.2.0.0 or above
Header | Shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll


2.22.2.5 SsmUnlockMediaCh

Releases the media channel. When the media channel is locked or unlocked, release it to put it into the idle state.

Format:

int SsmUnlockMediaCh(int ch)

Parameter Description:

ch

Media channel number

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Call successful

Function Description:

If the media channel is not in the idle state, release the locked resources on this channel and put it into the idle state.

If the media channel is in the idle state, the return value will be -1.

Note:

l This function is special to VoIP resource boards.

Related Information:

Driver version | SynCTI Ver. 5.2.0.0 or above
Header | Shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll


2.22.2.6 SsmUpdateMediaCh

Updates the media channel.

Format:

int SsmUpdateMediaCh (int ch, struct MediaParam *mParam)

Parameter Description:

ch | Media channel number
mParam | The pointer pointing to the MediaParam structure

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
0 | Call successful

Function Description:

Updates the RTP Session on the specified media channel. Parameters include transmit and receive modes, local RTP port and address, remote RTP port and address, load type and etc.

Note:

l This function is valid only when the media channel is opened. It is special to VoIP resource boards.

Related Information:

Driver version | SynCTI Ver. 5.2.0.0 or above
Header | Shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll


2.22.3 Setting Special API functions for NAT Traversal


2.22.3.1 SsmIPGetStunPublicIP

Performs NAT detection to obtain the IP address and the port of the public network.

Format:

int SsmIPGetStunPublicIP(int nBid,WORD nLocalPort,int nStunServerPort,LPSTR pstrStunServer,StunAddress4 *stunServerAdd,int flag)

Parameter Description:

nBid | Board ID
nLocalPort | Local port
nStunServerPort | Port of Stun Server
pstrStunServer | IP address or domain name of Stun Server
stunServerAdd | Returned IP address and port of public network
flag | Way to detect

Return Value:

-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg
≥0 | Detected NAT type. 0: unknown; 1: without NAT; 2: ConeNat; 3: RestrictedNat; 4: PortRestrictedNat; 5: Symmetric NAT; 6: Symmetric NAT with firewall; 7: can’t detect over; 8: fail to detect

Function Description:

Performs NAT detection on VoIP boards or VoIP resource boards using the Stun protocol. If flag=0, it performs the detection of NAT types; if flag=1, it performs the NAT detection of only the IP address and the port of the public network. The former detection costs more time.

Note:

l To perform RTP traversal on the SHN series VoIP boards, set the configuration item special for RTP traversal to enable the RTP traversal feature and invoke this function once. Then this function should no longer be invoked again for subsequent calls.

Related Information:

Driver version | SynCTI Ver. 5.2.0.0 or above
Header | Shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll


2.23 Functions for ATP Series Recording Boards (REC Series)


2.23.1 Input Gain Control of Microphone Channel


2.23.1.1 SsmQueryOpMicGain

Enquires whether setting the gain of the input signal is supported by the channel.

Format:

int SsmQueryOpMicGain(int ch)

Parameter Description:

ch

Channel number

Return Value:

-1 | Call failed
0 | Not supported
1 | Supported

Function Description:

Enquires whether setting the gain of the input signal is supported by the channel.

Note:

l Only analog recording channels of ATP Series boards (including analog trunk channel and microphone recording channel) supports this feature.

Related Information:

Driver version | SynCTI Ver. 2.1or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSetMicGain


2.23.1.2 SsmSetMicGain

Sets the gain of the input signal on the analog recording channel.

Format:

int SsmSetMicGain(int ch, int nMicGain)

Parameter Description:

ch | Channel Number
nGain | Gain value: 0: normal gain 1: increase 20DB

Return Value:

-1 | Call failed
0 | Successful

Function Description:

Sets the gain of the input signal on the analog recording channel.

Note:

l The configuration item MicGain may implement the same features.

l This function is only applicable to analog recording channels of ATP Series boards

Related Information:

Driver version | SynCTI Ver. 2.1or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetMicGain


2.23.1.3 SsmGetMicGain

Obtains the preset gain value of the input signal on the analog recording channel.

Format:

int SsmGetMicGain(int ch)

Parameter Description:

ch

Channel Number

Return Value:

-1 | Call failed
0 | Normal gain
1 | High gain (20DB)

Function Description:

Obtains the preset gain value of the input signal on the analog recording channel.

Note:

l This function is only applicable to analog recording channels of ATP Series boards.

Related Information:

Driver version | SynCTI Ver. 2.1 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmSetMicGain


2.23.2 MF detector functions


2.23.2.1 SsmClearRxMFBuf

Clears up the MF-reception buffer area in the driver.

Format:

int SsmClearRxMFBuf(int ch)

Parameter Description:

ch

Channel number

Return Value:

-1 | Failed. The failure reason can be acquired via the function SsmGetLastErrMsg.
0 | Successful

Function Description:

Clears up the MF-reception buffer area in the driver.

Note:

l When the channel goes into the state of idle, the driver automatically clears the buffer area of the MF detector.

Related Information:

Driver Version | SynCTI Ver 5.3.1.1 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function:


2.23.2.2 SsmGetMFStr

Obtains the MF characters saved in the MF-reception buffer area. The characters are in ASCII.

Format:

int SsmGetMFStr(int ch, LPSTR pszMF)

Parameter Description:

ch | Channel number
pszMF | The pointer storing the received MF strings, the storage space is allocated by the application

Return Value:

-1 | Failed
≥0 | The number of digits in the MF detector

Function Description:

Obtains the MF characters saved in the MF-reception buffer area. The characters are in ASCII.

Note:

l The driver will not clear the MF-reception buffer area when this function is being called.

Related Information:

Driver Version | SynCTI Ver 5.3.1.1 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function:


2.24 Functions for DTP Series Boards (REC Series)


2.24.1 State Machine Programming Mode Based Functions


2.24.1.1 Obtaining Basic Information


2.24.1.1.1 SpyGetMaxCic

Obtains the total number of the monitored circuits.

Format:

int SpyGetMaxCic()

Parameter Description: none

Return Value:

-1 | Call failed
≥0 | The total number of SpyCic

Function Description:

Obtains the total number of the monitored circuits, i.e. the set value of the configuration item TotalAppSpyCIC in the configuration section [AppSpyCICTable]. For more information about SpyCic, refer to ‘DTP Series’ in Chapter 1.

Note:

l This function is only applicable to DTP Series.

Related Information:

Driver version | SynCTI Ver. 3.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SpyChToCic


2.24.1.1.2 SpyChToCic

Searches the corresponding logical number of the SpyCic according to the channel logical number.

Format:

int SpyChToCic(int ch)

Parameter Description:

ch

Channel logical number

Return Value:

-1 | Failed
≥0 | The logical number of the corresponding SpyCic

Function Description:

Searches the corresponding logical number of the SpyCic according to the channel logical number. For more information about the SpyCic logical number, refer to the ‘DTP Series’ in Chapter 1.

Note:

l This function is only applicable to DTP Series.

Related Information:

Driver version | SynCTI Ver. 3.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SpyGetMaxCic


2.24.1.2 Obtaining Call Progress Information


2.24.1.2.1 SpyGetState

Obtains the current state of the SpyCic based state machine.

Format:

int SpyGetState(int nCic)

Parameter Description:

nCic

The number of the monitored circuit

Return Value:

Return value equals to -1 means Call failed. The meanings of the other return values are listed below:

Value

MACRO in shpa3api.h

State Description

0

S_SPY_STANDBY

Idle

2

S_SPY_RINGING

Ringing

3

S_SPY_TALKING

Connected (talking). After the SpyCic is transferred to the state of S_SPY_TALKING, the application may do the followings:

² Call SpyRecToFile to start recording;

² Call SpyGetCalleeId to get the callee ID;

² Call SpyGetCallerId to get the caller ID;

² Using the channel number of the calling party or called party as the parameter, the application may call the channel based functions to get other related information

11

S_CALL_UNAVAILABLE

Channel unavailable

105

S_SPY_RCVPHONUM

Receive the phone number of the called party

110

S_SPY_SS1RESET

Circuit resets

111

S_SPY_SS1WAITBWDACK

SS1: waiting for the backward acknowledgement

112

S_SPY_SS1WAITKB

SS1: waiting for the KB signal

Function Description:

Obtains the current state of the SpyCic based state machine.

Note:

l It’s recommended to use the event of E_CHG_SpyState to replace this function;

l This function is only applicable to DTP Series.

Related Information:

Driver version | SynCTI Ver. 3.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SpyGetCalleeId, SpyGetCallerId, SpyGetCallOutCh, SpyGetCallInCh


2.24.1.3 Obtaining Call Direction


2.24.1.3.1 SpyGetCallInCh

Refer to SpyGetCallOutCh


2.24.1.3.2 SpyGetCallOutCh

Obtains the logical number of the called party channel (SpyGetCallOutCh) or calling party channel (SpyGetCallInCh) in the current call.

Format:

int SpyGetCallInCh(int nCic)

int SpyGetCallOutCh(int nCic)

Parameter Description:

nCic

The logical number of the SpyCic. For more information about SpyCic, refer to ‘DTP Series’ in Chapter 1.

Return Value:

-1 | Call failed
≥0 | SpyGetCallInCh: returns the logical number of the calling party channel; SpyGetCallOutCh: returns the logical number of the called party channel

Function Description:

Obtains the logical number of the called party channel (SpyGetCallOutCh) or calling party channel (SpyGetCallInCh) in the current call. For more information about the called party’s channel, refer to ‘DTP Series’ .

Note:

l Only when the state of the SpyCic has been transferred to the state of S_SPY_RINGING or S_SPY_TALKING, calling the function of SpyGetCallOutCh or SpyGetCallInCh may get valid information.

l This function is only applicable to DTP Series.

Related Information:

Driver version | SynCTI Ver. 3.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SpyGetCallerId, SpyGetCalleeId


2.24.1.4 Obtaining Calling and Called Party Numbers


2.24.1.4.1 SpyGetCallerId

Refer to SpyGetCalleeld


2.24.1.4.2 SpyGetCalleeId

Obtains the calling party number (SpyGetCallerId) or the called party number (SpyGetCalleeId) in the current call.

Format:

int SpyGetCallerId(int nCic, char *pszCallingPartyNumber )

int SpyGetCalleeId(int nCic, char * pszCalledPartyNumber)

Parameter Description:

nCic | The logical number of SpyCic
pszCallingPartyNumber | The pointer pointing to the buffer area storing the calling party number, the application allocates its storage space, the storage space can’t be less than 50 characters
pszCalledPartyNumber | The pointer pointing to the buffer area storing the called party number, the application allocates its storage space, the storage space can’t be less than 50 characters

Return Value:

-1 | Call failed
≥0 | The length of the phone number

Function Description:

After the call is established, the function of SpyGetCallerId obtains the calling party number of the current call,

the function of SpyGetCalleeId obtains the called party number of the current call.

Note:

l Only when the state of the SpyCic has been transferred to the state of S_SPY_RINGING or S_SPY_TALKING, calling the function of SpyGetCallerId or SpyGetCalleeId may get the integrated information;

l This function is only applicable to DTP Series.

Related Information:

Driver version | SynCTI Ver. 3.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SpyGetCallOutCh, SpyGetCallInCh


2.24.1.5 Obtaining Hangup Information


2.24.1.5.1 SpyGetHangupInfo

Obtains the current hangup information based on SpyCic.

Format:

DWORD WINAPI SpyGetHangupInfo(int nCic)

Parameter Description:

nCic

The number of monitored circuit

Return Value:

-1 | Call failed or hangup information unavailable
Others | The 16 higher bits represent the monitored PCM number for SpyCic that sends the disconnect message. The 16 lower bits imply the hangup information of SpyCic. To be exact: 0: Called party hangs up first 1: Calling party hangs up first

Function Description:

Obtains the current hangup information based on SpyCic.

Note:

l We suggest you use the event E_CHG_SpyHangupInfo instead of this function.

l This function is only applicable to DTP Series, ISDN protocol.

Related Information:

Driver version | SynCTI Ver. 5.1.1.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SpyGetCalleeId, SpyGetCallerId, SpyGetCallOutCh, SpyGetCallInCh


2.24.1.6 Obtaining Calling and Called Party Number Types


2.24.1.6.1 SpyGetCallerType

Refer to SpyGetCalleeType


2.24.1.6.2 SpyGetCalleeType

Obtains the calling party number type (SpyGetCallerType) or the called party number type (SpyGetCalleeType) of the current call.

Format:

int WINAPI SpyGetCallerType(int nCic)

int WINAPI SpyGetCalleeType(int nCic)

Parameter Description:

nCic

The logical number of SpyCic

Return Value:

-1 | Call failed
≥0 | The calling/called party number type

Function Description:

After the call is established, the function SpyGetCallerType obtains the calling party number type of the current call, while the function SpyGetCalleeType obtains the called party number type of the current call.

Note:

l Only when the state of the SpyCic has been transferred to the state of S_SPY_RINGING or S_SPY_TALKING, you can call the function SpyGetCallerType or SpyGetCalleeType to get complete information;

l This function is only applicable to ISDN monitoring for DTP Series.

Related Information:

Driver version | SynCTI Ver. 5.1.0.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SpyGetCallOutCh, SpyGetCallInCh


2.24.1.7 Obtaining Digital Trunk State


2.24.1.7.1 SpyGetLinkStatus

Obtains the operating status of the monitored signaling link.

Format:

int SpyGetLinkStatus(int nSpyPcmNo,UCHAR ucFlag);

Parameter Description:

nSpyPcmNo | The logical number of the monitored PCM, the range of value is determined by the configuration item of TotalSpyPcm
ucFlag | 0: Choose the outbound digital trunk 1: Choose the inbound digital trunk

Return Value:

-1 | Call failed
0 | Error (disconnected)
1 | Normal (connected)

Function Description:

Obtains the operating status of the monitored signaling link.

Note:

l This function is only applicable to DTP Series.

Related Information:

Driver version | SynCTI Ver. 3.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function:


2.24.1.8 Obtaining Original Signaling Messages from SS7 Call State Machine


2.24.1.8.1 SsmGetSs7SpyMsu

Obtains the original signaling messages synchronously output by the call state machine of SS7 signaling.

Format:

int SsmGetSs7SpyMsu (PUCHAR* ppucMsuBuf)

Parameter Description:

ppucMsuBuf

The pointer pointing to the buffer area storing original ISUP/TUP messages, the storage space is allocated by the application, it can’t be less than 273 bytes

Return Value:

0 | No messages
>0 | Returns the length (bytes) of the message
-1 | Call failed.

Function Description:

Obtains the original signaling messages synchronously output by the call state machine of SS7 signaling. The method used for taking out the messages is ‘First in, first out”, i.e. always return the earliest received message in the buffer. Every time when the driver receives an MSU message, it will put the message into its internal buffer storing MSU messages and then throw out the event E_RCV_Ss7SpyMsu to the application.

Note:

l Only when the configuration item bOpenSpySS7Msu is set to 1 will the driver copy the received ISUP/TUP messages to the internal buffer area and throw out the event E_RCV_Ss7SpyMsu to the application.

Related Information:

Driver version | SynCTI Ver. 4.7.2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: none

Related Event: E_RCV_Ss7SpyMsu


2.24.1.9 Obtaining Connection Number


2.24.1.9.1 SpyGetConId

Obtains the connection number of this call.

Format:

int WINAPI SpyGetConId (int nCic, char *pcCid)

Parameter Description:

nCic | The logical number of SpyCic
pcCid | The pointer pointing to the buffer area storing connection numbers. The storage space, not less than 50 characters, is allocated by the application.

Return Value:

≥0 | Returns the length of the number
-1 | Call failed.

Function Description:

Obtains the connection number of this call.

Note:

l If the state of SpyCic has transferred to S_SPY_TALKING, only by invoking the function SpyGetConId can you get the complete information.

l This function is only applicable to the DTP series boards.

Related Information:

Driver version | SynCTI Ver. 5.1.0.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: none


2.25 Functions for DST Series Recording Boards (REC Series)


2.25.1 SsmGetDstChSNRofUplink

Obtains the siganl-to-noise ratio of uplink signals on a specified channel of the DST board.

Format:

int SsmGetDstChSNRofUplink(int ch)

Parameter Description:

ch

Channel number

Return Value:

-1 | Failed
≥0 | Value of the signal-to-noise ratio

Function Description:

Obtains the siganl-to-noise ratio of uplink signals on a specified channel of the DST board, to monitor the signal quality on the line.

Note:

l This function only supports DST Series B-type boards.

Related Information:

Driver version | SynCTI Ver. 5.1.0.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetDstChSNRofDownlink


2.25.2 SsmGetDstChSNRofDownlink

Obtains the siganl-to-noise ratio of downlink signals on a specified channel of the DST board.

Format:

int SsmGetDstChSNRofDownlink(int ch)

Parameter Description:

ch

Channel number

Return Value:

-1 | Failed
≥0 | Value of the signal-to-noise ratio

Function Description:

Obtains the siganl-to-noise ratio of downlink signals on a specified channel of the DST board, to monitor the signal quality on the line.

Note:

l This function only supports DST Series B-type boards.

Related Information:

Driver version | SynCTI Ver. 5.1.0.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmGetDstChSNRofUplink


2.25.3 SsmGetDstChVoltageState

Obtains the signal level on a specified channel of the DST board.

Format:

int SsmGetDstChVoltageState (int ch)

Parameter Description:

ch

Channel number

Return Value:

-1 | Failed
0 | Normal
3 | Abnormal

Function Description:

Obtains the signal level on a specified channel of the DST board.

Note:

l This function is only supported for DST Series B-type boards.

Related Information:

Driver version | SynCTI Ver. 5.2.0.1 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function:


2.26 Functions for PCM1280E Recording Board (REC Series)


2.26.1 SsmGetPcm32LineState

Obtains the line synchronization status and the signal state.

Format:

int WINAPI SsmGetPcm32LineState(int ch)

Parameter Description:

ch

Channel number

Return Value:

-1 | Call failed
≥0 | Only the lower 16 bits are used to represent the line synchronization status and the signal state, among which bit0-bit7 indicate the line synchronization status and bit8-bit15 indicate the signal state. See below for details. a) Value range for line synchronization status: 1) 0 - frame synchronization normal 2) 1 - disconnected 3) 2 - reset state 4) 3 - frame synchronization abnormal b) Value range for signal state: 1) 0 - data normal 2) 1 - disconnected or no data 3) 2 - reset state 4) 3 - data abnormal

Function Description:

Obtains the line synchronization status and the signal state.

Note:

l This function is only supported for the PCM1280E board.

Related Information:

Driver version | SynCTI Ver. 5.3.1.2 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function:


2.27 CODEC Transcoding Functions


2.27.1 fPcm_Mp3ConvertALaw

Refer to fPcm_Mp3ConvertULaw


2.27.2 fPcm_Mp3ConvertULaw

fPcm_Mp3ConvertALaw converts IMP3 formatted files recorded by the Synway board to be A-law formatted files, fPcm_Mp3ConvertULaw converts MP3 formatted files to be m-law formatted files.

Format:

int fPcm_Mp3ConvertALaw (char*szSourecFile, char*szTargetFile)

int fPcm_Mp3ConvertULaw (char*szSourecFile, char*szTargetFile)

Parameter Description:

szSoureFile | The name of the MP3-formatted source file recorded by Synway boards, it may include the full path of the file. The file format could be either the non-header file (i.e. without file header) or the standard wav file. It's through analyzing the source file of szSourceFile to determine whether it has the wav file header instead of checking the file extension name that the driver decides if the source file is standard or not. If it’s not a standard wav file, it will be regarded as a non-header file
SzTargetFile | The target file name, it may include the full path of the file. If the target file doesn’t exist, the driver will automatically create it; If the target file exists already, it will be overlaid. If the extension name of the target file is wav, the converted file format is the standard wav; otherwise, the format is plain

Return Value:

1 | Successful
-1 | Call failed. The failure reason may be obtained by the function fPcm_GetLastErrMsg

Function Description:

fPcm_Mp3ConvertALaw converts the MP3 formatted file to be A-law formatted file, fPcm_Mp3ConvertULaw converts the MP3 formatted file to be m-law formatted file. The source file must be MP3-formatted non-header files or standard wav files recorded by Synway boards.

Note:

l Because this function is provided by ShPcmHandle.dll, it can be invoked before SsmStartCti is called successfully;

l When this function is called, the ACM decoding engine of MP3 will be used.

Related Information:

Driver version | SynCTI Ver. 4.0 or above
Header | ShPcmApi.h
Library | ShPcmHandle.lib
DLL | ShPcmHandle.dll

Related Function:


2.27.3 fPcm_AdpcmToAlaw

Refer to Pcm_AdpcmToMp3


2.27.4 fPcm_AdpcmToGsm

Refer to fPcm_AdpcmToMp3


2.27.5 fPcm_AdpcmToMp3

Converts the IMA ADPCM formatted file recorded by Synway boards to be A-law formatted file (by the function of fPcm_AdpcmToAlaw), GSM 6.10 formatted file (by the function of fPcm_AdpcmToGsm), or MP3 formatted file (fPcm_AdpcmToMp3).

Format:

int fPcm_AdpcmToAlaw(char*szSoureFile, char* szTargetFile)

int fPcm_AdpcmToGsm(char*szSoureFile,char*szTargetFile)

int fPcm_AdpcmToMp3(char*szSoureFile, char* szTargetFile)

Parameter Description:

szSoureFile | The name of the IMA ADPCM formatted source file recorded by Synway boards, it may include the full path of the file. The file format could be either the non-header file (i.e. without file header) or the standard wav file. It's through analyzing the source file of szSourceFile to determine whether it has the wav file header instead of checking the file extension name that the driver decides if the source file is standard or not. If it’s not a standard wav file, it will be regarded as a non-header file
szTargetFile | The name of A-law formatted target file, it may include the full path of the file. If the target file doesn’t exist, the driver will automatically create it; If the target file exists already, it will be overlaid. If the extension name of the target file is wav, the converted file format is the standard wav; otherwise, the format is plain

Return Value:

1 | Successful
-1 | Call failed. The failure reason may be obtained by the function fPcm_GetLastErrMsg.

Function Description:

The function of fPcm_AdpcmToAlaw converts the IMA ADPCM formatted file recorded by Synway boards to be A-law formatted file, the function of fPcm_AdpcmToGsm converts the IMA ADPCM formatted file to be GSM 6.10 formatted file, the function of fPcm_AdpcmToMp3 converts the IMA ADPCM formatted file to be Mp3 formatted file.

Note:

l Because this function is provided by ShPcmHandle.dll, it can be invoked before SsmStartCti is called successfully;

Related Information:

Driver version | fPcm_AdpcmToAlaw requires SynCTI Ver. 4.0 or above; fPcm_AdpcmToGsm requires SynCTI Ver. 4.7.2.0 or above; fPcm_AdpcmToMp3 requires SynCTI Ver. 4.7.3.1 or above
Header | ShPcmApi.h
Library | ShPcmHandle.lib
DLL | ShPcmHandle.dll

Related Function: fPcm_MemAdpcmToALAW, fPcm_MemAdpcmToULAW


2.27.6 fPcm_AlawToUlaw

Refer to fPcm_UlawToAlaw


2.27.7 fPcm_UlawToAlaw

Converts A-Law formatted files recorded by the Synway board to be µ-Law formatted files (fPcm_ AlawToUlaw), or converts µ-Law formatted files to be A-Law formatted files (fPcm_ UlawToAlaw).

Format:

int WINAPI fPcm_AlawToUlaw(char*szSourceFile, char*szTargetFile)

int WINAPI fPcm_UlawToAlaw(char*szSourceFile, char*szTargetFile)

Parameter Description:

szSoureFile | The name of the A-Law or µ-Law formatted source file recorded by Synway boards, it may include the full path of the file. The file format could be either the non-header file (i.e. without file header) or the standard wav file. It's through analyzing the source file of szSourceFile to determine whether it has the wav file header instead of checking the file extension name that the driver decides if the source file is standard or not. If it’s not a standard wav file, it will be regarded as a non-header file.
szTargetFile | The target file name, it may include the full path of the file. If the target file doesn’t exist, the driver will automatically create it; If the target file exists already, it will be overlaid. If the extension name of the target file is wav, the converted file format is the standard wav; otherwise, the format is plain.

Return Value:

1 | Call successful
-1 | Call failed. The failure reason may be obtained by the function fPcm_GetLastErrMsg

Function Description:

fPcm_ AlawToUlaw converts A-Law formatted files recorded by the Synway board to be µ-Law formatted files; fPcm_ UlawToAlaw converts µ-Law formatted files to be A-Law formatted files.

Note:

l Because this function is provided by ShPcmHandle.dll, it can be invoked before the call of SsmStartCti .

Related Information:

Driver version | SynCTI Ver. 5.0.0.0 or above
Header | ShPcmApi.h
Library | ShPcmHandle.lib
DLL | ShPcmHandle.dll

Related Function:


2.27.8 fPcm_MemAdpcmToALAW

Refer to fPcm_MemAdpcmToULAW


2.27.9 fPcm_MemAdpcmToULAW

Converts the IMA ADPCM formatted data which is stored in the buffer area and recorded by Synway boards to

be A-law or m-law formatted data. The function of fPcm_MemAdpcmToALAW converts IMA ADPCM to be A-law, The function of fPcm_MemAdpcmToULAW converts IMA ADPCM to be m-law.

Format:

DWORD fPcm_MemAdpcmToALAW(char * pSource, DWORD dwSourceSize, char * pTarget, DWORD dwTargetSize)

DWORD fPcm_MemAdpcmToULAW(char * pSource, DWORD dwSourceSize, char * pTarget, DWORD dwTargetSize)

Parameter Description:

pSource | The first address pointer pointing to the input buffer area
dwSourceSize | The size (bytes) of the input buffer. Because the length of the IMA ADPCM formatted frame is 256 bytes, this parameter must be integral times of 256 bytes
pTarget | The first address pointer pointing to the output buffer area storing the converted data, the storage space is allocated by the application
dwTargetSize | The size of the output buffer area. Because 505 bytes data is generated after each IMA ADPCM formatted frame is converted to be A-law or m-law formatted data, the size of the output buffer area should be not less than dwSourceSize / 256 * 505 + 1

Return Value:

0 | Conversion failed, the failure reason may be obtained via the function call of fPcm_GetLastErrMsg
>0 | The byte number of the voice data after conversion

Function Description:

Converts the IMA ADPCM formatted data which is stored in the buffer area and recorded by Synway boards to

be A-law or m-law formatted data.

Note:

l Because this function is provided by ShPcmHandle.dll, it can be invoked before SsmStartCti is called successfully.

Related Information:

Driver version | SynCTI Ver. 4.0 or above
Header | ShPcmApi.h
Library | ShPcmHandle.lib
DLL | ShPcmHandle.dll

Related Function: fPcm_AdpcmToAlaw


2.27.10 fPcm_ALawConvertPcm16

Refer to fPcm_ALawConvertMp3


2.27.11 fPcm_ALawConvertPcm16_16K

Refer to fPcm_ALawConvertMp3


2.27.12 fPcm_ALawConvertPcm8

Refer to fPcm_ALawConvertMp3


2.27.13 fPCM_AlawConvertGC8

Refer to fPcm_ALawConvertMp3


2.27.14 fPcm_ALawConvertMp3

Converts the A-law formatted file to the 16 bit PCM formatted file (by fPcm_ALawConvertPcm16), the 16 bit 16KHz PCM formatted file (by fPcm_ALawConvertPcm16_16K), the 8 bit unsigned PCM formatted file (by fPcm_ALawConvertPcm8), the G.729A formatted file (by fPCM_AlawConvertGC8), or the MP3 formatted file (by fPcm_ALawConvertMp3).

Format:

int fPcm_ALawConvertPcm16(char*fnALaw, char* szTargetFile)

int WINAPI fPcm_ALawConvertPcm16_16K(char* fnALaw, char*szTargetFile)

int fPcm_AlawConvertPcm8(char* fnALaw, char* szTargetFile)

int fPCM_AlawConvertGC8(char * fnALaw,char*szTargetFile)

int fPcm_ALawConvertMp3(char*szSourceFile, char*szTargetFile)

Parameter Description:

fnALaw | The name of the A-law formatted source file, it may include the full path of the file. The file format could be either the non-header file (i.e. without file header) or the standard wav file. It's through analyzing the source file of szSourceFile to determine whether it has the wav file header instead of checking the file extension name that the driver decides if the source file is standard or not. If it’s not a standard wav file, it will be regarded as a non-header file
szTargetFile | The target file name, it may include the full path of the file. If the target file doesn’t exist, the driver will automatically create it; If the target file exists already, it will be overlaid. If the extension name of the target file is wav, the converted file format is the standard wav; otherwise, the format is plain

Return Value:

1 | Call of fPcm_ALawConvertPcm16, fPcm_ALawConvertPcm16_16K, fPcm_AlawConvertPcm8 or fPcm_ALawConvertMp3 successful
0 | Call of fPCM_AlawConvertGC8 successful
-1 | Call of fPcm_ALawConvertPcm16, fPcm_ALawConvertPcm16_16K, fPcm_AlawConvertPcm8, fPCM_AlawConvertGC8 or fPcm_ALawConvertMp3 failed, the failure reason may be obtained via the function call of fPcm_GetLastErrMsg

Function Description:

fPcm_ALawConvertPcm16 converts the A-law formatted file to the 16 bit PCM formatted file; fPcm_ALawConvertPcm16_16K converts the A-law formatted file to the 16 bit 16KHz PCM formatted file; fPcm_ALawConvertPcm8 converts the A-law formatted file to the unsigned 8-bit PCM formatted file; fPCM_AlawConvertGC8 converts the A-law formatted file to the G.729A formatted file; fPcm_ALawConvertMp3 converts the A-law formatted file to the MP3 formatted file provided the MP3 recording engine has been installed.

Note:

l Because this function is provided by ShPcmHandle.dll, it can be invoked before SsmStartCti is called successfully;

l fPcm_ALawConvertPcm16, fPcm_ALawConvertPcm16_16K, fPcm_AlawConvertPcm8 or fPcm_ALawConvertMp3 returns only 1 or -1;

l fPCM_AlawConvertGC8 returns only 0 or -1.

Related Information:

Driver version | fPcm_ALawConvertPcm16, fPcm_ALawConvertPcm8 require SynCTI Ver. 4.0 or above; fPCM_AlawConvertGC8 requires SynCTI Ver. 4.7.1.8 or above; fPcm_ALawConvertMp3 requires SynCTI Ver. 4.8.0.0 or above; fPcm_ALawConvertPcm16_16K requires SynCTI Ver. 5.2.0.1 or above.
Header | ShPcmApi.h
Library | ShPcmHandle.lib
DLL | ShPcmHandle.dll

Related Function: fPcm_Pcm16ConvertALaw, fPcm_GC8Convert, fPcm_MemAlawToPcm8, fPcm_MemAlawToPcm16


2.27.15 fPcm_ULawConvertMp3

Converts the µ-Law formatted file to the MP3 formatted file.

Format:

Int WINAPI fPcm_ULawConvertMp3(char*szSourceFile, char*szTargetFile)

Parameter Description:

szSoureFile | The name of the µ-Law formatted source file which is recorded by Synway boards. It may include the full path of the file. The file could be either a non-header file (i.e. without file header) or a standard wav file. Instead of checking the file extension name, the driver judges if the source file is standard or not by analyzing szSourceFile to find whether it has the wav file header. If it’s not a standard wav file, it will be regarded as a non-header file.
szTargetFile | The target file name. It may include the full path of the file. If the target file doesn’t exist, the driver will automatically create it; if the target file exists already, it will be overlaid. If the extension name of the target file is wav, the converted file is a standard wav file; otherwise, it will be a non-header file.

Return Value:

1 | Successful
-1 | Call failed. The failure reason may be obtained via the function call of fPcm_GetLastErrMsg

Function Description:

Converts the µ-Law formatted file recorded by Synway boards to the MP3 formatted file.

Note:

l Because this function is provided by ShPcmHandle.dll, it can be invoked before the call of SsmStartCti .

Related Information:

Driver version | SynCTI Ver. 5.0.0.0 or above.
Header | ShPcmApi.h
Library | ShPcmHandle.lib
DLL | ShPcmHandle.dll

Related Function: fPcm_ALawConvertMp3


2.27.16 fPcm_ALawToVox

Converts the A-Law formatted file to the vox formatted file.

Format:

int WINAPI fPcm_ALawToVox (char *szSourceFile, char *szTargetFile)

Parameter Description:

szSoureFile | The name of the A-Law formatted source file which is recorded by Synway boards. It may include the full path of the file. The file could be either a non-header file (i.e. without file header) or a standard wav file. Instead of checking the file extension name, the driver judges if the source file is standard or not by analyzing szSourceFile to find whether it has the wav file header. If it’s not a standard wav file, it will be regarded as a non-header file.
szTargetFile | The target file name. It may include the full path of the file. If the target file doesn’t exist, the driver will automatically create it; if the target file exists already, it will be overlaid.

Return Value:

0 | Successful
-1 | Call failed. The failure reason may be obtained via the function call of fPcm_GetLastErrMsg

Function Description:

Converts the A-Law formatted file recorded by Synway boards to the vox formatted file.

Note:

l Because this function is provided by ShPcmHandle.dll, it can be invoked before the call of SsmStartCti .

Related Information:

Driver version | SynCTI Ver. 5.1.1.0 or above.
Header | ShPcmApi.h
Library | ShPcmHandle.lib
DLL | ShPcmHandle.dll

Related Function:


2.27.17 fPcm_MemAlawToPcm8

Refer to fPcm_MemAlawToPcm16


2.27.18 fPcm_MemAlawToPcm16

Converts the A-law formatted data stored in the buffer area to be unsigned 8-bit PCM formatted data (by the function fPcm_MemAlawToPcm8) or 16 bit PCM formatted data (by the function fPcm_MemAlawToPcm16).

Format:

DWORD fPcm_MemAlawToPcm8 (char*pSrcBuf,DWORD dwSrcSize,char *pDstBuf,DWORD dwDstSize8)

DWORD fPcm_MemAlawToPcm16(char* pSrcBuf,DWORD dwSrcSize,char * pDstBuf,DWORD dwDstSize16)

Parameter Description:

pSrcBuf | The pointer pointing to the buffer area storing source data, it stores A-law formatted voice data
dwSrcSize | The size (bytes) of pSrcBuf
pDstBuf | The pointer pointing to the buffer area storing the converted data, the storage space is allocated by the application
dwDstSize8 dwDstSize16 | The size of pDstBuf (bytes). dwDstSize8 must be larger than or equal to dwSrcSize, dwDstSize16 must be larger than or equal to two times of dwSrcSize

Return Value:

0 | Conversion failed. The failure reason may be obtained by the function fPcm_GetLastErrMsg
>0 | The number of the converted bytes

Function Description:

fPcm_MemAlawToPcm8 converts the A-law format to be unsigned 8-bit PCM format, fPcm_MemAlawToPcm16 converts the A-law format to be 16 bit PCM format.

Note:

l Because this function is provided by ShPcmHandle.dll, it can be invoked before SsmStartCti is called successfully.

Related Information:

Driver version | SynCTI Ver. 4.7.2.0 or above
Header | ShPcmApi.h
Library | ShPcmHandle.lib
DLL | ShPcmHandle.dll

Related Function: fPcm_ALawConvertPcm16, fPcm_ALawConvertPcm8, fPcm_MemPcm8ToAlaw


2.27.19 fPcm_MemAlawToPcm16_16K

Converts the A-law formatted data stored in the buffer area to be 16 bit 16KHz PCM formatted data.

Format:

Int WINAPI fPcm_MemAlawToPcm16_16K(char * szSource, int nSourceLen, char * szTarget, int nTargetLen)

Parameter Description:

szSource | The pointer pointing to the buffer area storing source data, it stores A-law formatted voice data
nSourceLen | The size (bytes) of szSource
szTarget | The pointer pointing to the buffer area storing the converted data, the storage space is allocated by the application
nTargetLen | The size of szTarget (bytes). nTargetLen must be larger than or equal to four times of nSourceLen.

Return Value:

0 | Conversion failed. The failure reason may be obtained by the function fPcm_GetLastErrMsg
>0 | The number of the converted bytes

Function Description:

fPcm_MemAlawToPcm16_16K converts the A-law format to be the 16 bit 16KHz PCM format.

Note:

l Because this function is provided by ShPcmHandle.dll, it can be invoked before SsmStartCti is called successfully.

Related Information:

Driver version | SynCTI Ver. 5.2.0.1 or above
Header | ShPcmApi.h
Library | ShPcmHandle.lib
DLL | ShPcmHandle.dll

Related Function: fPcm_ALawConvertPcm16 , fPcm_ALawConvertPcm8 , fPcm_MemPcm8ToAlaw


2.27.20 fPcm_MemGSMToPcm16

Converts the GSM formatted data stored in the buffer to the 16 Bit PCM formatted data.

Format:

DWORD WINAPI fPcm_MemGSMToPcm16(char *pSource, DWORD dwSourceSize, char *pTarget, DWORD dwTargetSize)

Parameter Description:

pSource | The pointer that points to the source buffer area storing GSM formatted voice data
dwSourceSize | The size of the source buffer area, calculated by byte. 2600≤dwSourceSize＜3250 and had better be the multiple of 65.
pTarget | The pointer that points to the target buffer area storing 16 Bit PCM formatted voice data.
dwTargetSize | The size of the target buffer area. It must be greater than or equal to 10 times of dwSourceSize.

Return Value:

0 | Conversion failed
>0 | The number of converted bytes

Function Description:

Converts the GSM formatted file to the 16 Bit PCM formatted file.

Note:

l Because this function is provided by ShPcmHandle.dll, it can be invoked before the call of SsmStartCti .

Related Information:

Driver version | SynCTI Ver. 4.8.0.0 or above
Header | ShPcmApi.h
Library | ShPcmHandle.lib
DLL | ShPcmHandle.dll

Related Function: fPcm_ALawConvertPcm16 , fPcm_ALawConvertPcm8 , fPcm_MemPcm8ToAlaw , fPcm_MemGSMToPcm8


2.27.21 fPcm_MemGSMToPcm8

Converts the GSM formatted data stored in the buffer to the unsigned 8 Bit PCM formatted data.

Format:

DWORD WINAPI fPcm_MemGSMToPcm8(char *pSource, DWORD dwSourceSize, char *pTarget, DWORD dwTargetSize)

Parameter Description:

pSource | The pointer that points to the source buffer area storing GSM formatted voice data
dwSourceSize | The size of the source buffer area, calculated by byte 2600≤dwSourceSize＜3250 and had better be the multiple of 65
pTarget | The pointer that points to the target buffer area storing 8 Bit PCM formatted voice data
dwTargetSize | The size of the target buffer area. It must be greater than or equal to 5 times of dwSourceSize

Return Value:

0 | Conversion failed
>0 | The number of converted bytes

Function Description:

Converts the GSM formatted data stored in the buffer to the unsigned 8 Bit PCM formatted data.

Note:

l Because this function is provided by ShPcmHandle.dll, it can be invoked before the call of SsmStartCti .

Related Information:

Driver version | SynCTI Ver. 5.0.3.0 or above
Header | ShPcmApi.h
Library | ShPcmHandle.lib
DLL | ShPcmHandle.dll

Related Function: fPcm_ALawConvertPcm16 , fPcm_ALawConvertPcm8 , fPcm_MemPcm8ToAlaw , fPcm_MemGSMToPcm16


2.27.22 fPcm_MemGSMToUlaw

Converts the GSM formatted data stored in the buffer to μ-law formatted data.

Format:

DWORD WINAPI fPcm_MemGSMToUlaw (char *pSource, DWORD dwSourceSize, char *pTarget, DWORD dwTargetSize)

Parameter Description:

pSource | The pointer that points to the source buffer area storing GSM formatted voice data
dwSourceSize | The size of the source buffer area, calculated by byte 2600≤dwSourceSize＜3250 and had better be the multiple of 65
pTarget | The pointer that points to the target buffer area storing μ-law formatted voice data
dwTargetSize | The size of the target buffer area. It must be greater than or equal to 10 times of dwSourceSize

Return Value:

0 | Conversion failed
>0 | The number of converted bytes

Function Description:

Converts the GSM formatted data stored in the buffer to μ-law formatted data.

Note:

l Because this function is provided by ShPcmHandle.dll, it can be invoked before the call of SsmStartCti .

Related Information:

Driver version | SynCTI Ver. 5.0.3.0 or above
Header | ShPcmApi.h
Library | ShPcmHandle.lib
DLL | ShPcmHandle.dll

Related Function: fPcm_ALawConvertPcm16 , fPcm_ALawConvertPcm8 , fPcm_MemPcm8ToAlaw , fPcm_MemGSMToPcm16


2.27.23 fPcm_Pcm16ConvertALaw

Converts the 16 bits PCM formatted file to be A-law formatted file.

Format:

int fPcm_Pcm16ConvertALaw (char*fnPCM16, char* szTargetFile)

Parameter Description:

fnPCM16 | The name of the 16 bit PCM formatted source file, it may include the full path of the file. The file format could be either the non-header file (i.e. without file header) or the standard wav file. It's through analyzing the source file to determine whether it has the wav file header instead of checking the file extension name that the driver decides if the source file is standard or not. If it’s not a standard wav file, it will be regarded as a non-header file
szTargetFile | The target file name, it may include the full path of the file. If the target file doesn’t exist, the driver will automatically create it; If the target file exists already, it will be overlaid. If the extension name of the target file is wav, the converted file format is the standard wav; otherwise, the format is plain

Return Value:

1 | Successful
-1 | Call failed. The failure reason may be obtained via the function fPcm_GetLastErrMsg

Function Description:

Converts the 16 bit PCM formatted file to be the A-law formatted file.

Note:

l Because this function is provided by ShPcmHandle.dll, it can be invoked before SsmStartCti is called successfully.

Related Information:

Driver version | SynCTI Ver. 4.7.1.7 or above
Header | ShPcmApi.h
Library | ShPcmHandle.lib
DLL | ShPcmHandle.dll

Related Function:


2.27.24 fPcm_Pcm16_16KconvertALaw

Converts the 16 bits 16KHz PCM formatted file to be A-law formatted file.

Format:

int fPcm_Pcm16_16KConvertALaw (char*fnPCM16, char* szTargetFile)

Parameter Description:

fnPCM16 | The name of the 16 bit 16KHz PCM formatted source file, it may include the full path of the file. The file format could be either the non-header file (i.e. without file header) or the standard wav file. The driver, by analyzing the source file to determine whether it has the wav file header, but not by checking the file extension name, decides if the source file is standard or not. If it’s not a standard wav file, it will be regarded as a non-header file.
szTargetFile | The target file name, it may include the full path of the file. If the target file doesn’t exist, the driver will automatically create it; If the target file exists already, it will be overlaid. If the extension name of the target file is wav, the converted file format is the standard wav; otherwise, the format is plain.

Return Value:

1 | Successful
-1 | Call failed. The failure reason may be obtained via the function fPcm_GetLastErrMsg .

Function Description:

Converts the 16 bit 16KHz PCM formatted file to be the A-law formatted file.

Note:

l Because this function is provided by ShPcmHandle.dll, it can be invoked before SsmStartCti is called successfully.

Related Information:

Driver version | SynCTI Ver. 5.2.0.1 or above
Header | ShPcmApi.h
Library | ShPcmHandle.lib
DLL | ShPcmHandle.dll

Related Function:


2.27.25 fPcm_MemPcm8ToAlaw

Converts the unsigned 8-bit PCM formatted data stored in the buffer area to be the A-law formatted data.

Format:

int fPcm_MemPcm8ToAlaw(char * szSource, int nSourceLen, char * szTarget, int nTargetLen)

Parameter Description:

szSource | The pointer pointing to the first address of the input buffer area, it stores 8-bit PCM formatted voice data
nSourceLen | The size (bytes) of szSource
szTarget | The pointer pointing to the buffer area storing the converted data, the storage space is allocated by the application
nTargetLen | The size of szTarget, must be larger than or equal to dwSrcSize

Return Value:

0 | Conversion failed. The failure reason may be obtained by the function fPcm_GetLastErrMsg
>0 | The number of the converted bytes

Function Description:

Converts the unsigned 8-bit PCM formatted data stored in the buffer area to be the A-law formatted data.

Note:

l Because this function is provided by ShPcmHandle.dll, it can be invoked before SsmStartCti is called successfully.

Related Information:

Driver version | SynCTI Ver. 4.7.2.0 or above
Header | ShPcmApi.h
Library | ShPcmHandle.lib
DLL | ShPcmHandle.dll

Related Function: fPcm_MemAlawToPcm8, fPcm_ALawConvertPcm8


2.27.26 fPcm_MemAlawToUlaw

Refer to fPcm_MemUlawtoAlaw


2.27.27 fPcm_MemUlawtoAlaw

Converts the A-law formatted data stored in the buffer area to be µ-Law formatted data (fPcm_MemAlawToUlaw), or converts the µ-Law formatted data stored in the buffer area to be A-law formatted data (fPcm_MemUlawtoAlaw).

Format:

int WINAPI fPcm_MemAlawToUlaw(char * szSource, int nSourceLen, char * szTarget, int nTargetLen)

int WINAPI fPcm_MemUlawtoAlaw(char * szSource, int nSourceLen, char * szTarget, int nTargetLen)

Parameter Description:

szSource | The pointer pointing to the first address of the input buffer area, it stores A-Law or µ-Law formatted voice data
nSourceLen | The size (bytes) of szSource
szTarget | The pointer pointing to the buffer area storing the converted data, the storage space is allocated by the application
nTargetLen | The size of szTarget, must be larger than or equal to nSourceLen

Return Value:

0 | Conversion failed. The failure reason may be obtained by the function fPcm_GetLastErrMsg
>0 | The number of the converted bytes

Function Description:

fPcm_MemAlawToUlaw converts the A-law formatted data stored in the buffer area to be µ-Law formatted data; fPcm_MemUlawtoAlaw converts the µ-Law formatted data stored in the buffer area to be A-law formatted data.

Note:

l Because this function is provided by ShPcmHandle.dll, it can be invoked before the call of SsmStartCti.

Related Information:

Driver version | SynCTI Ver. 5.0.0.0 or above
Header | ShPcmApi.h
Library | ShPcmHandle.lib
DLL | ShPcmHandle.dll

Related Function:


2.27.28 fPcm_MemPcm16ToAlaw

Converts the unsigned 16-bit PCM formatted data stored in the buffer area to be the A-law formatted data.

Format:

DWORD fPcm_MemPcm16ToAlaw(char *pSrcBuf, DWORD dwSrcSize,char *pDstBuf, DWORD dwDstSize)

Parameter Description:

szSource | The pointer pointing to the first address of the input buffer area, it stores 16-bit PCM formatted voice data
nSourceLen | The size (bytes) of nSourceLen
szTarget | The pointer pointing to the buffer area storing the converted data, the storage space is allocated by the application
nTargetLen | The size of szTarget, must be larger than or equal to dwSrcSize

Return Value:

0 | Conversion failed. The failure reason may be obtained by the function fPcm_GetLastErrMsg
>0 | The number of the converted bytes

Function Description:

Converts the unsigned 16-bit PCM formatted data stored in the buffer area to be the A-law formatted data.

Note:

l Because this function is provided by ShPcmHandle.dll, it can be invoked before SsmStartCti is called successfully.

Related Information:

Driver version | SynCTI Ver. 4.7.2.0 or above
Header | ShPcmApi.h
Library | ShPcmHandle.lib
DLL | ShPcmHandle.dll

Related Function: fPcm_MemAlawToPcm16, fPcm_ALawConvertPcm16


2.27.29 fPcm_MemPcm16_16KtoAlaw

Converts the unsigned 16-bit 16KHz PCM formatted data stored in the buffer area to be the A-law formatted data.

Format:

DWORD WINAPI fPcm_MemPcm16_16KToAlaw(char * pSource, DWORD dwSourceSize, char * pTarget, DWORD dwTargetSize)

Parameter Description:

pSource | The pointer pointing to the first address of the input buffer area, it stores 16-bit PCM formatted voice data
dwSourceSize | The size (bytes) of pSource
pTarget | The pointer pointing to the buffer area storing the converted data, the storage space is allocated by the application
dwTargetSize | The size of pTarget, must be larger than or equal to 1/4 of dwSourceSize

Return Value:

0 | Conversion failed. The failure reason may be obtained by the function fPcm_GetLastErrMsg
>0 | The number of the converted bytes

Function Description:

Converts the unsigned 16-bit 16KHz PCM formatted data stored in the buffer area to be the A-law formatted data.

Note:

l Because this function is provided by ShPcmHandle.dll, it can be invoked before SsmStartCti is called successfully.

Related Information:

Driver version | SynCTI Ver. 5.2.0.1 or above
Header | ShPcmApi.h
Library | ShPcmHandle.lib
DLL | ShPcmHandle.dll

Related Function: fPcm_MemAlawToPcm16 , fPcm_ALawConvertPcm16


2.27.30 fPcm_GC8Convert

Refer to fPcm_G729AConvert


2.27.31 fPcm_Vox6KTo8K

Refer to fPcm_Vox8KTo6K


2.27.32 fPcm_Vox8KTo6K

Implements the conversion between 6K sampling rate and 8K sampling rate of the VOX formatted voice file.

Format:

int fPcm_Vox6kTo8k(char *sz6kHzFile,char *sz8kHzFile)

int fPcm_Vox8KTo6K (char *sz8kHzFile,char *sz6kHzFile)

Parameter Description:

sz6kHzFile | The voice file with the sampling rate 6kHz and Vox encoding format, without file header. If the full path is not included, the driver will look for the file under the current directory
sz8kHzFile | The voice file with the sampling rate 8kHz and Vox encoding format, without file header. If the full path is not included, the driver will look for the file under the current directory

Return Value:

1 | Successful
-1 | Call failed. The failure reason may be obtained via the function fPcm_GetLastErrMsg

Function Description:

fPcm_Vox6kTo8k converts the Vox file with 6kHz sampling rate to be the Vox file with 8kHz sampling rate, fPcm_Vox8KTo6K converts the Vox file with 8kHz sampling rate to be the Vox file with 6kHz sampling rate.

Note:

l Because this function is provided by ShPcmHandle.dll, it can be invoked before SsmStartCti is called successfully.

Related Information:

Driver version | SynCTI Ver. 4.7.1.7 or above
Header | ShPcmApi.h
Library | ShPcmHandle.lib
DLL | ShPcmHandle.dll

Related Function:


2.27.33 fPcm_ULawConvertGSM

Converts the μ-Law formatted file to the GSM formatted file.

Format:

int WINAPI fPcm_ULawConvertGSM(char*szSourceFile, char*szTargetFile)

Parameter Description:

szSourceFile | The name of the μ-Law formatted source file, allowed to include the full path of the file. The file format could be either the non-header file or the standard wav file. The driver decides whether the source file is a standard wav file or not by analyzing if it has a wav file header, rather than by checking the file extension name. If it is not a standard wav file, it will be regarded as a non-header file
szTargetFile | The target file name, allowed to include the full path of the file. If the target file doesn’t exist, the driver will automatically create it; If the target file exists already, it will be overlaid. If the extension name of the target file is wav, the converted file is a standard wav file; otherwise, it is a non-header file.

Return Value:

1 | Call successful
-1 | Call failed. The failure reason may be obtained via the function fPcm_GetLastErrMsg

Function Description:

fPcm_ULawConvertGSM is used to convert the μ-Law formatted file to the GSM formatted file.

Note:

l Because this function is provided by ShPcmHandle.dll, it can be invoked before the call of SsmStartCti .

l In case the driver has not yet been installed, not only ShPcmHandle.dll but also macmcvt.dll needs to be used to invoke fPcm_ULawConvertGSM.

Related Information:

Driver version | SynCTI Ver. 4.8.0.0 or above
Header | ShPcmApi.h
Library | ShPcmHandle.lib
DLL | ShPcmHandle.dll, macmcvt.dll

Related Function: fPcm_Pcm16ConvertALaw , fPcm_GC8Convert , fPcm_MemAlawToPcm8 , fPcm_MemAlawToPcm16


2.27.34 fPCM_Pcm16ConvertG729A

Converts the 16 Bit PCM formatted file to the G.729A formatted file.

Format:

Int WINAPI fPCM_Pcm16ConvertG729A(char*szSoureFile, char* szTargetFile)

Parameter Description:

szSoureFile | The name of the 16 Bit PCM formatted source file which is recorded by Synway boards. It may include the full path of the file. The file could be either a non-header file (i.e. without file header) or a standard wav file. Instead of checking the file extension name, the driver judges if the source file is standard or not by analyzing szSourceFile to find whether it has the wav file header. If it’s not a standard wav file, it will be regarded as a non-header file.
szTargetFile | The target file name. It may include the full path of the file. If the target file doesn’t exist, the driver will automatically create it; if the target file exists already, it will be overlaid. If the extension name of the target file is wav, the converted file is a standard wav file; otherwise, it will be a non-header file.

Return Value:

0 | Successful
-1 | Call failed. The failure reason may be obtained via the function call of fPcm_GetLastErrMsg

Function Description:

Converts the 16 Bit PCM formatted file recorded by Synway boards to the G.729A formatted file.

Note:

l Because this function is provided by ShPcmHandle.dll, it can be invoked before the call of SsmStartCti .

Related Information:

Driver version | SynCTI Ver. 5.0.0.0 or above.
Header | ShPcmApi.h
Library | ShPcmHandle.lib
DLL | ShPcmHandle.dll

Related Function: fPcm_Pcm16ConvertALaw


2.27.35 fPcm_Pcm8ConvertGSM

Converts the 8 bit PCM formatted file to the GSM formatted file.

Format:

Int WINAPI fPcm_Pcm8ConvertGSM(char*szSoureFile, char* szTargetFile)

Parameter Description:

szSoureFile | The name of the 8 bit PCM formatted source file which is recorded by Synway boards. It may include the full path of the file. The file could be either a non-header file (i.e. without file header) or a standard wav file. Instead of checking the file extension name, the driver judges if the source file is standard or not by analyzing szSourceFile to find whether it has the wav file header. If it’s not a standard wav file, it will be regarded as a non-header file.
szTargetFile | The target file name. It may include the full path of the file. If the target file doesn’t exist, the driver will automatically create it; if the target file exists already, it will be overlaid. If the extension name of the target file is wav, the converted file is a standard wav file; otherwise, it will be a non-header file.

Return Value:

0 | Successful
-1 | Call failed. The failure reason may be obtained via the function call of fPcm_GetLastErrMsg

Function Description:

Converts the 8 bit PCM formatted file to the GSM formatted file.

Note:

l Because this function is provided by ShPcmHandle.dll, it can be invoked before the call of SsmStartCti .

Related Information:

Driver version | SynCTI Ver. 5.1.0.0 or above.
Header | ShPcm.h
Library | ShPcmHandle.lib
DLL | ShPcmHandle.dll

Related Function:


2.27.36 fPcm_GSMToMp3

Converts the GSM formatted file to the MP3 formatted file.

Format:

Int WINAPI fPcm_GSMToMp3 (char*szSoureFile, char* szTargetFile)

Parameter Description:

szSoureFile | The name of the GSM formatted source file which is recorded by Synway boards. It may include the full path of the file. The file could be either a non-header file (i.e. without file header) or a standard wav file. Instead of checking the file extension name, the driver judges if the source file is standard or not by analyzing szSourceFile to find whether it has the wav file header. If it’s not a standard wav file, it will be regarded as a non-header file.
szTargetFile | The target file name. It may include the full path of the file. If the target file doesn’t exist, the driver will automatically create it; if the target file exists already, it will be overlaid. If the extension name of the target file is wav, the converted file is a standard wav file; if the extension name of the target file is mp3, the converted file is an mp3 file; otherwise, it will be a non-header file.

Return Value:

1 | Successful
-1 | Call failed. The failure reason may be obtained via the function call of fPcm_GetLastErrMsg

Function Description:

Converts the GSM formatted file recorded by Synway boards to the MP3 formatted file.

Note:

l Because this function is provided by ShPcmHandle.dll, it can be invoked before the call of SsmStartCti .

Related Information:

Driver version | SynCTI Ver. 5.0.0.0 or above.
Header | ShPcmApi.h
Library | ShPcmHandle.lib
DLL | ShPcmHandle.dll

Related Function:


2.27.37 fPcm_G729AConvert

Converts the G.792A formatted file to a voice file of other encoding format.

Format:

Int WINAPI fPcm_G729AConvert(char*szSoureFile, char* szTargetFile, int nTargetFormat)

Parameter Description:

szSoureFile | The name of the G.792A formatted source file, it may include the full path of the file. The file format could be either the non-header file (i.e. without file header) or the standard wav file. It's through analyzing the source file to determine whether it has the wav file header instead of checking the file extension name that the driver decides if the source file is standard or not. If it’s not a standard wav file, it will be regarded as a non-header file
szTargetFile | The target file name, it may include the full path of the file. If the target file doesn’t exist, the driver will automatically create it; If the target file exists already, it will be overlaid. If the extension name of the target file is wav, the converted file format is the standard wav; otherwise, the format is plain
nTargetFormat | The encoding format of the target file: =10001: 16 Bit PCM =6: A-law

Return Value:

1 | Successful
-1 | Call failed. The failure reason may be obtained by the function fPcm_GetLastErrMsg .

Function Description:

Converts the G.792A formatted file to a voice file of other encoding format.

Note:

l Because this function is provided by ShPcmHandle.dll, it can be invoked before SsmStartCti is called successfully.

Related Information:

Driver version | SynCTI Ver. 4.0 or above
Header | ShPcmApi.h
Library | ShPcmHandle.lib
DLL | ShPcmHandle.dll

Related Function: fPCM_AlawConvertGC8


2.27.38 fPCM_MemULawToG729A

Converts the μ-Law data saved in the buffer to G.729A format.

Format:

Int WINAPI fPCM_MemULawToG729A (char* szSoure, int nSourceLen, char* szTarget, int nTargetLen)

Parameter Description:

szSource | The pointer pointing to the buffer area that stores µ-Law formatted source data
nSourceLen | The size of szSource in byte
szTarget | The pointer pointing to the buffer area that stores the converted data, the storage space is allocated by the application. According to the scale between the sizes of µ-Law and G.729A format data, szTarget must be greater than nSourceLen/8.
nTargetLen | The size of data actually returned by szTarget,

Return Value:

>0 | The number of converted bytes
0 | Conversion failed. The failure reason may be obtained by the function fPcm_GetLastErrMsg

Function Description:

Converts the μ-Law data saved in the buffer to G.729A format.

Note:

l Because this function is provided by ShPcmHandle.dll, it can be invoked before the successful call of SsmStartCti .

Related Information:

Driver version | SynCTI Ver. 5.1.1.0 or above
Header | ShPcmApi.h
Library | ShPcmHandle.lib
DLL | ShPcmHandle.dll

Related Function:


2.27.39 fPcm_MemMp3ToPcm16

Converts the MP3 formatted data stored in the buffer area to be the 16 Bit PCM formatted data.

Format:

Int WINAPI fPCM_MemMp3ToPcm16 (char* szSoure, int nSourceLen, char* szTarget, int nTargetLen)

Parameter Description:

szSoure | The pointer pointing to the buffer area that stores the MP3 formatted source data
nSourceLen | The size of szSource in byte
szTarget | The pointer pointing to the buffer area that stores the converted data, the storage space is allocated by the application. According to the scale between the size of the MP3 data and that of the 16 Bit PCM formatted data, szTarget must be greater than nSourceLen*16.
nTargetLen | The actual size of the data that are returned by szTarget

Return Value:

>0 | The number of converted bytes
0 | Conversion failed. The failure reason may be obtained by the function fPcm_GetLastErrMsg

Function Description:

Converts the MP3 formatted data stored in the buffer area to be the 16 Bit PCM formatted data.

Note:

l Because this function is provided by ShPcmHandle.dll, it can be invoked before SsmStartCti .

Related Information:

Driver version | SynCTI Ver. 5.1.1.0 or above
Header | ShPcm.h
Library | ShPcmHandle.lib
DLL | ShPcmHandle.dll

Related Function:


2.27.40 fPcm_MemG729AToPcm8

Refer to fPcm_MemG729AToPcm16


2.27.41 fPcm_MemG729AToPcm16

Converts the G.729A data saved in the buffer area to the PCM16 or PCM8 format.

Format:

DWORD WINAPI fPcm_MemG729AToPcm16(char *pSource, DWORD dwSourceSize, char *pTarget, DWORD dwTargetSize);

DWORD WINAPI fPcm_MemG729AToPcm8(char *pSource, DWORD dwSourceSize, char *pTarget, DWORD dwTargetSize);

Parameter Description:

pSource | The pointer pointing to the buffer area that stores G.729A formatted source data
dwSourceSize | The size of pSource in byte
pTarget | The pointer pointing to the buffer area that stores the converted data, the storage space is allocated by the application. According to the scale between the sizes of G.729A and PCM16 (or PCM8) formatted data, pTarget must be 16 times as dwSourceSize for the PCM16 formatted data and 8 times as dwSourceSize for the PCM8 formatted data.
dwTargetSize | The size of data actually returned by pTarget in byte

Return Value:

>0 | The number of the converted bytes
0 | Conversion failed. The failure reason may be obtained by the function fPcm_GetLastErrMsg

Note:

l Because this function is provided by ShPcmHandle.dll, it can be invoked before the successful call of SsmStartCti .

Related Information:

Driver version | SynCTI Ver. 5.3.1.1 or above
Header | ShPcmApi.h
Library | ShPcmHandle.lib
DLL | ShPcmHandle.dll

Related Function:


2.27.42 fPcm_GetLastErrMsg

Obtains the call failure reason of the functions for voice encoding format conversion.

Format:

int fPcm_GetLastErrMsg(char*szMsg)

Parameter Description:

szMsg:

The pointer storing error messages, the storage space is allocated by the application

Return Value:

1 | Successful
-1 | Call failed

Function Description:

Obtains the call failure reason of the functions for voice encoding format conversion.

Note:

l Because this function is provided by ShPcmHandle.dll, it can be invoked before SsmStartCti is called successfully.

Related Information:

Driver version | SynCTI Ver. 4.0 or above
Header | ShPcmApi.h
Library | ShPcmHandle.lib
DLL | ShPcmHandle.dll

Related Function:


2.27.43 fPcm_Close

Releases all resources used by ShPcmHandle.dll.

Format:

void fPcm_Close()

Parameter Description: Nil

Return Value: Nil

Function Description:

Releases all resources used by ShPcmHandle.dll.

Note:

l Please make sure to call this function to release used resources after invoking all transcoding functions in ShPcmHandle.dll.

Related Information:

Driver version | SynCTI Ver. 4.0 or above
Header | ShPcmApi.h
Library | ShPcmHandle.lib
DLL | ShPcmHandle.dll

Related Function:


2.28 Faxing Functions (CTI Series)


2.28.1 Setting Faxing Parameters


2.28.1.1 SsmFaxSetMaxSpeed

Sets the maximum rate used to send or receive fax.

Format:

void SsmFaxSetMaxSpeed(int speed)

Parameter Description:

speed

Maximum rate (bps). Optional value: 4800 bps, 9600bps and 14400 bps; Default value: 9600bps

Return Value: none

Function Description:

Sets the maximum rate used to send or receive fax.

Note:

The parameters set by this function is effective to all the fax channels.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmFaxGetSpeed


2.28.1.2 SsmFaxSetID

Sets the local fax identification code.

Format:

int SsmFaxSetID(int ch,char *szID)

Parameter Description:

ch | Fax channel n umber
szID | Pointer pointing to the string of the ASCII formatted local fax identification code. Valid length: less than 20 characters

Return Value:

-1 | Call failed
0 | Successful

Function Description:

Sets the local fax identification code. The identification code normally is the local phone number, it could also be some other ASCII formatted string.

This local identification code will be sent to the remote fax machine during sending or receiving fax.

Note:

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmFaxGetID


2.28.2 Transmitting Fax


2.28.2.1 SsmFaxStartSend

Refer to SsmFaxStartSendEx


2.28.2.2 SsmFaxStartSendEx

Starts transmission of a single fax file. SsmFaxStartSend is used to transmit the entire file, SsmFaxStartSendEx is used to transmit a range of pages with designated starting and ending page number.

Format:

int SsmFaxStartSend(int ch,char *filename)

int SsmFaxStartSendEx(int ch, char *filename, int nStartPage, int nEndPage)

Parameter Description:

ch | Fax channel number
filename | Name of the file in the tiff format. The file extension name could be ‘.tif’or ‘.tiff’. For more information about file formats supported by fax channels, refer to Fax in Chapter 1
nStartPage | Designated the start page number of the fax file. If ‘filename’ includes N pages, the range of value is : 1~N
nEndPage | Designated the end page number of the fax file. If ‘filename’ includes N pages, the range value is : 1~N: the number of the designated ending page; ³N: transmit until page number N (included); -1: transmit until the last page (i.e. the page numbered N). Note: nEndPage must be larger than or equal to nStartPage

Return Value:

0 | Successful
-1 | Call failed. The failure reason may be that the channel is not free or failure in opening the file

Function Description:

Starts transmission of a single fax file.

After the fax transmission is started, the driver begins to exchange the handshake message with the remote fax machine. If the handshake is successful, the fax file will be sent to the remote fax machine.

Each time when the driver finishes the transmission of one page, it throws out the event of E_CHG_FaxPages to the application; When the driver finishes the fax transmission, it throws out the event of E_PROC_FaxEnd to the application. During the fax transmission, the application may call the function of SsmFaxCheckEnd to check whether the transmission has been finished successfully, or call the function of SsmFaxStop to terminate the transmission.

Note:

l Only when the incoming or outgoing call has been established on the analog trunk channel or the digital trunk channel, can the fax transmission be started.

l The fax channel only works in simplex mode, i.e. it can’t transmit or receive fax simultaneously.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmFaxCheckEnd, SsmFaxStop,SsmFaxSendMultiFile, SsmFaxSendMultiFileEx, SsmFaxAppendSend


2.28.2.3 SsmFaxSendMultiFile

Refer to SsmFaxSendMultiFileEx


2.28.2.4 SsmFaxSendMultiFileEx

Starts transmission of multiple fax files, SsmFaxSendMultiFileEx can specify the range of pages.

Format:

int SsmFaxSendMultiFile(int ch, char * szPath, char * szFile)

int SsmFaxSendMultiFileEx(int ch, FAX_FILE_SCT *pFileNameList, int nNum)

Parameter Description:

ch | Fax channel number
szPath | The path of the fax file szFile. For example, if the fax file is stored under the directory of FaxFile in drive C, for C/C++, szPath may be written as: ‘C:\\FaxFile\\’
szFile | File name list of fax files, the file name extension could be ‘.tif’ or ‘.tiff’, the adjacent file names are separated by ‘;’ For example, there are two fax files to be transmitted, namely ‘A.tif’ and ‘B.tif’, szFile should be written as ‘A.tif;B.tif’. Note: the fax files in szFile must have the same formats
pFileNameList | The fax file list. The struct of FAX_FILE_SCT is declared as: typedef struct tagFAX_FILE_SCT{ char szFileName[256]; //The file name including the full path int nStartPage; //The start page, range of value: 1~N int nEndPage; //=1~N: The designated end page; =-1: to the last page int nReserve1; //Reserved int nReserve2; //Reserved }FAX_FILE_SCT, *PFAX_FILE_SCT; In the above struct, N is the total page number of the fax file. For example, nStartPage=1 and nEndPage=1 means that only the first page is sent; nStart=1 and nEndPage=2 means that the first and second page are sent; if nStart=1 and nEndPage=-1, the entire file is transmitted. Note: nEndPage must be larger than or equal to nStartPage
nNum | The number of the fax files

Return Value:

0 | Successful
-1 | Call failed, the failure reason can be obtained by the function SsmGetLastErrMsg

Function Description:

Starts transmission of multiple fax files.

After this function is called, the driver starts to exchange the handshake message with the remote fax machine, and then transmits the files designated in szFile based on the sequence (from left to right) to the remote fax machine, or sends the fax files starting from the head of the list of pFileNameList until the last file is transmitted.

Each time when the driver finishes the transmission or reception of one page, it throws out the event of E_CHG_FaxPages to the application; When the driver finishes the fax transmission, it throws out the event of E_PROC_FaxEnd to the application. During the multiple fax files transmission, the application may call the function of SsmFaxCheckEnd to check whether the transmission has been finished successfully, or call the function of SsmFaxStop to terminate the transmission.

Note:

l Only when the incoming or outgoing call has been established on the analog trunk channel or the digital trunk channel, can the fax transmission be started.

l The fax channel only works in simplex mode, i.e. it can’t transmit or receive fax simultaneously.

l The punctuation symbols such as colon, pause, period, etc are illegal in the file path string. When multiple fax files are transmitted simultaneously, it’s required that the fax files have the same format.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmFaxCheckEnd, SsmFaxStop, SsmFaxStartSend, SsmFaxStartSendEx


2.28.2.5 SsmFaxAppendSend

Appends a single file to send.

Format:

int SsmFaxAppendSend (int ch,char *filename)

Parameter Description:

ch | Fax channel number
filename | Fax file name. The file name extension may be ‘.tif’ or ‘.tiff’. For more information about the file formats supported by fax channels, refer to Fax in Chapter 1

Return Value:

0 | Successful, the driver has added the designated fax file into the fax transmission pool
-1 | Call failed, the failure reason may be that the channel is free or failure in opening the file

Function Description:

Appends a single file to send. It’s applicable to the fax transmission triggered by the function call of SsmFaxSendMultiFileEx, SsmFaxStartSend or SsmFaxStartSendEx

After this function is called, the driver adds the appended fax file into the fax transmission pool. When the current fax file has been transmitted, the fax files in the transmission pool will be sent immediately.

Note:

l This function can be called only when the fax transmission has been started.

l During the fax transmission, if the transmission is stopped by the client or the transmission failed, the appended fax file will be discarded.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmFaxStartSend, SsmFaxStartSendEx, SsmFaxSendMultiFile, SsmFaxSendMultiFileEx, SsmFaxCheckEnd, SsmFaxStop


2.28.3 Receiving Fax


2.28.3.1 SsmFaxStartReceive

Starts fax reception once.

Format:

int SsmFaxStartReceive(int ch,char *pszFileName)

Parameter Description:

ch | Fax channel number
pszFileName | The name of the Tiff formatted file storing fax data, it must use ‘.tif’ or ‘.tiff’ as the file extension name. If the file exists already, it’s original content will be overlaid

Return Value:

0 | Successful
-1 | Call failed, the failure reason may be that the channel is not free or failure in opening the file

Function Description:

Starts fax reception once.

After this function is called, the driver starts to exchange the handshake message with the remote fax machine. If the handshake is successful, it starts to receive the fax and stores the fax into the file designated by the parameter pszFileName.

Each time when the driver finishes the reception of one page, it throws out the event of E_CHG_FaxPages to the application; When the driver finishes the reception of all the fax pages, it throws out the event of E_PROC_FaxEnd to the application. During the fax reception, the application may call the function of SsmFaxStop to terminate the fax reception.

Note:

l The fax channel only works in simplex mode, i.e. it can’t transmit or receive fax simultaneously.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmFaxCheckEnd, SsmFaxStop


2.28.4 Stopping Faxing


2.28.4.1 SsmFaxStop

Stops the current faxing compulsorily.

Format:

int SsmFaxStop(int ch)

Parameter Description:

ch

Fax channel number

Return Value:

-1 | Call failed
0 | Successful

Function Description:

Stops the current faxing (transmission/reception) compulsorily.

This function not only terminates the fax transmission triggered by the function call of SsmFaxSendMultiFile, SsmFaxSendMultiFileEx and SsmFaxStartSend, SsmFaxStartSendEx but also terminates the fax reception triggered by the function call of SsmFaxStartReceive.

After this function call has completed, the driver will throw out the event of E_PROC_FaxEnd to the application. The execution status of this function can also be obtained via the function call of SsmFaxCheckEnd.

Note:

l This function is an asynchronous function, its execution status may be obtained via the function call of SsmFaxCheckEnd

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmFaxStartSend, SsmFaxStartSendEx, SsmFaxSendMultiFile, SsmFaxSendMultiFileEx, SsmFaxAppendSend, SsmFaxStartReceive, SsmFaxCheckEnd


2.28.5 Obtaining Faxing Information


2.28.5.1 SsmFaxGetSpeed

Obtains the current fax transmission and reception rate.

Format:

int SsmFaxGetSpeed(int ch)

Parameter Description:

ch

Fax channel number

Return Value:

-1 | Not supported by this function
>0 | Actual faxing rate, with the value probably being 24, 48, 72, 96, 120, 144 which respectively represent 2400, 4800, 7200, 9600, 12000, 14400bps

Function Description:

Obtains the current fax transmission and reception rate.

Note:

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmFaxSetMaxSpeed


2.28.5.2 SsmFaxCheckEnd

Obtains the execution status of the fax transmission or reception.

Format:

int SsmFaxCheckEnd(int ch)

Parameter Description:

ch

The number of the fax channel

Return Value:

0 | Faxing has not been finished
1 | Faxing is finished, the fax channel enters the ‘idle’ state
2 | Driver errors during the latest fax transmission or reception, or the faxing has been terminated by the function call of the SsmFaxStop. The channel has returned to the idle state. If this function is called again, it returns 1.
3 | Fax data transmission or reception has been completed, undergoing the negotiation process of disconnection
-1 | Call failed

Function Description:

Obtains the execution status of the fax transmission or reception.

Note:

l This function is applicable to both fax transmission and fax reception;

l If the return value is 2, the faxing has not been finished, but maybe the fax data transmission or reception has been finished;

l If the application programming uses the event mode, it’s recommended to use the event of E_PROC_FaxEnd to replace this function.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmFaxStartSend, SsmFaxStartSendEx ,SsmFaxSendMultiFile, SsmFaxStop, SsmFaxSendMultiFileEx, SsmFaxStartReceive, SsmFaxAppendSend


2.28.5.3 SsmFaxGetDcnTag

When the fax reception is successfully completed by using a fax board, judge if the remote fax machine has ever been compelled to stop.

Format:

int WINAPI SsmFaxGetDcnTag(int ch)

Parameter Description:

ch

Fax channel number

Return Value:

-1 | This function is unsupported by the channel.
0 | The faxing process is complete.
1 | If the faxing is terminated by receiving a DCN message, it may result from the compulsive stop of the fax machine.

Function Description:

When the fax reception is successfully completed by using a fax board, judge if the remote fax machine has ever been compelled to stop.

Note:

l This function is only applicable to the fax reception.

l This function can be used to judge if the remote fax machine has ever been stopped compulsively, and it should be invoked after SsmFaxCheckEnd returns 1.

l If the application program uses the event mode for programming, we suggest you use the event E_PROC_FaxDcnTag instead.

Related Information:

Driver version | SynCTI Ver. 5.0.2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmFaxCheckEnd


2.28.5.4 SsmFaxGetChStateMsg

Obtains the fax channel state.

Format:

int SsmFaxGetChStateMsg(int ch ,char *buf)

Parameter Description:

ch | Fax channel number
buf | Returns the string indicating the channel state. The storage space of buf must be allocated by the application and greater than 100 characters

Return Value:

-1 | Call failed
0 | Successful

Function Description:

Obtains the fax channel state.

Note:

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function:


2.28.5.5 SsmFaxGetPages

Obtains the number of sent/received pages during faxing.

Format:

int SsmFaxGetPages(int ch)

Parameter Description:

ch

Fax channel number

Return Value:

-1 | Call failed
>0 | The number of the finished fax pages

Function Description:

Obtains the number of sent/received pages during faxing.

Note:

l If, after the fax transmission/reception is finished, the return value of this function is 0, it means the current fax transmission/reception failed;

l If the application programming uses the event mode, it’s recommended to use the event of E_CHG_FaxPages to replace this function.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function:


2.28.5.6 SsmFaxGetFailReason

Get the reason why the fax channel fails to fax.

Format:

int SsmFaxGetFailReason(int ch)

Parameter Description:

ch

Fax channel number

Return Value:

-1 | Call failed or error information of ‘No Fax’
0 | Fail to send Dis
1 | No dcs information received (the remote end is not a fax machine or the ‘Start’ button on the fax machine is not pressed)
2 | dis information received during the fax reception (the remote end is receiving the fax but did something wrong with the operation)
3 | No training packet detected during the fax reception
4 | Always fail to pass the training during the fax
5 | Fail to send FTT information
6 | Fail to send cfr
7 | No carrier detected
8 | No subsequent frames detected after carrier reception
9 | Fail to send MCF
10 | Fail to send PPR
11 | Fail to send CTR
12 | Fail to send RTN
13 | Fail to send ERR
14 | Unidentifiable frames received
15 | Received page data not good
16 | Data unavailable
17 | Page data from the sender wrong
20 | No Dis information received by the fax sender (the remote end is not a fax machine or the ‘Start’ button on the fax machine is not pressed, or the the fax board fails to detect Dis information)
21 | No response of the fax receiver to train received
22 | Fail to send fax data
23 | Fail to send frames after fax transmission
24 | No response of the fax receiver detected after the transmission of a page of data
25 | DSP running out of track
26 | Fail to write data into file
27 | Fax resending refused by the remote end
28 | Faxing stopped on the application layer
29 | Repeatedly fail to send RR
30 | RR T5 times out

Function Description:

Get the reason why the fax channel fails to fax.

Note:

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function:


2.28.5.7 SsmFaxGetID

Obtains the identification code of the remote fax machine.

Format:

int SsmFaxGetID(int ch,char *myid)

Parameter Description:

ch | Fax channel number
myid | The pointer pointing to the buffer area storing the identification code, its storage space is allocated by the application. The length of the buffer area can’t be less than 20 bytes

Return Value:

-1 | Call failed
0 | Successful

Function Description:

Obtains the identification code of the remote fax machine.

Note:

l This function can only be called after the handshake has been completed, otherwise, the correct identification code is not able to be obtained.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function: SsmFaxSetID


2.28.5.8 SsmFaxGetMode

Obtains the operating status and supported modes of the fax channel—transmitting or receiving, fine mode or common mode, ECM mode or data stream mode.

Format:

int SsmFaxGetMode(int ch, int * pnDir, int *pnResMode, int * pnTransMode)

Parameter Description:

ch | The number of the fax channel
pnDir | Used to store transmitting or receiving indicator =0: indicates the fax channel is receiving data =1: indicates the fax channel is transmitting data
pnResMode | Used to store the fax data mode indicator =0: indicates the common mode =1: indicates the fine mode
pnTransMode | Used to store the transmitting mode indicator for the fax channel =0: indicates the data stream mode =1: indicates the ECM mode

Return Value:

-1 | The fax channel does not support this operation
0 | The fax channel is idle and necessary parameters are unavailable by this function
1 | Function call is successful

Function Description:

Obtains the operating status and supported modes of the fax channel—transmitting or receiving, fine mode or common mode, ECM mode or data stream mode.

Note:

l This function can be only invoked after the handshake phase; otherwise it is impossible to obtain the correct indicator.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function:


2.28.5.9 SsmFaxGetAllBytes

During fax transmission, obtains the total number of bytes on the fax page.

Format:

int SsmFaxGetAllBytes(int ch)

Parameter Description:

ch

Fax channel number

Return Value:

-1 | Call failed
≥0 | The total number of bytes on the current fax page

Function Description:

During fax transmission, obtains the total number of bytes on the fax page.

Note:

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function:


2.28.5.10 SsmFaxGetSendBytes

Obtains the number of sent bytes on the current page during fax transmission.

Format:

int SsmFaxGetSendBytes(int ch)

Parameter Description:

ch

Fax channel number

Return Value:

-1 | Call failed
≥0 | The number of sent bytes on the current page

Function Description:

Obtains the number of sent bytes on the current page during fax transmission.

Note:

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function:


2.28.5.11 SsmFaxGetRcvBytes

Obtains the number of received bytes on the current page during fax reception.

Format:

int SsmFaxGetRcvBytes(int ch)

Parameter Description:

ch

Fax Channel Number

Return Value:

-1 | Call failed
≥0 | The number of received bytes on the current page

Function Description:

Obtains the number of received bytes on the current page during fax reception.

Note:

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | shpa3api.h
Library | shp_a3.lib
DLL | shp_a3.dll

Related Function:


2.28.6 Relatvie Operations on .tif File


2.28.6.1 fBmp_ValidateFaxFile

Determines whether the .tif file qualifies the fax format of Synway boards.

Format：

int fBmp_ValidateFaxFile(char *szFile)

Parameter Description：

szFile

The string storing the fax file

Return Value：

0 | Successful, fax transmission supports the .tif file
-1 | Fax transmission doesn’t support the .tif file, more detailed reason may be obtained via the function fBmp_GetErrMsg
-2 | Failure in opening the file, more detailed reason may be obtained via the function fBmp_GetErrMsg

Function Description:

Determines whether the .tif file qualifies the fax format of Synway boards.

Note:

Related Information:

Driver version | SynCTI Ver. 4.7.3.1 or above
Header | BmpApi.h
Library | BmpUtil.lib
DLL | BmpUtil.dll

Related Function:


2.28.6.2 fBmp_SetHeaderFormat

Sets the property of the page header of .tif formatted fax file.

Format：

int fBmp_SetHeaderFormat(int nRow, int nFromX, int nFromY, char szFrom, int nSubX, int nSubY, char*szSubject, int nToX, int nToY, char*szTo, int nTimeX, int nTimeY, char*szTime)

Parameter Description：

nRow | Indicates the rows number of the page header, range of value: 1~3, with the default value of 1
nFromX | Indicates the starting position of the field of From, with the default value of 5
nFromY | Indicates the number of the row where the field From locates, it’s between 1 and 3, 1 denotes the first line, the defaulted row number is 1
szFrom | Indicates the prompting field of the field of From, by default it is ‘From:’, maximum length is 20 bytes
nSubX | Indicates the starting position of the field of From, with the default value of 270
nSubY | Indicates the number of the row where the field of Subject locates, it’s between 1 and 3, 1 denotes the first line, the defaulted row number is 1
szSubject | Indicates the prompting field of the field of Subject, by default it’s ‘Sub’, maximum length is 20 bytes
nToX | Indicates the starting position of the field of To, with the default value of 440
nToY | Indicates the number of the row where the field of To locates, it’s between 1 and 3, 1 denotes the first line, the defaulted row number is 1
szTo | Indicates the prompting field of the field of To, by default it is ‘To:’, maximum length is 20 bytes
nTimeX | Indicates the starting position of the field of Time, with the default value of 660
nTimeY | Indicates the number of the row where the field of Time locates, it’s between 1 and 3, 1 denotes the first line, the defaulted row number is 1
szTime | Indicates the prompting field of the field of Time, by default it is ‘’, maximum length is 20 bytes

Return Value：

-1 | Call failed, the failure reason may be obtained via the function fBmp_GetErrMsg
1 | Successful

Function Description:

Sets the property of the page header generated by fBmp_AddTxtToTif.

Note:

l If Subject needs to be put on the second row, set nRow =2, nSubY=2.

l The horizontal range is 0~864. Adjust the positions of the data fields and keep them in the range.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | BmpApi.h
Library | BmpUtil.lib
DLL | BmpUtil.dll

Related Function: fBmp_AddTxtToTif, fBmp_AddTxtToTif_Big, fBmp_UniteTif


2.28.6.3 fBmp_AddTxtToTif

Adds the page header to the .tif file, only international encoding supported.

Format：

int fBmp_AddTxtToTif(char szTifName, char* szFaxFrom, char*szFaxTo, char *szFaxSubbject, char * szDataTime , char *szTargetFile, DWORD dwReserve)

Parameter Description：

szTifName | The .tif file where page headers are required to add
szFaxFrom | The information about the fax transmit end, the maximum length is 20 bytes, each Chinese character occupies 2 bytes
szFaxTo | The information about the fax receive end, the maximum length is 20 bytes, each Chinese character occupies 2 bytes
szFaxSubject | The fax subject, the maximum length is 10 bytes, each Chinese character occupies 2 bytes
szDataTime | Time information, the maximum length is 20 bytes
szTargetFile | The to-be-generated tif file with page headers, if it has the same name as szTifName, the original file will be overlapped
dwReserve | Invalid at present, reserved for further extension use. It should be set to 0 if it is used. When it is set to 1, the size of all parameters mentioned above goes unlimited

Return Value：

-1 | Call failed, the failure reason may be obtained via the function fBmp_GetErrMsg
1 | Successful

Function Description:

Adds the page header to the .tif file. Adds the page header data which is 16 rows (each row has 1728 pixels) on the top of the file szTifName, and outputs the result to the file of szTargetFile. If the second bit of dwReserve is set 1, the higher 16 bits denote the page on which the page header will be added.

Note:

l If szTifName and szTargetFile are the same, the original file will be overlapped;

l The data on the top of the file is positioned from left to right: szFaxFrom,szSubject,szFaxTo,szDataTime

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | BmpApi.h
Library | BmpUtil.lib
DLL | BmpUtil.dll

Related Function: fBmp_SetHeaderFormat, fBmp_AddTxtToTif_Big, fBmp_CutTifHeader


2.28.6.4 fBmp_AddTxtToTif_Big

Adds the page header to the .tif file. Apart from supporting the international code, it also supports Big-5 traditional Chinese characters code.

Format：

int fBmp_AddTxtToTif_Big(char*szTifName, char*szFaxFrom, char*szFaxTo, char*szFaxSubject, Char *szDataTime, char *szTargetFile, DWORD dwReserve )

Parameter Description：

szTifName | The tif file which needs the page header to be added
szFaxFrom | The information about the fax transmit end, the maximum length is 20 bytes, each Chinese character occupies 2 bytes
szFaxTo | The information about the fax receive end, the maximum length is 20 bytes, each Chinese character occupies 2 bytes
szFaxSubject | The fax subject, the maximum length is 10 bytes, each Chinese character occupies 2 bytes
szDataTime | Time information, the maximum length is 20 bytes
szTargetFile | The to be generated tif file which has the page header, if it has the same name as szTifName, the original file will be overlapped
dwReserve | Reserved for further needs, set it 0 when it’s been used

Return Value：

-1 | Call failed, the failure reason may be obtained via the function fBmp_GetErrMsg
1 | Successful

Function Description:

Adds the page header to the .tif file. It also supports Big-5 traditional Chinese characters code.

Adds the page header data which is 16 rows (each row has 1728 pixels) on the top of the file szTifName, and outputs the result to the file of szTargetFile. If the second bit of dwReserve is set 1, the higher 16 bits denote the page on which the page header will be added.

Note:

l If szTifName and szTargetFile are the same, the original file will be overlapped;

l The data on the top of the file is positioned from left to right: szFaxFrom,szSubject,szFaxTo,szDataTime;

l The function supports the fonts supported by the operating system.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | BmpApi.h
Library | BmpUtil.lib
DLL | BmpUtil.dll

Related Function: fBmp_SetHeaderFormat, fBmp_AddTxtToTif, fBmp_CutTifHeader


2.28.6.5 fBmp_UniteTif

Creates the union of two .tif files.

Format：

int fBmp_UniteTif(char*szHeadTif, char * szSourceTif, char *szTargetTif, DWORD dwReserve)

Parameter Description：

szHeadTif | The smaller .tif file added to the top of another file. It can only be a single page file
szSourceTif | The .tif file on top of which a smaller file will be added. It can be a file with multiple pages
szTargetTif | The generated .tif file
dwReserve | Reserved

Return Value：

-1 | Call failed, the failure reason may be obtained via the function fBmp_GetErrMsg
1 | Successful

Function Description:

Creates the union of two .tif files. Adds szHeadTif on the top of szSourecTif and creates szTargetTif.

Note:

l If szTifName and szTargetFile are the same, the original file will be overlapped;

l If the second bit of dwReserve is set 1, the higher 16 bits denote the page on which the page header will be added. If this page is not specified, all the pages of the file SzSourceTif will be added with szHeadTif.

Related Information:

Driver version | SynCTI Ver. 2.0 or above
Header | BmpApi.h
Library | BmpUtil.lib
DLL | BmpUtil.dll

Related Function: fBmp_SetHeaderFormat


2.28.6.6 fBmp_CutTifHeader

Cuts the file header of the .tif file.

Format：

int fBmp_CutTifHeader(char *Source, char*szTarget, int nHeight, int nPgeNo, DWORD dwReserve)

Parameter Description：

szSource | The .tif source file, its file header needs to be cut
szTarget | Generated target file. If the file exists, it will overlap the original file
nHeight | The height to be cut
nPageNo | The number of the specified page in the .tif file, the page’s file header needs to be cut
dwReserve | Reserved

Return Value：

-1 | Call failed, the failure reason may be obtained via the function fBmp_GetErrMsg
1 | Successful

Function Description:

Cuts the file header of the .tif file. The preset part will be cut from the top of the .tif file.

Note:

l If szSourceTif and szTargetFile are the same, the original file szSourceTif will be overlapped;

l Normally nHeight is in the range of 16~40. For a single row file header, the height is approximately 20;

l nPageNo is the designated page. If it’s set -1, the file headers of all the pages will be cut.

Related Information:

Driver version | SynCTI Ver. 4.7.1.5 or above
Header | BmpApi.h
Library | BmpUtil.lib
DLL | BmpUtil.dll

Related Function: fBmp_AddTxtToTif_Big, fBmp_AddTxtToTif


2.28.6.7 fBmp_GetFileAllPage

Outputs the total page number of the fax file.

Format：

int fBmp_GetFileAllPage(char *filename)

Parameter Description：

filename

The string storing the fax file

Return Value：

-1 | Failed, the failure reason may be failure in opening the file or incorrect file format
>=0 | Successful, outputs the total page number of the file

Function Description:

Outputs the total page number of the fax file of filename.

Note:

Related Information:

Driver version | SynCTI Ver. 4.4.0.6 or above
Header | BmpApi.h
Library | BmpUtil.lib
DLL | BmpUtil.dll

Related Function：


3 SynCTI Driver Configuration


3.1 System Configuration File ShConfig.ini

When Synway boards are being used, correct and necessary configurations must be implemented on the driver in order to make the application operate properly.

The configuration information of SynCTI driver is saved in the INI file adopting the text format. After the SynCTI driver is successfully installed, the installation program will generate a sample configuration file namely ShConfig.ini under the installation directory. The developers may not only straightly edit or modify the configuration file by using text editing software, but may also be able to change the configuration by using the system configuration tools provided by Synway.

In the configuration file, the configuration information is grouped with sections (Section); each section includes one or multiple items (Item). The name of the section appears in a pair of square brackets, each of the continuous text rows is a configuration item. The effective range of one section starts from the second row of the current section and ends with one row above the next section. Each configuration item has the format of ‘x=y’, the name of the configuration item is at the left side; the content of the configuration is at the right side.


3.1.1 Essential Configuration Items


3.1.1.1 Setting Total Number of Boards


3.1.1.1.1 TotalBoards
Configuration Item | TotalBoards
Section | [SystemConfig]
Format | TotalBoards=N
Value Range | N equals to the total number of Synway’s boards installed in the System.
Feature | Sets the total number of Synway’s boards installed in the System.


3.1.1.1.2 WhoSupplySysClock
Configuration Item | WhoSupplySysClock
Section | [SystemConfig]
Written Format | WhoSupplySysClock=n
Value Range | n=-1: Set all the Synway’s boards to be slave boards; n=N: Set all the Synway’s boards to be master boards; 0≤n≤N-1: Set the board with logical number n to be the master board, all the rest of the boards are slave boards. Note: N is the set value of the configuration item TotalBoards .
Description | Sets the master board of the Synway’s boards in the application system. For more information, refer to ‘ System Clock Configuration ’.


3.1.1.2 Setting Channel Number


3.1.1.2.1 TotalAppCh
Configuration Item | TotalAppCh
Section | [AppChToBoardChTable]
Written Format | TotalAppCh=M
Value Range | M is the total channel number of all the boards in the System.
Description | Sets the total channel number in the System.


3.1.1.2.2 AppCh
Configuration Item | AppCh
Section | [AppChToBoardChTable]
Written Format | Format 1:AppCh[is]=k,js…je Format 2:AppCh[i]=k,j In the above formulas, i: The channel number used by the application, it normally starts with 0 is: The start channel number used by the application k:The BoardID of the board on which a mapping needs to be created j: The internal channel number on the board js:The internal start channel number on the board je:The internal end channel number on the board
Value Range |
Description | Creates the mapping between the channel number of the application and the channel number on the board. Format 1 is used for batched mapping creation; format 2 is used for one by one mapping creation.


3.1.1.3 Setting Board Information


3.1.1.3.1 BoardModel
Configuration Item | BoardModel
Section | [BoardId=x]
Written Format | BoardModel=s
Value Range | s is the string denoting the board model. For the available models, refer to Board Classification .
Description | Sets the board model.
Example | BoardModel=SHT-16B-CT/PCI


3.1.1.3.2 BoardSerialNumber
Configuration Item | BoardSerialNumber
Section | [BoardId=x]
Written Format | BoardSerialNumber=N
Value Range | The serial number of the board.
Description | Sets the board serial number, for the detailed value, refer to the related hardware manual.
Example | BoardSerialNumber=11


3.1.1.4 SHD/DTP Series


3.1.1.4.1 Setting Board Reset Feature


3.1.1.4.1.1 ResetBoardOnClose
Configuration Item | ResetBoardOnClose
Section | [BoardId=x]
Written Format | ResetBoardOnClose =n
Value Range | n=0:Not to reset; n=1:Reset (default).
Description | Sets whether to reset the board when the board is being closed.


3.1.1.4.2 Setting Parameters of Digital Trunk


3.1.1.4.2.1 PcmNumber

Refer to CRC-4


3.1.1.4.2.2 PcmSSx

Refer to CRC-4


3.1.1.4.2.3 PcmClockMode

Refer to CRC-4


3.1.1.4.2.4 PcmLinkType

Refer to CRC-4


3.1.1.4.2.5 IsdnAutoBuildLink

Refer to CRC-4


3.1.1.4.2.6 CRC-4

Configuration Item

PcmNumber

PcmSSx

PcmClockMode

PcmLinkType

IsdnAutoBuildLink

CRC-4

Section

[BoardId=x]

Written Format

PcmNumber=M

PcmSSx[i]=n

PcmClockMode[i]=m

PcmLinkType[i]=k

IsdnAutoBuildLink[i]=b

CRC-4[i]=c //Note: Requires the version of SynCTI Ver. 4.7.1.5 or above

Value Range

M: The total number of the digital trunks on the board, it’s related with the board model, for more information, refer to ‘ SHD Series ’ in Chapter 1;

i: The physical number of the digital trunk on the board, for more information, refer to related manuals. Range of value: 0≤i≤M;

n: Choose the signaling protocol. Range of value:

n=0: ISDN protocol (User side);

n=1: SS1 signaling (SS1);

n=2: ISDN protocol (Network side);

n=7: SS7 signaling (SS7);

m: Set the clock mode of the current digital trunk, below are the details:

m=0: Master clock, line-synchronization ( the board must be a master board)

m=1: Master clock, free-run (the board must be a master board)

m=2: Slave clock.

k: Choose the type of the communication cable. Range of value:

k=0:120 ohm twisted pair cable;

k=1:75 ohm coaxial cable.

b: Set whether to enable the feature of automatic link building for the ISDN signaling.

b=0: Disabled (default);

b=1: Enabled (If you enable this feature, you should set the configuration items of UserSendEstablish and NetSendEstablish in the [ISDN] section both to 0).

c: The control switch for CRC-4 verification:

c=0: Disabled;

c=1: Enabled (default).

Description

PcmNumber sets the total number of the digital trunks on the board;

PcmSSx sets the signaling type of the digital trunk;

PcmClockMode sets the operating mode of the clock, for more information, refer to ‘ System Clock Configuration ’ in chapter 1;

PcmLinkType sets the communication type of the cable;

CRC-4 sets the CRC-4 verification feature of the digital trunk on the board.

Note

l If the set value of PcmNumber is larger than 0, for the configuration items PcmSSx, PcmClockMode and PcmLinkType, starting from i=0, the configuration needs to be repeated M times, i.e. each physical digital trunk needs to be configured;

l These configuration items are only applicable to SHD/DTP Series.

Example

It’s supposed that there are two pieces of SHD-60A-CT/PCI/SS7 boards installed in the system.

Board 0 uses SS7 signaling, connects with 120 ohm twisted pair cable. Digital Trunk 0 on Board 0 provides the master clock to the application using line-synchronization mode; Board 0 uses ISDN protocol (user side), connects with 75 ohm twisted pair cable. Below are the configuration items:

[BoardId=x]

……

PcmNumber=4

PcmSSx[0]=7 //SS7 signaling

PcmSSx[1]=7

PcmSSx[2]=0 //ISDN user side

PcmSSx[3]=0

PcmClockMode[0]=0 //Master clock, line-synchronization

PcmClockMode[1]=2 //Must be set as slave clock

PcmClockMode[2]=2

PcmClockMode[3]=2

PcmLinkType[0]=0 //120 ohm twisted pair cable

PcmLinkType[1]=0

PcmLinkType[2]=1 //75 ohm coaxial cable

PcmLinkType[3]=1


3.1.1.4.2.7 Loopback

Configuration Item

loopback

Section

[BoardId=x]

Written Format

loopback[pcm]=c

Value Range

pcm: The on-board physical number for corresponding digital trunk. Refer to relative manuals for more information. Range of value: 0≤i≤M.

c: Controls the loopback feature of digital trunks:

=0x1: Transmitted data loop back from the framer to the receive end (LOOP_FRAME);

=0x2: Transmitted data loop back from LIU transmitter to LIU receiver (LOOP_LOCAL);

=0x4: Analog signals loop back over LIU (LOOP_ANALOG, only for D-type and E-type boards);

=0x10: Transmitted data loop back to LIU transmitter after being decoded in LIU receiver (LOOP_REMOTE);

=0x20: Payload data loop back to the transmitter end (LOOP_PAYLOAD).

Description

Sets the loopback feature of trunks, used for diagnoses or debugging.

Note

l This configuration item requires SynCTI Ver. 5.1.0.0 or above.

l It is only applicable to SHD/DTP Series.

Example

[BoardId=x]

……

Loopback[0]=0x20

……


3.1.1.4.2.8 SpySyncAndCCS

Configuration Item

SpySyncAndCCS

Section

[BoardId=x]

Written Format

SpySyncAndCCS=n

Value Range

n=0: Disable the sync & signaling messages acquisition mode;

n=1: Enable the sync & signaling messages acquisition mode. Don’t enable this switch in normal operation.

Description

This switch shall be enabled only when the line synchronization or the signaling delivery is in an abnormal state. In such situation, set SpySyncAndCCS=1 to enable the sync& signaling messages acquisition mode and use the test program ‘TEST.EXE’ contained in the driver to record sync and signaling messages. That is, connect the time slots which deliver sync and signaling messages to corresponding channels which previously transported voice data, and select ‘A-law’ to start recording. To be exact, record the raw data on the time slot for synchronization via the PCM channel 0, record the raw data on the time slot for signaling reception via the PCM channel 1 and record the raw data on the time slot for signaling transmission via the PCM channel 2. Record all these data to .PCM files.

Note

l For ISDN lines, enable the feature of CRC check via the configuration items UserCrcMode and NetCrcMode before using this feature;

l For DTP series C-type boards, set the configuration item DefaultVoiceFormat to 7 and use µ-Law to record speech files;

l Make sure you use this feature under the direction of Synway technical support engineers. Then provide the recorded files to our developers for further analysis and diagnosis;

l Requires the version of SynCTI 5.3.0.3 or above;

l This configuration item is only applicable to some of the SHD/DTP series boards. See below for detailed information.

Below is a list of board models that support this feature.

Board Model | Acquisition of raw data on the time slot for synchronization | Acquisition of raw data on the time slot for signaling reception | Acquisition of raw data on the time slot for signaling transmission
SHD_30A_CT_PCI_SS1 | √ | √ | ×
SHD_30A_CT_PCI_ISDN | √ | √ | ×
SHD_30A_CT_PCI_SS7 | √ | √ | ×
SHD_30A_CT_PCI_FJ | √ | √ | -
SHD_60A_CT_PCI_SS1 | √ | √ | ×
SHD_60A_CT_PCI_ISDN | √ | √ | ×
SHD_60A_CT_PCI_SS7 | √ | √ | ×
SHD_60A_CT_PCI_FJ | √ | √ | -
SHD_120A_CT_PCI_SS1 | √ | √ | ×
SHD_120A_CT_PCI_ISDN | √ | √ | ×
SHD_120A_CT_PCI_SS7 | √ | √ | ×
SHD_30B_CT_PCI_FJ | √ | √ | -
SHD_60B_CT_PCI_FJ | √ | √ | -
SHD_30C_CT_PCI | √ | √ | ×
SHD_30C_CT_PCI_FAX | √ | √ | ×
SHD_60C_CT_PCI | √ | √ | ×
SHD_60C_CT_PCI_FAX | √ | √ | ×
SHD_120D_CT_PCI | √ | √ | √
SHD_120D_CT_PCI_EC | √ | √ | √
SHD_240D_CT_PCI | √ | √ | √
SHD_240D_CT_PCI_EC | √ | √ | √
SHD_30E_CT_PCI | × | √ | ×
SHD_30E_CT_PCI_EC | × | √ | ×
SHD_30E_CT_PCI_FAX | × | √ | ×
SHD_60E_CT_PCI | × | √ | ×
SHD_60E_CT_PCI_EC | × | √ | ×
SHD_60E_CT_PCI_FAX | × | √ | ×
SHD_120E_CT_PCI | √ | √ | √
SHD_120E_CT_PCI_EC | √ | √ | √
SHD_120E_CT_PCI_FAX | √ | √ | √
SHD_240E_CT_PCI | √ | √ | √
SHD_240E_CT_PCI_EC | √ | √ | √
SHD_240E_CT_PCI_FAX | √ | √ | √
SHD_30E_CT_PCIe | × | √ | ×
SHD_30E_CT_PCIe_EC | × | √ | ×
SHD_30E_CT_PCIe_FAX | × | √ | ×
SHD_60E_CT_PCIe | × | √ | ×
SHD_60E_CT_PCIe_EC | × | √ | ×
SHD_60E_CT_PCIe_FAX | × | √ | ×
SHD_120E_CT_PCIe | √ | √ | √
SHD_120E_CT_PCIe_EC | √ | √ | √
SHD_120E_CT_PCIe_FAX | √ | √ | √
SHD_240E_CT_PCIe | √ | √ | √
SHD_240E_CT_PCIe_EC | √ | √ | √
SHD_240E_CT_PCIe_FAX | √ | √ | √
DTP_30C_PCI | √ | √ | -
DTP_30C_PCI_EX | √ | √ | -
DTP_60C_PCI | √ | √ | -
DTP_60C_PCI_EX | √ | √ | -
DTP_120C_PCI | √ | √ | -
DTP_120C_PCI_EX | √ | √ | -
DTP_30C_PCIe | √ | √ | -
DTP_30C_PCIe_EX | √ | √ | -
DTP_60C_PCIe | √ | √ | -
DTP_60C_PCIe_EX | √ | √ | -
DTP_120C_PCIe | √ | √ | -
DTP_120C_PCIe_EX | √ | √ | -

Legend: √: Supported ×: Unsupported -: Invalid


3.1.1.4.3 Setting Logical PCM Number


3.1.1.4.3.1 TotalPcm

Refer to Pcm


3.1.1.4.3.2 Pcm

Configuration Item

TotalPcm

Pcm

Section

[PcmInfo]

Written Format

TotalPcm=M

Pcm[m]=k,j

Value Range

M: The total number of the digital trunks in the application. It must be less than or equal to the total physical PCM number in the system;

m: The logical number of the digital trunk in the application. It must start from 0, the range of value: 0≤m<M (M is the set value of the configuration item TotalPcm)

k: The logical number of the board. Range of value:

² 0≤k<N: N is the set value of the configuration item TotalBoards . The logical number of the digital trunk in the application is bound with the actual physical digital trunk.

² k=-1: The logical number of the digital trunk in the application is bound with the virtual circuit. The binding is only applicable to SS7 TUP and ISUP protocols, it requires the driver version to be 4.7.1.0 or above. For more information about the virtual circuit, refer to ‘ Virtual Circuit Programming Interface on SS7 Server ’ in chapter 1.

j: If k≠-1, j denotes the physical number of the digital trunk, it must be the number of physically existing PCM; If k=-1, the corresponding digital trunk of j maybe virtual.

Description

TotalPcm sets the total number of the digital trunks in the application;

Pcm establishes the mapping relation between the logical number and physical number of the digital trunk .

Note

This configuration item is only applicable to the SHD and DTP Series.

Example

It’s supposed that there are two pieces of SHD-60A-CT/PCI/ISDN boards installed in the system, the below configuration items illustrate how to establish the mapping relation between the logical number and physical number of the digital trunk:

[PcmInfo]

TotalPcm=4

Pcm[0]=0,0 //Set Digital Trunk 0 on Board 0 to be Digital Trunk 0 in the application

Pcm[1]=0,1 //Set Digital Trunk 1 on Board 0 to be Digital Trunk 1 in the application

Pcm[2]=1,0 //Set Digital Trunk 0 on Board 1 to be Digital Trunk 2 in the application

Pcm[3]=1,1 //Set Digital Trunk 1 on Board 1 to be Digital Trunk 3 in the application


3.1.1.4.3.3 2PcmIn1Line

Configuration Item

2PcmIn1Line

Section

[BoardId=x]

Written Format

2PcmIn1Line=m

Value Range

M=0 (default): We recommend you use the outlet board RSD081 (standard 8-pin RJ48C) for the UMCT intelligent switch, as in such situation the interfaces are arranged in the same order as the PCM numbers. For the outlet board RSD082 (4-pin RJ48C/M), the first jack corresponds to PCM0 and PCM4, the second corresponds to PCM1 and PCM5, the third corresponds to PCM2 and PCM6, and the fourth corresponds to PCM3 and PCM7.

M=1: We recommend you use the outlet board RSD082 (4-pin RJ48C/M) for the UMCT intelligent switch. In such situation, the first jack corresponds to PCM0 and PCM1, the second corresponds to PCM2 and PCM3, the third corresponds to PCM4 and PCM5, and the fourth corresponds to PCM6 and PCM7. For the outlet board RSD081 (standard 8-pin RJ48C), the 8 jacks in order correspond to PCM0, PCM4, PCM1, PCM5, PCM2, PCM6, PCM3 and PCM7.

Description

As on the UMCT intelligent switch the mainboard is separated from the outlet board and the switch itself can not distinguish RSD081 from RSD08, this configuration item helps to make the PCM arrangement more in accordance with the common use habit.

Note

This configuration item is applicable to the 240-port E-type digital boards used on the UMCT intelligent switch.


3.1.1.4.4 Setting SpyPCM Number (DTP Series)


3.1.1.4.4.1 TotalSpyPcm

Refer to SpyPcm


3.1.1.4.4.2 SpyPcm

Configuration Item

TotalSpyPcm

SpyPcm

Section

[SpyPcm]

Written Format

TotalSpyPcm=M

SpyPcm[m]=Pcm[j],Pcm[k]

Value Range

M: The total number of digital trunks to be monitored in the application;

m: The number of SpyPcm, starts from 0, 0≤m≤M;

j,k: The logical number of the digital trunk, it’s set by the configuration item Pcm in the section of [PcmInfo]. For more information, refer to ‘ Digital Trunk ’ in chapter 1.

It’s recommended to use the connecting input ports of two digital trunks on the board which have continuous logical number to monitor one SpyPCM, hence, under most conditions, k=j+1. Note: j and K must be located on the same board.

Description

TotalSpyPcm sets the total number of the digital trunks in the application system to be monitored;

SpyPcm determines which two on-board digital trunks should be connected with circuits to process the monitored digital trunk. That is, bind SpyPCM m to the circuits on Digital Trunk j and Digital Trunk k.

Note

This configuration item is only applicable to DTP Series

Example

It’s supposed that only one board of SHD-60A-CT/PCI/FJ is installed in the system, the board is used to record the 60 voice channels (30x2) and two ISDN PRI signaling channels on the two E1 trunks (75 ohm coaxial cable). The following configuration is needed to implement the monitoring:

[BoardId=x]

……

PcmNumber=4

PcmSSx[0]=0 //ISDN user side

PcmSSx[1]=0

PcmSSx[2]=0

PcmSSx[3]=0

PcmClockMode[0]=0 //Master clock, line-synchronization

PcmClockMode[1]=2 // It must be set to be slave clock

PcmClockMode[2]=2

PcmClockMode[3]=2

PcmLinkType[0]=1 //75 ohm coaxial cable

PcmLinkType[1]=1

PcmLinkType[2]=1

PcmLinkType[3]=1

[PcmInfo]

TotalPcm=4

Pcm[0]=0,0 // Set Digital Trunk 0 on Board 0 to be Digital Trunk 0 in the application

Pcm[1]=0,1 // Set Digital Trunk 1 on Board 0 to be Digital Trunk 1 in the application

Pcm[2]=0,2 // Set Digital Trunk 2 on Board 0 to be Digital Trunk 2 in the application

Pcm[3]=0,3 // Set Digital Trunk 3 on Board 0 to be Digital Trunk 3 in the application

[SpyPcm]

TotalSpyPcm=2

SpyPcm[0]=Pcm[0],Pcm[1] //Using PCM 0 and PCM 1 to record the information on SpyPCM 0

SpyPcm[1]= Pcm[2],Pcm[3] //Using PCM 2 and PCM 3 to record the information on SpyPCM 1

[AppSpyCICTable]

TotalAppSpyCIC=60

AppSpyCIC[0]=SpyPcm[0],0..29 // Set the physical position for the SpyCIC which has a logical number in the range of 0..29

AppSpyCIC[30]=SpyPcm[1],0..29 // Set the physical position for the SpyCIC which has a logical number in the range of 30~59


3.1.1.4.4.3 SpyT1TransE1Line
Configuration Item | SpyT1TransE1Line
Section | [SpyPcm]
Written Format | SpyT1TransE1Line=b
Value Range | b=0: The monitored line is the common E1 line; b=1: The monitored line is the line transformed by a T1-to-E1 device.
Description | Sets whether the channels are numbered by continuous codes (E1:1-30 or T1:1-23) or discontinuous codes (E1:1-15, 17-31).
Note | l This configuration item is only applicable to monitoring of ISDN lines; l This configuration item is only applicable to DTP Series.


3.1.1.4.5 Setting SpyCIC Number (DTP Series)


3.1.1.4.5.1 TotalAppSpyCIC

Refer to AppSpyCIC


3.1.1.4.5.2 AppSpyCIC

Configuration Item

TotalAppSpyCIC

AppSpyCIC

Section

[AppSpyCICTable]

Written Format

TotalAppSpyCIC=N

Format 1: AppSpyCIC[n]=SpyPcm[m],k

Format 2: AppSpyCIC[n]=SpyPcm[m],ks..ke

Value Range

N: The total number of SpyCIC;

n: The logical number of SpyCIC, numbered from 0, 0≤n<N;

m: The logical number of SpyPCM, for more information, refer to the configuration item TotalSpyPcm or SpyPcm ;

k: The circuit number on SpyPcm, 0≤k≤29. For SS7 signaling, the value of k is the CIC field in the message of TUP or ISUP; For ISDN PRI signaling, the actual relation between the value of k and PCM is:

ks: The starting circuit number on SpyPcm, 0≤ks≤29;

ke: The ending circuit number on SpyPcm, 0≤ke≤29

Description

TotalAppSpyCIC sets the total number of the monitored circuits;

AppSpyCIC establishes the mapping between the logical number of the SpyCIC in the application and one actual circuit on the SpyPCM. For more information, refer to ‘ DTP Series ’ in Chapter 1

Note

l Format 1 is used for one-by-one setting, format 2 is used for batched setting which is equivalent to the continuous ke-ks+1 times of setting with format 1 starting from ks;

l This configuration item is only applicable to DTP Series

Example

Refer to the example in the configuration item TotalSpyPcm


3.1.1.4.6 Essential Configuration Items for SS7 (DTP Series)


3.1.1.4.6.1 TotalSpyLinkSet

Refer to SpyIsupCICPcm


3.1.1.4.6.2 SpyLinkSet

Refer to SpyIsupCICPcm


3.1.1.4.6.3 TotalSpyLinkPcm

Refer to SpyIsupCICPcm


3.1.1.4.6.4 SpyLinkPcm

Refer to SpyIsupCICPcm


3.1.1.4.6.5 SpyCICPcm

Refer to SpyIsupCICPcm


3.1.1.4.6.6 SpySpCodeLen

Refer to SpyIsupCICPcm


3.1.1.4.6.7 SpyIsupCICPcm

Configuration Item

TotalSpyLinkSet

SpyLinkSet

TotalSpyLinkPcm

SpyLinkPcm

SpyCICPcm

SpySpCodeLen

SpyIsupCICPcm

Section

[SS7Spy]

Written Format

Configuration 1: applicable to single-link group:

TotalSpyLinkPcm=M

SpyLinkPcm[m]=SpyPcm[x]

SpyCICPcm[k]=SpyPcm[y]

SpyIsupCICPcm[k]=SpyPcm[y]

SpySpCodeLen=j

Configuration 2: applicable to single-link group or multi-link group:

TotalSpyLinkSet=N

Format 1: SpyLinkSet[n]=SpyPcm[x]

Format 2: SpyLinkSet[n]=SpyPcm[x]+SpyPcm[y]

SpyLinkSet[n].SpyCICPcm[k]=SpyPcm[m]

SpyLinkSet[n].SpyIsupCICPcm[k]=SpyPcm[m]

SpySpCodeLen=j

Note: Format 1 is applicable to a link set which contains one signaling link only; Format 2 is applicable to a link set which has two signaling links.

Note: Configuration 1 has a higher priority than Configuration 2.

Value Range

N: The total number of signaling link sets, 1≤N≤48, must start from n=0, continuously configure SpyLinkSet N times;

n: The logical number of the link set, 0≤n<N;

x, y, m: The logical number of SpyPcm, 0≤x<M, 0≤y<M, 0≤m<M;

k: The digital trunk number assigned to SpyPcm by the Central Office, i.e. the value of the PCM parameter in the CIC field of TUP or ISUP messages, it can be obtained from the Central office;

j : The value is either 24 or 14. It is used to set the encoding standard for signaling points: 24bit is the National Signaling Point Code (NSPC) format, 14bit is the International Signaling Point Code (ISPC) format.

Note: M is the set value of the configuration item TotalSpyPcm . TotalSpyLinkPcm has the same value as TotalSpyPcm.

Description

² TotalSpyLinkSet sets the total number of the SS7 signaling link sets;

² SpyLinkSet sets the physical position of the signaling link in the designated Link Set n;

² TotalSpyLinkPcm sets the total number of digital trunks to be monitored in the application program;

² SpyLinkPcm sets the physical position of a signaling link in the specified link set;

² SpyCICPcm and SpyIsupCICPcm establish the mapping relation between the number of the digital trunk in the CIC field of TUP or ISUP messages and the logical number of SpyPCM in Link Set n, SpyCICPcm is only applicable to the TUP protocol, SpyIsupCICPcm is only applicable to the ISUP protocol.

Note

l SpyLinkSet[n].SpyCICPcm[k] is only applicable to the TUP protocol;

l SpyLinkSet[n].SpyIsupCICPcm[k] is only applicable to the ISUP protocol;

l This configuration item is only applicable to the SS7 signaling of DTP Series;

l This configuration item requires the SynCTI driver of version 4.5.8.0 or above.

Example

Refer to ‘ Application and Configuration Instance for DTP Series ’ in Chapter 1.


3.1.1.4.7 Essential Configuration Items for SS7 (SHD Series)


3.1.1.4.7.1 Setting Digital Trunk Using ISUP Protocol


3.1.1.4.7.1.1 TotalIsupPcm

Refer to IsupPcm


3.1.1.4.7.1.2 IsupPcm

Configuration Item

TotalIsupPcm

IsupPcm

Section

[SS7]

Written Format

TotalIsupPcm=M

IsupPcm[m]=LocalPcm[k]

Value Range

M: The total number of digital trunks using the ISUP protocol, 0≤M<N. N is the set value of the configuration item. If M is not 0, the configuration item IsupPcm must be set;

m: The logical number of the digital trunk using ISUP protocol, numbered from 0. Range of value: 0≤m<M

k: The logical number of the digital trunk in the application, range of value: 0≤k<N. The logical number of the digital trunk is set by the configuration item TotalPcm and Pcm .

Description

TotalIsupPcm sets the total number of the digital trunks using the ISUP protocol in the application;

IsupPcm sets the digital trunk using ISUP protocol in the local PC

Note

l If the ISUP protocol is not used in the system, this configuration item doesn’t need to be set;

l If TotalIsupPcm is set to be 0, the configuration item IsupPcm doesn’ t need to be set, and the configuration item AutoHandleIsup will be ignored;

l This configuration item is only applicable to SHD Series


3.1.1.4.8 Essential Configuration Items for ISDN (SHD Series)


3.1.1.4.8.1 Setting Operating Mode


3.1.1.4.8.1.1 UseISDNMode

Configuration Item | UseISDNMode
Section | [ISDN]
Written Format | UseISDNMode=m
Value Range | m=0: User side (default); m=1: Network side; m=2: User side + Network side. Note: Under this mode, all the digital trunks must have the same mode on one single board, i.e. either all of them are user side mode, or all of them are network side mode, but different boards may support different modes
Description | Sets the operating mode when ISDN protocol is used. For more information, refer to ‘ Network-side Mode and User-side Mode ’ in Chapter 1


3.1.1.4.8.2 Setting Digital Trunk Using ISDN Signaling (User Side)


3.1.1.4.8.2.1 TotalUserLinker

Refer to UserTEIValue


3.1.1.4.8.2.2 UserPcmLink

Refer to UserTEIValue


3.1.1.4.8.2.3 UserSendEstablish

Refer to UserTEIValue


3.1.1.4.8.2.4 UserTEIValue

Configuration Item

TotalUserLinker

UserPcmLink

UserSendEstablish

UserTEIValue

Section

[ISDN]

Written Format

TotalUserLinker=N

UserPcmLink[n]=LocalPCM[k]

UserSendEstablish[n]=b

UserTEIValue[n]=m

Value Range

N: The total number of digital trunks at user side;

n: The logical number of each digital trunk at user side, numbered from 0;

k: The logical number of the digital trunk at local end. For more information, refer to the description of the configuration item TotalPcm and Pcm ;

b: Determines whether this end sends the message of automatic link building for the ISDN signaling or not.

0: Not to send;

1: Send (default).

m: TEI value. Range of value:

0≤m≤63: Fixed TEI;

m>63: Dynamic TEI.

The default value of m is 0.

Note: the value of m must be the same as the value at the network side; otherwise the link between the local and network side can’t be established. It’s supposed that the TEI value is x at the network side, if 0≤x≤63, m must be equal to x; if x>63, m may be equal to x, but it may also not be equal to x. For more information about TEI value, refer to ‘ TEI value ’ in Chapter 1

Description

TotalUserLinker sets the total number of local digital trunks which use the ISDN signaling and operate at the user side;

UserPcmLink establishes the mapping relation between the number of each digital trunk at user side and its logical number;

UserTEIValue sets the TEI value of the digital trunk at user side

Note

l If N>0, both UserPcmLink and UserTEIValue must be set N times;

l This configuration item is only applicable to the mode of user side


3.1.1.4.8.3 Setting Digital Trunk Using ISDN Signaling (Network Side)


3.1.1.4.8.3.1 TotalNetLinker

Refer to NetTEIValue


3.1.1.4.8.3.2 NetPcmLink

Refer to NetTEIValue


3.1.1.4.8.3.3 NetSendEstablish

Refer to NetTEIValue


3.1.1.4.8.3.4 NetTEIValue

Configuration Item

TotalNetLinker

NetPcmLink

NetSendEstablish

NetTEIValue

Section

[ISDN]

Written Format

TotalNetLinker=N

NetPcmLink[n]=LocalPCM[k]

NetSendEstablish[n]=b

NetTEIValue[n]=m

Value Range

N: The total number of the digital trunks at network side in the system;

n: The logical number of the digital trunk at network side, numbered from 0;

k: The logical number of the digital trunk at local end. For more information, refer to the description of the configuration item TotalPcm and Pcm ;

b: Determines whether this end sends the message of automatic link building for the ISDN signaling or not.

0: Not to send;

1: Send (default).

m: TEI value. Range of value:

0≤m≤63: Fixed TEI;

m>63: Dynamic TEI.

The default value of m is 0

Description

TotalNetLinker sets the total number of the digital trunks at local end working in network-side mode;

NetPcmLink establishes the mapping relation between each digital trunk working in network-side mode and its logical number;

NetTEIValue sets the TEI value of each digital trunk working in network-side mode

Note

l If N>0, both NetPcmLink and NetTEIValue must be set N times;

l This configuration item is only applicable to the mode of user side


3.1.1.4.9 Essential Configuration Items for China SS1 (SHD Series)


3.1.1.4.9.1 ProtocolType

Configuration Item

ProtocolType

Section

[SS1Config]

Written Format

ProtocolType=m

Value Range

m=0: Use SS1 signaling (default);

m=1: Use the LineSide protocol;

m=2: Use the ASB protocol;

m=3: Use the LineSide (OPS-FX) protocol;

m=4: Use the VPS protocol.

Description

Sets the signaling mode for the channel currently using SS1 signaling by default.

Here gives a brief explanation for the different values of ProtocolType. Customers can configure it according to the requirements of the remote PBX.

When m = 1, 3 or 4, the CD value of the sent CAS is equal to the value of the configuration item TxCas_CD . The channel, if it receives a CAS with the AB value of 0 in an idle state, will turn into the ringing state. When you pick up the phone, if m=1, the AB value of the sent CAS is 2; if m=3, the AB value of the sent CAS is 3; if m=4, the AB value of the sent CAS is 0x0f.

When m = 2, the AB value of the sent CAS is equal to the value of the configuration item TxCas_CD . The channel, if it receives a CAS with the ABCD value of 2 in an idle state, will turn into the ringing state. When you pick up the phone, the CD value of the sent CAS is 2.


3.1.1.5 SHN Series


3.1.1.5.1 Common Configuration Items for SHN Series


3.1.1.5.1.1 LocalSipIp

Note: This configuration item is named LocalIp and can not be found in Section [SIP] for SHN B series VoIP boards in versions below SynCTI 5.1.0.0.

Refer to LocalSipPort


3.1.1.5.1.2 LocalSipPort

Note: This configuration item is named LocalPort and can not be found in Section [SIP] for SHN B series VoIP boards in versions below SynCTI 5.1.0.0

Configuration Item

LocalSipIp

LocalSipPort

Section

[SIP]

Written Format

LocalSipIp=m

LocalSipPort=n

Value Range

m: Sets the network address carried by SIP signaling. m is a character string in the form of Ipv4 address, containing less than 256 characters. The exceptional case is m=0.0.0.0: Select a random IP address of the local host as the network address carried by SIP signaling.

n: Sets the network intercept port carried by SIP. It is 5060 by default and provides the value range of 1024 ~ 65536.

Description

Sets the network address and port carried by SIP signaling for VoIP boards


3.1.1.5.2 Essential Configuration Items for SHN A Series


3.1.1.5.2.1 Setting Protocol Type


3.1.1.5.2.1.1 ProtocolType

Configuration Item | ProtocolType
Section | [BoardId=x]
Written Format | ProtocolType=m
Value Range | m: Sets the protocol used by this VoIP board. See below for details: m=1: Use the SIP protocol. m=2: Set the VoIP board to be a VoIP resource board.
Description | ProtocolType is used to set the protocol for the VoIP board or set the VoIP board to be a VoIP resource board.


3.1.1.5.2.2 Essential Configuration Items for SIP


3.1.1.5.2.2.1 RTPRange

Configuration Item | RTPRange
Section | [SIP]
Written Format | RTPRange= tL, tH
Value Range | tL: Minimum RTP port range (1024≤tL, with the default value of 6000); tH: Maximum RTP port range (tH≤65535, with the default value of 10000).
Description | Sets the RTP port range for the SHN A series boards.


3.1.1.5.2.2.2 AudioCodecList

Refer to SendDtmfType


3.1.1.5.2.2.3 SendDtmfType

Configuration Item | AudioCodecList SendDtmfType
Section | [BoardId=x]
Written Format | AudioCodecList= p1,p2,…. pn SendDtmfType=j
Value Range | p1,p2,..pn: The voice codecs list for calls, with the default value of 6,7,131. n≤10 and the value staying ahead has a higher priority. See below for what they mean exactly., px=6: G.711 A-Law; px=7: G.711 µ-Law; px=131: G.729A. j: Sets the DTMF transmission mode. See below for details: j=0: Use the mode of RFC2833 to send DTMF; j=1: Use the mode of Signaling to send DTMF; j=2: Use the mode of In-band to send DTMF.
Description | Set the voice codecs and the DTMF transmission mode for the SHN A series.


3.1.1.5.3 Essential Configuration Items for SHN B Series


3.1.1.5.3.1 Essential Configuration Items for SIP


3.1.1.5.3.1.1 BoardIP

Note: This configuration item is named LocalIp and works as the common IP used for both signaling and RTP in versions below SynCTI 5.1.0.0.

Refer to SendDtmfType


3.1.1.5.3.1.2 SubMask

Refer to SendDtmfType


3.1.1.5.3.1.3 Gateway

Refer to SendDtmfType


3.1.1.5.3.1.4 DNS

Refer to SendDtmfType


3.1.1.5.3.1.5 AudioCodecList

Refer to SendDtmfType


3.1.1.5.3.1.6 RTPRange

Refer to SendDtmfType


3.1.1.5.3.1.7 SendSipMsg

Refer to SendDtmfType


3.1.1.5.3.1.8 SendDtmfType

Configuration Item

BoardIP

SubMask

Gateway

DNS

AudioCodecList

RTPRange

SendSipMsg

SendDtmfType

Section

[BoardId=x]

Written Format

BoardIP=m

Submask=v

Gateway=p

DNS=L

AudioCodecList= q1,q2,…. qn

RTPRange= tL, tH

SendSipMsg=n

SendDtmfType=j

Value Range

m: Sets the IP address of the network card equipped on the SHN B board.

v: Sets the subnet mask for the SHN B Series. v is a character string in the form of Ipv4 address, containing less than 256 characters. By default, v=255.255.255.0.

p: Sets the gateway for the SHN B Series.

L: Sets the DNS address. L is a character string in the form of Ipv4 address, containing less than 256 characters. By default, L=192.168.1.100.

q1,q2,…. qn: The voice codecs list for calls, with the default value of 6,7,131,49. n≤10 and the value staying ahead has a higher priority. See below for what they mean exactly.

qx=6: G.711 A-Law;

qx=7: G.711 µ-Law;

qx=131: G.729A;

qx=49: GSM (Only for SHN B Series).

tL: Minimum RTP port range (1024≤tL, with the default value of 6000);

tH: Maximum RTP port range (tH≤65535, with the default value of 10000).

n: Sets the switch for playing voices upon receiving rings to the remote end on an SIP channel. This configuration item is valid only when n=183. Once the driver receives the invite call, it will automatically respond 183+DSP instead of sending the 180 message. This configuration item is invalid as long as n≠183. It is only applicable to B-type boards, not to A-type boards.

j: Sets the DTMF transmission mode. See below for details:

j=0: Use the mode of RFC2833 to send DTMF;

j=1: Use the mode of Signaling to send DTMF;

j=2: Use the mode of In-band to send DTMF.

Description

Set the network address carried by SIP signaling, the DTMF transmission mode and other SIP operational parameters for the SHN B series.


3.1.1.6 Essential Configuration Items for DST Series (REC Series only)


3.1.1.6.1 PBXType
Configuration Item | PBXType
Section | [BoardId=x]
Written Format | PBXType=s
Value Range | s: Denotes the string of the PBX model. For more information about the available models, refer to ‘ DST Series Supported PBX Models ’
Description | Sets the model of the PBX connected with DST Series boards
Example | PBXType=ALCATEL4300


3.1.1.6.2 PhoneType
Configuration Item | PhoneType
Section | [BoardId=x]
Written Format | PhoneType=n1,n2,n3,n4,n5,n6,n7,n8,n9,n10,n11,n12,n13,n14,n15,n16
Value Range | n1~n16: The number denotes the model of the digital phone. For the available value, refer to ‘ DST Series Supported PBX Models ’ in Chapter 1
Description | Sets the value of the model of the digital phone connected with the DST board


3.1.1.6.3 ldr531

Refer to 3.1.1.6.1 ldr531


3.1.1.6.4 DstRecRawData
Configuration Item | DstRecRawData
Section | [BoardId=x]
Written Format | DstRecRawData=n
Value Range | n=0 (default): Common working mode n=1: Raw data acquisition mode
Description | Allows to set the raw data acquisition mode to acquire the raw wave data on the line for analysis and troubleshooting.
Note | l This configuration item is only applicable to DST series B-type boards.


3.1.1.6.5 SetAnalogCtrlEnable
Configuration Item | SetAnalogCtrlEnable
Section | [BoardId=x]
Written Format | SetAnalogCtrlEnable=n
Value Range | n=0: The configuration item AnalogCtrl goes invalid; n=1: The configuration item AnalogCtrl becomes valid.
Description | Sets whether to enable the configuration item AnalogCtrl .
Note | l This configuration item is only applicable to DST series B-type boards. l This configuration item is not necessary to be added in most situations. If you need, please set it under the instruction from our technicians.


3.1.1.6.6 AnalogCtrl

Configuration Item

AnalogCtrl

Section

[BoardId=x]

Written Format

AnalogCtrl =0xabcd,0xabcd,0xabcd

Value Range

Hexadecimal data. These three data respectively correspond to three modules. Refer to the following table for reference values of analog switches. You may adjust in real situation if necessary.

PBX Model | Reference Value of Analog Switch | PBX Model | Reference Value of Analog Switch
Alcatel4200/4400 | 0x2 | MirtelSx2000 | 0x4
AscotelIntelligate | 0x4 | NEC | 0x4
Aspect | 0x6 | Nortel Matra | 0x6
AvayaDefinity-2w | 0x2 | Nortel Meridian1 | 0x2
AvayaDefinity-4w | 0x0 | Nortel Norstar | 0x2
AvayaIndex | 0x4 | Panasonic KX | 0x2
AvayaMerlingMagix | 0x2 | Panasonic 7600se | 0x0
AvayaMLX | 0x4 | PhilipsSOPHOis30002w | 0x2
BoschIntegral2w | 0x2 | PhilipsSOPHOis30004w | 0x4
BoschIntegral4w | 0x4 | RockwellSpectrum | 0x4
BoschIntegral552w | 0x2 | SamsungDCS-828 | 0x4
BRI ISDN | 0x4 | SamsungINFOREX | 0x4
BRI ISDNI1 | 0x4 | Siemens Hicom | 0x2
Eon_EQ | 0x4 | Siemens RolmLink | 0x2
Ericsson ELU25/28 | 0x4 | Siemens Realifis DT | 0x4
Fujitsu F9600 | 0x0 | Siemens ISDT2W | 0x0
Intecom2-wire | 0x2 | Tadran Coral | 0x2
Intercom4-wire | 0x2 | Teltronics(Harris2020) | 0x6
Intel-Tel | 0x4 | ToshibaStrataDK/CTX | 0x4
LG_StareXCS | 0x4 |  |

Description

Sets the value for analog switches.

Note

l This configuration item is only applicable to DST series B-type boards.

l This configuration item is only valid when SetAnalogCtrlEnable =1.

l This configuration item is not necessary to be added in most situations. Please contact our technical support should you have any query about this configuration item.


3.1.1.6.7 SetVoxChSelectEnable
Configuration Item | SetVoxChSelectEnable
Section | [BoardId=x]
Written Format | SetVoxChSelectEnable =n
Value Range | n=0: The configuration item VoxChSelect goes invalid; n=1: The configuration item VoxChSelect becomes valid.
Description | Sets whether to enable the configuration item VoxChSelect .
Note | l This configuration item is only applicable to DST series B-type boards. l This configuration item is not necessary to be added in most situations. If you need, please set it under the instruction from our technicians.


3.1.1.6.8 VoxChSelect
Configuration Item | VoxChSelect
Section | [BoardId=x]
Written Format | VoxChSelect =0xabcd,0xabcd,0xabcd
Value Range | Hexadecimal data, bit 0-15 respectively correspond to Channel 1-8. Each channel occupies 2 bits. To be exact, 00 – B1; 01 – B2; 10 – B3.
Description | Sets the value for analog control.
Example | VoxChSelect=0x4924,0x0,0x5555 indicates Channel 0-7 are respectively B0, B1, B2, B0, B1, B2, B0, B1, Channel 8-15 are all B1, and Channel16-23 are all B2.
Note | l This configuration item is only applicable to DST series B-type boards. l This configuration item is only valid when SetVoxChSelectEnable =1. l This configuration item is not necessary to be added in most situations. If you need, please set it under the instruction from our technicians.


3.1.1.6.9 SetFilterSwitchEnable
Configuration Item | SetFilterSwitchEnable
Section | [BoardId=x]
Written Format | SetFilterSwitchEnable =n
Value Range | n=0: The configuration item FiiterSwitch goes invalid; n=1: The configuration item FiiterSwitch becomes valid.
Description | Sets whether to enable the configuration item FiiterSwitch .
Note | l This configuration item is only applicable to DST series B-type boards. l This configuration item is not necessary to be added in most situations. If you need, please set it under the instruction from our technicians.


3.1.1.6.10 FilterSwitch
Configuration Item | FilterSwitch
Section | [BoardId=x]
Written Format | FilterSwitch =0xabcd,0xabcd,0xabcd
Value Range | Hexadecimal data, varying on actual condition. These three data respectively correspond to three modules.
Description | Sets the filter switch.
Note | l This configuration item is only applicable to DST series B-type boards. l This configuration item is only valid when SetFilterSwitchEnable =1. l This configuration item is not necessary to be added in most situations. If you need, please set it under the instruction from our technicians.


3.1.1.6.11 SetVoltageReferenceEnable
Configuration Item | SetVoltageReferenceEnable
Section | [BoardId=x]
Written Format | SetVoltageReferenceEnable =n
Value Range | n=0: The configuration item VoltageReference goes invalid; n=1: The configuration item VoltageReference becomes valid.
Description | Sets whether to enable the configuration item VoltageReference .
Note | l This configuration item is only applicable to DST series B-type boards. l This configuration item is not necessary to be added in most situations. If you need, please set it under the instruction from our technicians.


3.1.1.6.12 VoltageReference
Configuration Item | VoltageReference
Section | [BoardId=x]
Written Format | VoltageReference =0xabcd,0xabcd,0xabcd
Value Range | Hexadecimal data, varying on actual condition. These three data respectively correspond to three modules.
Description | Sets initial maximum level and reference voltage amplitude.
Note | l This configuration item is only applicable to DST series B-type boards. l This configuration item is only valid when SetVoltageReferenceEnable =1. l This configuration item is not necessary to be added in most situations. If you need, please set it under the instruction from our technicians.


3.1.2 Common Configuration Items


3.1.2.1 Setting Protocol for SHD/DTP Series Board


3.1.2.1.1 CardType

Configuration Item

CardType

Section

[BoardId=x]

Written Format

CardType=n

Value Range

n=0: E1 interface

n=1: T1 interface

n=2: J1 interface

The default value is 0.

Description

This configuration item and the PcmSSx configuration item can enable the system to run based on T1/J1 ISDN protocol. However, you need to modify the following configuration items according to the voice CODECs used on the line.

1. DefaultVoiceFormat under Section [BoardId=x] which is used to configure the voice CODEC for DSP reception/transmission;

2. UserVoiceFormat or NetVoiceFormat under Section [ISDN] if ISDN lines are used.


3.1.2.2 Setting Events Thrown out by Driver


3.1.2.2.1 DefaultEventOutput
Configuration Item | DefaultEventOutput
Section | [SystemConfig]
Written Format | DefaultEventOutput=m
Value Range | m=0: Not output any events m=1: Only output commonly-used events. For more information about the commonly-used events, refer to the related information in Chapter 1; m=2: Output all of the events
Description | Sets the event filter of the driver. For more information, refer to ‘ Event Filter ’ in Chapter 1


3.1.2.2.2 OvrlEnrgEventOut
Configuration Item | OvrlEnrgEventOut
Section | [SystemConfig]
Written Format | OvrlEnrgEventOut=n
Value Range | n=0: not output E_CHG_OvrlEnrgLevel n=1: output E_CHG_OvrlEnrgLevel, any other value except 0 will be regarded as 1 The default value is 0.
Description | Sets the event filter for E_CHG_OvrlEnrgLevel in the driver. To output E_CHG_OvrlEnrgLevel, the precondition is the value of DefaultEventOutput is not 0.


3.1.2.3 Setting Data Structure of Event


3.1.2.3.1 EventInterfaceType
Configuration Item | EventInterfaceType
Section | [SystemConfig]
Written Format | EventInterfaceType=n
Value Range | n=0: It is the default value. When MESSAGE_INFO is used, the function SsmWaitForEvent , SsmGetEvent and SsmPutUserEvent are valid; n=1: When SSM_EVENT is used, the function SsmWaitForEventA , SsmGetEventA and SsmPutUserEventA are valid
Description | When the driver outputs the event to the event queue, this configuration item determines the data structure to be used by the event
Note | If not only the DST Series boards are used, but also the event of E_RCV_DSTDChannel is used, this configuration item must be configured to be 1


3.1.2.4 Setting Depth of Internal Event Queue


3.1.2.4.1 MaxEventPerChannel
Configuration Item | MaxEventPerChannel
Section | [SystemConfig]
Written Format | MaxEventPerChannel=n
Value Range | n>0, calcaulated by the total number of events, with the default value of 100
Description | Sets the depth of the event-queue of one channel. When the application invokes the function of SsmSetEvent using the parameter wEvent=0xffff to enable the event polling or event callback mode, the driver will allocate memory for the event queue using the set value of this configuration item


3.1.2.4.2 MaxUserEventSize
Configuration Item | MaxUserEventSize
Section | [SystemConfig]
Written Format | MaxUserEventSize=n
Value Range | n≥0, with the default value of 0 which means the application is forbidden to add self-defined event to the driver
Description | During the time interval (8ms) of one hardware interruption, the maximum number of the self-defined events that the application may add to the interval event output queue in the driver.


3.1.2.5 Setting General Parameters for State Machine


3.1.2.5.1 MaxWaitAutoDialAnswerTime
Configuration Item | MaxWaitAutoDialAnswerTime
Section | [SystemConfig] / [SS1Config] / [ISUP] / [TUP] / [ISDN] / [SIP]
Written Format | MaxWaitAutoDialAnswerTime=t
Value Range | t: Maximum wait time (seconds), the default value varies according to the channel type: ² Analog trunk channel: 25 seconds; ² SS1 channel: 90 seconds; ² ISUP channel: 180 seconds; ² TUP channel: 60 seconds; ² ISDN channel: 60 seconds; ² SIP channel: 60 seconds.
Description | The maximum wait time waiting for the called party pickup after the channel state turns to ‘WaitAnswer’, during an outgoing call. For the execution process of AutoDial, refer to the following parts of Chapter 1: ² Analog trunk channel: ‘ Analog Trunk Channel State Machine ’; ² SS1 channel: Timer T6 in China SS1 State Machine ’; ² ISUP channel: Timer T4 in ‘ ISUP Channel State Machine ’; ² TUP channel: Timer T4 in ‘ TUP Channel State Machine ’; ² ISDN channel: Timer T310 in ‘ ISDN Channel State Machine ’; SIP channel: Timer evTimeout(*2) in ‘ SIP Channel State Machine ’.
Note | l For the configuration of analog trunk channels, use the configuration section [SystemConfig]; for the configuration of SS1 channels, use the configuration section [SS1Config]; for the configuration of ISUP channels, use the configuration section [ISUP]; for the configuration of TUP channels, use the configuration section [TUP]; for the configuration of ISDN channels, use the configuration section [ISDN]; for the configuration of SIP channels, use the configuration section [SIP].


3.1.2.5.2 RingToPending
Configuration Item | RingToPending
Section | [TUP] / [ISUP]
Written Format | RingToPending=m
Value Range | m=0: Response to the ‘disconnected’ message from the other end, start to tear down the connection; m=1: Not to response to the tear-down message from the other end, the channel is transitioned to the ‘pending’ state. The reason of pending is also set to be PEND_RemoteHangupOnRinging, so that when to tear down the connection is determined by the application itself; The default value is 0
Description | During incoming call, when the local end is in the ‘ringing’ state, if the remote PBX quits call, it sends tear-down message to the local end. When the driver receives the tear-down message, this configuration item determines which next state of the channel will be entered. For more information about this configuration item, refer to the channel state transition in Chapter 1
Note | l This configuration item is only applicable to TUP and ISUP channels l For the configuration of TUP channels, use the configuration section [TUP], for the configuration of ISUP channel, use the configuration section [ISUP]


3.1.2.5.3 AutoClearCallerIdBufOnHangup
Configuration Item | AutoClearCallerIdBufOnHangup
Section | [SystemConfig]
Written Format | AutoClearCallerIdBufOnHangup=b
Value Range | b=0: No b=1: Yes(default)
Description | When the call is finished, this configuration item determines whether the driver will automatically clear the buffer area storing the calling party ID and the extended buffer area. If it’s ISUP channel or TUP channel, the buffer area storing the called party number and 1st called party number will also be cleared
Note | This configuration item requires the driver version 2.1 or above


3.1.2.5.4 AutomaticAisGeneration
Configuration Item | AutomaticAisGeneration
Section | [BoardId=x]
Written Format | AutomaticAisGeneration[n]=b
Value Range | n: Logical PCM number, numbered from 0; b=0: No; (default) b=1: Yes
Description | When the input signal is interrupted, it determines whether to enable the automatic generation of the AIS message
Note | l This configuration item is only applicable to 8E1/16E1 links; l When the current configuration item for PCM 4m is configured, the AutomaticAisGeneration for PCM 4*m+1, PCM 4*m+2 and PCM 4*m+3 will be automatically set by the system simultaneously (m is the natural number which makes the logical PCM index meaningful); l This configuration item requires the driver version 4.7.3.1 or above


3.1.2.5.5 AutomaticRaiGereration
Configuration Item | AutomaticRaiGereration
Section | [BoardId=x]
Written Format | AutomaticRaiGereration =b
Value Range | b=0: No; (default) b=1: Yes
Description | When the input signal is lost, it determines whether to enable the automatic generation of the RAI message
Note | l This configuration item is only applicable to 8E1/16E1 links l When the current configuration item for PCM 4m is configured, the AutomaticRAIGeneration for PCM 4*m+1, PCM 4*m+2 and PCM 4*m+3 will be automatically set by the system simultaneously (m is the natural number which makes the logical PCM index meaningful); l This configuration item requires the driver version 4.7.3.1 or above


3.1.2.5.6 IgnoreBlockInGra
Configuration Item | IgnoreBlockInGra
Section | [TUP]
Written Format | IgnoreBlockInGra =b
Value Range | b=0: No; (default) b=1: Yes
Description | Whether to ignore the status indication field in GRA
Note | This configuration item is only valid to the TUP connection


3.1.2.5.7 AllowTimeoutInSpyISDN

Configuration Item

AllowTimeoutInSpyISDN

Section

[BoardId=x]

Written Format

AllowTimeoutInSpyISDN=b

Value Range

b=1: Reset the channel state back to S_SPY_STANDBY if time’s out after the channel keeps in the S_SPY_RCVPHONUM state for a long time (default);

b=0: Not to reset the channel state back to S_SPY_STANDBY if time’s out after the channel keeps in the S_SPY_RCVPHONUM state for a long time.

Description

Sets whether to reset the channel state back to S_SPY_STANDBY if time’s out after the channel keeps in the S_SPY_RCVPHONUM state for a long time.

Note

This configuration item is only applicable to the Synway DTP series boards. Forbidding the use of this configuration item may cause an incomplete call so as to suspend the system in the S_SPY_RCVPHONUM state for long time.


3.1.2.6 Setting Voice CODECs on Digital Lines


3.1.2.6.1 DefaultVoiceFormat

Configuration Item

DefaultVoiceFormat

Section

[BoardId=x]

Written Format

DefaultVoiceFormat=m

Value Range

m=6:A-Law;

m=7:μ-Law

Description

Sets the voice data encoding format of the B-channel on digital lines (includes digital lines connecting with DST Series boards and digital trunks connecting with SHD/DTP Series boards).

In north America and Japan, μ-Law is adopted; In Europe and China, A-Law is adopted. The encoding format of the B-channel voice data can be determined by referring to related manuals of the PBX and telephone, and can also be determined by experiment

Note

l          This configuration item is only applicable to DST, SHD, DTP Series and C-type fax boards;

l          For C-type fax boards, this configuration item is used to set the format of bit stream (A-Law or μ-Law);

l If the set value of this configuration item is not the same as the actual voice data encoding format of the B-channel, the recorded voice data will have noises


3.1.2.7 Setting Tone Detector


3.1.2.7.1 Setting Start/stop of Tone Detector on Digital Voice Board


3.1.2.7.1.1 DefaultToneCheckState
Configuration Item | DefaultToneCheckState
Section | [BoardId=x]
Written Format | DefaultToneCheckState =n
Value Range | n=0: Stop (Default) n=1: Start
Description | Sets whether to start or stop the tone detector on the digital voice board.


3.1.2.7.2 Setting Parameters of Noise Filter


3.1.2.7.2.1 MinimumVoiceDetermineEnergy
Configuration Item | MinimumVoiceDetermineEnergy
Section | [SystemConfig]
Written Format | MinimumVoiceDetermineEnergy=e
Value Range | e: e³700, with the default value of 100000. For the conversion between the value of this parameter and the DB value, refer to ‘FFT’ in ‘ Tone Detector ’ of Chapter 1
Description | Sets the threshold value for noise detection on the line. For more information, refer to SsmSetMinVocDtrEnergy .


3.1.2.7.3 Setting Parameters of DTMF Pulse-width Filter


3.1.2.7.3.1 ToneHighFilterPoint

Refer to ToneLowFilterPoint


3.1.2.7.3.2 ToneLowFilterPoint

Configuration Item

ToneHighFilterPoint

ToneLowFilterPoint

Section

[SystemConfig]

Written Format

ToneHighFilterPoint=tH

ToneLowFilterPoint=tL

Value Range

tH: The minimum duration (ms) of the tone at on state, it must be integral times of 16ms, tH >0, with the default value of 64ms

tL: The minimum duration (ms) of the tone at off state, it must be integral times of 16ms, tL >0, with the default value of 160 ms

Description

ToneHighFilterPoint sets the minimum duration of the tone. If the incoming signal is the same as that of the tone, but its duration is less than the set value of this parameter, the driver will regard it as the interfering signal;

ToneLowFilterPoint sets the minimum duration that the tone disappears. If it’s determined that the incoming signal is the same as that of the tone, and also the duration that this signal disappears is larger than the set value of this parameter, the driver confirms that this signal has disappeared.


3.1.2.7.4 Setting 1st Call Progress Tone Detector


3.1.2.7.4.1 Setting Parameters of Frequency Detector


3.1.2.7.4.1.1 TonePara

Configuration Item

TonePara

Section

[SystemConfig]

Written Format

TonePara =f1,b1,f2,b2,r

Value Range

f1: The first center frequency (Hz), range of value: 300~3400, with the default value of 450

b1: The bandwidth (Hz) of the first center frequency, range of value: 40~120, with the default value of 80

f2: The second center frequency (Hz), range of value: 300~3400, with the default value of 0

b2: The bandwidth (Hz) of the second center frequency, range of value: 40~120, with the default value of 0

r: The threshold value (%), range of value: 15~80, with the default value of 50

For more information, refer to the description of the function SsmSetTonePara

Description

Sets the Parameters of the frequency detector in the call progress tone detector. For more information, refer to Call Progress Tone Detector in Chapter 1


3.1.2.7.4.2 Setting Parameters of Dial Tone Detector


3.1.2.7.4.2.1 IsDialToneDetermineTime

Configuration Item | IsDialToneDetermineTime
Section | [SystemConfig]
Written Format | IsDialToneDetermineTime=t
Value Range | t: Minimum duration (ms), t≥1200, with the default value of 1500
Description | Sets the parameters of the dial tone detector in the 1st call progress tone detector. For more information, refer to SsmSetIsDialToneDtrTime


3.1.2.7.4.3 Setting Parameters of Echo Tone Detector


3.1.2.7.4.3.1 RingEchoTonePara

Configuration Item

RingEchoTonePara

Section

[SystemConfig]

Written Format

RingEchoTonePara=tH,tL

Value Range

tH: The duration (ms) of the tone at on state, range of value: 300≤tH≤2500, with the default value of 1000

tL: The duration (ms) of the tone at off state, range of value: 800≤tL≤6000, with the default value of 4000

Description

Sets the durations of the tone at on and off states for the echo tone detector. For more information, refer to the function of SsmSetRingEchoTonePara


3.1.2.7.4.4 Setting Parameters of Busy Tone Detector


3.1.2.7.4.4.1 BusyTonePeriod

Refer to IsBusyToneDetermineCount


3.1.2.7.4.4.2 IsBusyToneDetermineCount

Configuration Item

BusyTonePeriod

IsBusyToneDetermineCount

Section

[SystemConfig]

Written Format

Format 1:BusyTonePeriod=p1

Format 2:BusyTonePeriod=p1,p2

Format 3:BusyTonePeriod=p1,p2,p3

Format 4:BusyTonePeriod=p1,p2,p3,p4

IsBusyToneDetermineCount=n

Value Range

p1,p2,p3,p4: Busy tone cycle (ms), range of value: 200≤pi≤2000, with the default value of 700ms;

n: The minimum number of busy tone cycles, 1≤n≤10, with the default value of 2

Description

Sets the parameters of the busy tone detector in the 1st Call Progress Tone Detector . For more information, refer to Busy Tone Detector in Chapter 1;

BusyTonePeriod sets the busy tone cycles, at most 4 busy tone cycles can be set, separated by comma. Format 1, Format 2, Format 3 and Format 4 are applicable to setting 1~4 cycles respectively. For more information, refer to the function SsmSetBusyTonePeriodEx ;

IsBusyToneDetermineCount sets the minimum number of the busy tone cycles

Example

BusyTonePeriod=700 // Detect one type of busy tone, the cycle is 700ms

BusyTonePeriod=700,1400 // Detect two types of busy tones, the cycles are 700ms and 1400ms respectively


3.1.2.7.4.5 Setting Parameters for Kewl Start


3.1.2.7.4.5.1 EnableKewlStart

Configuration Item | EnableKewlStart
Section | [SystemConfig]
Written Format | EnableKewlStart=m
Value Range | m=0: disable the Kewl Start feature (default) m=1: enable the Kewl Start feature
Description | Enables the Kewl Start feature to detect remote hangup.


3.1.2.7.4.5.2 KSVoltageThreshold

Configuration Item | KSVoltageThreshold
Section | [SystemConfig]
Written Format | KSVoltageThreshold=n
Value Range | Duration (V), with the default value of 0
Description | Sets the threshold voltage for Kewl Start to detect remote hangup. For more information, refer to Change in Analog Phone Line Voltage section in Chapter 1.


3.1.2.7.4.5.3 KSKeepTime

Configuration Item | KSKeepTime
Section | [SystemConfig]
Written Format | KSKeepTime=m
Value Range | Duration(ms), with the default value of 256
Description | Sets the filter time for Kewl Start to detect remote hangup. For more information, refer to Change in Analog Phone Line Voltage section in Chapter 1.


3.1.2.7.4.6 Setting Parameters of User-defined Tone Detector


3.1.2.7.4.6.1 AppointedToneAnalyzerSwitch

Configuration Item | AppointedToneAnalyzerSwitch
Section | [SystemConfig]
Written Format | AppointedToneAnalyzerSwitch=m
Value Range | m=0: Stop the user-defined tone detector; m=1: Start the user-defined tone detector, detect the continuous tone, the configuration item IsAppointedToneDetermineTime is valid here; m=2: Start the user-defined tone detector, detect the periodic tones, the configuration item AppointedTonePara and IsAppointedToneDetermineCount are valid here
Description | Sets the user-defined tone detector in the 1st Call Progress Tone Detector. For more details, refer to User-defined Tone Detector in Chapter 1


3.1.2.7.4.6.2 IsAppointedToneDetermineTime

Configuration Item

IsAppointedToneDetermineTime

Section

[SystemConfig]

Written Format

IsAppointedToneDetermineTime=t

Value Range

t³16: Minimum duration (ms), with the default value of 80

Description

Sets the minimum duration of the user-defined continuous tone, it’s applicable to the user-defined tone detector in the 1st Call Progress Tone Detector. For more information, refer to User-defined Tone Detector in chapter 1

Note

l Only when the configuration item AppointedToneAnalyzerSwitch is set to be 1, this configuration item is valid;

l If the set value of this configuration item is less than the set value of IsDialToneDetermineTime , the dial tone will not be detected correctly; If the set value of this configuration item is larger than the set value of IsDialToneDetermineTime , the user-defined continuous tone will not be detected correctly


3.1.2.7.4.6.3 AppointedTonePara

Refer to IsAppointedToneDetermineCount


3.1.2.7.4.6.4 IsAppointedToneDetermineCount

Configuration Item

AppointedTonePara

IsAppointedToneDetermineCount

Section

[SystemConfig]

Written Format

AppointedTonePara=tH,tL

IsAppointedToneDetermineCount=n

Value Range

tH: The duration (ms) of the tone at on state, 16≤tH≤6000, with the default value of 2000

tL: The duration (ms) of the tone at off state, 16≤tL≤6000, with the default value of 2000

n: User-defined minimum number of tone cycles, 1≤n≤10, with the default value of 2

Description

Sets parameters of the periodic tones of User-defined Tone Detector in the 1st Call Progress Tone Detector ;

AppointedTonePara sets the durations of the tone at on and off states; IsAppointedToneDetermineCount sets the minimum number of the tone cycles to be counted.

Note

Only when the configuration item AppointedToneAnalyzerSwitch is set to be 2, this configuration item is valid


3.1.2.7.5 Setting 2nd Call Progress Tone Detector


3.1.2.7.5.1 Setting Operating Status


3.1.2.7.5.1.1 Enable2ndToneAnalyzer

Configuration Item | Enable2ndToneAnalyzer
Section | [SystemConfig]
Written Format | Enable2ndToneAnalyzer=b
Value Range | b=1: Start 2nd Call Progress Tone Detector; b=0: Stop 2nd Call Progress Tone Detector
Description | Sets the operating status of the 2nd Call Progress Tone Detector. For more information, refer to SsmStart2ndToneAnalyzer


3.1.2.7.5.1.2 Check2ndToneOnAutoDial

Configuration Item | Check2ndToneOnAutoDial
Section | [SystemConfig]
Written Format | Check2ndToneOnAutoDial=b
Value Range | b=1: Yes b=0: No (default)
Description | Sets whether the detected result of the 2nd Call Progress Tone Detector affects the state transition of the analog trunk channel. For more information, refer to ‘ Call Progress Tone Detector ’ in Chapter 1


3.1.2.7.5.2 Setting Parameters of Frequency Detector


3.1.2.7.5.2.1 2ndTonePara

Configuration Item

2ndTonePara

Section

[SystemConfig]

Written Format

TonePara =f1,b1,f2,b2,r

Value Range

f1: The first center frequency (Hz), range of value: 300~3400, with the default value of 450

b1: The bandwidth (Hz) of the first center frequency, range of value: 40~120, with the default value of 80

f2: The second center frequency (Hz), range of value: 300~3400, with the default value of 0

b2: The bandwidth (Hz) of the second center frequency, range of value: 40~120, with the default value of 0

r: The threshold value (%), range of value: 15~80, with the default value of 50

For more information, refer to the description of the function SsmSet2ndTonePara

Description

Sets parameters of the frequency detector in the 2nd Call Progress Tone Detector, for more information, refer to Call Progress Tone Detector in Chapter 1


3.1.2.7.5.3 Setting Parameters of Dial Tone Detector


3.1.2.7.5.3.1 2ndIsDialToneDetermineTime

Configuration Item | 2ndIsDialToneDetermineTime
Section | [SystemConfig]
Written Format | 2ndIsDialToneDetermineTime=t
Value Range | t: The minimum duration (ms) of the dial tone, n≥1200, with the default value of 1500
Description | Sets the dial tone detection parameters of the 2nd Call Progress Tone Detector. For more information, refer to SsmSet2ndIsDialToneDtrTime


3.1.2.7.5.4 Setting Parameters of Echo Tone Detector


3.1.2.7.5.4.1 2ndRingEchoTonePara

Configuration Item

2ndRingEchoTonePara

Section

[SystemConfig]

Written Format

2ndRingEchoTonePara=tH,tL

Value Range

tH: The duration (ms) of the tone at on state, range of value: 300≤tH≤2500, with the default value of 1000

tL: The duration (ms) of the tone at off state, range of value: 800≤tL≤6000, with the default value of 4000

Description

Sets the durations of the tone at on and off states for the ringback tone detector in the 2nd Call Progress Tone Detector. For more information, refer to SsmSet2ndRingEchoTonePara


3.1.2.7.5.5 Setting Parameters of Busy Tone Detector


3.1.2.7.5.5.1 2ndBusyTonePeriod

Refer to 2ndIsBusyToneDetermineCount


3.1.2.7.5.5.2 2ndIsBusyToneDetermineCount

Configuration Item | 2ndBusyTonePeriod 2ndIsBusyToneDetermineCount
Section | [SystemConfig]
Written Format | Format 1:2ndBusyTonePeriod=p1 Format 2:2ndBusyTonePeriod=p1,p2 Format 3:2ndBusyTonePeriod=p1,p2,p3 Format 4:2ndBusyTonePeriod=p1,p2,p3,p4 2ndIsBusyToneDetermineCount=n
Value Range | p1,p2,p3,p4: Busy tone cycle (ms), range of value: 200≤pi≤2000, default value: 700ms。 n: The minimum number of the busy tone cycles,1≤n≤10, with the default value of 2
Description | Sets parameters of the Busy Tone Detector in the 2nd Call Progress Tone Detector 2ndBusyTonePeriod sets the busy tone cycle, at most 4 busy tone cycles can be set, separated by ‘,’. Format 1, format 2, format 3 and format 4 are applicable to setting 1~4 cycles respectively . For more information, refer to SsmSetBusyTonePeriodEx ; 2ndIsBusyToneDetermineCount sets the minimum number of the busy tone cycles
Example | 2ndBusyTonePeriod=700 // Detect one type of busy tone, the cycle is 700 ms 2ndBusyTonePeriod=700,1400 //Detect two types of busy tones, the cycles are 700 ms and 1400 ms respectively


3.1.2.7.5.5.3 MaxBsTnOffTime

Configuration Item | MaxBsTnOffTime
Section | [SystemConfig]
Written Format | MaxBsTnOffTime=t
Value Range | t (ms) ³400, with the default value of 2000 ms
Description | Sets the duration of the busy tone detection. For more information, refer to Busy Tone Detector in Chapter 1
Note | This configuration item also affects the 2nd Call Progress Tone Detector


3.1.2.7.5.6 Setting Parameters of User-defined Tone Detector


3.1.2.7.5.6.1 2ndAppointedToneAnalyzerSwitch

Configuration Item | 2ndAppointedToneAnalyzerSwitch
Section | [SystemConfig]
Written Format | 2ndAppointedToneAnalyzerSwitch=m
Value Range | m=0: Stop the User-defined Tone Detector; m=1, Start the User-defined Tone Detector, detect continuous tone; m=2: Start the User-defined Tone Detector, detect periodic tone
Description | Sets the operating status of the User-defined Tone Detector in the 2nd Call Progress Tone Detector. For more information, refer to User-defined Tone Detector in Chapter 1


3.1.2.7.5.6.2 2ndIsAppointedToneDetermineTime

Configuration Item

2ndIsAppointedToneDetermineTime

Section

[SystemConfig]

Written Format

2ndIsAppointedToneDetermineTime=t

Value Range

t (ms) ³16: the minimum duration, with the default value of 80

Description

Sets the minimum duration of the user-defined continuous tone, it’s applicable to the User-defined Tone Detector in the 2nd Progress Tone Detector. For more information, refer to User-defined Tone Detector in Chapter 1

Note

l Only when the configuration item 2ndAppointedToneAnalyzerSwitch is set 1, this configuration item is valid;

l If the set value of this configuration item is less than the set value of 2ndIsDialToneDetermineTime , the dial tone will not be detected correctly; If the set value of this configuration item is larger than the set value of 2ndIsDialToneDetermineTime , the user-defined continuous tone will not be detected correctly


3.1.2.7.5.6.3 2ndAppointedTonePara

Refer to 2ndIsAppointedToneDetermineCount


3.1.2.7.5.6.4 2ndIsAppointedToneDetermineCount

Configuration Item

2ndAppointedTonePara

2ndIsAppointedToneDetermineCount

Section

[SystemConfig]

Written Format

2ndAppointedTonePara=tH,tL

2ndIsAppointedToneDetermineCount=n

Value Range

tH: The duration (ms) of the tone at on state, 16≤tH≤6000, with the default value of 2000

tL: The duration (ms) of the tone at off state, 16≤tL≤6000, with the default value of 2000

n: User-defined minimum number of tone cycles, 1≤n≤10, with the default value of 2

Description

Sets parameters of the periodic tones of User-defined Tone Detector in the 2nd Call Progress Tone Detector ;

2ndAppointedTonePara sets the duration of the tone at off and on states, 2ndIsAppointedToneDetermineCount sets the minimum number of the tone cycles to be counted

Note

Only when the configuration item 2ndAppointedToneAnalyzerSwitch is set to be 2, this configuration item is valid


3.1.2.7.6 Setting Fax Progress Tone Detector


3.1.2.7.6.1 VoiceFreqF1Para

Refer to VoiceFreqF2Para


3.1.2.7.6.2 VoiceFreqF2Para

Configuration Item

VoiceFreqF1Para

VoiceFreqF2Para

Section

[SystemConfig]

Written Format

VoiceFreqF1Para=f1,b1,r1,t1

VoiceFreqF2Para=f2,b2,r2,t2

Value Range

f1,f2: Center frequency (Hz), range of value: 300~3400, the default value of f1 is 1100, the default value of f2 is 2100;

b1,b2: Bandwidth (Hz), range of value: 40~120, with the default value of 80;

r1,r2: The minimum threshold value (%) for the percentage of in-band energy to overall energy, range of value: 15~80, with the default value of 50

t1,t2: The minimum duration (ms), range of value: ³64, with the default value of 250

Description

Sets parameters of the fax progress tone detector. VoiceFreqF1Para sets the 1st fax progress tone detector, VoiceFreqF2Para sets the 2nd fax progress tone detector.

For more information, refer to SsmSetVoiceFxPara


3.1.2.7.7 Setting Simplified Busy Tone Detector


3.1.2.7.7.1 Setting Operating Status


3.1.2.7.7.1.1 ToneAnalyzeAtRcvFsk

Configuration Item | ToneAnalyzeAtRcvFsk
Section | [BoardId=x]
Written Format | ToneAnalyzeAtRcvFsk=b
Value Range | b=0: No (default); b=1: Yes
Description | When the FSK receiver is working, whether to start the Simplified Busy Tone Detector. For more information, refer to ‘ Simplified Busy Tone Detector ’ in Chapter 1
Note | This configuration item normally is only applicable to analog trunk channels of SHT Series, being valid when ToneDetectorMode=1.


3.1.2.7.7.2 Setting Parameters of Noise Filter


3.1.2.7.7.2.1 TAARFDetermineEnergy

Configuration Item | TAARFDetermineEnergy
Section | [BoardId=x]
Written Format | TAARFDetermineEnergy=e
Value Range | e³700, with the default value of 100000; For the conversion between the value of this parameter and the DB value, refer to ‘FFT’ in ‘ Tone Detector ’ of Chapter 1.
Description | Sets the threshold value for noise detection on the line. For more information, refer to Simplified Busy Tone Detector in Chapter 1.


3.1.2.7.8 Setting Way to Detect Ringback Tones


3.1.2.7.8.1 Setting Way to Detect Ringback Tones


3.1.2.7.8.1.1 IsEchoQuickDetect

Configuration Item

IsEchoQuickDetect

Section

[BoardId=x]

Written Format

IsEchoQuickDetect=b

Value Range

b=0: A complete ringback tone must be detected, and the ringback tone starts to be measured when it goes at off state (default);

b=1: Based on the allowance error set by EchoOnTolerance or EchoOffTolerance, the ringback tone is detected. The ringback tone may start to be measured when it goes either at on or off state.

Description

Setting ringback tone detection method


3.1.2.7.8.2 Sets Allowance Error in Detecting Echo Tone at On State


3.1.2.7.8.2.1 EchoOnTolerance

Configuration Item | EchoOnTolerance
Section | [BoardId=x]
Written Format | EchoOnTolerance=e
Value Range | 0≤e≤50, with the default value of 40
Description | Sets the allowance error in detecting the ringback tone at on state. If the value is set to 40, 40% error is allowed, i.e. for the ringback tone of 1sec on, as long as it is detected to go at on state for 600ms, it is regarded as the ringback tone at on state
Note | Works cooperatively with IsEchoQuickDetect and EchoOffTolerance


3.1.2.7.8.3 Setting Allowance Error in Detecting Echo Tone at Off State


3.1.2.7.8.3.1 EchoOffTolerance

Configuration Item | EchoOffTolerance
Section | [BoardId=x]
Written Format | EchoOffTolerance =e
Value Range | 0≤e≤50, with the default value of 50
Description | Sets the allowance error in detecting the ringback tone at off state. If the value is set to 50, 50% error is allowed, i.e. for the ringback tone of 4sec off, as long as it is detected to go at off state for 2sec, it is regarded as the ringback tone at off state
Note | Works cooperatively with IsEchoQuickDetect and EchoOnTolerance


3.1.2.7.9 Setting CCIR Tone Detector


3.1.2.7.9.1 CCIREnableDetector
Configuration Item | CCIREnableDetector
Section | [SystemConfig]
Written Format | CCIREnableDetector=b
Value Range | b=0: Disable the CCIR tone detector (default); b=1: Enable the CCIR tone detector.
Description | Sets whether to enable the CCIR tone detector.
Note | This configuration item is only applicable to the following boards: SHT-8A/PCI SHT-8B/PCI SHT-8B/PCI/FAX SHT-8C/PCI/FAX SHT-8C/PCI/EC SHT-16A-CT/PCI SHT-16B-CT/PCI SHT-16B-CT/PCI/FAX SHT-16B-CT/cPCI SHT-16B-CT/cPCI/MP3 SHT-16B-CT/cPCI/FAX SHT-16C-CT/PCI/FAX SHT-16C-CT/PCI/EC SHT-2A/USB SHT-4A/USB SHT-2B/USB SHT-4B/USB


3.1.2.8 Setting Answering Machine Detector


3.1.2.8.1 EnableAMD
Configuration Item | EnableAMD
Section | [SystemConfig]
Written Format | EnableAMD =b
Value Range | b=0: No; b=1: Yes (default).
Description | Sets whether to turn on the answering machine detector while the tone detector is working. For more details, refer to ‘ Answering Machine Detector ’ in Chapter 1.


3.1.2.8.2 AMDNoSoundAfterDialTime
Configuration Item | AMDNoSoundAfterDialTime
Section | [SystemConfig]
Written Format | AMDNoSoundAfterDialTime=n
Value Range | Default value is 15000 (ms).
Description | Uses to judge if the line silence after dial tone lasts overtime or not. If the line silence time is longer than the vaule of AMDNoSoundAfterDialTime, the event E_CHG_AMD will be thrown out (on this condition, the value of E_CHG_AMD is 5)


3.1.2.8.3 AMDNoSoundTime
Configuration Item | AMDNoSoundTime
Section | [SystemConfig]
Written Format | AMDNoSoundTime=n
Value Range | Default value is 10000 (ms).
Description | Uses to judge if the silence after tone or color ring lasts overtime or not. If the silence time is over the vaule of AMDNoSoundTime, the event E_CHG_AMD will be thrown out (on this condition, the value of E_CHG_AMD is 4)


3.1.2.8.4 AMDTimeOut
Configuration Item | AMDTimeOut
Section | [SystemConfig]
Written Format | AMDTimeOut =n
Value Range | Default value is 70000 (ms).
Description | Uses to judge if the whole AMD detecting process is overtime or not. If the time is over the vaule of AMDTimeOut, the event E_CHG_AMD will be thrown out (on this condition, the value of E_CHG_AMD is 3)


3.1.2.8.5 AMDToneCount
Configuration Item | AMDToneCount
Section | [SystemConfig]
Written Format | AMDToneCount=n
Value Range | 16ms per unit. Default value is 10, that is 10x16ms=160ms.
Description | Judges if the time threshold for tone is detected. If this time is longer than the value of AMDToneCount, the event E_CHG_AMD will be thrown out (on this condition, the value of E_CHG_AMD is 1).


3.1.2.8.6 AMDTOn
Configuration Item | AMDTOn
Section | [SystemConfig]
Written Format | AMDTOn =n
Value Range | Default value is 80(ms).
Description | Uses to set the shortest duration for the voice to turn into the ON state.


3.1.2.8.7 AMDTOff
Configuration Item | AMDTOff
Section | [SystemConfig]
Written Format | AMDTOff =n
Value Range | Default value is 400(ms).
Description | Uses to set the shortest duration for the voice to turn into the OFF state.


3.1.2.8.8 AMDTimeA
Configuration Item | AMDTimeA
Section | [SystemConfig]
Written Format | AMDTimeA =n
Value Range | Default value is 600(ms).
Description | Uses to set the shortest silence duration before the phone is picked up by a man.


3.1.2.8.9 AMDTimeB
Configuration Item | AMDTimeB
Section | [SystemConfig]
Written Format | AMDTimeB =n
Value Range | Default value is 80(ms).
Description | Uses to set the shortest duration for the man who picked up the phone to speak.


3.1.2.8.10 AMDTimeC
Configuration Item | AMDTimeC
Section | [SystemConfig]
Written Format | AMDTimeC =n
Value Range | Default value is 1200(ms).
Description | Uses to set the longest duration for the man who picked up the phone to speak.


3.1.2.8.11 AMDTimeD
Configuration Item | AMDTimeD
Section | [SystemConfig]
Written Format | AMDTimeD =n
Value Range | Default value is 1000(ms).
Description | Uses to set the shortest silence duration after the phone is picked up by a man.


3.1.2.8.12 AMDSilentEnergy
Configuration Item | AMDSilentEnergy
Section | [BoardId=x]
Written Format | AMDSilentEnergy =n
Value Range | Energy value. Default value is 17000.
Description | Uses to set an energy value which decides it is voice or silence.


3.1.2.9 Setting Enhanced Tone Detector


3.1.2.9.1 ToneDetectorMode
Configuration Item | ToneDetectorMode
Section | [SystemConfig]
Written Format | ToneDetectorMode =b
Value Range | b=0: Use the common tone detector (default); b=1: Use the enhanced tone detector.
Description | Selects a kind of tone detector for use.
Note | This configuration item is only applicable to the following boards: SHT-8A/PCI SHT-8B/PCI SHT-8B/PCI/FAX SHT-8C/PCI/FAX SHT-8C/PCI/EC SHT-16A-CT/PCI SHT-16B-CT/PCI SHT-16B-CT/PCI/FAX SHT-16B-CT/cPCI SHT-16B-CT/cPCI/MP3 SHT-16B-CT/cPCI/FAX SHT-16C-CT/PCI/FAX SHT-16C-CT/PCI/EC SHT-2A/USB SHT-4A/USB SHT-2B/USB SHT-4B/USB


3.1.2.9.2 VoiceOffDetermineTime
Configuration Item | VoiceOffDetermineTime
Section | [SystemConfig]
Written Format | VoiceOffDetermineTime =n
Value Range | n: Calculated by millisecond (ms), usually being 1.2 times the period of a ringback tone, with the default value of 5000ms.
Description | Sets the time of silence detection.


3.1.2.9.3 MaxToneDetectorItem
Configuration Item | MaxToneDetectorItem
Section | [SystemConfig]
Written Format | MaxToneDetectorItem =N
Value Range | 1≦N≦20, with the default value of 5.
Description | Sets there are how many kinds of tones to be detected.


3.1.2.9.4 ToneDetectorItem

Configuration Item

ToneDetectorItem

Section

[SystemConfig]

Written Format

ToneDetectorItem[n] = M,F1,F2,F3,T1,T2,T3,Con,Coff,Ferr,Rbw,Terr,Pend,Ccnt,Tclr,Ppop,Eevent,Sstate,Sstop,We

Value Range

The number of this configuration item varies on the value of MaxToneDetectorItem N. When the value range of n is 0~N-1, the enhanced tone detector supports 3 kinds of tones and the value of each item is shown as follows.

Parameter | Continuous Tone | Periodic Tone | SIT
M | Value Range: =0 Continuous tones, such as dial tones and fax tones F1, F2. | Value Range: =1 Periodic tones, such as busy tones, howler tones and ringback tones. | Value Range: =2 SIT_TONE (consists of 3 continuous single tones )
F1(Hz) | Value Range: (>=300 && <=3400) The 1st mid-frequency | Value Range: (>=300 && <=3400) The 1st mid-frequency | Value Range: (>=300 && <=3400) The frequency of the 1st band
F2(Hz) | Value Range: (==0 || (>=300 && <=3400)) The 2nd mid-frequency, which is equal to 0 in detection of single tones. | Value Range: (==0 || (>=300 && <=3400)) The 2nd mid-frequency, which is equal to 0 in detection of single tones. | Value Range: (>=300 && <=3400) The frequency of the 2nd band
F3(Hz) | Invalid | Invalid | Value Range: (>=300 && <=3400) The frequency of the 3rd band
T1(ms) | Value Range: >= 16 Duration at on state | Value Range: >= 16 Duration at on state | Value Range: >= 16 Duration of the 1st band
T2(ms) | Invalid | Value Range: >= 16 Duration at off state | Value Range: >= 16 Duration of the 2nd band
T3(ms) | Invalid | Invalid | Value Range: >= 16 Duration of the 3rd band
Con | Value Range: (>0&&<=100) Filtering point number at on state (time length at each point is 16ms) | Value Range: (>0&&<=100) Filtering point number at on state (time length at each point is 16ms) | Value Range: (>0&&<=100) Filtering point number at on state (time length at each point is 16ms)
Coff | Value Range: (>0&&<=100) Filtering point number at off state (time length at each point is 16ms) | Value Range: (>0&&<=100) Filtering point number at off state (time length at each point is 16ms) | Value Range: (>0&&<=100) Filtering point number at off state (time length at each point is 16ms)
Ferr(Hz) | Value Range: (>0 && <=3400) Frequency error threshold | Value Range: (>0 && <=3400) Frequency error threshold | Value Range: (>0 && <=3400) Frequency error threshold
Rbw(%) | Value Range: (>=15 && <=80) Threshold value for the minimum percentage of in-band energy to overall energy | Value Range: (>=15 && <=80) Threshold value for the minimum percentage of in-band energy to overall energy | Value Range: (>=15 && <=80) Threshold value for the minimum percentage of in-band energy to overall energy
Terr(%) | Value Range: (>0 && <100) Accepted maximum error threshold for duration at on state (in percentage) | Value Range: (>0 && <100) Accepted maximum error threshold for duration at on state (in percentage) | Value Range: (>0 && <100) Accepted maximum error threshold for duration at on state (in percentage)
Pend | Invalid | Value Range: 0 or 1 Way to judge a complete period. 0 indicates the use of threshold value to judge the off state; 1 indicates the use of error to judge the off state. | Invalid
Ccnt | Invalid | Value Range: (>0 && <=10) Throw out the event E_CHG_ToneDetector upon detection of Ccnt complete periods. | Invalid
Tclr(ms) | Invalid | Value Range:>= 16 Clear the period count if no complete period is detected during the time Tclr(ms) | Invalid
Eevent | The type of the event which is thrown out to the application program after tone detection. See Note 1 for details. | The type of the event which is thrown out to the application program after tone detection. See Note 1 for details. | The type of the event which is thrown out to the application program after tone detection. See Note 1 for details.
Sstate | Value Range: 0 or 1 Whether to throw out the event to the channel state machine. 0: Not throw out; 1: Throw out. | Value Range: 0 or 1 Whether to throw out the event to the channel state machine. 0: Not throw out; 1: Throw out. | Value Range: 0 or 1 Whether to throw out the event to the channel state machine. 0: Not throw out; 1: Throw out.
Sstop | Value Range: 0 or 1 Whether to stop tone detection once a tone is detected. 0: Not stop; 1: Stop. | Value Range: 0 or 1 Whether to stop tone detection once a tone is detected. 0: Not stop; 1: Stop. | Value Range: 0 or 1 Whether to stop tone detection once a tone is detected. 0: Not stop; 1: Stop.
We | Value Range: 0 or 1 0 indicates the tone detector is working in FFT analysis; 1 indicates the tone detector is working in FSK reception. | Value Range: 0 or 1 0 indicates the tone detector is working in FFT analysis; 1 indicates the tone detector is working in FSK reception. | Value Range: 0 or 1 0 indicates the tone detector is working in FFT analysis; 1 indicates the tone detector is working in FSK reception.

Note 1: The driver will throw out the event E_CHG_ToneDetector upon tone detection. The 2 lower bits in the parameter dwParam of this event represent the tone type, which are evaluated by Event in the configuration item ToneDetectorParamItem[n] in the use of the enhanced tone detector. The value range of Event is 0~0xFFFF, while 0~9 have been defined by the driver. See the table below for details.

Configured Value | Corresponding Flag in Driver | Description | Use analog channel call state machine? | Can be used by application program?
0 | CHKTONE_NO_RESULT | Detecting… | N | N
1 | CHKTONE_DIALTONE | Dial tone detected | Y | Y
2 | CHKTONE_BUSYTONE | Busy tone detected | Y | Y
3 | CHKTONE_ECHOTONE | Ringback tone detected | Y | Y
4 | CHKTONE_ECHO_NOVOICE | Silent when ringback tone detected | Y | N
5 | CHKTONE_NOVOICE | Silence detected | Y | N
6 | CHKTONE_VOICE | Speaking voice detected | Y | N
7 | CHKTONE_VOICEF1 | Tones at the frequency of F1 detected | Y | Y
8 | CHKTONE_VOICEF2 | Tones at the frequency of F2 detected | Y | Y
9 | CHKTONE_APPOINTEDTONE | User-specified tone type detected | N | Y
0xA~ 0x001F | Remained by driver |  | N | N
0x0020~ 0xFFFF | Unused |  | N | Y

In the table above, if CHKTONE_DIALTONE, CHKTONE_BUSYTONE, CHKTONE_ECHOTONE, CHKTONE_VOICEF1, CHKTONE_VOICEF2 are not used by the application program, the analog channel call state machine will not work.

Below is a list of the default setting of ToneDetectorParamItem [n]. Make sure it is identical for both common and enhanced tone detectors.

Parameter | DIALTONE | BUSYTONE | ECHOTONE | VOICEF1 | VOICEF2
M | 0 | 1 | 1 | 0 | 0
F1(Hz) | 450 | 450 | 450 | 1100 | 2100
F2(Hz) | 0 | 0 | 0 | 0 | 0
F3(Hz) | 0 | 0 | 0 | 0 | 0
T1(ms) | 1500 | 350 | 1000 | 250 | 250
T2(ms) | 0 | 350 | 4000 | 0 | 0
T3(ms) | 0 | 0 | 0 | 0 | 0
Con | 4 | 4 | 4 | 4 | 4
Coff | 10 | 10 | 10 | 10 | 10
Ferr(Hz) | 30 | 30 | 30 | 30 | 30
Rbw(%) | 50 | 50 | 50 | 50 | 50
Terr(%) | 20 | 20 | 20 | 20 | 20
Pend | 0 | 1 | 0 | 0 | 0
Cnt | 0 | 2 | 1 | 0 | 0
Tclr(ms) | 0 | 3000 | 6000 | 0 | 0
Eevent | 1 | 2 | 3 | 7 | 8
Sstate | 1 | 1 | 1 | 1 | 1
Sstop | 0 | 0 | 0 | 0 | 0
We | 0 | 0 | 0 | 0 | 0

Description

Sets each parameter for tone detection so as to detect all specified tones.


3.1.2.10 Setting Tone Generator(CTI Series)


3.1.2.10.1 DefaultSendToneFrequence

Refer to DefaultSendToneVolume


3.1.2.10.2 DefaultSendToneVolume

Configuration Item

DefaultSendToneFrequence

DefaultSendToneVolume

Section

[BoardId=x]

Written Format

DefaultSendToneFrequence=f1,f2

DefaultSendToneVolume=v1,v2

Value Range

f1: The 1st frequency (Hz) of the tone, with the default value of 450;

f2: The 2nd frequency (Hz) of the tone, f2 equals to 0 means single tone, greater than 0 means dual tone. Default value is 0;

v1: The 1st volume of the tone, range of value: -7≤v1≤+6. v1=-7 means this tone is disabled; if v1 is greater than 0, it indicates the increase in volume; if v1 is less than 0, it means the decrease in volume. The set value multiplied by 3 equals to the DB value, with the default value of 0;

v2: The 2nd volume of the tone, the range of value and meaning are the same as v1, with the default value of -7

Description

Sets the parameters of the tone generator. DefaultSendToneFrequence sets the frequency of the tone, DefaultSendToneVolume sets the volume of the tone

Example

DefaultSendToneFrequence=450, 600 // Using dual tone

DefaultSendToneVolume=0,0


3.1.2.11 Setting Teleconferencing Parameters (CTI Series)


3.1.2.11.1 ClearInVoiceOnRxDtmf
Configuration Item | ClearInVoiceOnRxDtmf
Section | [BoardId=x]
Written Format | Format 1:ClearInVoiceOnRxDtmf=n,n,n,n Format 2:ClearInVoiceOnRxDtmf=n,n,n,n,n,n,n,n Format 3:ClearInVoiceOnRxDtmf=n,n,n,n,n,n,n,n,n,n,n,n,n,n,n,n Format 4:ClearInVoiceOnRxDtmf=n
Value Range | n=0: Disable the DTMF clamping feature (default); n=1: Enable the DTMF clamping feature
Description | Whether to enable the DTMF clamping feature. For more information, refer to ‘ Distributed Teleconferencing System ’ in Chapter 1
Note | l Format 1 is applicable to SHT Series voice boxes and ATP Series recording boxes adopting USB ; l Format 2 is applicable to 8-channel SHT Series boards; l Format 3 is applicable to 16-channel SHT Series boards; l Format 4 is applicable to SHD Series boards; l The function of SsmSetFlag (with the parameter of F_ClearInVoiceOnRcvDtmf) may implement the same feature


3.1.2.11.2 ClearInVoiceOnRx450Hz
Configuration Item | ClearInVoiceOnRx450Hz
Section | [BoardId=x]
Written Format | Format 1: ClearInVoiceOnRx450Hz =n,n,n,n,n,n,n,n Format 2: ClearInVoiceOnRx450Hz =n,n,n,n,n,n,n,n,n,n,n,n,n,n,n,n
Value Range | n=0: Not onto bus (default); n=1: Onto bus.
Description | Sets whether to put tones onto bus.
Note | l Format 1 is applicable to 8-channel SHT Series; l Format 2 is applicable to 16-channel SHT Series.


3.1.2.11.3 ConfMaxGroup
Configuration Item | ConfMaxGroup
Section | [SystemConfig]
Written Format | ConfMaxGroup=n
Value Range | n:n≥0 (with the default value of 64)
Description | Sets the maximum number of the conference rooms that can be created


3.1.2.11.4 ConfDefaultMaxGroupMember
Configuration Item | ConfDefaultMaxGroupMember
Section | [SystemConfig]
Written Format | ConfDefaultMaxGroupMember=n
Value Range | n:n≥0 (with the default value of 64)
Description | Sets the maximum number of the conference channels that can be put into the conference room


3.1.2.11.5 ConfDefaultMaxGroupSpeaker
Configuration Item | ConfDefaultMaxGroupSpeaker
Section | [SystemConfig]
Written Format | ConfDefaultMaxGroupSpeaker=n
Value Range | n: The number of the conference channels, with the default value of 24
Description | Sets the maximum number of the conference channels with speaking rights. The speaking modes of organizer, chairman and dynamic speaker are all provided with speaking rights. Whether the speaking mode of background music is provided with speaking right is determined by the setting of the configuration item BackgroundVoicePriority


3.1.2.11.6 ConfDefaultMaxGroupSpeaking
Configuration Item | ConfDefaultMaxGroupSpeaking
Section | [SystemConfig]
Written Format | ConfDefaultMaxGroupSpeaking=n
Value Range | n≤6, with the default value of 6
Description | Sets the maximum number of conference channels speaking simultanously in a conference room.


3.1.2.11.7 ConfJoinedbyEnergy
Configuration Item | ConfJoinedbyEnergy
Section | [SystemConfig]
Written Format | ConfJoinedbyEnergy=n
Value Range | n=0: Not preemptible; n=2: Support preemptible speaking (default)
Description | Determines whether to support the preemptible speaking in the dynamic speaker mode.


3.1.2.11.8 ConfMaxListener
Configuration Item | ConfMaxListener
Section | [SystemConfig]
Written Format | ConfMaxListener =n
Value Range | n: The conference channel number, with the default value of 480
Description | The maximum number of the listeners that are allowed to join the conference room


3.1.2.11.9 ConfDefaultMaxSilenceTime
Configuration Item | ConfDefaultMaxSilenceTime
Section | [SystemConfig]
Written Format | ConfDefaultMaxSilenceTime=t
Value Range | t: Duration (seconds) , with the default value of 5 seconds
Description | Sets the minimum duration for the channel to keep silent. For more information, refer to ‘ Distributed Teleconferencing System ’ in Chapter 1
Note | Now this configuration item has been invalid.


3.1.2.11.10 BackgroundVoicePriority
Configuration Item | BackgroundVoicePriority
Section | [SystemConfig]
Written Format | BackgroundVoicePriority=n
Value Range | n=1: The priority is higher than the organizer mode. It’s provided with special conference mixer; n=2: The priority is lower than the organizer mode, but higher than the chairman mode default value); n=3: The priority is lower than the chairman mode, but higher than the dynamic speaker mode; n=4: The priority is lower than the dynamic mode
Description | Sets the scheduling priority for the speaking mode of the channel which is used to play the background music. For more information, refer to ‘ Distributed Teleconferencing System ’ in Chapter 1


3.1.2.11.11 PlayVoiceIsListen
Configuration Item | PlayVoiceIsListen
Section | [SystemConfig]
Written Format | PlayVoiceIsListen =n
Value Range | n=0: this channl can only speak (can not listen); n=1: this channel can speak and listen
Description | Sets whether to enable the channel which is used to play background music to listen to the teleconference.


3.1.2.12 Setting Voice Playing Operation


3.1.2.12.1 Setting Termination Condition of Voice Playing


3.1.2.12.1.1 DefaultDtmfStopPlay

Refer to DtmfStopPlayCharSet


3.1.2.12.1.2 DtmfStopPlayCharSet
Configuration Item | DefaultDtmfStopPlay DtmfStopPlayCharSet
Section | [BoardId=x]
Written Format | Format 1:DefaultDtmfStopPlay=b,b,b,b DtmfStopPlayCharSet={s,s,s,s} Format 2:DefaultDtmfStopPlay=b,b,b,b,b,b,b,b DtmfStopPlayCharSet={s,s,s,s,s,s,s,s} Format 3:DefaultDtmfStopPlay=b,b,b,b,b,b,b,b,b,b,b,b,b,b,b,b DtmfStopPlayCharSet={s,s,s,s,s,s,s,s,s,s,s,s,s,s,s,s} Format 4:DefaultDtmfStopPlay=b DtmfStopPlayCharSet=s
Value Range | b=0: No (default), DtmfStopPlayCharSet is invalid at this time; b=1: Yes, DtmfStopPlayCharSet is valid at this time; s={0123456789*#abcd }, the character set containing any number of DTMF characters, the default value is a full set
Description | DefaultDtmfStopPlay sets whether the voice playing is terminated because the DTMF Detector detects the DTMF character or not. If it is set to ‘yes’, DtmfStopPlayCharSet sets the DTMF character set
Note | l Format 1 is applicable to SHT Series USB voice boxes; l Format 2 and format 3 are applicable to 8-channel and 16-channel SHT Series respectively; l Format 4 is applicable to SHD Series
Example | DefaultDtmfStopPlay=1 DtmfStopPlayCharSet={#} // SHD Series: The voice playing is stopped once ‘#’ is detected, other characters are not effective


3.1.2.12.1.3 HangupStopPlay
Configuration Item | HangupStopPlay
Section | [BoardId=x]
Written Format | Format 1:HangupStopPlay=b,b,b,b Format 2:HangupStopPlay=b,b,b,b,b,b,b,b Format 3:HangupStopPlay=b,b,b,b,b,b,b,b,b,b,b,b,b,b,b,b Format 4:HangupStopPlay=b
Value Range | b=0: No (default); b=1: Yes
Description | Sets whether the voice playing is terminated because the state machine of the driver detects remote hangup
Note | l Format 1 is applicable to SHT Series USB voice boxes; l Format 2 and format 3 are applicable to 8-channel and 16-channel SHT Series respectively; l Format 4 is applicable to SHD Series


3.1.2.12.1.4 DefaultBargeInStopPlay
Configuration Item | DefaultBargeInStopPlay
Section | [BoardId=x]
Written Format | Format 1:DefaultBargeInStopPlay=b,b,b,b Format 2:DefaultBargeInStopPlay=b,b,b,b,b,b,b,b Format 3:DefaultBargeInStopPlay=b,b,b,b,b,b,b,b,b,b,b,b,b,b,b,b Format 4:DefaultBargeInStopPlay=b
Value Range | b=0: No (default); b=1: Yes
Description | Sets whether the voice playing is terminated because the Barge in Detector detects voice activities
Note | l Format 1 is applicable to SHT Series USB voice boxes; l Format 2 and format 3 are applicable to 8-channel and 16-channel SHT Series respectively; l Format 4 is applicable to SHD Series


3.1.2.12.2 Setting Internal Playback Buffer


3.1.2.12.2.1 PlayBufSize
Configuration Item | PlayBufSize
Section | [SystemConfig]
Written Format | PlayBufSize=k
Value Range | k: The length (bytes) of the playback buffer area, it must be integral times of 512, with the default value of 32768 bytes
Description | Sets the size of the playback buffer area


3.1.2.12.3 Setting Parameters of Voice Playing in File List Mode


3.1.2.12.3.1 MaxPlayFileList
Configuration Item | MaxPlayFileList
Section | [SystemConfig]
Written Format | MaxPlayFileList=n
Value Range | 0≤n≤65535, with the default value of 256
Description | Sets the upper limit number of the voice files that the application is allowed to submit to the driver through the function call of SsmAddToFileList


3.1.2.12.4 Setting Parameters of Voice Playing in Preload File Mode


3.1.2.12.4.1 MaxPlayIndexList
Configuration Item | MaxPlayIndexList
Section | [SystemConfig]
Written Format | MaxPlayIndexList=n
Value Range | 0≤n≤512, with the default value of 256.
Description | Sets the upper limit number of preload voice segments allowed to be played upon one call of SsmPlayIndexList or SsmPlayIndexString .


3.1.2.12.5 Setting Parameters of Voice Playing in Buffer List Mode


3.1.2.12.5.1 MaxPlayMemList
Configuration Item | MaxPlayMemList
Section | [SystemConfig]
Written Format | MaxPlayMemList=n
Value Range | 0≤n≤65535, with the default value of 256
Description | Sets the upper limit number of the buffer areas that the application is allowed to submit to the driver through the function call of SsmAddToPlayMemList


3.1.2.12.6 Setting Parameters of Voice Playing in Single File Mode


3.1.2.12.6.1 FastPlayTime
Configuration Item | FastPlayTime
Section | [SystemConfig]
Written Format | FastPlayTime=t
Value Range | t denotes the step size (ms) of each operation of fast-forward or fast-backward, the with the default value of 1000
Description | Sets the step sizes of the functions of SsmFastFwdPlay and SsmFastBwdPlay


3.1.2.12.7 Setting Volume of Voice Playing


3.1.2.12.7.1 DefaultPlayVolume
Configuration Item | DefaultPlayVolume
Section | [BoardId=x]
Written Format | Format 1:DefaultPlayVolume=v,v,v,v Format 2:DefaultPlayVolume=v,v,v,v,v,v,v,v Format 3:DefaultPlayVolume=v,v,v,v,v,v,v,v,v,v,v,v,v,v,v,v Format 4:DefaultPlayVolume=v
Value Range | -7≤v≤+6, with the default value of 0
Description | Sets the gain of the volume adjuster A1 of SHD/SHT Series
Note | l Format 1 is applicable to SHT Series USB voice boxes and ATP Series USB recording boxes; l Format 2 is applicable to 8-channel SHT and ATP Series; l Format 3 is applicable to 16-channel SHT, ATP and DST Series; l Format 4 is applicable to SHD and DTP Series


3.1.2.12.8 Setting Encoding Format of Voice Playing


3.1.2.12.8.1 DefaultPlayFormat
Configuration Item | DefaultPlayFormat
Section | [BoardId=x]
Written Format | Format 1: DefaultPlayFormat =v,v,v,v Format 2: DefaultPlayFormat =v,v,v,v,v,v,v,v Format 3: DefaultPlayFormat =v,v,v,v,v,v,v,v,v,v,v,v,v,v,v,v Format 4: DefaultPlayFormat =v
Value Range | v=6, A-law (default); v=7, μ-law; v=17, ADPCM.
Description | Sets the channel’s defaulted encoding format of voice playing
Note | l Format 1 is applicable to SHT Series USB voice boxes and ATP Series USB recording boxes; l Format 2 is applicable to 8-channel SHT and ATP Series; l Format 3 is applicable to 16-channel SHT, ATP and DST Series; l Format 4 is applicable to SHD and DTP Series


3.1.2.12.9 Setting Other Parameters of Voice Playing


3.1.2.12.9.1 DefaultPausePlayOnRxDtmf
Configuration Item | DefaultPausePlayOnRxDtmf
Section | [BoardId=x]
Written Format | Format 1:DefaultPausePlayOnRxDtmf=b,b,b,b Format 2:DefaultPausePlayObRxDtmf=b,b,b,b,b,b,b,b Format 3:DefaultPausePlayObRxDtmf=b,b,b,b,b,b,b,b,b,b,b,b,b,b,b,b Format 4:DefaultPausePlayObRxDtmf=b Format 5:DefaultPausePlayObRxDtmf=[0,29]:b
Value Range | b=0: No; b=1: Yes (default)
Description | When the DTMF Detector detects DTMF signals in the incoming call, if the voice is playing on the channel, in order to ensure the correct operation of the DTMF Detector, the driver needs to suspend the voice playing. The driver will automatically resume the voice playing until the DTMF signal disappears. This configuration item sets whether to enable this feature or not. Normally, it’s set to be 0 for recording channels and 1 for other channels
Note | l Format 1 is applicable to SHT and ATP Series USB voice boxes/recording boxes; l Format 2 is applicable to 8-channel SHT and ATP Series; l Format 3 is applicable to 16-channel SHT, ATP and ATP Series; l Format 4 is applicable to SHD Series l Format 5 is applicable to the channel bank of 30 channels l This configuration item is inapplicable to 16-channel C-type SHT series.


3.1.2.12.9.2 PlayFilterFlag
Configuration Item | PlayFilterFlag
Section | [BoardId=x]
Written Format | Format 1: PlayFilterFlag =b,b,b,b,b,b,b,b Format 2: PlayFilterFlag =b,b,b,b,b,b,b,b,b,b,b,b,b,b,b,b
Value Range | b=0: No (default); b=1: Yes.
Description | If voices are played in great volume, the DTMF detector probably fails to acquire the correct DTMF digits sent from the remote end. In such situation, the filter should be enabled to avoid the effect of the great volume on DTMF reception. This configuration item just determines whether to enable the filter or not.
Note | l This configuration item is only applicable to SHT-8C/PCI/EC, SHT-16C/PCI/EC and SHT-16C/PCI/FAX boards; l Format 1 is applicable to 8-channel SHT Series; l Format 2 is applicable to 16-channel SHT Series.


3.1.2.13 Setting Recording Operation


3.1.2.13.1 Setting Termination Condition of Voice Recording


3.1.2.13.1.1 DtmfStopRecCharSet
Configuration Item | DtmfStopRecCharSet
Section | [BoardId=x]
Written Format | Format 1:DtmfStopRecCharSet={s,s,s,s} Format 2:DtmfStopRecCharSet={s,s,s,s,s,s,s,s} Format 3:DtmfStopRecCharSet={s,s,s,s,s,s,s,s,s,s,s,s,s,s,s,s} Format 4:DtmfStopRecCharSet=s
Value Range | ‘s’ is the DTMF character set with the format of {***}, in which * may be any one character of ‘0123456789*#abcd’, the number of characters is set based on the actual needs. If ‘s’ is an empty set, this feature is disabled; If ‘s’ is not empty, this feature is enabled. Default value is an empty set
Description | Sets whether the recording is terminated because the DTMF Detector detects the DTMF character
Note | l Format 1 is applicable to the SHT Series USB voice box and the ATP Series USB recording box; l Format 2 is applicable to 8-channel SHT and ATP Series; l Format 3 is applicable to 16-channel SHT, ATP and DST Series; l Format 4 is applicable to SHD and DTP Series.
Example | DtmfStopRecCharSet={0123456789*#abcd } //SHD Series: The recording stops once any of the characters in the set is detected


3.1.2.13.1.2 HangupStopRec
Configuration Item | HangupStopRec
Section | [BoardId=x]
Written Format | Format 1:HangupStopRec=b,b,b,b Format 2:HangupStopRec=b,b,b,b,b,b,b,b Format 3:HangupStopRec=b,b,b,b,b,b,b,b,b,b,b,b,b,b,b,b Format 4:HangupStopRec=b
Value Range | b=0: No (default); b=1: Yes
Description | Sets whether the voice recording is terminated because the state machine of the driver detects remote hangup
Note | l Format 1 is applicable to the SHT Series USB voice box and the ATP Series USB recording box; l Format 2 is applicable to 8-channel SHT and ATP Series; l Format 3 is applicable to 16-channel SHT and ATP Series; l Format 4 is applicable to SHD Series.


3.1.2.13.2 Setting Recording Signal Sources


3.1.2.13.2.1 DefaultRecordVolume

Refer to DefaultRecordMixerVolume


3.1.2.13.2.2 DefaultRecordMixerVolume
Configuration Item | DefaultRecordVolume DefaultRecordMixerVolume
Section | [BoardId=x]
Written Format | Format 1:DefaultRecordVolume=v3,v3,v3,v3 DefaultRecordMixerVolume=v2,v2,v2,v2 Format 2:DefaultRecordVolume=v3,v3,v3,v3,v3,v3,v3,v3 DefaultRecordMixerVolume=v2,v2,v2,v2,v2,v2,v2,v2 Format 3:DefaultRecordVolume= v3,v3,v3,v3,v3,v3,v3,v3,v3,v3,v3,v3,v3,v3,v3,v3 DefaultRecordMixerVolume=v2,v2,v2,v2,v2,v2,v2,v2,v2,v2,v2,v2,v2,v2,v2,v2 Format 4:DefaultRecordVolume=v3 DefaultRecordMixerVolume=v2
Value Range | v3,v2: Volume of the volume adjuster, -7≤v3≤+6,-7≤v2≤+6. -7 implies the volume adjuster is stopped. Other values represent the volume gains (v3/v2×3 being the decibel value (db)), those greater than 0 indicating the increase in volume and those less than 0 reflecting the decrease in volume. The default value of v3 is 0 while the default value of v2 is -7.
Description | Sets the gain of signals entering the recording mixer M3. DefaultRecordVolume sets the gain of the volume adjuster A3, while DefaultRecordMixerVolume sets the gain of the volume adjuster A2. For more information, refer to the operation principle of corresponding boards in Chapter 1
Note | l Format 1 is applicable to the SHT Series USB voice box and the ATP Series USB recording box; l Format 2 is applicable to 8-channel SHT and ATP Series; l Format 3 is applicable to 16-channel SHT and ATP Series (DefaultRecordVolume is also applicable to DST Series) l Format 4 is applicable to SHD and DTP Series
Example | DefaultRecordVolume=1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1 // Increase the volume by 3DB


3.1.2.13.3 Setting Tail-Truncation Feature for File Recording


3.1.2.13.3.1 TruncateTailOnRecordToFile
Configuration Item | TruncateTailOnRecordToFile
Section | [SystemConfig]
Written Format | TruncateTailOnRecordToFile=t
Value Range | t=0: Disable this feature (default); t>0: The length (ms) of the voice data truncated from the file tail
Description | Sets the time length for tail truncation during the file recording. For more information about the file tail truncation during file recording, refer to the description of the function SsmSetTruncateTail .
Note | This configuration item requires SynCTI Ver. 2.1 or above


3.1.2.13.4 Setting Encoding Format of Voice Recording


3.1.2.13.4.1 DefaultRecordFormat
Configuration Item | DefaultRecordFormat
Section | [BoardId=x]
Written Format | Format 1: DefaultRecordFormat =v,v,v,v Format 2: DefaultRecordFormat =v,v,v,v,v,v,v,v Format 3: DefaultRecordFormat =v,v,v,v,v,v,v,v,v,v,v,v,v,v,v,v Format 4: DefaultRecordFormat =v
Value Range | V=6, A-law (default); V=7, μ-law; V=17, ADPCM.
Description | Sets the channel’s defaulted encoding format of voice recording.
Note | l Format 1 is applicable to SHT Series USB voice boxes and ATP Series USB recording boxes; l Format 2 is applicable to 8-channel SHT and ATP Series; l Format 3 is applicable to 16-channel SHT, ATP and DST Series; l Format 4 is applicable to SHD and DTP Series


3.1.2.13.5 Setting Internal Recording Buffer


3.1.2.13.5.1 RecordBufSize
Configuration Item | RecordBufSize
Section | [SystemConfig]
Written Format | RecordBufSize=k
Value Range | k: The length of the buffer area, calculated by byte. It must be the multiple of 512, with the minimum value of 4096 and the default value of 32768. When GsmCodecEnable is enabled, the minimum value of this configuration item turns to be 16384.
Description | Sets the size of the internal recording buffer area allocated by the driver for the channel


3.1.2.13.6 Setting WAV Format for Recording


3.1.2.13.6.1 RecAsWavFormat
Configuration Item | RecAsWavFormat
Section | [SystemConfig]
Written Format | RecAsWavFormat =K
Value Range | K=0: Use the format of the file itself for recording, i.e. only the file with an extension name of wav or mp3 is recorded in wav format. K=1: All files are recorded in wav format.
Description | Sets the use of wav format to record files.


3.1.2.13.6.2 Mp3IsOnlyRead
Configuration Item | Mp3IsOnlyRead
Section | [SystemConfig]
Written Format | Mp3IsOnlyRead =K
Value Range | K=0: The recorded MP3 file is in the common state, readable and writable; K=1: The recorded MP3 file is in the read-only state, read only, not writable.
Description | Sets the property of the recorded MP3 files.


3.1.2.13.7 Setting AGC Parameters


3.1.2.13.7.1 AGCMAXGAIN

Refer to AGCMINGAINDOWNLINK


3.1.2.13.7.2 AGCMINGAIN

Refer to AGCMINGAINDOWNLINK


3.1.2.13.7.3 AGCMAXGAINUPLINK

Refer to AGCMINGAINDOWNLINK


3.1.2.13.7.4 AGCMINGAINUPLINK

Refer to AGCMINGAINDOWNLINK


3.1.2.13.7.5 AGCMAXGAINDOWNLINK

Refer to AGCMINGAINDOWNLINK


3.1.2.13.7.6 AGCMINGAINDOWNLINK

Configuration Item

AGCMAXGAIN

AGCMINGAIN

AGCMAXGAINUPLINK

AGCMINGAINUPLINK

AGCMAXGAINDOWNLINK

AGCMINGAINDOWNLINK

Section

[BoardId=x]

Written Format

AGCMAXGAIN=Gmax

AGCMINGAIN=Gmin

AGCMAXGAINUPLINK=Gmax

AGCMINGAINUPLINK=Gmin

AGCMAXGAINDOWNLINK=Gmax

AGCMINGAINDOWNLINK=Gmin

Value Range

Gmax: 1≤Gmax≤255, with the default value of 255. When Gmax=255, the maximum AGC gain is 24dB. This parameter is used to control the maximum gain increase of small signals. The greater the value is, the easier the level of small signals is increased; however, the background noise gets larger at the same time.

Gmin: 1≤Gmin≤255, with the default value of 6. When Gmin=6, the minimum AGC gain is -8.5dB. This parameter is used to control the maximum gain decrease of large signals. This parameter should be equal to or greater than 16 if the AGC controller is required to provide gain increase only.

Description

Parameters to control the range of DSP gain increase and decrease

Note

l The default setting of AGC is 16, which indicates the gain of 0dB (neither increase nor decrease). When the output signal level is lower than the expected level, the AGC value gets greater; otherwise it drops. The actual level gain of AGC is 20log (gain value/16) dB. This configuration item is an advanced one. Our default AGC settings are suitable for most application environments. If you are required to reset the parameters for AGC in particular cases, please do it under the instruction of our technicians.

l As the special AGC configuration items for DST-24B/PCI, DST-24B/PCI+, DST-24B/PCIe, DST-24B/PCIe+ boards, the configuration items AGCMAXGAINUPLINK , AGCMINGAINUPLINK , AGCMAXGAINDOWNLINK and AGCMINGAINDOWNLINK are used to set the uplink and downlink AGC parameters.


3.1.2.13.7.7 AGCMAXLEVEL

Refer to AGCMINLEVELDOWNLINK


3.1.2.13.7.8 AGCMINLEVEL

Refer to AGCMINLEVELDOWNLINK


3.1.2.13.7.9 AGCMAXLEVELUPLINK

Refer to AGCMINLEVELDOWNLINK


3.1.2.13.7.10 AGCMINLEVELUPLINK

Refer to AGCMINLEVELDOWNLINK


3.1.2.13.7.11 AGCMAXLEVELDOWNLINK

Refer to AGCMINLEVELDOWNLINK


3.1.2.13.7.12 AGCMINLEVELDOWNLINK

Configuration Item

AGCMAXLEVEL

AGCMINLEVEL

AGCMAXLEVELUPLINK

AGCMINLEVELUPLINK

AGCMAXLEVELDOWNLINK

AGCMINLEVELDOWNLINK

Section

[BoardId=x]

Written Format

AGCMAXLEVEL=Lmax

AGCMINLEVEL=Lmin

AGCMAXLEVELUPLINKL=Lmax

AGCMINLEVELUPLINK=Lmin

AGCMAXLEVELDOWNLINKL=Lmax

AGCMINLEVELDOWNLINK=Lmin

Value Range

Lmax: AGCMINLEVEL≤Lmax≤25600000, with the default value of 3200000. The maximum output voltage level. If the actual output voltage level is greater than Lmax, the AGC module starts reducing the gain and doesn’t stop until the minimum gain set by the configuration item AGCMINGAIN is reached.

Lmin: 0≤Lmin≤AGCMAXLEVEL, with the default value of 2560000. The minimum output voltage level. If the actual output voltage level is less than Lmin and keeps for a certain period of time, the AGC module starts increasing the gain and doesn’t stop until the maximum gain set by the configuration item AGCMAXGAIN is reached.

Description

Parameters to control the expected value of the AGC output voltage level

Note

l AGC adjusts the gain to control the output signals within a specified range. If the output voltage level is expected to be as stable as possible, you may set the two parameters to be nearly equal but not completely equal; otherwise, the frequent adjustment of gain will lead to the fluctuation of the AGC output voltage level even if the input voltage level is quite stable. The full amplitude of the voltage level is 25600000. If the full-amplitude level is assumed to be 0dB, the level value should be set to 10log (set value/25600000) dB, with the default values 3200000 and 2560000 respectivley corresponding to -9dB and -10dB. This configuration item is an advanced one. Our default settings are suitable for most application environments. If you are required to reset this item, please do it under the instruction of our technicians.

l As the special AGC configuration items for DST-24B/PCI, DST-24B/PCI+, DST-24B/PCIe, DST-24B/PCIe+ boards, the configuration items AGCMAXLEVELUPLINK , AGCMINLEVELUPLINK , AGCMAXLEVELDOWNLINK and AGCMINLEVELDOWNLINK are used to set the uplink and downlink AGC parameters.


3.1.2.13.7.13 AGCDOWNRATIO

Refer to AGCKEEPTIME


3.1.2.13.7.14 AGCUPRATIO

Refer to AGCKEEPTIME


3.1.2.13.7.15 AGCDOWNRATIOUPLINK

Refer to AGCKEEPTIME


3.1.2.13.7.16 AGCUPRATIOUPLINK

Refer to AGCKEEPTIME


3.1.2.13.7.17 AGCDOWNRATIODOWNLINK

Refer to AGCKEEPTIME


3.1.2.13.7.18 AGCUPRATIODOWNLINK

Refer to AGCKEEPTIME


3.1.2.13.7.19 AGCKEEPTIME

Configuration Item

AGCDOWNRATIO

AGCUPRATIO

AGCDOWNRATIOUPLINK

AGCUPRATIOUPLINK

AGCDOWNRATIODOWNLINK

AGCUPRATIODOWNLINK

AGCKEEPTIME

Section

[BoardId=x]

Written Format

AGCDOWNRATIO=Rdown

AGCUPRATIO=Rup

AGCDOWNRATIOUPLINK=Rdown

AGCUPRATIOUPLINK=Rup

AGCDOWNRATIODOWNLINK=Rdown

AGCUPRATIODOWNLINK=Rup

AGCKEEPTIME=t

Value Range

Rdown: 0≤Rdown≤100, with the default value of 35. The step size of automatic gain decrease (5 denotes 5%), used to control the speed of gain decrease. Usually it should be set to a high speed so as to avoid signal chopped distortion.

Rup: 0≤Rup≤100, with the default value of 1. The step size of automatic gain increase (5 denotes 5%), used to control the speed of gain increase. Usually it should be set to a low speed so as to eliminate the background noise for output signals. However, if the speed is set too low, small signals cannot be amplified in time.

t: 0≤t≤32768, with the default value of 0. Duration, each unit is 8ms. There may keep a periodof time before the gain turns from decrease to increse. Duration=*16ms(set value). The setting of this parameter can help eliminate the backgroud noise for voice interval, but will delaly the gain increase of small signals. It is not necessary for gain decrease.

Description

Parameters to control the speed of AGC gain decrease/increase

Note

l The speed of gain decrease/increase set by DOWN_TIMEand UP_TIME is 20log(1/(1-set value/100))dB/16ms. The defualt decrease speed is 3.7dB/16ms. That is, the gain can decrease from the maximum value to 0dB in approximately 100ms. The defualt increase speed is 0. 087dB/16ms. That is, the gain can increase from 0dB to the maximum value in about 4 seconds. This configuration item is an advanced one. Our default settings are suitable for most application environments. If you are required to reset this item, please do it under the instruction of our technicians.

l As the special AGC configuration items for DST-24B/PCI, DST-24B/PCI+, DST-24B/PCIe, DST-24B/PCIe+ boards, the configuration items AGCDOWNRATIOUPLINK , AGCUPRATIOUPLINK , AGCDOWNRATIODOWNLINK and AGCUPRATIODOWNLINK are used to set the uplink and downlink AGC parameters


3.1.2.13.7.20 OpenRecEnAndPlayEnOnIdle
Configuration Item | OpenRecEnAndPlayEnOnIdle
Section | [BoardId=x]
Written Format | Format 1:OpenRecEnAndPlayEnOnIdle=b,b,b,b Format 2:OpenRecEnAndPlayEnOnIdle=b,b,b,b,b,b,b,b Format 3:OpenRecEnAndPlayEnOnIdle=b,b,b,b,b,b,b,b,b,b,b,b,b,b,b,b
Value Range | b=0: No (default); b=1: Yes
Description | Sets whether to enable the AGC feature during the recording operation when the analog trunk channel is in the idle state
Note | l This configuration item is only applicable to SHT Series analog trunk channels; l This configuration item requires SynCTI Ver. 4.7.2.0 or above


3.1.2.13.7.21 AutoRecAgcSwitch
Configuration Item | AutoRecAgcSwitch
Section | [BoardId=x]
Written Format | AutoRecAgcSwitch=a
Value Range | a=0: disabled (default); a>0: for DST series B-type digital station tap boards, Bit0, Bit1, Bit2 and Bit3 of a are valid: Bit0=0, the AGC downlink is disabled; Bit0=1, the AGC downlink is enabled; Bit1=0, the AGC uplink is disabled; Bit1=1, the AGC uplink is enabled; Bit2=0, DC-isolated is disabled; Bit2=1, DC-isolated is enabled. For other boards, Bit0 is valid. Bit0=0, the AGC is disabled; Bit0=1, the AGC is enabled.
Description | Sets whether to automatically enable the AGC feature when the channel is being recorded.
Note | l This configuration item requires SynCTI Ver5.3.1.1 or above.


3.1.2.13.8 Setting Other Parameters


3.1.2.13.8.1 RecEliDTDurTalking
Configuration Item | RecEliDTDurTalking
Section | [BoardId=x]
Written Format | RecEliDTDurTalking =b,b,b,b,b,b,b,b,b,b,b,b,b,b,b,b
Value Range | b=0: No (default); b=1: Yes.
Description | Determines whether to clamp DTMF digits from the call during the recording process.
Note | This configuration item is only applicable to the SHT-16C/PCI/EC board.


3.1.2.13.9 Setting Bit Rate for MP3 Recording


3.1.2.13.9.1 Mp3EncodingBitRate
Configuration Item | Mp3EncodingBitRate
Section | [SystemConfig]
Written Format | Mp3EncodingBitRate=b
Value Range | b=1: MP3 recording at the bit rate of 8Kbps(default); b=2: MP3 recording at the bit rate of 16Kbps; b=3: MP3 recording at the bit rate of 32Kbps.
Description | Sets the bit rate for MP3 recording.


3.1.2.14 Setting Parameters Required for Both Recording and Playing Operations


3.1.2.14.1 Setting Minimum Size of Pingpong Buffer Area


3.1.2.14.1.1 RecordAndPlayUseAsIP
Configuration Item | RecordAndPlayUseAsIP
Section | [SystemConfig]
Written Format | RecordAndPlayUseAsIP=b
Value Range | b=0: No (default); b=1: Yes
Description | Sets whether the recording/playing operation supports the mini-buffer. For more information, refer to SsmPlayMemBlock and SsmRecordMemBlock


3.1.2.14.2 Setting Software-based GSM Format


3.1.2.14.2.1 GsmCodecEnable

Configuration Item

GsmCodecEnable

Section

[SystemConfig]

Written Format

GsmCodecEnable=b

Value Range

b=0: No (default);

b=1: Yes

Description

It decides whether the driver will automatically load macmcvt.dll which is the ACM component provided by the SynCTI driver for audio encoding and decoding. This component enables software-based GSM/Mp3 encoding/decoding and G.729A decoding. If the application needs to implement the GSM, Mp3 or G.729A formatted recording/playing on Synway boards which don’t have corresponding hardware encoders/decoders, the SynCTI driver can acquire the capability of software encoding and decoding by configuring this item to load the external ACM program.

Note

l If b is set to be 1, it must be ensured that the corresponding audio encoder/decoder (ACM) has been installed in the Windows system;

l This configuration item is only applicable to the Windows operating system;

l When BusPlayListen=0, GsmCodecEnable=0 will be invalid and the driver will load the record/playback software engine to support the monitoring in compressed format.


3.1.2.15 Setting DTMF Detector


3.1.2.15.1 Starting/Stopping DTMF Detector


3.1.2.15.1.1 AlwaysEnableRxDtmf
Configuration Item | AlwaysEnableRxDtmf
Section | [BoardId=x]
Written Format | AlwaysEnableRxDtmf=m
Value Range | m=0: The operating status of the DTMF Detector is always automatically controlled by the driver according to the channel state transition status. When the channel enters the ‘Talking’ state, it is started automatically; When the channel exits the ‘Talking’ state, it is stopped automatically. But the application can control the DTMF Detector by the function SsmEnableRxDtmf . m=1: DTMF Detector is always started
Description | Sets the operating status of the DTMF Detector
Note | This configuration item is applicable to SHD and DTP Series.


3.1.2.15.1.2 RcvDtmfOnIdle
Configuration Item | RcvDtmfOnIdle
Section | [BoardId=x]
Written Format | Format 1:RcvDtmfOnIdle=b,b,b,b Format 2:RcvDtmfOnIdle=b,b,b,b,b,b,b,b Format 3:RcvDtmfOnIdle=b,b,b,b,b,b,b,b,b,b,b,b,b,b,b,b Format 4:RcvDtmfOnIdle=[0,29]:b
Value Range | b=0: Stop the DTMF Detector (default) b=1: Start the DTMF Detector
Description | When the station channel is in the ‘Idle’ state, sets the operating status of DTMF Detector
Note | l This configuration item only supports the station channel; l Format 1 is only applicable to the SHT Series USB voice boxes; l Format 2 is applicable to 8-channel SHT Series; l Format 3 is applicable to 16-channel SHT Series; l Format 4 is applicable to the 30-channel channel bank.


3.1.2.15.2 Setting Buffer Size for DTMF Detector


3.1.2.15.2.1 RxDtmfBufSize
Configuration Item | RxDtmfBufSize
Section | [SystemConfig]
Written Format | RxDtmfBufSize=k
Value Range | k: The size (bytes) of the buffer area, with the default value of 200
Description | Sets the size of the buffer area for the DTMF Detector


3.1.2.15.3 Setting Parameters of DTMF Filter


3.1.2.15.3.1 DualAndAllFreqEnScale

Configuration Item

DualAndAllFreqEnScale

Section

[BoardId=x]

Written Format

Format 1:DualAndAllFreqEnScale=n,n,n,n

Format 2:DualAndAllFreqEnScale=n,n,n,n,n,n,n,n

Format 3:DualAndAllFreqEnScale=n,n,n,n,n,n,n,n,n,n,n,n,n,n,n,n

Format 4:DualAndAllFreqEnScale=m

Value Range

0≤n (%) ≤58, with the default value of 32;

0≤m(%) ≤58, with the default value of 32

Description

Sets the threshold value in percentage for the rate of DTMF in-band energy to overall energy. For more information about this configuration item, refer to DTMF Filter

Note

l Format 1 is applicable to the SHT Series USB voice boxes and the ATP Series USB recording boxes;

l Format 2 is applicable to 8-channel SHT Series and ATP Series;

l Format 3 is applicable to 16-channel SHT, ATP and DST Series;

l Format 4 is applicable to SHD and DTP Series. However, the following board models require SynCTI Ver. 4.5.1.7 or above:

² SHD-240A-CT/cPCI

² SHD-240S-CT/cPCI

² SHD-480A-CT/cPCI

² SHD-480S-CT/cPCI

l The function SsmSetFlag (with the parameter of F_DualAndAllFreqEnScale) may implement the same features;

l Set this configuration item to 15 especially for 8B, 16B, 8C, 16C series boards tp receive abcd.


3.1.2.15.3.2 HighAndLowFreqEnScale
Configuration Item | HighAndLowFreqEnScale
Section | [BoardId=x]
Written Format | Format 1:HighAndLowFreqEnScale=n,n,n,n Format 2:HighAndLowFreqEnScale=n,n,n,n,n,n,n,n Format 3:HighAndLowFreqEnScale=n,n,n,n,n,n,n,n,n,n,n,n,n,n,n,n Format 4:HighAndLowFreqEnScale=m
Value Range | 0£n (%) £100, with the default value of 10; 0£m (%) £100, with the default value of 32
Description | Sets the proportion of the high-frequency DTMF energy to the low-frequency in the DTMF signals. Only if the proportion is greater than the set value of this configuration item will the driver confirm that those detected are DTMF signals.
Note | l Format 1 is applicable to the SHT Series USB voice boxes and the ATP Series USB recording boxes; l Format 2 is applicable to 8-channel SHT and ATP Series; l Format 3 is applicable to 16-channel SHT, ATP and DST Series; l Format 4 is applicable to SHD and DTP Series l The same purpose can be achieved by the function SsmSetFlag (with the parameter F_HighAndLowFreqEnScale).


3.1.2.15.3.3 DtmfEnergy
Configuration Item | DtmfEnergy
Section | [BoardId=x]
Written Format | Format 1:DtmfEnergy=n,n,n,n Format 2:DtmfEnergy=n,n,n,n,n,n,n,n Format 3:DtmfEnergy=n,n,n,n,n,n,n,n,n,n,n,n,n,n,n,n Format 4:DtmfEnergy=m
Value Range | n≥0, with the default value of 0. For more information, refer to the configuration item MinimumVoiceDetermineEnergy
Description | Sets the absolute value of DTMF in-band energy. Only if the DTMF in-band energy is greater than the set value of this configuration item will the driver confirm that those detected are DTMF signals.
Note | l Format 1 is applicable to the SHT Series USB voice boxes and the ATP Series USB recording boxes; l Format 2 is applicable to 8-channel SHT and ATP Series; l Format 3 is applicable to 16-channel SHT, ATP and DST Series; l Format 4 is applicable to SHD and DTP Series


3.1.2.15.4 Setting Parameters of DTMF Pulse-width Filter


3.1.2.15.4.1 ReceiveDtmfSensitive

Configuration Item

ReceiveDtmfSensitive

Section

[BoardId=x]

Written Format

ReceiveDtmfSensitive=n

Value Range

n is comprised of 8 bits (namely Bit7…Bit0), below is the meaning of each bit:

Bit3~Bit0: The minimum duration of the DTMF signal at on state. Range of value is 1~6, the unit is 16ms, with the default value of 3;

Bit7~Bit4: The minimum duration of the DTMF signal at off state. Range of value is 0~6, the unit is 16ms, with the default value of 0;

Note: If the value of Bit7~Bit4 is 0, the minimum duration of DTMF signal at off state is determined by the minimum duration at on state. If the minimum duration of the DTMF signal at on state is less than 3, the value of the minimum duration of the DTMF signal at off state is 1; otherwise, the value of the minimum duration of the DTMF signal at off state is 2.

n is represented by hexadecimal number, e.g. ReceiveDtmfSensitive=0x43. This formula means that the minimum durations of the DTMF signals at on and off states are 48ms and 64ms respectively. ReceiveDtmfSensitive=0x03: the minimum durations of the DTMF signal at on and off states are 48ms and 32ms respectively.

Description

The minimum durations of the DTMF signal at on and off states. For more information, refer to DTMF Pulse-width Filter in Chapter 1

Note

It is applicable to SHD, SHT, ATP and DTP Series. However, the following board models among the SHD Series require SynCTI Ver. 4.5.1.7 or above:

² SHD-240A-CT/cPCI

² SHD-240S-CT/cPCI

² SHD-480A-CT/cPCI

² SHD-480S-CT/cPCI


3.1.2.15.4.2 OmitABCD

Configuration Item

OmitABCD

Section

[BoardId=x]

Written Format

Format 1:OmitABCD=b,b,b,b

Format 2:OmitABCD=b,b,b,b,b,b,b,b

Format 3:OmitABCD=b,b,b,b,b,b,b,b,b,b,b,b,b,b,b,b

Format 4:OmitABCD=b

Value Range

b=0: discard;

b=1: Not to discard

Default value is 0

Description

Sets whether to discard the characters of ‘A’, ‘B’, ‘C’, and ‘D’ received by the DTMF Detector. For more information about this configuration item, refer to DTMF Pulse-width Filter in Chapter 1

Note

l Format 1 is applicable to the SHT Series USB voice boxes and the ATP Series USB recording boxes;

l Format 2 is applicable to 8-channel SHT and ATP Series;

l Format 3 is applicable to 16-channel SHT, ATP and DST Series;

l Format 4 is applicable to SHD and DTP Series

l When you enable the reception of abcd codes, the value of DualAndAllFreqEnScale is by default adjusted to 15. If the reception fails, you may need to lower the value and try again.


3.1.2.15.4.3 DtrmOnDtmfHighLevel

Configuration Item

DtrmOnDtmfHighLevel

Section

[BoardId=x]

Written Format

Format 1:DtrmOnDtmfHighLevel=n,n,n,n

Format 2:DtrmOnDtmfHighLevel=n,n,n,n,n,n,n,n

Format 3:DtrmOnDtmfHighLevel=n,n,n,n,n,n,n,n,n,n,n,n,n,n,n,n

Format 4:DtrmOnDtmfHighLevel=n

Value Range

n=0: Only when the duration of the DTMF signals at off state exceeds the minimum duration designated by the configuration item ReceiveDtmfSensitive will the driver output the DTMF characters;

n=1: When the duration of the DTMF signals at on state exceeds the minimum duration designated by the configuration item ReceiveDtmfSensitive will the driver output the DTMF characters immediately;

Default value is 0

Description

Sets the timing of outputting the DTMF characters. For more information about this configuration item, refer to DTMF Pulse-width Filter in Chapter 1

Note

l Format 1 is applicable to the SHT Series USB voice boxes and the ATP Series USB recording boxes;

l Format 2 is applicable to 8-channel SHT and ATP Series;

l Format 3 is applicable to 16-channel SHT, ATP and DST Series;

l Format 4 is applicable to SHD and DTP Series


3.1.2.16 Setting DTMF Generator (CTI Series)


3.1.2.16.1 Setting Size of Transmission Buffer Area


3.1.2.16.1.1 TxDtmfBufSize
Configuration Item | TxDtmfBufSize
Section | [SystemConfig]
Written Format | TxDtmfBufSize=n
Value Range | n³1, Default value is 50 characters
Description | Sets the size of the transmission buffer area for the DTMF generator


3.1.2.16.2 Setting Parameters for DTMF Generator


3.1.2.16.2.1 TxDtmfTimePara

Configuration Item

TxDtmfTimePara

Section

[BoardId=x]

Written Format

Format 1:TxDtmfTimePara={tH,tL},{tH,tL},{tH,tL},{tH,tL}

Format 2:TxDtmfTimePara={tH,tL},{tH,tL},{tH,tL},{tH,tL},{tH,tL},{tH,tL},{tH,tL},{tH,tL}

Format 3:TxDtmfTimePara={tH,tL},{tH,tL},{tH,tL},{tH,tL},{tH,tL},{tH,tL},{tH,tL},{tH,tL},

{tH,tL},{tH,tL},{tH,tL},{tH,tL},{tH,tL},{tH,tL},{tH,tL},{tH,tL}

Format 4:TxDtmfTimePara={tH,tL}

Value Range

tH³40: The duration (ms) of the DTMF signal at on state, it must be integral times of 8ms, with the default value of 80

tL ³40: The duration (ms) of the DTMF signal at off state, it must be integral times of 8ms, with the default value of 80

Description

Sets the durations (ms) of DTMF signals generated by the DTMF Generator respectively at off and on states. For more information, refer to DTMF Generator in Chapter 1

Note

l Format 1 is applicable to the SHT Series USB voice boxes;

l Format 2 and Format 3 are applicable to 8-channel and 16-channel SHT Series respectively;

l Format 4 is applicable to SHD Series


3.1.2.16.2.2 DefaultTxDelayTime
Configuration Item | DefaultTxDelayTime
Section | [SystemConfig]
Written Format | DefaultTxDelayTime=n
Value Range | n: The duration (ms) of silence, with the default value of 2000
Description | Sets the delay time of the DTMF characters when being transmitted. For more information, refer to SsmTxDtmf


3.1.2.17 Setting Echo Canceller (CTI Series)


3.1.2.17.1 Setting Operating Status


3.1.2.17.1.1 EnableEchoCancellor
Configuration Item | EnableEchoCancellor
Section | [BoardId=x]
Written Format | Format 1：EnableEchoCancellor=b,b,b,b Format 2：EbableEchoCancellor=b,b,b,b,b,b,b,b Format 3：EnableEchoCancellor=b,b,b,b,b,b,b,b,b,b,b,b,b,b,b,b Format 4：EnableEchoCancellor=b
Value Range | b=0：Disable the echo canceller b=1：Enable the echo canceller (default)
Description | Sets the operating status of the echo canceller. For more information, refer to Echo Canceller In Chapter 1
Note | l Format 1 is applicable to the SHT Series USB voice boxes and the ATP Series USB recording boxes; l Format 2 is applicable to the 8-channel SHT Series; l Format 3 is applicable to the 16-channel SHT Series; l Format 4 is applicable to SHD Series


3.1.2.17.2 Setting Parameters


3.1.2.17.2.1 EchoCancelDelaySize
Configuration Item | EchoCancelDelaySize
Section | [BoardId=x]
Written Format | EchoCancelDelaySize=k
Value Range | k：the coefficient of the filter delay. Both the value range and the default value are determined by the configuration item LoadFskBin : LoadFskBin=0：0≤k≤7, default value：6; LoadFskBin>0：0≤k≤31, default value：12
Description | Sets the coefficient of the filter delay of the echo canceller
Note | This configuration item is only applicable to SHD and SHT Series USB voice boxes


3.1.2.18 Setting Barge-in Detector (CTI Series)


3.1.2.18.1 Setting Way to Start Barge-in Detector


3.1.2.18.1.1 AlwaysDetectBargeIn
Configuration Item | AlwaysDetectBargeIn
Section | [BoardId=x]
Written Format | AlwaysDetectBargeIn=b
Value Range | b=0: Under the automatic control of the driver. When the channel goes into the S_CALL_TALKING state and join the conference as a dynamic speaker, the driver will automatically start the Barge-in detector; when the channel goes out of the S_CALL_TALKING state or any dynamic speaker channel leaves the conference room, the driver will automatically stop the Barge-in detector; b=1: Always being started. The default value is 0.
Description | Sets the way to start the Barge-in Detector.
Note | This configuration item is applicable to SHD, SHN, DTP and SHV Series. For SHD series boards, AlwaysDetectBargeIn=0 and AlwaysDetectBargeIn=1 are both valid. For SHN, DTP and SHV series boards, AlwaysDetectBargeIn=0 means the Barge in detector is thoroughly disabled and the driver will no longer control the detector automatically. To find more information, refer to ‘Barge in Detector’ in Chapter 1.


3.1.2.18.2 Setting Parameters for Barge-in Detector


3.1.2.18.2.1 VoiceEnergyMinValue
Configuration Item | VoiceEnergyMinValue
Section | [BoardId=x]
Written Format | VoiceEnergyMinValue=k
Value Range | k: The threshold value for noise detection, with the default value of 100,000.
Description | Sets the threshold value to judge noises for the Barge-in detector. The transformational relation between voice energy and DB: SHT Series: DB=10*lg(X/72,000,000) SHD Series: DB=10*lg(X/33,000,000) SHN Series: DB=10*lg(X/33,000,000) ATP Series: DB=10*lg(X/72,000,000) DTP Series: DB=10*lg(X/33,000,000) DST Series: DB=10*lg(X/33,000,000) 24DA Boards: DB=10*lg(X/22,000,000,000)


3.1.2.18.2.2 BargeInSensitive
Configuration Item | BargeInSensitive
Section | [BoardId=x]
Written Format | Format 1: BargeInSensitive=k,k,k,k Format 2: BargeInSensitive=k,k,k,k,k,k,k,k Format 3: BargeInSensitive=k,k,k,k,k,k,k,k,k,k,k,k,k,k,k,k Format 4: BargeInSensitive=k
Value Range | 0≤k≤31, with the default value of 6. The greater the value is, the more sensitive the detector is.
Description | Sets the sensitivity of the Barge-in detector.
Note | l Format 1 is applicable to the SHT Series USB voice boxes and the ATP Series USB recording boxes; l Format 2 is applicable to 8-channel SHT and ATP Series; l Format 3 is applicable to 16-channel SHT and DST Series; l Format 4 is applicable to SHV, SHD, SHN and DTP Series; l See the function SsmSetBargeInSens for details.


3.1.2.18.2.3 BargeInDtrmTime
Configuration Item | BargeInDtrmTime
Section | [BoardId=x]
Written Format | Format 1: BargeInDtrmTime=k,k,k,k Format 2: BargeInDtrmTime=k,k,k,k,k,k,k,k Format 3: BargeInDtrmTime=k,k,k,k,k,k,k,k,k,k,k,k,k,k,k,k Format 4: BargeInDtrmTime=k
Value Range | k³16 and must be the multiple of 16, calculated by millisecond (ms), with the default value of 32.
Description | Sets the minimum signal duration for the Barge-in detector.
Note | l Format 1 is applicable to the SHT Series USB voice boxes and the ATP Series USB recording boxes; l Format 2 is applicable to 8-channel SHT Series; l Format 3 is applicable to 16-channel SHT and DST Series; l Format 4 is applicable to SHD and DTP Series; l See the function SsmSetIsBargeInDtrmTime for details.


3.1.2.18.2.4 IsNoSoundDtrmTime
Configuration Item | IsNoSoundDtrmTime
Section | [SystemConfig]
Written Format | IsNoSoundDtrmTime=k
Value Range | The minimum duration for the line to keep silence, calculated by millisecond (ms). k³16 and must be the multiple of 16, with the default value of 5000ms.
Description | Sets the minimum duration for the line to keep silence. See the function SsmSetNoSoundDtrmTime for details.
Example | IsNoSoundDtrmTime= 5000


3.1.2.18.2.5 DefaultDtmfIsSound
Configuration Item | DefaultDtmfIsSound
Section | [BoardId=x]
Written Format | Format 1: DefaultDtmfIsSound=b,b,b,b Format 2: DefaultDtmfIsSound=b,b,b,b,b,b,b,b Format 3: DefaultDtmfIsSound=b,b,b,b,b,b,b,b,b,b,b,b,b,b,b,b Format 4: DefaultDtmfIsSound=b
Value Range | b=0: No; b=1: Yes (default).
Description | Sets whether to regard the DTMF signal in the incoming call as the voice signal.
Note | l Format 1 is applicable to the SHT Series USB voice boxes and the ATP Series USB recording boxes; l Format 2 is applicable to 8-channel SHT and ATP Series; l Format 3 is applicable to 16-channel SHT and DST Series; l Format 4 is applicable to SHD and DTP Series; l This configuration item requires SynCTI Ver. 4.5.2.9 or above.


3.1.2.19 Setting TDM Connection


3.1.2.19.1 InVoiceToBus
Configuration Item | InVoiceToBus
Section | [BoardId=x]
Written Format | Format 1: InVoiceToBus=b,b,b,b Format 2: InVoiceToBus=b,b,b,b,b,b,b,b Format 3: InVoiceToBus=b,b,b,b,b,b,b,b,b,b,b,b,b,b,b,b Format 4: InVoiceToBus=b
Value Range | b=0: No; b=1: Yes (default).
Description | Determines whether to connect incoming signals to the TDM bus upon the system initialization. The function SsmSetFlag (with the parameter F_InVoiceToBus) can be used for the same purpose.
Note | l Format 1 is applicable to the SHT Series USB voice boxes and the ATP Series USB recording boxes; l Format 2 is applicable to 8-channel SHT and ATP Series; l Format 3 is applicable to 16-channel SHT and DST Series; l Format 4 is applicable to SHD and DTP Series; l This configuration item requires SynCTI Ver. 4.0 or above.


3.1.2.19.2 LinkFromStopPlayAndTone
Configuration Item | LinkFromStopPlayAndTone
Section | [BoardId=x]
Written Format | LinkFromStopPlayAndTone=b
Value Range | b=1: Immediately terminates the task of voice playing or the task performed by the tone generator (default); b=0: Waits for the task of voice playing to go into an end and then executes the off-bus command.
Description | See the Operation Principle of SHD Series section in Chapter 1 for details.
Note | l This configuration item is only applicable to the 30/60/120-channel SHD Series; l It requires SynCTI Ver. 4.5.2.9 or above.


3.1.2.19.3 DefaultSpeakVolume
Configuration Item | DefaultSpeakVolume
Section | [BoardId=x]
Written Format | Format 1: DefaultSpeakVolume=k,k,k,k Format 2: DefaultSpeakVolume=k,k,k,k,k,k,k,k Format 3: DefaultSpeakVolume=k,k,k,k,k,k,k,k,k,k,k,k,k,k,k,k Format 4: DefaultSpeakVolume=k
Value Range | -7≤k≤6, k×3 being the decibel value (db), with the default value of 0.If it is greater than 0, the volume is increased; if it is less than 0, the volume is decreased.
Description | Sets the volume of this channel’s voice signals before they pass the TDM bus and go down to the off-bus mixer M2 of another channel. See sections about the board operation principle in Chapter 1 for details.
Note | l Format 1 is applicable to the SHT Series USB voice boxes and the ATP Series USB recording boxes; l Format 2 is applicable to 8-channel SHT and ATP Series; l Format 3 is applicable to 16-channel SHT, ATP and DST Series. l Format 4 is applicable to SHD series.


3.1.2.19.4 EnableCommonTimeSlot
Configuration Item | EnableCommonTimeSlot
Section | [SystemConfig]
Written Format | EnableCommonTimeSlot=b
Value Range | b=0: Not open (default); b=1: Open all the time slots on the TDM bus.
Description | Opens all the common time slots on the TDM bus
Note | l This configuration item is only applicable to the situation where Synway boards are interoperated with third party boards; l It requires SynCTI Ver. 5.2.0.0 or above versions.


3.1.2.20 Setting Caller ID Detector for Analog Phone Line (SHT＋ATP Series)


3.1.2.20.1 Setting Operating Mode of Caller ID Detector


3.1.2.20.1.1 CallerIdStyle

Configuration Item

CallerIdStyle

Section

[BoardId=x]

Written Format

Format 1: CallerIdStyle=m,m

Format 2: CallerIdStyle=m,m,m,m

Format 3: CallerIdStyle=m,m,m,m,m,m,m,m

Format 4: CallerIdStyle=m,m,m,m,m,m,m,m,m,m,m,m,m,m,m,m

Value Range

m=0: DTMF Mode. The configuration items DtmfCallerIDStyleLength and DtmfCallerIDInterTimeout are effective.

m=1: FSK Mode. The configuration items CloseCallerIdOnReceived and FSKCallerIdDtrmTime are effective.

The default value is 1.

Description

Sets the mode for the remote PBX to send the calling party number on the analog phone line. Refer to the Caller ID on Analog Phone Line section in Chapter 1 for details.

Note

l This configuration item is only applicable to the analog trunk channel on the SHT Series boards;

l Format 1 and Format 2 are respectively applicable to 2-/4-channel USB voice boxes and USB recording boxes; Format 3 is applicable to 8-channel boards; Format 4 is applicable to 16-channel boards;

l The same purpose can be achieved via the function call of SsmSetFlag (with the parameter F_CALLERIDTYPE);

l It is invalid to the recording channel on ATP-24A series boards.


3.1.2.20.2 Setting Parameters for FSK Mode


3.1.2.20.2.1 CloseCallerIdOnReceived
Configuration Item | CloseCallerIdOnReceived
Section | [SystemConfig]
Written Format | CloseCallerIdOnReceived=b
Value Range | b=0: Enabled; b=1: Disabled (default).
Description | This configuration item is set to determine whether the Caller ID detector will be automatically disabled by the driver after it receives the complete calling party number in the FSK mode. Refer to the Caller ID on Analog Phone Line section in Chapter 1 for more information.
Note | This configuration item is only applicable to SHT and ATP Series.


3.1.2.20.2.2 FSKCallerIdDtrmTime

Configuration Item

FSKCallerIdDtrmTime

Section

[BoardId=x]

Written Format

Format 1: FSKCallerIdDtrmTime=k,k

Format 2: FSKCallerIdDtrmTime=k,k,k,k

Format 3: FSKCallerIdDtrmTime=k,k,k,k,k,k,k,k

Format 4: FSKCallerIdDtrmTime=k,k,k,k,k,k,k,k,k,k,k,k,k,k,k,k

Value Range

k: The time to judge the completion, calculated by millisecond (ms),100≤k≤500, with the default value of 500ms.

Description

When the Caller ID detector is started in the FSK mode, since there is no clear symbol to tell the completion in transmitting the FSK calling party number, the driver has to depend on the relativity between time and data to judge the completion of the process. That is, if the received Caller ID character keeps unchanged in length for the period of time set by this parameter, the driver will consider the signal transmission of the FSK Caller ID to be ended.

Note

l This configuration item is only applicable to the analog trunk channel on the SHT Series boards and the recording channel on the ATP Series boards;

l Format 1 and Format 2 are respectively applicable to 2-/4-channel USB voice boxes and USB recording boxes; Format 3 is applicable to 8-channel boards; Format 4 is applicable to 16-channel boards;


3.1.2.20.2.3 FilterInvalidCID

Configuration Item

FilterInvalidCID

Section

[BoardId=x]

Written Format

Format 1: FilterInvalidCID=b,b,b,b,b,b,b,b

Format 2: FilterInvalidCID=b,b,b,b,b,b,b,b,b,b,b,b,b,b,b,b

Value Range

b=0: No (default);

b=1: Yes.

Description

Sets whether to enable the ‘Filter Out Wrong FSK Caller ID’ feature. The FSK calling party number received by the driver may be incorrect:

² The number is a false one formed by echoes in the sound, not sent by the remote PBX;

² The number is exactly sent by the remote PBX, but becomes incomplete because of signals being damaged by disturbance or other elements during the transmission.

Note

l Format 1 and Foramt 2 are respectively applicable to 8-channel and 16-channel SHT/ATP Series;

l This configuration item requires SynCTI Ver. 4.7.1.8 or above.


3.1.2.20.2.4 FSKMinGate
Configuration Item | FSKMinGate
Section | [BoardId=x]
Written Format | Format 1: FSKMinGate =b,b,b,b,b,b,b,b Format 2: FSKMinGate =b,b,b,b,b,b,b,b,b,b,b,b,b,b,b,b Format 3: FSKMinGate =b,b,b,b,b,b,b,b,b,b,b,b,b,b,b,b,b,b,b,b,b,b,b,b
Value Range | b=n (n>0): The set threshold value; b=150: The default value.
Description | Sets an energy threshold value for FSK receiving.
Note | l Format 1 , Format 2 and Format 3 are respectively applicable to 8-channel , 16-channel and 24-channel SHT/ATP Series; l This configuration item requires SynCTI 5.0.2.0 or above.


3.1.2.20.2.5 FskNoPhase
Configuration Item | FskNoPhase
Section | [BoardId=x]
Written Format | FskNoPhase=m
Value Range | m=0: The syn code of the 0/1 up-and-down waveform followed by the flag code composed of all 1s (default); m=1: The syn code of 0804 followed by the flag code composed of all 1s.
Description | Sets the format of the syn code in the FSK calling party number.
Note | This configuration item is only applicable to the analog trunk channel on the SHT Series boards and the recording channel on the ATP Series boards.


3.1.2.20.3 Setting Parameters for DTMF Mode


3.1.2.20.3.1 DtmfCallerIDStyleLength

Refer to DtmfCallerIDInterTimeOut


3.1.2.20.3.2 DtmfCallerIDInterTimeOut
Configuration Item | DtmfCallerIDStyleLength DtmfCallerIDInterTimeOut
Section | [SystemConfig]
Written Format | DtmfCallerIDStyleLength=n DtmfCallerIDInterTimeOut=t
Value Range | n: The minimum number of DTMF digits, 1≤n≤29, with the default value of 1. t: The time interval, calculated by millisecond (ms), t≥300, with the default value of 500.
Description | When the Caller ID detector works in the DTMF mode, if the number of DTMF digits received by the driver is less than or equal to n, all received digits will be abandoned; if the time interval between the receptions of two DTMF digits is greater than t, all digits previously received will be abandoned.
Note | l DtmfCallerIDInterTimeOut requires SynCTI Ver. 4.5.2.1 or above; l This configuration item is only applicable to the SHT and ATP Series boards.


3.1.2.21 Setting Ringing Current Signal Detector (SHT+ATP Series)


3.1.2.21.1 RingDetectFilterPara

Configuration Item

RingDetectFilterPara

Section

[SystemConfig]

Written Format

RingDetectFilterPara=tH, tL

Value Range

tH: The minimum duration of signals at on state. tH≥4 and is calculated by the multiple of 8ms, with the default value of 6 (i.e. 48ms). Only if the signal stays at on state for tH or longer than tH will the driver confirm the detection of a ringing current signal. The greater tH is, the less sensitive the ringing current detector is.

tL: The minimum duration of signals at off state. tL≥1 and is calculated by the multiple of 8ms, with the default value of 40 (i.e. 320ms). Only if the signal stays at off state for tL or longer than tL will the driver confirm the disappearance of ringing current signals.

Description

Sets the filter paramters for the ringing current detector, that is, the parameters used to detect rings on the analog trunk channel and the magnet channel. The driver takes a sample of ringing signals on the analog trunk channel and the magnet channel every 8 ms. A ringing signal is regarded gone when the count of signals at off state goes equal to or greater than the value for judging signals at off state (the 2nd parameter); a ringing signal is confirmed detected when the count of signals at on state goes equal to or greater than the value for judging signals at on state (the 1st parameter). Increasing the value for judging signals at on state will lead to the decrease in the ringing detection’s sensitivity; vice versa.

Note

This configuration item is only applicable to the analog trunk channel and the magnet channel on the SHT Series boards as well as the analog recording channel on the ATP Series boards.


3.1.2.21.2 CallBackRingDetectFilterPara

Configuration Item

CallBackRingDetectFilterPara

Section

[SystemConfig]

Written Format

CallBackRingDetectFilterPara=tH, tL

Value Range

tH: The maximum duration of signals at on state. tH≥4 and is calculated by the multiple of 8ms, with the default value of 25 (i.e. 200ms).

tL: The maximum duration of signals at off state. tL≥1 and is calculated by the multiple of 8ms, with the default value of 40 (i.e. 320ms).

Description

Sets the filter parameters for the ringback current detector, that is the parameters used to detect rings on the analog trunk channel and the magnet channel. The driver takes a sample of ringing signals on the analog trunk channel and the magnet channel every 8ms. A signal, when the count of it at on and off states is consistent with the setting of RingDetectFilterPara , with the duration at on state less than tH and the duration at off state less than tL, is judged as a ringback signal. This feature can be used to distinguish two different ringing signals. At the same time, the driver will throw out the events E_CHG_RingCount and E_CHG_CallBackRingCount .

Note

This configuration item is applicable to the analog trunk channel and the magnet channel on SHT series boards as well as the analog recording channel on ATP series boards.


3.1.2.21.3 RingEndDtrTime
Configuration Item | RingEndDtrTime
Section | [SystemConfig]
Written Format | RingEndDtrTime=k
Value Range | k>0: The maximum waiting time (ms) for the ringing current signal to be terminated. If the ringing current does not terminate within the maximum waiting time, it will be recounted from 0. The default value of k is 6000(ms).
Description | This configuration item is used to set the maximum durations of the ringing current at the off state which is ‘tL+RingEndDtrTime’. ’tL’ is the minimum duration at the off state, which can be obtained via the configuration item RingDetectFilterPara. The ringing current can be detected only when the condition ‘tL ≦ duration at the off state ≦ tL+RingEndDtrTime’ is satisfied. When the period of a ringing current signal lasts too long, the value of k should be increased to prevent the lost of any ringing current signal.
Note | This configuration item is only applicable to the analog trunk channel and the magnet channel on the SHT Series boards as well as the analog recording channel on the ATP Series boards.


3.1.2.21.4 AlwaysToRingingOnRingCntX

Configuration Item

AlwaysToRingingOnRingCntX

Section

[SystemConfig]

Written Format

AlwaysToRingingOnRingCntX=k

Value Range

k=0: The channel state transfers to ‘Ringing’ when the driver detects two (the Caller ID detector is set to work in the DTMF or FSK mode) complete ringing current signals;

k³1: No matter the Caller ID detector is working in which mode, the channel state will transfer to ‘Ringing’ once the driver detects k complete ringing current signals.

The default value is 0.

Description

Sets the parameters for the ringing current detector. Refer to the Ringing Current on Analog Phone Line section in Chapter 1 for more information.

Note

l This configuration item may be covered by the configuration item ChToRingingOnRingCnt. Refer to the Ringing Current on Analog Phone Line section in Chapter 1 for more information;

l The parameters set by this configuration item can also be configured by the function SsmSetFlag (with the parameter F_ChToRingingOnRingCnt)；

l This configuration item is only applicable to the analog trunk channel on the SHT Series boards.


3.1.2.21.5 ChToRingingOnRingCnt

Configuration Item

ChToRingingOnRingCnt

Section

[BoardId=x]

Written Format

Format 1: ChToRingingOnRingCnt=n,n,n,n

Format 2: ChToRingingOnRingCnt=n,n,n,n,n,n,n,n

Format 3: ChToRingingOnRingCnt=n,n,n,n,n,n,n,n,n,n,n,n,n,n,n,n

Value Range

n=0: The channel state transfers to ‘Ringing’ when the driver detects two (the Caller ID detector is set to work in the DTMF or FSK mode) complete ringing current signals;

n³1: No matter the Caller ID detector is working in which mode, the channel state will transfer to ‘Ringing’ once the driver detects n complete ringing current signals.

The default value is 0.

Description

Sets the parameters for the ringing current detector. Refer to the Ringing Current on Analog Phone Line section in Chapter 1 for more information.

Note

l This configuration item is only applicable to the analog trunk channel on the SHT Series boards;

l If this configuration item is specified for certain channel and n>0, the parameters of the configuration item AlwaysToRingingOnRingCntX for this channel will be covered. Refer to the Ringing Current on Analog Phone Line section in Chapter 1 for more information.

l The parameters set by this configuration item can also be configured by the function SsmSetFlag (with the parameter F_ChToRingingOnRingCnt);

l Format 1 is applicable to USB voice boxes with analog trunk;

l Format 2 is applicable to 8-channel analog trunk boards;

l Format 3 is applicable to 16-channel analog trunk boards.


3.1.2.22 Setting FSK Transceiver (CTI Series)


3.1.2.22.1 Setting Parameters for FSK Transceiver


3.1.2.22.1.1 FreqBit0

Refer to MdlAmp


3.1.2.22.1.2 FreqBit1

Refer to MdlAmp


3.1.2.22.1.3 Baudrate

Refer to MdlAmp


3.1.2.22.1.4 MdlAmp
Configuration Item | FreqBit0 FreqBit1 Baudrate MdlAmp
Section | [FskConfig]
Written Format | FreqBit0=f0 FreqBit1=f1 Baudrate=k MdlAmp=a
Value Range | f0: The carrier frequency of Bit 0 (Hz), 300≤f0≤3400, with the default value of 2200Hz. f1: The carrier frequency of Bit 1 (Hz), 300≤f1≤3400, with the default value of 1200Hz. k: The baud rate (bps), 300≤k≤2400, with the default value of 1200bps. a: The signal amplitude, 0≤n≤255, with the default value of 128.
Description | FreqBit0 and FreqBit1 are respectively used to set the carrier frequency of Bit 0 and Bit 1; Baudrate sets the baud rate while MdlAmp configures the modulating-signal amplitude. Regarding the FSK Transceiver, see the FSK Transceiver section in Chapter 1 for more information.


3.1.2.23 Setting FSK Transceiver (CTI Series)


3.1.2.23.1 FskMarkSignal
Configuration Item | FskMarkSignal
Section | [BoardId=x]
Written Format | Format 1: FskMarkSignal=m0,m1,m2,m3,m4,m5,m6,m7 Format 2: FskMarkSignal=m0,m1,m2,m3,m4,m5,m6,m7,m8,m9,m10,m11,m12,m13,m14,m15 Format 3: FskMarkSignal=m
Value Range | m, mi: The number of digits in the identification code (The subscript i represents the physical channel number). =0: The identification code is composed of twelve 1s; =1: The identification code is composed of eight 1s.
Description | Sets the format of the identification code in the FSK data stream.
Note | l Format 1, Format 2 are respectively applicable to 8-channel and 16-channel SHT Series; l Format 3 is applicable to the SHD Series boards.


3.1.2.23.2 FskFrameMode
Configuration Item | FskFrameMode
Section | [BoardId=x]
Written Format | FskFrameMode=m
Value Range | m=0: Use the format ‘flag code+data frame’; m=1:Use the format ‘Sync code+flag code+data frame’ (default). For more information, refer to Section FSK Receiver in Chapter 1.
Description | Sets the frame format mode that accepted by the FSK receiver.
Note | l It is only applicable to SHD Series (except D-type boards).


3.1.2.23.3 FskEchoCancelDelay
Configuration Item | FskEchoCancelDelay
Section | [BoardId=x]
Written Format | Format 1: FskEchoCancelDelay=b0,b1,b2,b3,b4,b5,b6,b7,b8,b9,b10,b11,b12,b13,b14,b15 Format 2: FskEchoCancelDelay=b0,b1,b2,b3,b4,b5,b6,b7
Value Range | bi=0: Disable; bi=1: Enable (default). Note: The subscript i represents the physical channel number
Description | Sets whether to disable the echo canceller when the FSK transceiver is working.
Note | l Format1, Format2 are respectively applicable to 8-channel and 16-channel SHT Series; l When the FSK transceiver is enabled on the channel, if this configuration item is set to 1, the echo canceller will be disabled compulsorily; otherwise, the status of the echo canceller is determined by the configuration item EnableEchoCancellor; l This configuration item requires SynCTI Ver4.5.6.2 or above; l The same purpose can be achieved by the function SsmSetFlag (with the parameter F_EchoCancelInFsk).


3.1.2.24 Setting Parameters for Fax Channel


3.1.2.24.1 MaxSpeed
Configuration Item | MaxSpeed
Section | [Fax]
Written Format | MaxSpeed=k
Value Range | k: The faxing rate (bps). It can be set to 4800, 9600 or 14400. The default value is 9600.
Description | Sets the maximum faxing rate used in receiving or transmitting faxes.


3.1.2.24.2 RcvDisTime
Configuration Item | RcvDisTime
Section | [Fax]
Written Format | RcvDisTime=n
Value Range | 0≤n≤10, with the default value of 4.
Description | This configuration item is used to set the times to repeat the Dis detection in case the Dis signal is undetected or invalid during the faxing process. It is supported by SynCTI Ver. 4.7.2.0.
Note | This configuration item requires SynCTI Ver. 4.7.2.0 or above.


3.1.2.24.3 ResendForRTN
Configuration Item | ResendForRTN
Section | [Fax]
Written Format | ResendForRTN=k
Value Range | k: 0 not resend the page data upon the reception of an RTN message (default); k:1 resend the page data upon the reception of an RTN message.
Description | Sets whether to resend the page data upon the reception of an RTN message.


3.1.2.24.4 ResetRcvForRTN

Configuration Item

ResetRcvForRTN

Section

[Fax]

Written Format

ResetRcvForRTN =k

Value Range

k: 0 send an RTN message upon the reception of pages with incomplete and/or incorrect fax data (default);

k: 1 hang up the phone directly instead of sending an RTN message upon the reception of pages with incomplete and/or incorrect fax data.

Description

Determines whether to send an RTN message or hang up the phone immediately upon the reception of pages with incomplete and/or incorrect fax data.


3.1.2.24.5 KeepPageForRTN
Configuration Item | KeepPageForRTN
Section | [Fax]
Written Format | KeepPageForRTN =k
Value Range | k: 0 not keep the received pages with incomplete and/or incorrect fax data; k: 1 keep the received pages with incomplete and/or incorrect fax data (default).
Description | Dedermines whether to keep the received pages with incomplete and/or incorrect fax data.


3.1.2.24.6 PercentageForRTN
Configuration Item | PercentageForRTN
Section | [Fax]
Written Format | PercentageForRTN =n
Value Range | 0≤n≤100, with the default value of 30.
Description | If the percentage received is greater than the value of this configuration item, the page is considered to be with incomplete and/or incorrect fax data; otherwise, it is regarded as the one reaching the standard.


3.1.2.25 Setting Voltage Detector


3.1.2.25.1 Ignoring Detected Result of Voltage Detector


3.1.2.25.1.1 IgnoreLineVoltage
Configuration Item | IgnoreLineVoltage
Section | [BoardId=x]
Written Format | Format 1: IgnoreLineVoltage=b,b,b,b Format 2: IgnoreLineVoltage=b,b,b,b,b,b,b,b Format 3: IgnoreLineVoltage=b,b,b,b,b,b,b,b,b,b,b,b,b,b,b,b
Value Range | b=0: No (default); b=1: Yes.
Description | Sets whether to ignore the on-line voltage detected result. Refer to the Change in Analog Phone Line Voltage section in Chapter 1 for details.
Note | l This configuration item is only applicable to the recording channel on the ATP Series boards (including the analog recording module and the microphone module); l Format 1 is applicable to the ATP Series USB recording boxes; l Format 2 is applicable to the 8-channel ATP Series; l Format 3 is applicable to the 16-channel ATP Series.
Related Function | SsmSetIgnoreLineVoltage


3.1.2.25.2 Setting Voltage Threshold for Ring Detection


3.1.2.25.2.1 JudgeLineVoltage
Configuration Item | JudgeLineVoltage
Section | [SystemConfig]
Written Format | JudgeLineVoltage=k
Value Range | 0<k<256: The difference between the line voltage when ringing and that when idle, calculated by Volt (V), with the default value of 15V.
Description | Set the voltage threshold value for different rings on the analog line.
Note | l This configuration item is only applicable to the recording channel on the ATP/SHT Series boards (including the analog recording module and the trunk module).


3.1.2.25.3 Setting Judgement on Pickup/Hangup


3.1.2.25.3.1 IsHangupDtrmVoltage
Configuration Item | IsHangupDtrmVoltage
Section | [BoardId=x]
Written Format | Format 1: IsHangupDtrmVoltage=k,k,k,k Format 2: IsHangupDtrmVoltage=k,k,k,k,k,k,k,k Format 3: IsHangupDtrmVoltage=k,k,k,k,k,k,k,k,k,k,k,k,k,k,k,k
Value Range | k: The judging voltage (V), with the default value of 26V.
Description | Set the voltage used to judge the pickup/hangup behavior of the recording channel on the ATP Series boards. Refer to the Change in Analog Phone Line Voltage section in Chapter 1 for details.
Note | l This configuration item is only applicable to the recording channel on the ATP Series boards (including the analog recording module and the microphone module); l Format 1 is applicable to the ATP Series USB recording boxes; l Format 2 is applicable to the 8-channel ATP Series; l Format 3 is applicable to the 16-channel ATP Series.
Related Function | SsmSetDtrmLineVoltage


3.1.2.25.3.2 LineOncnt
Configuration Item | LineOncnt
Section | [SystemConfig]
Written Format | LineOncnt=t
Value Range | t: The minimum value is one time, 1≤t≤65536, each time equals to 8ms; the default value is 25 times (i.e. 200ms).
Description | Only if the line voltage meets the set voltage for judging the pickup behavior and lasts for the minimum duration specified by this configuration item will the driver confirm the pickup behavior on the line. Refer to the Change in Analog Phone Line Voltage section in Chapter 1 for more information.
Note | l This configuration item is only applicable to the recording channel on the ATP or SHT Series boards; l It requires SynCTI Ver. 4.7.2.0 or above.


3.1.2.25.4 Setting Off-line Detection


3.1.2.25.4.1 OffLineSet
Configuration Item | OffLineSet
Section | [SystemConfig]
Written Format | OffLineSet=k
Value Range | k: The threshold voltage value (V), which is two times the actual voltage value. The default value is 5, which corresponds to the actual voltage of 2.5V.
Description | Sets the threshold voltage value for judging the disconnection of the analog phone line. Refer to the Change in Analog Phone Line Voltage section in Chapter 1 for details.
Note | This configuration item is only applicable to the analog trunk recording channel.


3.1.2.25.4.2 OffLineDetermineTime
Configuration Item | OffLineDetermineTime
Section | [SystemConfig]
Written Format | OffLineDetermineTime=t
Value Range | t: The minimum duration, calculated by millisecond (ms), with the default value of 200.
Description | Sets the minimum duration for judging the disconnection of the analog phone line. Refer to the Change in Analog Phone Line Voltage section in Chapter 1 for details.
Note | This configuration item is only applicable to the recording channel on the ATP Series boards and the analog trunk channel on the SHT Series boards.


3.1.2.25.5 Setting Effect of Polarity Reversal Signal


3.1.2.25.5.1 DisablePolarReverse
Configuration Item | DisablePolarReverse
Section | [BoardId=x]
Written Format | Format 1: DisablePolarReverse=b,b,b,b Format 2: DisablePolarReverse=b,b,b,b,b,b,b,b Format 3: DisablePolarReverse=b,b,b,b,b,b,b,b,b,b,b,b,b,b,b,b Format 4: DisablePolarReverse= [0,29]:b
Value Range | b=0: Affect (default); b=1: Not affect
Description | Sets whether the polarity reversal signal affects the channel state transition. Refer to the Change in Analog Phone Line Voltage section in Chapter 1 for details.
Note | l This configuration item is only applicable to the analog trunk channel on the SHT Series boards; l Format 1 is applicable to the SHT Series USB recording boxes; l Format 2 is applicable to the 8-channel SHT Series; l Format 3 is applicable to the 16-channel SHT Series; l Format 4 is applicable to the 30-channel channel bank.


3.1.2.25.6 Setting Threshold Voltage to Ignore Interfering Signal


3.1.2.25.6.1 PolarIgnore
Configuration Item | PolarIgnore
Section | [BoardId=x]
Written Format | PolarIgnore =b
Value Range | b>=0, with the default value of 0.
Description | Sets a threshold voltage to ignore interfering signals on a line lest they are mistaken by the driver for polarity reversal signals. To be exact, when PolarIgnore=b, all signals with voltage values less than or equal to b will be ignored, that is, not be regarded as polarity reversal signals. Refer to the Change in Analog Phone Line Voltage section in Chapter 1 for details.
Note | This configuration item is applicable to analog trunk channels on the SHT Series boards and analog recording channels on the ATP Series boards.


3.1.2.26 Setting Speaker of USB Recording/voice Box


3.1.2.26.1 USBLine0Output
Configuration Item | USBLine0Output
Section | [BoardId=x]
Written Format | USBLine0Output=m
Value Range | m=0: Send the voice to the on-board speaker for play; m=1: Send the voice to the external speaker for play via the on-board speaker output jack
Description | Enable or disable the on-board speaker in the USB recording/voice box. See the Operation Principle of ATP Series or Operation Principle of SHT Series section in Chapter 1 for more information.
Note | l This configuration item is only applicable to the ATP Series USB recording boxes and the SHT Series USB voice boxes; l It requires SynCTI Ver. 4.7.1.7 or above.


3.1.2.27 Common Configuration Item for SHT Series (CTI Series)


3.1.2.27.1 Special Configuration Item for Analog Trunk Channel


3.1.2.27.1.1 Setting Analog Trunk Channel to Be Recording Channel


3.1.2.27.1.1.1 SetAnalogChToRecCh

Configuration Item | SetAnalogChToRecCh
Section | [Boardid=x]
Written Format | Format 1: SetAnalogChToRecCh =b,b,b,b Format 2: SetAnalogChToRecCh =b,b,b,b,b,b,b,b Format 3: SetAnalogChToRecCh =b,b,b,b,b,b,b,b,b,b,b,b,b,b,b,b
Value Range | b=1: Channel open, working as a recording channel; b=0: Channel closed (default), this configuration item being invalid.
Description | Mandatorily sets the analog trunk channel to be a recording channel
Note | l This configuration item is only effective to SynCTI 5.0.1.0 or above versions; l This configuration item is only applicable to the analog trunk channel, including SHT Series boards with analog trunk modules and USB voice boxes; l Format 1 is applicable to the SHT Series USB voice boxes; l Format 2 is applicable to the 8-channel SHT Series; l Format 3 is applicable to the 16-channel SHT Series.


3.1.2.27.1.2 Setting Parameters for Outgoing Call


3.1.2.27.1.2.1 MaxWaitDialToneTime

Configuration Item

MaxWaitDialToneTime

Section

[SystemConfig]

Written Format

MaxWaitDialToneTime=t

Value Range

t: The maximum waiting time, calculated by millisecond (ms), 0≤t≤30, with the default value of 3ms.

Description

Sets the maximum time to wait for the dial tone.

The driver should detect the dial tone first after the application invokes the function SsmAutoDial to start the AutoDial task. If the dial tone can not be detected within the time specified by this configuration item, the AutoDial task fails.

See the Analog Trunk Channel State Machine section in Chapter 1 for more information about the AutoDial task.

Note

This configuration item is only applicable to the analog trunk channel.


3.1.2.27.2 Setting Flash Signal and Duration


3.1.2.27.2.1 DefaultTxFlashChar
Configuration Item | DefaultTxFlashChar
Section | [SystemConfig]
Written Format | DefaultTxFlashChar =s
Value Range | s: The character used to represent the flash, with the default value of ‘!’, not allowed to be standard DTMF digits or ‘?’.
Description | Sets the character to represent the flash. A flash signal will be sent upon this character being put into the function SsmTxDtmf.


3.1.2.27.2.2 DefaultTxFlashTime
Configuration Item | DefaultTxFlashTime
Section | [SystemConfig]
Written Format | DefaultTxFlashTime=t
Value Range | 32£t£1000, calculated by millisecond (ms), with the default value of 500.
Description | Sets the duration of the flash signal generated on the analog trunk via the function call of SsmTxDtmf where the character ‘!’ is used as a parameter. Refer to the Generating Flash Signal on Analog Line section in Chapter 1 for more information.


3.1.2.27.2.3 Remote Pickup Detector


3.1.2.27.2.3.1 Setting Parameters for Ordinary Remote Pickup Detector


3.1.2.27.2.3.1.1 WaitAfterDialTime

Configuration Item | WaitAfterDialTime
Section | [SystemConfig]
Written Format | WaitAfterDialTime=t
Value Range | t: The maximum waiting time, calculated by millisecond (ms), 16≤t≤60000, with the default value of 18000.
Description | After the function SsmAutoDial is invoked on the analog trunk channel, the driver will throw out the E_CHG_ToneAnalyze event (with the parameter CHKTONE_NOVOICE) if it neither detects ringback tones on the line following the transmission of the complete called party number to the remote PBX, nor detects voice activities within the time specified by this configuration item. See the Ordinary Remote Pickup Detector section in Chapter 1 for more information.
Note | This configuration item is only applicable to the analog trunk channel on the SHT Series boards.


3.1.2.27.2.3.1.2 MaxWaitVocAfterEcho

Configuration Item | MaxWaitVocAfterEcho
Section | [SystemConfig]
Written Format | MaxWaitVocAfterEcho=t
Value Range | t: The maximum waiting time, calculated by millisecond (ms), with the default value of 10.
Description | After the function SsmAutoDial is invoked on the analog trunk channel, the driver will throw out the E_CHG_ToneAnalyze event (with the parameter CHKTONE_ECHO_NOVOICE) if it detects ringback tones on the line following the transmission of the complete called party number to the remote PBX, but does not detect any voice activity within the time specified by this configuration item. See the Ordinary Remote Pickup Detector section in Chapter 1 for more information.
Note | This configuration item is only applicable to the analog trunk channel on the SHT Series boards.


3.1.2.27.2.3.1.3 VoiceOnDetermineTime

Configuration Item | VoiceOnDetermineTime
Section | [SystemConfig]
Written Format | VoiceOnDetermineTime=t
Value Range | 16≤t≤1024 and must be the multiple of 16, calculated by millisecond (ms), with the default value of 96ms.
Description | Sets the minimum duration of voice activities. Only if continuous voice activities occur on the line and last for a period of time longer than the preset value of this configuration item will the driver confirm there are real voice activities available on the line. See the Ordinary Remote Pickup Detector section in Chapter 1 for more information.
Note | This configuration item is only applicable to the analog trunk channel on the SHT Series boards.


3.1.2.27.2.3.1.4 EchoNoVoiceToTalking

Configuration Item | EchoNoVoiceToTalking
Section | [SystemConfig]
Written Format | EchoNoVoiceToTalking=N
Value Range | N=0: Disabled (default); N=1: Enabled.
Description | When the pickup pulse on the line following ringback tones is very small or approaching zero, the event ‘no voice after ringback’ will be thrown out. Setting this configuration at the time the event ‘no voice after ringback’ is generated can make the channel go into the talking state automatically. It is applicable to some particular occasions. For more information, see the Ordinary Remote Pickup Detector section in Chapter 1.
Note | This configuration item is only applicable to the analog trunk channel on the SHT Series boards.


3.1.2.27.2.3.2 Setting Parameters for Enhanced Remote Pickup Detector


3.1.2.27.2.3.2.1 RelativeEngyHookDetect

Configuration Item

RelativeEngyHookDetect

Section

[SystemConfig]

Written Format

RelativeEngyHookDetect=b

Value Range

b=0: Disable

b=1: Enable (default)

Description

Sets the operating mode of the enhanced remote pickup detector on the analog trunk channel. Refer to the Enhanced Remote Pickup Detector section in Chapter 1 for more information.

Note

l This configuration item is only applicable to the analog trunk channel on the SHT Series boards and requires SynCTI Ver. 3.5.2.4 or above;

l The same purpose can be achieved via the function call of SsmSetFlag (with the parameter F_RELATIVEENGYHOOKDETECT).


3.1.2.27.2.3.2.2 HookEngyConfigMulti

Refer to HookValidEngyCnt


3.1.2.27.2.3.2.3 HookValidEngyCnt

Configuration Item

HookEngyConfigMulti

HookValidEngyCnt

Section

[SystemConfig]

Written Format

HookEngyConfigMulti=k

HookValidEngyCnt=t

Value Range

k: The sensitivity, 2≤k≤65535, with the default value of 6. The greater the value is, the less sensitive, which means the increased miss detection rate and the decreased false detection rate.

t: The minimum duration, 32≤t≤65535, calculated by millisecond (ms), which has to be the multiple of 16, with the default value of 48ms. The greater the value is, the less sensitive, which means the increased miss detection rate and the decreased false detection rate.

Description

Sets the parameters for the enhanced remote pickup detector on the analog trunk channel. HookEngyConfigMulti sets the sensitivity of the pickup detection while HookValidEngyCnt configures the minimum duration to eliminate the interference of the signal dithering on the detected result. Only when the driver detects an instantaneous pickup behavior which lasts for a time equal to or longer than t will it conclude there is a real pickup behavior performed on the line.

Refer to the Enhanced Remote Pickup Detector section in Chapter 1 for more information.

Note

l This configuration item is only applicable to the analog trunk channel on the SHT Series boards, being valid only when the configuration item RelativeEngyHookDetect is set to 1;

l It requires SynCTI Ver. 3.5.2.4 or above.


3.1.2.27.3 Special Configuration Item for Station Channel


3.1.2.27.3.1 AutoSendDialTone

Configuration Item

AutoSendDialTone

Section

[BoardId=x]

Written Format

Format 1: AutoSendDialTone=b,b,b,b

Format 2: AutoSendDialTone=b,b,b,b,b,b,b,b

Format 3: AutoSendDialTone=b,b,b,b,b,b,b,b,b,b,b,b,b,b,b,b

Format 4: AutoSendDialTone=[S1,E1]:b+…+ [Sm,Em]:b

Value Range

b=1: Enable;

b=0: Disable (default).

S1: The start channel number, with the default value of 0.

E1: The end channel number, the default value being the total number of on-board channels.

m: The number of parameter fields, being equal to or greater than 1 but not exceeding the total number of on-board channels.

Description

Sets whether the dial tone is automatically sent by the driver upon detecting the pickup behavior of the phone connected to the station channel.

Note

l This configuration item is only applicable to the station channel, including the SHT Series boards equipped with the station module and the SHD Series boards connected to the channel bank;

l Format 1 is applicable to the SHT Series USB voice boxes;

l Format 2 is applicable to the 8-channel SHT Series;

l Format 3 is applicable to the 16-channel SHT Series;

l Format 4 is applicable to the SHD Series boards connected to the channel bank. See the Connection to Channel Bank section in Chapter 1 for more information.

Example

When the SHD-30A-CT/PCI/SS1 board is connected to the channel bank, you can follow the configuration below to enable this feature for the first 15 on-board channels and disable this feature for the last 15 channels.

AutoSendDialTone=[0,14]:1+[15,29]:0

If this feature is enabled for all 30 on-board channels, you can configure as follows.

AutoSendDialTone=[0, 29]:1


3.1.2.27.3.2 StopSendDialToneOnDtmf

Configuration Item

StopSendDialToneOnDtmf

Section

[BoardId=x]

Written Format

Format 1: StopSendDialToneOnDtmf=b,b,b,b

Format 2: StopSendDialToneOnDtmf=b,b,b,b,b,b,b,b

Format 3: StopSendDialToneOnDtmf=b,b,b,b,b,b,b,b,b,b,b,b,b,b,b,b

Format 4: StopSendDialToneOnDtmf =[S1,E1]:b+…+ [Sm,Em]:b

Value Range

b=1: Enable;

b=0: Disable (default)

S1: The start channel number, with the default value of 0.

E1: The end channel number, the default value being the total number of on-board channels.

m: The number of parameter fields, being equal to or greater than 1 but not exceeding the total number of on-board channels.

Description

This configuration item is used to set whether to enable the feature of ‘auto-stop of dial tone transmission by driver’ upon the driver’s detection of DTMF digits in sending tones to the phone.

Note

l This configuration item is only applicable to the station channel, including the SHT Series boards equipped with the station module and the SHD Series boards connected to the channel bank;

l Format 1 is applicable to the SHT Series USB voice box;

l Format 2 is applicable to the SHT Series 8-channel boards;

l Format 3 is applicable to the SHT Series 16-channel boards;

l Format 4 is applicable to the SHD Series boards connected to the channel bank. Refer to the Connection to Channel Bank section in Chapter 1 for more information. See the example given in the configuration item AutoSendDialTone for reference.


3.1.2.27.3.3 MaxLocalFlashTime
Configuration Item | MaxLocalFlashTime
Section | [SystemConfig]
Written Format | MaxLocalFlashTime=t
Value Range | 32£t£2000, calculated by millisecond (ms), with the default value of 700.
Description | Sets the maximum duration for judging the flash signal.
Note | This configuration item is only applicable to the station channel.


3.1.2.27.3.4 UserOnHookFilterTime

Configuration Item

UserOnHookFilterTime

Section

[BoardID=x]

Written Format

Format 1: UserOnHookFilterTime=t,t,t,t

Format 2: UserOnHookFilterTime=t,t,t,t,t,t,t,t

Format 3: UserOnHookFilterTime=t,t,t,t,t,t,t,t,t,t,t,t,t,t,t,t

Format 4: UserOnHookFilterTime =[S1,E1]:t+…+ [Sm,Em]:t

Value Range

t: The minimum duration of the pickup signal, calculated by millisecond (ms), which has to be the multiple of 16. The less the value is, the more sensitive. The default value is 64ms.

S1: The start channel number, with the default value of 0.

E1: The end channel number, the default value being the total number of on-board channels.

m: The number of parameter fields, being equal to or greater than 1 but not exceeding the total number of on-board channels.

Description

Sets the minimum duration of the pickup signal.

Note

l This configuration item is only applicable to the station channel, including the SHT Series boards equipped with the station module and the SHD Series boards connected to the channel bank;

l Format 1 is applicable to the SHT Series USB voice boxes;

l Format 2 is applicable to the 8-channel SHT Series;

l Format 3 is applicable to the 16-channel SHT Series;

l Format 4 is applicable to the SHD Series boards connected to the channel bank. Refer to the Connection to Channel Bank section in Chapter 1 for more information. See the example given in the configuration item AutoSendDialTone for reference.

l Usually there is no need to reconfigure this item as its default value is adequate for most application instances.


3.1.2.27.3.5 UserChGenerateRingMode
Configuration Item | UserChGenerateRingMode
Section | [BoardId=x]
Written Format | UserChGenerateRingMode=m
Value Range | m=0: 1sec on and 4sec off (default); m=1: Always at on state until the application sends the stop command.
Description | Sets the way how the station channel or the magnet channel generates the ringing signal.


3.1.2.27.3.6 UserSendPolar
Configuration Item | UserSendPolar
Section | [BoardId=x]
Written Format | Format 1: UserSendPolar=b,b,b,b Format 2: UserSendPolar=b,b,b,b,b,b,b,b Format 3: UserSendPolar=b,b,b,b,b,b,b,b,b,b,b,b,b,b,b,b
Value Range | b=0: No (default); b=1: Yes.
Description | Sets whether the station channel has the capability of generating the polarity reversal signal. Refer to the ‘Generating Polarity Reversal Signal on Phone Line’ section in Chapter 1 for more information.
Note | l This configuration item is only applicable to the station channel on the SHT Series boards; l Format 1 is applicable to the SHT Series USB voice boxes; l Format 2 is applicable to the 8-channel SHT Series; l Format 3 is applicable to the 16-channel SHT Series.


3.1.2.27.4 Special Configuration Item for Fax Channel


3.1.2.27.4.1 MaxFaxChannel
Configuration Item | MaxFaxChannel
Section | [BoardId=x]
Written Format | MaxFaxChannel=n
Value Range | Both the range of value and the default value depend on the board model. See the Setting Number of Fax Channels section in Chapter 1 for more information.
Description | Sets the total number of fax channels.


3.1.2.27.4.2 DSP3WORKMODE
Configuration Item | DSP3WORKMODE
Section | [BoardId=x]
Written Format | DSP3WORKMODE=n
Value Range | n=1: For SHT-16B-CT/PCI/FAX, enable this board to have faxing capability (default); n=2: For SHT-16B-CT/PCI/FAX, enable this board to support GSM recording in hardware; n=3: For SHT-16B-CT/PCI/MP3 and SHT-16B-CT/cPCI/MP3, enable them to support MP3 recording in hardware.
Description | For the SHT-16B-CT/PCI/FAX board, this configuration item is used to enable the capability of faxing or GSM recording in hardware; for the SHT-16B-CT/PCI/MP3 and SHT-16B-CT/cPCI/MP3 boards, this configuration item is used to enable the capability of MP3 recording in hardware. See the Brief Introduction of SHT Series section in Chapter 1 for more information.
Note | The board model of SHT-16B-CT/PCI/MP3 displayed by configuration tools is SHT-16B-CT/PCI/FAX. Therefore, don’t forget to configure DSP3WORDMODE=3 when you are using the SHT-16B-CT/PCI/MP3 board.


3.1.2.27.5 Special Configuration Item for Composite Module


3.1.2.27.5.1 UnimoduleState
Configuration Item | UnimoduleState
Section | [BoardId=x]
Written Format | Format 1: UnimoduleState=b,b,b,b Format 2: UnimoduleState=b,b,b,b,b,b,b,b Format 3: UnimoduleState=b,b,b,b,b,b,b,b,b,b,b,b,b,b,b,b
Value Range | b=0: Yes; b=1: No(default).
Description | Sets whether to connect the analog trunk channel on the composite module directly to the station channel.
Note | l Format 1 is applicable to the SHT Series USB voice boxes; l Format 2 is applicable to the 8-channel SHT Series; l Format 3 is applicable to the 16-channel SHT Series.


3.1.2.27.6 Special Configuration Item for Non-module channel


3.1.2.27.6.1 NoModuleChBusRec
Configuration Item | NoModuleChBusRec
Section | [BoardId=x]
Written Format | Format 1: NoModuleChBusRec=b,b,b,b Format 2: NoModuleChBusRec=b,b,b,b,b,b,b,b Format 3: NoModuleChBusRec=b,b,b,b,b,b,b,b,b,b,b,b,b,b,b,b
Value Range | b=0: Disable (default); b=1: Enable.
Description | Sets whether to input the voice signals (not the incoming signals) which come from the bus to the Barge-in Detector. See the Non-module Channel section in Chapter 1 for more information.
Note | l Format 1 is applicable to the SHT Series USB voice boxes; l Format 2 is applicable to the 8-channel SHT Series; l Format 3 is applicable to the 16-channel SHT Series.


3.1.2.27.7 Magnet Channel


3.1.2.27.7.1 IsMagnetModule
Configuration Item | IsMagnetModule
Section | [BoardId=x]
Written Format | Format 1: IsMagnetModule=b,b,b,b Format 2: IsMagnetModule=b,b,b,b,b,b,b,b Format 3: IsMagnetModule=b,b,b,b,b,b,b,b,b,b,b,b,b,b,b,b
Value Range | b=0: Analog trunk module (default); b=1: Magnet Module
Description | Determines whether it is the analog trunk module or the magnet module being fixed on the SHT Series board. See the Magnet Channel section in Chapter 1 for more information. Magnet Channel
Note | l Format 1 is applicable to the SHT Series USB voice boxes; l Format 2 is applicable to the 8-channel SHT Series; l Format 3 is applicable to the 16-channel SHT Series.


3.1.2.28 Common Configuration Item for SHD Series (CTI Series)


3.1.2.28.1 Setting Number-receiving Rule for Incoming Call


3.1.2.28.1.1 DefaultRcvPhoNumLen

Refer to RcvPhoNumCfgLen


3.1.2.28.1.2 DefaultRcvCallerID

Refer to RcvPhoNumCfgLen


3.1.2.28.1.3 RcvPhoNumCfgLen

Configuration Item

DefaultRcvPhoNumLen

DefaultRcvCallerID

RcvPhoNumCfgLen

Section

[TUP] / [ISUP] / [ISDN] / [SS1Config]

Written Format

DefaultRcvPhoNumLen=n

DefaultRcvCallerID=m

RcvPhoNumCfgLen=b

Value Range

n: The way to receive the number.

n=0: Prefix Mode. The configuration items MaxPhoNumRule and Rule are used to set particular rules in this mode.

1£n£40: Fixed-length Mode. n is the length of the called party number. Receiving all the n digits of the called party number in the incoming call puts the local end’s number reception into an end. At this time, the configuration items DefaultRcvCallerID and RcvPhoNumCfgLen are valid.

The default value of n is 0.

m: Determines whether it is necessary to receive the calling party number

m=0: Not necessary (default);

m=1: Necessary.

b: The way to save the called party number.

b=0: Save all the received digits of the called party number (default);

b=1: Only save some digits first received. The number of digits to be saved is specified by DefaultRcvPhoNumLen. The remaining digits received are all discarded.

Description

DefaultRcvPhoNumLen sets the way to receive the number in an incoming call;

DefaultRcvCallerID determines whether it is necessary to receive the calling party number;

RcvPhoNumCfgLen sets the way for the driver to save the received called party number to its internal buffer.

Note

l The configuration item DefaultRcvCallerID becomes valid only when the configuration item DefaultRcvPhoNumLen is set to Fixed-length Mode.

l RcvPhoNumCfgLen is only applicable to the TUP channel;

l This configuration item is only applicable to TUP, ISUP, ISDN, SS1 channels;

l The SS1 channel uses the configuration section [SS1Config];

l The ISUP channel uses the configuration section [ISUP];

l The TUP channel uses the configuration section [TUP];

l The ISDN channel uses the configuration section [ISDN]. For the ISDN channel, the number receiving rule set by this configuration item will be ignored if the driver works in the Tandem Exchange mode. Refer to the Terminating Office Mode vs. Tandem Exchange Mode section in Chapter 1 for more information.


3.1.2.28.1.4 MaxPhoNumRule

Refer to Rule


3.1.2.28.1.5 Rule

Configuration Item

MaxPhoNumRule

Rule

Section

[TUP] / [ISUP] / [ISDN] / [SS1Config]

Written Format

MaxPhoNumRule=N

Format 1: Rule[i]="a…x",n,f,y,z

Format 2: Rule[i]="a…x",n,f,y

Format 3: Rule[i]="a…x",n,f

Value Range

N: The times to set the number receiving rule. This configuration item is not required to be set if the set value of DefaultRcvPhoNumLen is greater than 0; otherwise, N must be set greater than 0 and the configuration item Rule should be set for N times, beginning with i=0. The default value of N is 0.

I : The rule number, numbered from 0, 0 £ i < N

‘a…x’: The string of the prefix, such as ‘114’, ‘127’, etc.

n: The set length for receiving the prefix string. n must be greater than or equal to the actual length of the prefix string. Except for SS1 and ISDN channels, this parameter gets valid only when y is set to 0.

f: Determines whether it is necessary to receive the calling party number

=1: Necessary;

=0: Not necessary.

y: Determines whether the length of the phone number is fixed.

=1: Not fixed. The parameters n and z are invalid. The driver will ask the application to control the number receiving process upon reception of the office number. After receiving the complete call number, the application can invoke the function SsmSetKB to refuse or accept the incoming call, and then asks the driver to control the process again.

=0: Fixed (default). The parameters n and z are valid.

z: The way to save the called party number.

z=0: Save all the received digits of the called party number (default);

z=1: Only save some digits first received. The number of digits to be saved is determined by n. The remaining digits received are all discarded.

Description

MaxPhoNumRule is used to specify the times to set the number receiving rule;

Rule is used to set details of the number receiving rule. Format 1 is only applicable to the TUP channel; Format 2 is only applicable to TUP and ISUP channels; Format 3 is applicable to SS1 and ISDN channels.

Note

l This configuration item becomes valid only when DefaultRcvPhoNumLen is set to Prefix Mode;

l This configuration item is only applicable to TUP, ISUP, ISDN, SS1 channels;

l The SS1 channel uses the configuration section [SS1Config];

l The ISUP channel uses the configuration section [ISUP];

l The TUP channel uses the configuration section [TUP];

l The ISDN channel uses the configuration section [ISDN]. For the ISDN channel, the number receiving rule set by this configuration item will be ignored if the driver works in the Tandem Exchange mode. Refer to the Terminating Office Mode vs. Tandem Exchange Mode section in Chapter 1 for more information.


3.1.2.28.1.6 MfcLenCtrlPos

Refer to CallerIdEnTable


3.1.2.28.1.7 MfcLengthTable

Refer to CallerIdEnTable


3.1.2.28.1.8 CallerIdEnTable

Configuration Item

MfcLenCtrlPos

MfcLengthTable

CallerIdEnTable

Section

[SS1Config]

Written Format

MfcLenCtrlPos=n

MfcLengthTable=m,m,m,m,m,m,m,m,m,m

CallerIdEnTable=b,b,b,b,b,b,b,b,b,b

Value Range

n: The length control bit taken as the index for receiving the called party number, n≥1;

m: The length of the called party number to be received;

b: Determines whether it is necessary to receive the calling party number

=1: Necessary;

=0: Not necessary.

Description

MfcLenCtrlPos sets the length control bit for receiving the called party number on the trunk channel;

MfcLengthTable sets the index of the length control bit for MFC number receiving on the trunk channel;

CallerIdEnTable sets the table controlling whether to enable the trunk channel to receive the calling party number or not. The digit at the position MfcLenCtrlPos in the called party number can be taken as the index for searching the corresponding length in the length control table MfcLengthTable; also it can be taken as the index to check if the corresponding calling party number should be received in CallerIdEnTable.

Note

This configuration item is only applicable to the SS1 channel.


3.1.2.28.2 Setting ‘Auto-answer of Incoming Call’ Feature


3.1.2.28.2.1 AutoSendKB

Refer to NetSideAutoSendAck


3.1.2.28.2.2 AutoSendACM

Refer to NetSideAutoSendAck


3.1.2.28.2.3 UserSideAutoSendAck

Refer to NetSideAutoSendAck


3.1.2.28.2.4 NetSideAutoSendAck
Configuration Item | AutoSendKB AutoSendACM UserSideAutoSendAck NetSideAutoSendAck
Section | [SS1Config] / [TUP] / [ISUP] / [ISDN]
Written Format | AutoSendKB=b //use [SS1Config] AutoSendACM=b //use [TUP] or [ISUP] UserSideAutoSendAck=b //use [ISDN] NetSideAutoSendAck=b //use [ISDN]
Value Range | b=0: No; b=1: Yes (default).
Description | Sets whether to enable the ‘Auto-answer of Incoming Call’ feature or not. AutoSendKB is used to set the SS1 channel. Refer to the China SS1 State Machine section in Chapter 1 for more information. AutoSendACM is used to set ISUP and TUP channels. Refer to the ISUP Channel State Machine or TUP Channel State Machine section in Chapter 1 for more information. UserSideAutoSendAck is used to set the ISDN channel (user-side) while NetSideAutoSendAck is used to set the ISDN channel (network-side). Refer to the ISDN Channel State Machine section in Chapter 1 for more information about the k2 switch.
Note | The same purpose can be achieved via the function call of SsmEnableAutoSendKB.


3.1.2.28.3 Setting Calling Party Number for Outgoing Call


3.1.2.28.3.1 TxCallerId

Refer to CalloutCallerId


3.1.2.28.3.2 CalloutCallerId

Configuration Item

TxCallerId

CalloutCallerId

Section

[SS1Config] / [TUP] / [ISUP] / [ISDN]

Written Format

Format 1: TxCallerId=s

Format 2: TxCallerId[m]=s

Format 1: CalloutCallerId=s

Format 2: CalloutCallerId[m]=s

Value Range

s: The ASCII string storing the calling party number. The number of the characters is up to 20 for the ISDN channel, up to 15 for the TUP channel, and up to 50 for other channels. s has to be made up of the digits ’0’~’9’. Other types of characters will be ignored. It being empty indicates the calling party number will not be sent to the remote PBX in the outgoing call.

m: The logical number of the digital truck in the application. It starts from 0, the range of value: 0≤m<M (M is the set value of the configuration item TotalPcm).

The default value is empty.

Description

Sets the phone number of the local end, i.e. the calling party number, in the outgoing call.

TxCallerId is used to set the SS1 channel (using Section [SS1Config]); CalloutCallerId is used to set the ISUP channel (using Section [ISUP]), the TUP channel (using Section [TUP]) and the ISDN channel (using Section [ISDN]). Format 1 is used to set the global channels; Format 2 is used to set the channel with a specific PCM number.

Note

l Some PBXes using TUP and ISUP protocols requires the calling party number string sent by the calling party to contain the ST signal. The configuration item SetSTSignal can be used for this purpose.

l If Format 1 and Format 2 exist at the same time, Format 2 has the priority.


3.1.2.28.3.3 SetSTSignal
Configuration Item | SetSTSignal
Section | [TUP] / [ISUP]
Written Format | SetSTSignal=b
Value Range | b=0: No (default); b=1: Yes.
Description | Sets whether the calling party number string sent by the local end to the remote PBX contains the ST signal in the outgoing call.
Note | This configuration item is only applicable to TUP and ISUP channels, the ISUP channel using the configuration section [ISUP] while the TUP channel using [TUP].


3.1.2.28.4 Connecting to Channel Bank


3.1.2.28.4.1 UsageMode
Configuration Item | UsageMode
Section | [BoardId=x]
Written Format | UsageMode=b
Value Range | b=0: No (default); b=1: Yes.
Description | Sets whether to connect the SHD Series boards to the channel bank. See the Connection to Channel Bank section in Chapter 1 for details.
Note | This configuration item is only applicable to the following board models in the SHD Series. ü SHD-30A-CT/PCI/SS1 ü SHD-30A-CT/PCI/ISDN ü SHD-30A-CT/PCI/SS7 ü SHD-30A-CT/cPCI ü SHD-30B-CT/PCI/FAX ü SHD-60A-CT/PCI/SS1 ü SHD-60A-CT/PCI/ISDN ü SHD-60A-CT/PCI/SS7 ü SHD-60A-CT/cPCI ü SHD-60B-CT/PCI/SS7/FAX ü SHD-60B-CT/cPCI/FAX ü SHD-120A-CT/PCI/SS1 ü SHD-120A-CT/PCI/ISDN ü SHD-120A-CT/PCI/SS7 ü SHD-120A-CT/cPCI ü SHD-120D-CT/PCI/CAS ü SHD-240D-CT/PCI/CAS ü SHD-30E-CT/PCI(ssw) ü SHD-30E-CT/PCI/FAX(ssw) ü SHD-30E-CT/PCI/EC(ssw) ü SHD-60E-CT/PCI(ssw) ü SHD-60E-CT/PCI/FAX(ssw) ü SHD-60E-CT/PCI/EC(ssw) ü SHD-120E-CT/PCI(ssw) ü SHD-120E-CT/PCI/FAX(ssw) ü SHD-120E-CT/PCI/EC(ssw) ü SHD-240E-CT/PCI(ssw) ü SHD-240E-CT/PCI/FAX(ssw) SHD-240E-CT/PCI/EC(ssw)


3.1.2.28.4.2 CBProtocolType
Configuration Item | CBProtocolType
Section | [BoardId=x]
Written Format | CBProtocolType=m
Value Range | m=0: CCS; m=1: CAS (default).
Description | Sets the signaling mode used in connecting the SHD Series boards to the channel bank.
Note | This configuration item becomes valid only when the configuration item UsageMode is set to 1.


3.1.2.28.4.3 CBChannelType
Configuration Item | CBChannelType
Section | [BoardId=x]
Written Format | CBChannelType=m
Value Range | m=0: Not use this channel; m=1: Station channel (default); m=2: E/M channel.
Description | Sets the channel type used in connecting the SHD Series boards to the channel bank.
Note | This configuration item becomes valid only when the configuration item UsageMode is set to 1.


3.1.2.28.5 Setting Board Operating Mode


3.1.2.28.5.1 RunAsSpy
Configuration Item | RunAsSpy
Section | [BoardId=x]
Written Format | RunAsSpy =b
Value Range | b=0: Normal mode (default); b=1: Monitoring mode.
Description | Sets the operating mode for the SHD Series boards.
Note | l This configuration item is invalid to the signaling-monitoring board as it always works in the monitoring mode; l This configuration item is only applicable to A-type and C-type digital boards.


3.1.2.28.6 Advanced Setting for SS1


3.1.2.28.6.1 Selecting Country


3.1.2.28.6.1.1 mfcr2_Protocol

Configuration Item

mfcr2_Protocol

Section

[SS1Config]

Written Format

mfcr2_Protocol=s

Value Range

s is a string which is described below.

Value | Supported Country/Protocol
al | ALGERIA
ar | ARGENTINA
bh | BAHRAIN
bo | BOLIVIA
br | BRAZIL
cl | CHILE
cn | CHINA
co-land | COLOMBIA_LAND
co-cell | COLOMBIA_CELL
cz | CZECH
cd | DEMO_CONGO
eg | EGYPT
gn | GHANA
hd | HONDURAS
in | INDIA
id | INDONESIA
iq | IRAQ
itu | ITU
kr | KOREA
kw | KUWAIT
my | MALAYSIA
mx | MEXICO
ng | NIGERIA
pa | PANAMA
ph | PHILIPINNES
ro | ROMANIA
sa | SAUDI_ARABIA
sg | SINGAPORE
th | THAILAND
ve | VENEZUELA

The default value of s is cn.

Description

Sets the country to use SS1.

Note

This configuration item becomes valid only if the configuration item ProtocolType is set to 0;

This configuration item is also applicable to the SS1 channel for DTP series.


3.1.2.28.6.2 Setting R2 Parameters for SS1 Connection

When the value of mfcr2_Protocol is not cn (CHINA), the following configuraiton items can be used to set the R2 parameters for SS1 connection as the expansion of the SS1 MFC-R2 protocol variant.


3.1.2.28.6.2.1 tonesgroupA

Configuration Item | tonesgroupA
Section | [SS1Config]
Written Format | tonesgroupA=k
Value Range | k: Composed of 16 bits. Each hexade (4 bits) of the parameter contains one request. Low to high hexade: 1. Send next DID (bit0-3). 2. Send Group I category (bit4-7). 3. Send next ANI (bit8-11). 4. Send Group II tone (and switch to group B tone reception) (bit12-15).
Description | Sets backward Group A tones. The driver uses them to send requests to the calling party during the compelled sequence.
Note | This configuration item is only applicable to the SS1 channel on the SHD Series boards.
Example | If the MFC-R2 protocol defines that A1 sends next DID, A5 sends Group I category, A5 sends next ANI, A3 sends Group II tone (and switch to group B tone reception), it should be set tonesgroupA=0x3551.


3.1.2.28.6.2.2 tonesgroupB

Configuration Item | tonesgroupB
Section | [SS1Config]
Written Format | tonesgroupB=k
Value Range | k: Composed of 16 bits. Each hexade (4 bits) of the parameter contains one Group B indication. Low to high hexade: 1. Indicate congestion (bit0-3). 2. Indicate unallocated number (bit4-7). 3. Indicate busy (bit8-11). 4. Indicate line out of order (bit12-15).
Description | Sets some backward Group B tones. The driver uses them to send the final indication of the compelled sequence to the calling party.
Note | This configuration item is only applicable to the SS1 channel on the SHD Series boards.


3.1.2.28.6.2.3 Tonesendofinfo

Configuration Item

Tonesendofinfo

Section

[SS1Config]

Written Format

tonesendofinfo=k

Value Range

k: Composed of 16 bits. Every 4 bits constitute a hexade. Low to high hexade:

1. End of DID (bit0-3). In some countries, a tone that signals the end of the DID digits does not exist. In this case, the first hexade will be 0.

2. Spare (bit4-7).

3. End of ANI - caller ID available (bit8-11).

4. End of ANI - called ID restricted (bit12-15). In most countries, there is no distinction for MFC-R2 between restricted and non-restricted caller ID. In this case, the fourth hexade is 0.

Description

Sets forward tones that indicate the end or the non-availability of certain types of information.

Note

This configuration item is only applicable to the SS1 channel on the SHD Series boards.


3.1.2.28.6.2.4 Tonesanswer

Configuration Item | Tonesanswer
Section | [SS1Config]
Written Format | tonesanswer=k
Value Range | k: Composed of 16 bits. Each hexade (4 bits) of the parameter contains one distinct type of acceptance indication. Low to high hexade: 1. Call accepted in Group B - charge. 2. Call accepted in Group B – free call. 3. Call accepted in Group A. 4. Spare.
Description | Sets backward tones indicating acceptance of the call.
Note | This configuration item is only applicable to the SS1 channel on the SHD Series boards.


3.1.2.28.6.2.5 Tonesrepeatrequest

Configuration Item | Tonesrepeatrequest
Section | [SS1Config]
Written Format | tonesrepeatrequest=k
Value Range | k: Composed of 16 bits. Every 4 bits constitute a hexade. Consider the DID that the outbound side played last to be DID n . Low to high hexade: 1. Repeat DID n-1 2. Repeat DID n-2 3. Repeat DID n-3 4. Repeat all DIDs (restart dialing)
Description | Sets backward Group A tones the inbound side plays to request a digit repetition from the outbound side.
Note | This configuration item is only applicable to the SS1 channel on the SHD Series boards.


3.1.2.28.6.3 Setting Basic Parameters for SS1 Connection


3.1.2.28.6.3.1 TxCas_CD

Configuration Item | TxCas_CD
Section | [SS1Config]
Written Format | TxCas_CD=k
Value Range | k: The high 6 bits should be set to 0, being reserved; the low 2 bits are C/D signaling code. Bit1: Signaling Code C, with the default value of 1; Bit0: Signaling Code D, with the default value of 1.
Description | Sets the value of CD in the ABCD signaling codes sent by the local end to the remote PBX.
Note | This configuration item is only applicable to the SS1 channel on the SHD Series boards, being valid only if the configuration item ProtocolType is set to 1,2,3 or 4.


3.1.2.28.6.3.2 RxCASFilterTime

Configuration Item | RxCASFilterTime
Section | [SS1Config]
Written Format | RxCASFilterTime=t
Value Range | t: The minimum duration of ABCD signaling codes sent out by the remote PBX, calculated by millisecond (ms), which has to be the multiple of 8, with the default value of 0.
Description | Sets the minimum duration of ABCD signaling codes sent out by the remote PBX. Only when the on-line ABCD signaling codes vary and the new value keeps for more then the time specified by this configuration item will the driver confirm the change of ABCD codes. Otherwise, the driver will believe there are undesired dithering signals on the line.
Note | l This configuration item is only applicable to the SS1 channel on the SHD Series boards; l It is used for those E1/T1 lines providing a relative low quality of signals. The severe signal dithering is likely to cause the misdetection of the remote pickup by the driver. This configuration item just helps set a minimum duration to eliminate the possibility of signal dithering. Note: The set value of this configuration item being too great may bring in some side effect. That is, in case the called party sends the ‘Called party first hangs up’ signaling (i.e. Ab/Bb=1/1) immediately following the ‘Called party answers’ signaling (i.e. Ab/Bb=0/1), the ‘Called party answers’ signaling is probably filtered out by the filter as dithering signals.


3.1.2.28.6.3.3 MaxWaitMfcTime

Configuration Item | MaxWaitMfcTime
Section | [SS1Config]
Written Format | MaxWaitMfcTime=t
Value Range | t: The maximum waiting time, calculated by second, with the default value of 10sec.
Description | Sets the timer T2 for the SS1 state machine. Refer to the China SS1 State Machine section in Chapter 1 for more information.
Note | This configuration item is only applicable to the SS1 channel on the SHD Series boards.


3.1.2.28.6.3.4 RxR2FilterTime

Configuration Item | RxR2FilterTime
Section | [BoardId=x]
Written Format | RxR2FilterTime=t
Value Range | t: The minimum duration of the R2 signal, calculated by millisecond (ms), which has to be the multiple of 16, with the default value of 16. The range of value is 16~96.
Description | Sets the minimum duration of the MFC R2 signal.
Note | l This configuration item is only applicable to the SS1 channel on the SHD Series boards; l The same purpose can be achieved by the function call of SsmSetFlag (with the parameter F_RXR2FILTERTIME).


3.1.2.28.6.3.5 LSRingTimeout

Configuration Item | LSRingTimeout
Section | [SS1Config]
Written Format | LSRingTimeout =t
Value Range | t: Calculated by millisecond (ms). Range of value is 1000~20000, with the default value of 6000.
Description | Sets the overtime for being in the ‘Ringing’ state. If a channel which is in the ‘Ringing’ state doesn’t receive any connection message within the overtime, it will go into the ‘Waiting for release’ state.
Note | l This configuration item is only applicable to the SS1 channel on the SHD Series boards; l This configuration item is valid only under the ‘LineSide(ProtocolType=1)’ mode.


3.1.2.28.6.4 Setting Operating Mode of SS1 Channel State Machine


3.1.2.28.6.4.1 EnableAutoCall

Configuration Item | EnableAutoCall
Section | [BoardId=x]
Written Format | EnableAutoCall[n]=b
Value Range | n: The internal digital trunk number on the board, 0 £ n £ M-1 (M is the total number of on-board digital trunks); b: Determines whether to use the state machine provided by the SynCTI driver. b=1: Yes (default); b=0: No.
Description | Sets the operating mode of the SS1 channel state machine.
Note | This configuration item is only applicable to the SS1 channel on the SHD Series boards.


3.1.2.28.6.4.2 AutoCallInTimeSlot

Configuration Item | AutoCallInTimeSlot
Section | [BoardId=x]
Written Format | AutoCallInTimeSlot[n]=i,k
Value Range | n: The internal digital trunk number on the board, 0 £ n £ M-1 (M is the total number of on-board digital trunks); i: The initial time slot set for the incoming call. k: The number of channels (time slots) set for the incoming call.
Description | Sets k time slots from TS i on PCM n to process incoming calls and others to process outgoing calls.
Note | This configuration item is only applicable to the SS1 channel on the SHD Series boards.


3.1.2.28.6.5 Setting Parameters for China SS1 State Machine


3.1.2.28.6.5.1 MfcKB

Configuration Item | MfcKB
Section | [SS1Config]
Written Format | MfcKB=k
Value Range | 1≤k≤6. The default value varies on the configuration item mfcr2 Protocol: 1 for Saudi Arabia, Mexico, China, Thailand and Brazil; 5 for Kuwait, 6 for other countries. When k is set to the default value, it indicates the called party is free and receives the incoming call. For the physical meanings of the value of KB, refer to the function SsmSetKB and the SS1 protocol of relevant countries.
Description | Sets the value of the KB signal sent to the remote PBX by the SS1 channel upon automatic reception of an incoming call. Refer to the China SS1 State Machine section in Chapter 1 for more information.
Note | This configuration item becomes valid only when the configuration item AutoSendKB is set to 1.


3.1.2.28.6.5.2 MaxWaitSetKBTime

Configuration Item | MaxWaitSetKBTime
Section | [SS1Config]
Written Format | MaxWaitSetKBTime=t
Value Range | t: The maximum waiting time, calculated by second, with the default value of 3sec.
Description | Sets the maximum time to wait for the application to configure the KB signal. Sets the maximum waiting time in the SS1 channel state machine for the application to respond to this incoming call request (i.e. the timer T4). Refer to the China SS1 State Machine section in Chapter 1 for more information.


3.1.2.28.6.5.3 MaxWaitKDTime

Configuration Item | MaxWaitKDTime
Section | [SS1Config]
Written Format | MaxWaitKDTime=t
Value Range | t: The maximum waiting time, calculated by second, with the default value of 60sec.
Description | Sets in the SS1 channel state machine the maximum time to wait for the remote PBX to send the KD signal (i.e. the timer T3). Refer to the China SS1 State Machine section in Chapter 1 for more information.


3.1.2.28.6.5.4 PcmSyncMask

Configuration Item | PcmSyncMask
Section | [SS1Config]
Written Format | PcmSyncMask=x
Value Range | x: The mask code for line synchronization value. It is 0x206 by default.
Description | Sets whether to shield the sync status of a PCM link on the E1 trunk. When PcmSyncMask is set to 0x0206, it indicates all sync statuses of a PCM link except those represented by bit1, bit2 and bit9 will be ignored. Refer to SsmGetPcmLinkStatus for more information.


3.1.2.28.6.5.5 PhoNumHoldup

Refer to A3pTime


3.1.2.28.6.5.6 A1ToA3pWaitTime

Refer to A3pTime


3.1.2.28.6.5.7 A3pTime

Configuration Item

PhoNumHoldup

A1ToA3pWaitTime

A3pTime

Section

[SS1Config]

Written Format

PhoNumHoldup=m

A1ToA3pWaitTime=twait

A3pTime=tkeep

Value Range

m: The switch to control the ‘Called Number Hold-up’ feature. Its value and the corresponding meaning are shown in the table below.

m

Description

0

Disable the ‘Called Number Hold-up’ feature.

1

The ‘Called Number Hold-up’ feature is enabled, allowing the holdup of 1 digit of the called party number. When the driver receives the last digit of the called party number according to the preset number receiving rule, it will send the A1 but not A3 signal to the remote PBX and keep waiting for the subsequent digit.

² If the driver receives the subsequent digit within twait, it will save this digit into the Callee ID buffer and finish the reception of the called party number. At that time, the driver will resume the A3 signal transmission in interworking mode to the remote PBX and the normal progress;

² If the driver does not receive the subsequent digit within twait, it will send the A3 signal in the form of pulse to the remote PBX and resume the normal progress.

2

The ‘Called Number Hold-up’ feature is enabled, allowing the holdup of several digits of the called party number. When the driver receives the last digit of the called party number according to the preset number receiving rule, it will continue to send the A1 and keep waiting for the subsequent digit. If the driver receives the subsequent digit within twait, it will save this digit into the Callee ID buffer and repeat the process described above. Only if the driver does not receive the subsequent digit within twait, it will send the A3 signal in the form of pulse to the remote PBX and resume the normal progress.

The default value of m is 0.

twait: The maximum waiting time, calculated by second, with the default value of 1000, being valid when m>0;

tkeep: The pulse width, calculated by second, with the default value of 150, being valid when m>0.

Description

Sets the ‘Called Number Hold-up’ feature. PhoNumHoldup is used to set the control switch of this feature; A1ToA3pWaitTime is to set the threshold value of the time to wait for the subsequent digit; A3pTime is to set the pulse width of the A3 signal.

Note

The purpose achieved by PhoNumHoldup also can be realized via the function call of SsmSetFlag (with the parameter F_RCVPHONUMHOLDUP).


3.1.2.28.6.5.8 Setting Parameters in State Machine for Outgoing Call


3.1.2.28.6.5.8.1 MaxWaitOccupyAckTime

Configuration Item | MaxWaitOccupyAckTime
Section | [SS1Config]
Written Format | MaxWaitOccupyAckTime=t
Value Range | t³1, calculated by second, with the default value of 60.
Description | Sets the value of the timer T5. Refer to the China SS1 State Machine section in Chapter 1 for more information.


3.1.2.28.6.5.8.2 MfcKD

Configuration Item | MfcKD
Section | [SS1Config]
Written Format | MfcKD=k
Value Range | 1≤k≤6, with the default value of 3 (local call). See description on the function SsmSetKD for more information about the KD signal.
Description | Sets the originating service type, i.e. KD, for the outgoing call.


3.1.2.28.6.5.8.3 MfcKA

Configuration Item | MfcKA
Section | [SS1Config]
Written Format | MfcKA=k
Value Range | 1≤k≤10, with the default value of 1 (ordinary/regular). See description on the function SsmSetKA for more information about the KA signal.
Description | Sets the KA signal (called party’s category at the local end) sent in an outgoing call.


3.1.2.28.6.5.8.4 MaxWaitKBTime

Configuration Item | MaxWaitKBTime
Section | [SS1Config]
Written Format | MaxWaitKBTime=t
Value Range | t: The maximum waiting time, calculated by second, with the default value of 60sec;
Description | Sets the maximum time to wait for the KB signal from the remote PBX.


3.1.2.28.6.5.9 Connecting with Dialogic SS1 Channel


3.1.2.28.6.5.9.1 ToRingingDelayTime

Configuration Item | ToRingingDelayTime
Section | [BoardId=x]
Written Format | ToRingingDelayTime=t
Value Range | t: The delay time, calculated by second, with the default value of 0.
Description | Sets the delay time. Upon the connection of a Synway board and a Dialogic board through the SS1 channel, if the SS1 channel on the Synway board serves as the incoming end, a period of waiting time is required before the channel goes into the ‘Ringing’ state following the reception of the complete called party number.
Note | This configuration item is only used in connecting the Synway SHD boards with the Dialogic boards.


3.1.2.28.6.5.9.2 RepeatPhoNumOn1stR2bwdIsA5

Configuration Item

RepeatPhoNumOn1stR2bwdIsA5

Section

[BoardId=x]

Written Format

RepeatPhoNumOn1stR2bwdIsA5=m

Value Range

m=0: The driver sets the pending reason value to be SS1OUT_BWD_A5 and transfers the channel state to S_CALL_PENDING;

m=1: If the local end receives the A5 signal from the remote end only after sending the 1st digit of the called party number, it will send the 1st digit again; otherwise, the driver will set the pending reason value to be SS1OUT_BWD_A5 and transfers the channel state to S_CALL_PENDING.

The default value is 1.

Description

This configuration item is used to select the driver’s subsequent behavior after the reception of the A5 signal (unallocated-number signal) from the remote end in an outgoing call.

Note

This configuration item is only used in connecting the Synway SHD boards with the Dialogic boards.


3.1.2.28.6.5.10 Setting Remote Blocked at Application’s Exit


3.1.2.28.6.5.10.1 IsBlockSS1In

Configuration Item | IsBlockSS1In
Section | [SS1Config]
Written Format | IsBlockSS1In=b
Value Range | b=1: Send (default); b=0: Not send.
Description | This configuration item is used to set whether the driver will automatically sent the blocking command to the remote PBX in order to inform it not to start a call towards the local end again at the time the application program exits.
Note | This configuration item is only applicable to the SS1 channel on the SHD Series boards.


3.1.2.28.6.5.11 Outputting Debugging Information


3.1.2.28.6.5.11.1 MfcR2ToRxCallerIdBuf

Configuration Item | MfcR2ToRxCallerIdBuf
Section | [SS1Config]
Written Format | MfcR2ToRxCallerIdBuf=b
Value Range | b=0: No (default); b=1: Yes.
Description | Sets whether to save the R2 signal sent by the remote PBX in the outgoing call to the Extended Caller ID buffer so as to facilitate the observation on the call process. If this feature is enabled, the driver will put the calling party number into the RxCallerIdExBuf buffer and throw out the E_CHG_CIDExBuf event to the application every time when the R2 signal sent by the remote PBX varies, including the appearance and disappearance of the R2 signal. The function SsmGetCallerIdEx is used to take out the strings stored in this buffer.


3.1.2.28.6.6 Setting Parameters for LineSide Protocol


3.1.2.28.6.6.1 LSWaitPickup

Configuration Item | LSWaitPickup
Section | [SS1Config]
Written Format | LSWaitPickup=t
Value Range | 16≤t≤10000, calculated by millisecond (ms), which has to be the multiple of 8, with the default value of 96. If the set value is out of the range of value, the driver will automatically modify it to 96ms.
Description | Sets the timer T1 in the LineSide state machine. Refer to the Line Side State Machine section in Chapter 1 for more information.
Note | This configuration item is only applicable to the SS1 channel using the LineSide protocol, being valid only when the configuration item ProtocolType is set to1.


3.1.2.28.6.6.2 Ss1SendIdleState

Configuration Item | Ss1SendIdleState
Section | [SS1Config]
Written Format | Ss1SendIdleState=m
Value Range | m=1: Use CAS01xx (especially for Alcatel PBXes); m=0: Use CAS00xx.
Description | Sets the ABCD signaling codes used in sending the idle indicator to the remote PBX.
Note | This configuration item is only applicable to the SS1 channel using the LineSide protocol, being valid only when the configuration item ProtocolType is set to1.


3.1.2.28.7 Advanced Setting for SS7


3.1.2.28.7.1 Setting TS16 Property


3.1.2.28.7.1.1 UseTS16AsCircuit

Refer to Ss7SignalingTS


3.1.2.28.7.1.2 Ss7SignalingTS

Configuration Item

UseTS16AsCircuit

Ss7SignalingTS

Section

[BoardId=x]

Written Format

UseTS16AsCircuit[n]=b

Ss7SignalingTS[n]=k

Value Range

n: The physical digital trunk number, with the value range of 0~M-1. M is the set value of the configuration item PcmNumber.

b: Determines whether this digital trunk contains SS7 signaling links.

b=0: Yes (default). The configuration item Ss7SignalingTS determines the specific time slot to provide signaling links;

b=1: No. The time slot specified by the configuration item Ss7SignalingTS can serve as neither the signaling link nor the voice path.

k: The time slot number, with the default value of 16.

1) For the driver versions below SynCTI 4.5.8.0, k has the fixed value of 16.

2) For the driver versions equal to or above SynCTI 4.5.8.0 and below SynCTI 4.8.0.0, the value of k depends on the board model.

If the board model is one of the followings,

² SHD-240A-CT/cPCI

² SHD-240S-CT/cPCI

² SHD-480A-CT/cPCI

² SHD-480S-CT/cPCI

k must be set to 16.

If the board model is one of others in SHD Series, k can be set to 1 or 16.

3) For SynCTI 4.8.0.0 or above, if the board model is one of the followings,

² SHD-240A-CT/cPCI

² SHD-240S-CT/cPCI

² SHD-480A-CT/cPCI

² SHD-480S-CT/cPCI

k must be set ≥0 and ≤32. When k is equal to 0 or 32, all time slots from TS1 to TS31 on this digital trunk are used as voice paths; other values except 0 and 32 indicate the particular signaling time slot number.

If the board model is one of the followings,

² SHD-240D-CT/PCI

² SHD-240D-CT/PCI/EC

² SHD-120D-CT/PCI

² SHD-120D-CT/PCI/EC

² SHD-60B-CT/PCI/FJ

² All E-type digital trunk boards

k must be set >0 and <33. To be exact,

In E1 mode, k=32 indicates all the 31 time slots on this PCM are used to deliver voice data. For SHD-60B-CT/PCI/FJ, k=32 indicates all the 31 time slots on the monitored PCM are used to deliver voice data, and this feature is only supported for E1 and SS7. (Note: While using SS1 or ISDN, k is set to 16 by default and cannot be modified.)

In T1/J1 mode, 1£k£25. k=25 indicates all of the 24 time slots on this PCM are used to deliver voice data. (Note: While using SS1, k is set to 25 by default; while using ISDN, k is set to 24 by default. Both cannot be modified.)

If the board model is one of others in SHD Series, k can be set to 1 or 16.

Description

UseTS16AsCircuit is used to set whether this digital trunk contains SS7 signaling links.

Note

l It is an advanced configuration item, only applicable to the SS7 signaling;

l If the value of the configuration item PcmNumber is greater than 1, this configuration item should be set for each digital trunk.


3.1.2.28.7.2 Setting Corresponding Characters for Spare Address Codes


3.1.2.28.7.2.1 AddressSignal

Configuration Item | AddressSignal
Section | [TUP] / [ISUP]
Written Format | AddressSignal[n]=c
Value Range | n: The spare address code in the TUP/ISUP message, 10≤n≤14. c: The character corresponding to n, not allowed to be any one of ’0’~’9’.
Description | Sets the corresponding character for each spare address code. See the Setting Corresponding Characters for Spare Address Codes section in Chapter 1 for more information.
Note | l This configuration item is only applicable to the TUP/ISUP channel; l The ISUP channel uses the configuration section [ISUP] while the TUP channel uses [TUP].


3.1.2.28.7.3 Setting IP Address of SS7 Server


3.1.2.28.7.3.1 Ss7ServerIP

Refer to SecondServerIP


3.1.2.28.7.3.2 SecondServerIP

Configuration Item | Ss7ServerIP SecondServerIP
Section | [SS7]
Written Format | Ss7ServerIP=a.b.c.d SecondServerIP=a.b.c.d
Value Range | a.b.c.d: The address of the SS7 server, with the default value of 127.0.0.1 (indicating there is only one SS7 server available, running with the application program on the local PC).
Description | Sets the address of the SS7 server.
Note | If both the SS7 server and the application program are running on the local PC, these two configuration items are not necessarily set; if the system contains two SS7 server, Ss7ServerIP and SecondServerIP are respectively used to set the IP address of the master server and that of the slave server.
Example | Ss7ServerIP=201.123.123.1


3.1.2.28.7.4 Setting IP Address of Local PC


3.1.2.28.7.4.1 LocalIP

Configuration Item | LocalIP
Section | [SS7]
Written Format | LocalIP=a.b.c.d
Value Range | a.b.c.d: The address of the local PC, with the default value of 127.0.0.1 (indicating both the SS7 server and the application program are running on the local PC).
Description | Sets the IP address of the SS7 server or the gateway.
Example | LocalIP=201.123.123.5


3.1.2.28.7.5 SS7 Server Outputting Data on Voice Time Slot


3.1.2.28.7.5.1 LoadShp_a3AsSIU

Configuration Item | LoadShp_a3AsSIU
Section | [SystemConfig]
Written Format | LoadShp_a3AsSIU=b
Value Range | b=0: No (default); b=1: Yes.
Description | Sets whether the SS7 server outputs the data on voice time slots. When the SS7 server is used not to run any service system but to provide SS7 service, it only process the data on signaling time slots of the digital trunk but not those on voice time slots. If the digital trunk that connects to the SS7 server has voice time slots on it besides the signaling links, the SS7 server is required to exchange the data from a voice time slot to another and then output the data from there. Such an operation is based on the two-way connection between all voice time slots of the digital trunk with the physical number of 0 and the corresponding voice time slots of the digital trunk with the physical number of 1. Refer to the Supplying SS7 Service for Third-party Board section in Chapter 4 for more information.
Note | It is only applicable to the SHD-60A-CT/PCI/SS7 board.


3.1.2.28.7.6 Setting SS7 Circuit for Digital Trunk


3.1.2.28.7.6.1 Ss7CircuitMap[pcm]

Configuration Item

Ss7CircuitMap[pcm]

Section

[BoardId=x]

Written Format

Ss7CircuitMap[pcm]=b

Value Range

pcm: The physical number of the digital trunk on the board. For more information, refer to related manuals. Range of value: 0≤pcm≤31;

b: composed of 32 bits, with the default value of 0xFFFFFFFF. The values of bit0-bit31 respectively indicate whether TS0-TS31 for a particular PCM are used as SS7 circuits: 0=not used as SS7 ciruit; 1=used as SS7 circuit. In an E1 system, TS0 and the time slot for processing SS7 signaling will be ignored.

Description

Sets the corresponding relationship between SS7 circuits and time slots for a particular PCM. The time slot which is set to ‘not used as SS7 circuit’ will not be reset by the driver and the inbound call from the other end to this time slot will be blocked. Meanwhile, the corresponding channel will turn to the ‘unused’ state.

Example

Ss7CircuitMap[0]= 0xFFFFFFFF


3.1.2.28.7.7 Advanced Configuration Item for TUP


3.1.2.28.7.7.1 Setting Range Field in Circuit Group Message


3.1.2.28.7.7.1.1 SendGRMRange

Configuration Item

SendGRMRange

Section

[TUP]

Written Format

SendGRMRange=m

Value Range

m=0: Use all-0 field. That is, the time slot number in the CIC field of the circuit group message is 1 and the Range field is 0, indicating this circuit group message covers all time slots TS1~31;

m=1: Use not all-0 field. The range of time slots covered by the circuit group message depends on the configuration item Ss7SignalingTS. Assuming the set value of Ss7SignalingTS is N:

² If N=1, the time slot number in the CIC field of the circuit group message is 2 and the Range field is 29;

² If N=16, the circuit group message will be divided into 2 messages: the time slot number in the CIC field of one message is 1 and the Range field is 14; the time slot number in the CIC field of the other message is 17 and the Range field is 14.

Description

This configuration item is used to set the range of time slots covered by the circuit group message when the local driver sends the message to the remote PBX.

Note

This configuration item will affect all circuit group messages, including the circuit group reset message and the circuit group blocking/unblocking message.


3.1.2.28.7.7.1.2 HangupRingSendCBK

Configuration Item | HangupRingSendCBK
Section | [TUP]
Written Format | HangupRingSendCBK=m
Value Range | m=0: Send the CFL message (default); m=1: Send the CBK message.
Description | When the channel stays in the S_CALL_RINGING state, the function call of SsmHangup or SsmHangupEx by the application will prompt the driver to send the call rejection message to the remote PBX. The call rejection message can be CBK or CFL. It is this configuration item that determines which one is used exactly.
Note | It requires SynCTI Ver. 4.7.1.5 or above.


3.1.2.28.7.7.2 Incoming Call: Customizing ACM Message


3.1.2.28.7.7.2.1 DefaultACM

Configuration Item

DefaultACM

Section

[TUP]

Written Format

DefaultACM=0xab

Value Range

ab：8-bit data, represented by hexadecimal digits. The 8 bits are arranged from high to low as HGFEDCBA.

Bit | Implication | Value | Description
HG | Spare |  |
F | Signaling Channel Indicator | 0 | Any channel
 |  | 1 | All are SS7 channels
E | Call Forwarding Indicator | 0 | Call non-forwarding
 |  | 1 | Call forwarding
D | Incoming Echo Suppression Indicator | 0 | Incoming half-echo suppressor not included
 |  | 1 | Incoming half-echo suppressor included
C | Subscriber Free Indicator | 0 | Not instructed
 |  | 1 | The subscriber is free.
BA | Address Complete Signal Type Indicator | 00 | Address complete signal
 |  | 01 | Address complete signal, charge
 |  | 10 | Address complete signal, no charge
 |  | 11 | Address complete signal, coin box

The default value is 0x05。

Description

In the incoming call, the local end is required to send the ACM message to the remote PBX after receiving the complete called party number and other information. This ACM message should contain the message indicator field to indicate the user’s status which is set via this configuration item. Refer to the TUP Channel State Machine section in Chapter 1 for more information.

Example

DefaultACM=0x05


3.1.2.28.7.7.3 Incoming Call: Customizing GRQ Message


3.1.2.28.7.7.3.1 ReqTypeIndicators

Configuration Item

ReqTypeIndicators

Section

[TUP]

Written Format

ReqTypeIndicators=0xk

Value Range

k: 8-bit data, represented by hexadecimal digits. The 8 bits are arranged from high to low as HGFEDCBA.

Bit | Implication | Value | Description
HG | Spare |  |
F | Echo Suppressor Request Indicator (also is applicable to the echo canceller) | 0 | Not requested
 |  | 1 | Requested
E | Request Holding Indicator | 0 | Not requested
 |  | 1 | Requested
D | Malicious Call Identification Indicator | 0 | Not encountered
 |  | 1 | Encountered
C | Original Called Party’s Address Indicator | 0 | Not requested
 |  | 1 | Requested
B | Calling Line Identification Indicator | 0 | Not requested
 |  | 1 | Requested
A | Calling Party’s Category Indicator | 0 | Not requested
 |  | 1 | Requested

The default value is 0x03.

Description

Sets the request type indicator in the GRQ message.

Example

ReqTypeIndicators=0x03


3.1.2.28.7.7.4 Outgoing Call: Customizing IAI/IAM Message


3.1.2.28.7.7.4.1 ConnectReqMsg

Configuration Item | ConnectReqMsg
Section | [TUP]
Written Format | ConnectReqMsg=m
Value Range | m=0: Automatically selected by the driver. If the driver’s internal outgoing Caller ID buffer (configurable via the function SsmSetTxCallerId or the configuration item TxCallerId) or original Callee ID buffer (configurable via the function SsmSetTxOriginalCallerID) is not empty, use the IAI message; otherwise, use the IAM message. m=1: Use the IAM message. m=2: Use the IAI message. The default value is 0.
Description | This configuration item is to set the initial address message type used by the local end to start an outgoing call.


3.1.2.28.7.7.4.2 CalloutIAM_CAT

Configuration Item

CalloutIAM_CAT

Section

[TUP]

Written Format

CalloutIAM_CAT=0xk

Value Range

k: 8-bit data, represented by hexadecimal digits. The 8 bits are arranged from high to low as HGFEDCBA.

Low bits: HGFEDCBA
Bit | Implication | Value | Description
HG | Spare | 00 |
FEDCBA | Calling Party’s Category | 000000 | Unknown, used in international semi-automatic working
 |  | 000001 | Operator, language French, used in international semi-automatic working
 |  | 000010 | Operator, language English, used in international semi-automatic working
 |  | 000011 | Operator, language German, used in international semi-automatic working
 |  | 000100 | Operator, language Russian, used in international semi-automatic working
 |  | 000101 | Operator, language Spanish, used in international semi-automatic working
 |  | 000110 | A particular language selected by mutual agreement (Chinese), used in international semi-automatic working
 |  | 000111 | A particular language selected by mutual agreement, used in international semi-automatic working
 |  | 001000 | A particular language selected by mutual agreement (Japanese), used in international semi-automatic working
 |  | 001001 | National operator (presentation allowed)
 |  | 001010 | Ordinary subscriber, used in international-to-long-distance, international-to-local network
 |  | 001011 | Subscriber with priority, used in international-to-long-distance, international-to-local, local-to-local network
 |  | 001100 | Data call
 |  | 001101 | Test call
 |  | 001110 | 001110~001111 Spare
 |  | 010000 | Ordinary, free, used in local-to-international network
 |  | 010001 | Ordinary, regular, used in local-to-international network
 |  | 010010 | Ordinary, subscriber list, instant, used in local-to-international network
 |  | 010011 | Ordinary, printer, instant, used in local-to-international network
 |  | 010100 | With priority, free, used in local-to-international network
 |  | 010101 | With priority, regular, used in local-to-international network
 |  | 010110 | Spare
 |  | 010111 | Spare
 |  | 011000 | Ordinary subscriber, used in local-to-local network
 |  | 011001 | 011001~111111 Spare

The default value is 0x18。

Description

Sets the calling party’s category field in the IAI/IAM message.

Example

CalloutIAM_CAT=0x18


3.1.2.28.7.7.4.3 CalloutIAM_MsgPntr

Configuration Item

CalloutIAM_MsgPntr

Section

[TUP]

Written Format

CalloutIAM_MsgPntr=0xabcd

Value Range

abcd: 16-bit data, represented by hexadecimal digits, the low 12 bits being valid. Bit11~Bit0 are written as LKJIHGFEDCBA, each of which is described below.

Bit | Implication | Value | Description
H | Incoming International Call Indicator | 0 | Not incoming international call
 |  | 1 | Incoming international call
G | Outgoing Echo Suppressor Indicator | 0 | Outgoing echo suppressor not included
 |  | 1 | Outgoing echo suppressor included
FE | Continuity Check Indicator | 00 | Continuity check not required
 |  | 01 | Continuity check required on this circuit
 |  | 10 | Continuity check performed on a previous circuit
 |  | 11 | Spare
DC | Nature of Circuit Indicator | 00 | No satellite circuit in the connection
 |  | 01 | satellite circuit available in the connection
 |  | Others | Spare
BA | Nature of Address Indicator | 00 | Local subscriber number
 |  | 01 | Spare
 |  | 10 | Valid national number
 |  | 11 | International number
L | Spare |  |
K | Signaling Channel Indicator | 0 | Any channel
 |  | 1 | All are SS7 channels
J | All Digital Channel Required Indicator | 0 | Ordinary call
 |  | 1 | All digital channels required
I | Call Transfer Indicator | 0 | Call transfer required
 |  | 1 | Call transfer not required

The default value is 0x0000。

Description

Sets the message indicator field in the IAI/IAM message.

Example

CalloutIAM_MsgPntr=0x0000


3.1.2.28.7.7.4.4 CallingIndicatorBit

Configuration Item | CallingIndicatorBit
Section | [TUP]
Written Format | CallingIndicatorBit=n
Value Range | n=0x10: Use Bit E； n=0x04: Use Bit C (default)
Description | There is a first indicator (octet) in the IAI message, Bit7~Bit0 being written as HGFEDCBA, among which Bit C is the calling party information indicator, Bit E is the calling line identification indicator. In case the IAI message contains the calling party number, some PBXes requires the use of Bit E, some requires the use of Bit C. Which one is exactly used can be set via this configuration item depending on the remote PBX’s requirement.
Example | CallingIndicatorBit=0x10


3.1.2.28.7.7.4.5 OriginalCalleeAddrInd

Configuration Item

OriginalCalleeAddrInd

Section

[TUP]

Written Format

OriginalCalleeAddrInd=0xn

Value Range

n: 8-bit data, represented by hexadecimal digits, the low 4 bits being valid. Bit3~Bit0 are written as DCBA, each of which is described below.

Bit | Implication | Value | Description
DC | Spare | 00 |
BA | Nature of Address Indicator | 00 | Local subscriber number
 |  | 01 | Spare national number
 |  | 10 | Valid national number
 |  | 11 | International number

The default value is 0x02.

Description

Sets the address indicator in the original called party address field of the IAI message.

Example

OriginalCalleeAddrInd=0x02


3.1.2.28.7.7.4.6 CallerAddrInd

Configuration Item

CallerAddrInd

Section

[TUP]

Written Format

CallerAddrInd =0xn

Value Range

n: Address indicator, 8-bit and hexadecimal, the low 4 bits being valid. Bit3~Bit0 are written as DCBA, each of which is described below.

Bit | Implication | Value | Description
D | Calling party number incomplete indicator | 0 | Not incomplete
 |  | 1 | Incomplete
C | Calling party number presentation indicator | 0 | Presentation unrestricted
 |  | 1 | Presentation restricted
BA | Nature of address indicator | 00 | Local subscriber number
 |  | 01 | Spare national number
 |  | 10 | Valid national number
 |  | 11 | International number

The default value is 0x02.

Description

Sets the address indicator in the calling line identification field in the IAI message.

Example

CallerAddrInd =0x02


3.1.2.28.7.7.5 Outgoing Call: Setting Way to Reply with GRQ Message


3.1.2.28.7.7.5.1 AutoSendGSM

Configuration Item | AutoSendGSM
Section | [TUP]
Written Format | AutoSendGSM=m
Value Range | m=0: Taken over by the application. The outgoing call is resumed after the channel state transfers to ‘Pending’ and the application program invoke the function SsmSetTxCallerId to set the calling party number. m=1: Automatically replied by the driver (default).
Description | In the outgoing call, once the GRQ message is received from the remote PBX, this configuration item is used to determine whether this message is automatically replied by the driver via sending the GSM message. See the TUP Channel State Machine section in Chapter 1 for more information.


3.1.2.28.7.7.6 Not Using SynCTI-provided TUP State Machine


3.1.2.28.7.7.6.1 AutoHandleTup

Configuration Item | AutoHandleTup
Section | [SS7]
Written Format | AutoHandleTup=b
Value Range | b=0: No; b=1: Yes (default).
Description | Sets whether to use the TUP state machine provided by the SynCTI driver or not.


3.1.2.28.7.7.7 Outputting Debugging Information


3.1.2.28.7.7.7.1 DebugViewTupCallProc

Configuration Item | DebugViewTupCallProc
Section | [SS7]
Written Format | DebugViewTupCallProc=b
Value Range | b=0: No (default); b=1: Yes.
Description | Sets whether to output the debugging information of the TUP state machine to the software tool DebugView. If Yes, DebugView is required to run first.
Note | Enabling the TUP debugging feature will reduce the system running efficiency. Hence this feature is only used for debugging.


3.1.2.28.7.8 Advanced Configuration Item for ISUP


3.1.2.28.7.8.1 Incoming Call: Customizing Message Type Used by Local End to Reply Incoming Call


3.1.2.28.7.8.1.1 DefaultCalledPickupMsg

Configuration Item | DefaultCalledPickupMsg
Section | [ISUP]
Written Format | DefaultCalledPickupMsg=k
Value Range | k=0x09: Use the ANM message (response); k=0x07: Use the CON message (address complete and phone picked up) The default value is 0x09.
Description | This configuration item is used to set the type of the message sent to the remote PBX when the ISUP channel stays in the ‘Ringing’ state and the application invokes the function SsmPickup or SsmPickupANX.
Note | It requires SynCTI Ver. 4.7.1.8 or above.
Example | DefaultCalledPickupMsg=0x09


3.1.2.28.7.8.2 Incoming Call: Customizing Backward Call Indicator


3.1.2.28.7.8.2.1 DefaultBackwardCallInd

Configuration Item

DefaultBackwardCallInd

Section

[ISUP]

Written Format

DefaultBackwardCallInd=k

Value Range

k: The parameter value of the backward call indicator field, including 2 bytes. The bits arranged from high (Bit15) to low (Bit0) are written as PONMLKJIHGFEDCBA, each of which is described below.

Bit | Implication | Value and Description
BA | Charge Indicator | 00: No indication 01: No charge 10: Charge 11: Spare
DC | Called Party’s Status Indicator | 00: No indication 01: Subscriber free 10: Connect when free 11: Spare
FE | Called Party’s Category Indicator | 00: No indication 01: Ordinary subscriber 10: payphone 11: Spare
HG | End-to-end Method Indicator (Note) | 00: No end-to-end method available (only link-by-link method available) 01: Pass-along method available 10: SCCP method available 11: Pass-along and SCCP methods available
I | Interworking Indicator (Note) | 0: No interworking encountered 1: Interworking encountered
J | End-to-end Information Indicator (Note) | 0: No end-to-end information available 1: End-to-end information available
K | ISDN User Part Indicator (Note) | 0: ISDN user part not used all the way 1: ISDN user part used all the way
L | Holding Indicator | 0: Holding not requested 1: Holding requested
M | ISDN Access Indicator | 0: Terminating access non-ISDN 1: Terminating access ISDN
N | Echo Control Device Indicator | 0: Incoming half-echo control device not included 1: Incoming half-echo control device included
PO | SCCP Method Indicator (Note) | 00: No indication 01: Connectionless method available 10: Connection oriented method available 11: Connectionless and connection oriented methods available

NOTE: Bits G-K and O-P constitute the protocol control indicator.

The default value is 0x1416.

Description

Sets the backward call indicator field in the ACM and CON messages.

Note

It requires SynCTI Ver. 4.7.1.8 or above.

Example

DefaultBackwardCallInd=0x1416


3.1.2.28.7.8.3 Incoming Call: Customizing REL Message


3.1.2.28.7.8.3.1 DefaultHangupRELInd

Configuration Item

DefaultHangupRELInd

Section

[ISUP]

Written Format

DefaultHangupRELInd=0xk

Value Range

The values and corresponding meanings of k are listed in the table below.

Value | Macro in shpa3api.h | Description
0x01 | C_ISUP_REL_UNN | Number unallocated
0x10 | C_ISUP_REL_NORMAL_REL | Normal release
0x11 | C_ISUP_REL_BUSY | User busy
0x12 | C_ISUP_REL_NOREPLY | No answer
0x15 | C_ISUP_REL_DENY | Refused
0x1c | C_ISUP_REL_LACKADDR | Address incomplete
0x1f | C_ISUP_REL_NORMAL | Normal
0x2a | C_ISUP_REL_BLOCK | Exchange device blocked

The default value is 0x15 (C_ISUP_REL_DENY).

Description

This configuration item is used to set the release cause value carried by the REL message when a call comes into the channel but has not yet been picked up, and the driver is prompted by the function call of SsmHangup to send the REL message to the remote PBX.

Note

l If the set value is out of the range shown above, the driver will automatically adjust the value to 0x15;

l It requires SynCTI Ver. 4.7.1.5 or above.

Example

DefaultHangupRELInd=0x15


3.1.2.28.7.8.3.2 DefaultCauseInd

Configuration Item

DefaultCauseInd

Section

[ISUP]

Written Format

DefaultCauseInd=n

Value Range

n: 16-bit data, represented by hexadecimal digits. Each bit in it is described below.

Low-bit Byte: HGFEDCBA
Bit | Implication | Value | Description
H | Extension Indicator | 0 | Information continues in the next octet (octet suggested)
 |  | 1 | Last octet
GF | Coding Standard | 00 | ITU-T standard code
 |  | Others | Reserved
E | Spare | 0 | Should be set to 0
DCBA | Location | 0000 | User (U)
 |  | 0001 | Local private network (LPN)
 |  | 0010 | Local public network (LN)
 |  | 0011 | Transfer network (TN)
 |  | 0100 | Remote public network (RLN)
 |  | 0101 | Remote private network (RPN)
 |  | 0111 | Internet(INTL)
 |  | 1010 | Network formed by points except two connected ones on the SS7 public network (BI)
 |  | Others | Spare
High-bit Byte: HGFEDCBA
Bit | Implication | Value | Description
H | Extension Indicator | 1 | Last octet
GFEDCBA | Recommendation | 0000000 | Q.931
 |  | 0000011 | X.21
 |  | 0000100 | X.25
 |  | 0000101 | Public Land Mobile Network (PLMN), Q.1031/Q.1051
 |  | Others | Reserved

The default value is 0x0000.

Description

Sets the coding standard, location and recommendation parameters for the cause indicator field. The recommendation parameter is optional: if not selected, the extension octet of the low 8 bits must be set to 1 and the value of the high 8 bits will be ignored by the driver; If selected, the extension octet of the low 8 bits must be set to 0.

Example

DefaultCauseInd=0x0000


3.1.2.28.7.8.4 Incoming Call: Setting Other Parameters


3.1.2.28.7.8.4.1 SaveRGNTo1stPhoNumStr

Configuration Item | SaveRGNTo1stPhoNumStr
Section | [ISUP]
Written Format | SaveRGNTo1stPhoNumStr=b
Value Range | b=0: No; b=1: Yes (default).
Description | Sets whether the redirection number information in the IAM message can be acquired via the function call of SsmGet1stPhoNumStr or SsmGet1stPhoNumStrA. See description on those two functions for more information.
Note | l This configuration item is only applicable to the ISUP channel; l It requires SynCTI Ver 4.7.1.7 or above.


3.1.2.28.7.8.5 Outgoing Call: Customizing IAM Message


3.1.2.28.7.8.5.1 DefaultNatureOfConnectionInd

Configuration Item | DefaultNatureOfConnectionInd
Section | [ISUP]
Written Format | DefaultNatureOfConnectionInd=0xk
Value Range | k: The nature of connection indicator, represented by hexadecimal digits, with the default value of 0x00. Regarding the specific value, see Appendix 2 ISUP Parameters. Usually it is provided by the remote PBX according to the particular configuration.
Description | Sets the nature of connection indicator in the IAM message.
Example | DefaultNatureOfConnectionInd=0x00


3.1.2.28.7.8.5.2 DefaultIAM_ForwardCallInd

Configuration Item | DefaultIAM_ForwardCallInd
Section | [ISUP]
Written Format | DefaultIAM_ForwardCallInd=0xk
Value Range | k: The forward call indicator, represented by hexadecimal digits, with the default value of 0x0040. Regarding the specific value, see Appendix 2 ISUP Parameters. Usually it is provided by the remote PBX according to the particular configuration.
Description | Sets the forward call indicator in the IAM message.
Example | DefaultIAM_ForwardCallInd=0x0040


3.1.2.28.7.8.5.3 DefaultIAM_CAT

Configuration Item | DefaultIAM_CAT
Section | [ISUP]
Written Format | DefaultIAM_CAT=0xk
Value Range | k: The calling party’s category indicator, with the default value of 0x0a. Regarding the specific value, see Appendix 2 ISUP Parameters . Usually it is provided by the remote PBX according to the particular configuration.
Description | Sets the calling party’s category indicator in the IAM message.
Example | DefaultIAM_CAT=0x0a


3.1.2.28.7.8.5.4 DefaultIAM_TransmissionMediumRequirment

Configuration Item

DefaultIAM_TransmissionMediumRequirment

Section

[ISUP]

Written Format

Format 1: DefaultIAM_TransmissionMediumRequirment=0xk

Format 2: DefaultIAM_TransmissionMediumRequirment[N]=0xk

Value Range

k: The transmission medium requirement parameter, represented by hexadecimal digits, with the default value of 0x02. Regarding the specific value, see Appendix 2 ISUP Parameters. Usually it is provided by the remote PBX according to the particular configuration.

N: The PCM number for the link it lies on. If the whole system uses the same transmission medium, use Format 1; if links in the system use different transmission medium, use Format 2, remaining Format 1 and setting k to 0xff.

Description

Sets the transmission medium requirement parameter in the IAM message.

Note

Don’t forget to remain Format 1 and set k to 0xff whiling using Format 2.

Example

Format 1:

DefaultIAM_TransmissionMediumRequirment=0x02

Format 2:

DefaultIAM_TransmissionMediumRequirment=0xff; must set

DefaultIAM_TransmissionMediumRequirment[0]=0x02; use 0x02 for PCM 0,1

DefaultIAM_TransmissionMediumRequirment[1]=0x02

DefaultIAM_TransmissionMediumRequirment[2]=0x04; use 0x04 for PCM 2,3

DefaultIAM_TransmissionMediumRequirment[3]=0x04


3.1.2.28.7.8.5.5 DefaultIAM_CalleeParam

Configuration Item

DefaultIAM_CalleeParam

Section

[ISUP]

Written Format

DefaultIAM_CalleeParam=0xk

Value Range

k: 16-bit data, represented by hexadecimal digits. Each bit in it is described below.

Low-bit Byte: HGFEDCBA
Bit | Implication | Value | Description
H | Odd/even Indicator | 0 | Even number of address signals
 |  | 1 | Odd number of address signals
GFEDCBA | Nature of Address Indicator | 0000001 | Subscriber number
 |  | 0000011 | National number
 |  | 0000100 | International number
 |  | Others | Spare
High-bit Byte: HGFEDCBA
Bit | Implication | Value | Description
H | Internal Network Number Indicator | 0 | Routing to internal network number allowed
 |  | 1 | Routing to internal network number not allowed
GFE | Numbering Plan Indicator | 001 | ISDN (Telephony) numbering plan (Recommendations E.164, E.163)
 |  | 011 | Data numbering plan(Recommendation X.164)
 |  | 100 | Telex numbering plan (Recommendation F.164)
 |  | Others | Spare
DCBA | Spare |  |

The default value is 0x1003.

Description

Sets the called party number parameter field in the IAM message.

Example

DefaultIAM_CalleeParam=0x1003


3.1.2.28.7.8.5.6 DefaultIAM_CallerParam

Configuration Item

DefaultIAM_CallerParam

Section

[ISUP]

Written Format

DefaultIAM_CallerParam=0xk

Value Range

k:16-bit data, represented by hexadecimal digits. Each bit in it is described below.

Low-bit Byte: HGFEDCBA
Bit | Implication | Value | Description
H | Odd/even Indicator | 0 | Even number of address signals
 |  | 1 | Odd number of address signals
GFEDCBA | Nature of Address Indicator | 0000001 | Subscriber number
 |  | 0000011 | National number
 |  | 0000100 | International number
 |  | Others | Spare
High-bit Byte: HGFEDCB
Bit | Implication | Value | Description
H | Number Incomplete Indicator | 0 | Complete
 |  | 1 | Incomplete
GFE | Numbering Plan Indicator | 001 | ISDN (Telephony) numbering plan (Recommendations E.164, E.163)
 |  | 011 | Data numbering plan(Recommendation X.164)
 |  | 100 | Telex numbering plan (Recommendation F.164)
 |  | Others | Spare
DC | Address Presentation Restricted Indicator | 00 | Presentation allowed
 |  | 01 | Presentation restricted
 |  | 10 | Address not available
 |  | Others | Spare
BA | Screening Indicator | 00 | User provided, not verified (national use)
 |  | 01 | User reserved, verified and passed
 |  | 10 | User provided, verified and not passed (national use)
 |  | 11 | Network provided

The default value is 0x1001.

Description

Sets the calling party number parameter field in the IAM message.

Example

DefaultIAM_CallerParam=0x1001


3.1.2.28.7.8.5.7 DefaultIAM_OriginalCalleeParam

Configuration Item | DefaultIAM_OriginalCalleeParam
Section | [ISUP]
Written Format | DefaultIAM_OriginalCalleeParam=0xk
Value Range | k:16-bit data, represented by hexadecimal digits, with the default value of 0x1001. Regarding the specific value, see Appendix 2 ISUP Parameters.
Description | Sets the first two bytes of the original called party number in the IAM message, including the nature of address indicator, numbering plan indicator and address presentation restricted indicator. Regarding the specific value, see Appendix 2 ISUP Parameters. Usually it is provided by the remote PBX according to the particular configuration.
Example | DefaultIAM_OriginalCalleeParam=0x1001


3.1.2.28.7.8.5.8 DefaultIAM_RedirectingNumber

Configuration Item | DefaultIAM_RedirectingNumber
Section | [ISUP]
Written Format | DefaultIAM_RedirectingNumber=0xk
Value Range | k:16-bit data, represented by hexadecimal digits, with the default value of 0x1001. Regarding the specific value, see Appendix 2 ISUP Parameters.
Description | Sets the first two bytes of the redirecting number in the IAM message, including the nature of address indicator, numbering plan indicator and address presentation restricted indicator. Regarding the specific value, see Appendix 2 ISUP Parameters. Usually it is provided by the remote PBX according to the particular configuration.
Example | DefaultIAM_RedirectingNumber=0x1001


3.1.2.28.7.8.5.9 bSubscriberSI

Refer to SubscriberSI


3.1.2.28.7.8.5.10 SubscriberSI

Configuration Item

bSubscriberSI

SubscriberSI

Section

[ISUP]

Written Format

bSubscriberSI=k

SubscriberSI=0xk1, 0xk2,…0xki,…, 0xk11

Value Range

k: =0: Not include (default);

=1: Include. The specific value of the user server information parameter is set in the configuration item SubscriberSI.

ki: The user service information parameter, represented by hexadecimal digits, with the default value of 0x80,0x90,0xa3. It is applicable to Huawei PBXes. Up to 11 ki are allowed to be configured. Regarding the specific value, see Appendix 2 ISUP Parameters. Usually it is provided by the remote PBX according to the particular configuration.

Description

bSubscriberSI is used to set whether the IAM message contains the user service information;

SubscriberSI is used to set the content of the user service information, being valid only if bSubscriberSI is set to 1.

Example

bSubscriberSI=1

SubscriberSI=0x80,0x90,0xa3


3.1.2.28.7.8.5.11 bOptionalFCI

Refer to OptionalFCI


3.1.2.28.7.8.5.12 OptionalFCI

Configuration Item

bOptionalFCI

OptionalFCI

Section

[ISUP]

Written Format

bOptionalFCI=b

OptionalFCI=0xk

Value Range

b: =0: Not include (default);

=1: Include.

k: 8-bit data, represented by hexadecimal digits. The bits arranged from high to low are written as HGFEDCBA, each of which is described below.

Bit | Implication | Value | Description
H | Connected Line Identity Request Indicator | 0 | Not requested
 |  | 1 | Requested
GFED | Spare |  |
C | Simple Segmentation Indicator | 0 | No additional information will be sent
 |  | 1 | Additional information will be sent in a segmentation message
BA | Closed User Group Call Indicator | 00 | Non-CUG call
 |  | 01 | Spare
 |  | 10 | Closed user group call, outgoing access allowed
 |  | 11 | Closed user group call, outgoing access not allowed

The default value is 0. If necessary, it is usually provided by the remote PBX according to the particular configuration

Description

bOptionalFCI is used to set whether the IAM message contains the optional forward call indicator. If this indicator is contained, its value is specified by the configuration item OptionalFCI.

OptionalFCI is used to set the specific value of the optional forward call indicator.

Example

bOptionalFCI=1

OptionalFCI=0x01


3.1.2.28.7.8.5.13 Usr2UsrInfo

Configuration Item | Usr2UsrInfo
Section | [ISUP]
Written Format | Usr2UsrInfo=s1,s2,…,si,…,sN
Value Range | si: A character represented by hexadecimal digits. The value is unallocated in default, i.e. this field is not included. Up to 131 si are allowed to be configured.
Description | Sets the user-to-user information field in the IAM message. The same purpose can be achieved via the function SsmSetIsupParameter.
Example | Usr2UsrInfo=a0,31,6c


3.1.2.28.7.8.5.14 LocationNumber

Configuration Item | LocationNumber
Section | [ISUP]
Written Format | LocationNumber =s1,s2,…,si,…,sN
Value Range | si: A character represented by hexadecimal digits. The value is unallocated in default, i.e. this field is not included. Up to 50 si are allowed to be configured.
Description | Sets the LocationNumber information field in the IAM message. The same purpose can be achieved via the function SsmSetIsupParameter.
Example | LocationNumber=0x04,0x13,0x19,0x89,0x45,0x90,0x09,0x20


3.1.2.28.7.8.6 Outgoing Call: Setting Way to Reply with INF Message


3.1.2.28.7.8.6.1 AutoSendINF

Configuration Item | AutoSendINF
Section | [ISUP]
Written Format | AutoSendINF=m
Value Range | m=0: Taken over by the application; m=1: Automatically replied by the driver (default).
Description | In the outgoing call, once the INR message is received from the remote PBX, this configuration item is used to determine whether this message is automatically replied by the driver via sending the INF message. See the ISUP Channel State Machine section in Chapter 1 for details.


3.1.2.28.7.8.7 Not Using SynCTI-provided ISUP State Machine


3.1.2.28.7.8.7.1 AutoHandleIsup

Configuration Item | AutoHandleIsup
Section | [SS7]
Written Format | AutoHandleIsup=b
Value Range | b=0: No; b=1: Yes (default).
Description | Sets whether to use the ISUP state machine provided by the SynCTI driver or not.


3.1.2.28.7.8.7.2 CircuitReset

Configuration Item

CircuitReset

Section

[ISUP]

Written Format

CircuitReset=m

Value Range

m=0: After the SS7 service is enabled, the circuit goes into an idle state without sending a circuit reset message.

m=1: After the SS7 service is enabled, the circuit sends a circuit reset message and goes into an idle state (default value). It is a boolean configuration item, not applicable to TUP.

Description

Determines if the circuit goes into an idle state or is reset after the ISUP service is enabled.


3.1.2.28.7.9 Advanced Configuration Item for SCCP


3.1.2.28.7.9.1 AutoHandleSccp

Configuration Item | AutoHandleSccp
Section | [SS7]
Written Format | AutoHandleSccp=b
Value Range | b=0: No; b=1: Yes (default).
Description | Sets if the SCCP message is processed by the SynCTI driver.
Note | It requires SynCTI Ver. 4.7.1.7 or above.


3.1.2.28.7.10 Setting Way to Output SS7 MSU


3.1.2.28.7.10.1 GetMsuOnAutoHandle

Configuration Item

GetMsuOnAutoHandle

Section

[SS7]

Written Format

GetMsuOnAutoHandle=b

Value Range

b=0: Not to output the original SS7 MSU in auto call connection which uses the driver’s state machine to process user-level protocols (default);

b=1: Allowed to obtain the original SS7 MSU in auto call connection which uses the driver’s state machine to process user-level protocols.

Description

Sets the way to output SS7 MSU. SS7 MSU。When the driver’s state machine is not used to process user-level protocols, i.e. when the auto call connection is disabled, the driver outputs the original SS7 MSU; when the driver’s state machine is used to process user-level protocols, i.e. when the auto call connection is enabled, the driver’s output of SS7 MSU is determined by the configuration item GetMsuOnAutoHandle.

Note

It requires SynCTI Ver.5.0.3.0 or above. All driver versions published before Ver.5.0.3.0 only support the operation based on GetMsuOnAutoHandle=0.


3.1.2.28.7.11 Setting Way to Handle SS7 MTP2 MSU


3.1.2.28.7.11.1 AppHandleMtp2Msu

Configuration Item | AppHandleMtp2Msu
Section | [SS7]
Written Format | AppHandleMtp2Msu=b
Value Range | b=0: SS7 MTP2 MSU handled by the driver (default); b=1: SS7 MTP2 MSU handled by the application program.
Description | Sets the way to handle SS7 MTP2 MSU.
Note | This configuration item requires SynCTI Ver.5.1.0.0 or above. All driver versions published before Ver.5.1.0.0 only support the operation based on AppHandleMtp2Msu=0.


3.1.2.28.8 Advanced Setting for ISDN


3.1.2.28.8.1 Setting ISDN Processing Mode


3.1.2.28.8.1.1 AutoHandleIsdn

Configuration Item | AutoHandleIsdn
Section | [ISDN]
Written Format | AutoHandleIsdn=b
Value Range | b=0: No; b=1: Yes (default).
Description | Sets whether ISDN messages are processed by the driver-provided ISDN state machine. Refer to the Advanced ISDN Programming Interface section in Chapter 1 for more information.
Note | It is an advanced configuration item, only required to be set when the application wants to process ISDN message by itself.


3.1.2.28.8.2 Setting Parameters for User-side/Network-side Digital Trunk


3.1.2.28.8.2.1 UserCrcMode

Refer to NetCrcMode


3.1.2.28.8.2.2 NetCrcMode

Configuration Item | UserCrcMode NetCrcMode
Section | [ISDN]
Written Format | UserCrcMode[n]=b NetCrcMode[n]=b
Value Range | n: The user-side (UserCrcMode) or network-side (NetCrcMode) digital trunk number b: The switch to control the CRC check b=0: Disable; b=1: Enable.
Description | Sets whether to enable the feature of CRC check for the digital trunk. UserCrcMode is applicable to the user side while NetCrcMode to the network side.
Note | l It is an advanced configuration item; l If the set value of the configuration item TotalUserLinker (assumed as N) is greater than 0, UserCrcMode should be configured for N times; if the set value of the configuration item TotalNetLinker (assumed as N) is greater than 0, NetCrcMode should be configured for N times.


3.1.2.28.8.2.3 UserChIdentify

Refer to NetChIdentify


3.1.2.28.8.2.4 NetChIdentify

Configuration Item | UserChIdentify NetChIdentify
Section | [ISDN]
Written Format | UserChIdentify[n]=k NetChIdentify[n]=k
Value Range | n: The user-side (UserChIdentify) or network-side (NetChIdentify) digital trunk number k: The way to represent the channel identification message k=0x11: In the form of Time Slot Diagram; k=0x10: In the form of Number (default). Note: The default value of k varies on the version of the SynCTI driver: if the driver used is below Ver. 4.7.3.1, the default value of k is 0x11; otherwise, it is 0x10.
Description | Sets the way to represent channel identification messages on the digital trunk. UserChIdentify is applicable to the user side while NetChIdentify to the network side. See the Representation of Channel Identification Message section in Chapter 1 for more information.


3.1.2.28.8.2.5 UserVoiceFormat

Refer to NetVoiceFormat


3.1.2.28.8.2.6 NetVoiceFormat

Configuration Item | UserVoiceFormat NetVoiceFormat
Section | [ISDN]
Written Format | UserVoiceFormat[n]=k NetVoiceFormat[n]=k
Value Range | n: The user-side (UserVoiceFormat) or network-side (NetVoiceFormat) digital trunk number k: The voice CODEC, k=6: A-law (default); k=7: m-law.
Description | Sets the voice CODEC used on the digital trunk. UserVoiceFormat is applicable to the user side while NetVoiceFormat to the network side.


3.1.2.28.8.2.7 UserRestarTime

Refer to NetRestarTime


3.1.2.28.8.2.8 NetRestarTime

Configuration Item | UserRestarTime NetRestarTime
Section | [ISDN]
Written Format | UserRestarTime=t NetRestarTime=t
Value Range | 100≤t≤120, calculated by second, with the default value of 100.
Description | Sets the time for the local end to respond to the link restart command from the remote end, i.e. from the moment the local link receives the link restart command from the remote end until it is successfully restarted. If the link fails to be restarted within the time specified by this configuration item, all channels on relative digital trunks enter into the ‘Unusable’ state (i.e. S_CALL_UNAVAILABLE). UserRestarTime is applicable to the user side while NetRestarTime to the network side.
Note | l It is an advanced configuration item, not required to be set in most cases. l It is applicable to all digital trunks in the system.


3.1.2.28.8.2.9 UserEstablishTime

Refer to NetEstablishTime


3.1.2.28.8.2.10 NetEstablishTime

Configuration Item | UserEstablishTime NetEstablishTime
Section | [ISDN]
Written Format | UserEstablishTime=t NetEstablishTime=t
Value Range | 5≤t≤10, calculated by second, with the default value of 5.
Description | Sets the interval for the driver to establish links between the local and remote ends. If the driver fails to establish links within the time specified by this configuration item, it will automatically start another attempt. UserEstablishTime is applicable to the user side while NetEstablishTime to the network side.
Note | l It is an advanced configuration item, not required to be set in most cases. l It is applicable to all user-side and network-side digital trunks in the system.


3.1.2.28.8.3 Setting Parameters for Outgoing Call


3.1.2.28.8.3.1 UserCalledNoSet

Refer to NetCallingNoSet


3.1.2.28.8.3.2 NetCalledNoSet

Refer to NetCallingNoSet


3.1.2.28.8.3.3 UserCallingNoSet

Refer to NetCallingNoSet


3.1.2.28.8.3.4 NetCallingNoSet

Configuration Item

UserCalledNoSet

NetCalledNoSet

UserCallingNoSet

NetCallingNoSet

Section

[ISDN]

Written Format

UserCalledNoSet[n]=k

NetCalledNoSet[n]=k

UserCallingNoSet[n]=g

NetCallingNoSet[n]=g

Value Range

n: The user-side (UserCalledNoSet, UserCallingNoSet) or network-side (NetCalledNoSet, NetCallingNoSet) digital trunk number

k: The type of number (TON) and numbering scheme, represented by hexadecimal digits.

k=0xa1: National Number (default);

k=0x91: International Number;

k=0xc1: Subscriber Number;

k=0xb1: Specified Number;

k=0x81: Unknown.

g: The type of number (TON) and numbering scheme, represented by hexadecimal digits.

g=0x21: National Number (default);

g=0x11: International Number;

g=0x41: Subscriber Number;

g=0x31: Specified Number;

g=0x01: Unknown.

Description

Sets the type of number (TON) and numbering scheme for the calling and called party numbers in the SETUP message during the outgoing call.

UserCalledNoSet, NetCalledNoSet are used to set called party numbers respectively for the user side and the network side;

UserCallingNoSet, NetCallingNoSet are used to set calling party numbers respectively for the user side and the network side.

Note

l It is an advanced configuration item;

l If the set value of the configuration item TotalUserLinker (assumed as N) is greater than 0, UserCalledNoSet and UserCallingNoSet should be configured for N times; if the set value of the configuration item TotalNetLinker (assumed as N) is greater than 0, NetCalledNoSet and NetCallingNoSet should be configured for N times.


3.1.2.28.8.3.5 UserNumIsFull

Refer to NetNumIsFull


3.1.2.28.8.3.6 NetNumIsFull

Configuration Item | UserNumIsFull NetNumIsFull
Section | [ISDN]
Written Format | UserNumIsFull=b NetNumIsFull=b
Value Range | b=0: No (default); b=1: Yes.
Description | Sets whether the ‘Called Number Complete’ parameter is included in the SETUP message during the outgoing call. UserNumIsFull is applicable to the user side while NetNumIsFull to the network side.
Note | It is an advanced configuration item.


3.1.2.28.8.3.7 UserChPreference

Refer to NetChPreference


3.1.2.28.8.3.8 NetChPreference

Configuration Item | UserChPreference NetChPreference
Section | [ISDN]
Written Format | UserChPreference=b NetChPreference=b
Value Range | b=0: No (default); b=1: Yes.
Description | Sets whether to allow the preferential channel selection. UserChPreference is applicable to the user side while NetChPreference to the network side.
Note | It is an advanced configuration item.


3.1.2.28.8.3.9 UserHighLayerCompatible

Refer to NetHighLayerCompatible


3.1.2.28.8.3.10 NetHighLayerCompatible

Configuration Item | UserHighLayerCompatible NetHighLayerCompatible
Section | [ISDN]
Written Format | UserHighLayerCompatible=b NetHighLayerCompatible=b
Value Range | b=0: No; b=1: Yes (default).
Description | Sets whether the ‘High Layer Compatibility’ field is included in the SETUP message. UserHighLayerCompatible is applicable to the user side while NetHighLayerCompatible to the network side.
Note | It is an advanced configuration item.


3.1.2.28.8.3.11 UserLowLayerCompatible

Refer to NetLowLayerCompatible


3.1.2.28.8.3.12 NetLowLayerCompatible

Configuration Item | UserLowLayerCompatible NetLowLayerCompatible
Section | [ISDN]
Written Format | UserLowLayerCompatible=b NetLowLayerCompatible=b
Value Range | b=0: No; b=1: Yes (default).
Description | Sets whether the ‘Low Layer Compatibility’ field is included in the SETUP message. UserLowLayerCompatible is applicable to the user side while NetLowLayerCompatible to the network side.
Note | It is an advanced configuration item.


3.1.2.28.8.3.13 UserDialTime

Refer to NetDialTime


3.1.2.28.8.3.14 NetDialTime

Configuration Item | UserDialTime NetDialTime
Section | [ISDN]
Written Format | UserDialTime=t NetDialTime=t
Value Range | t: The waiting time, calculated by second, with the default value of 60sec
Description | After the application calls the function SsmPickup or SsmSearchIdleCallOutCh on an ISDN channel, the driver will start a timer. If the application does not start an outgoing call before the timer overflows, the driver will reset the channel back to the idle state and then transfer it to the S_CALL_STANDBY state. This configuration item is used to set the value of this timer. See the ISDN Channel State Machine section in Chapter 1 for more information. UserDialTime is applicable to the user side while NetDialTime to the network side.
Note | It is an advanced configuration item.


3.1.2.28.8.3.15 TransferCapability

Configuration Item | TransferCapability
Section | [ISDN]
Written Format | TransferCapability=n
Value Range | =0: Voice (default) =1: 3.1k audio
Description | Sets the ‘Transfer Capability’ filed in the signaling message
Note | It is an advanced configuration item.


3.1.2.28.8.3.16 PresentNumber

Configuration Item | PresentNumber
Section | [ISDN]
Written Format | PresentNumber =n
Value Range | =0: not allowed to show number =1: allowed to show number (default)
Description | Sets the field that determines if it is allowed to show the calling party number in the signaling message.
Note | It is an advanced configuration item.


3.1.2.28.8.3.17 UserT303

Refer to NetT303


3.1.2.28.8.3.18 NetT303

Configuration Item | UserT303 NetT303
Section | [ISDN]
Written Format | UserT303=t NetT303=t
Value Range | t: The length of time for the timer T303, calculated by second, with the default value of 4sec
Description | Sets the timer T303. UserT303 is applicable to the user side while NetT303 to the network side. See the ISUP Channel State Machine section in Chapter 1 for more information.


3.1.2.28.8.3.19 UserT304

Refer to NetT304


3.1.2.28.8.3.20 NetT304

Configuration Item | UserT304 NetT304
Section | [SS7]
Written Format | UserT304=t NetT304=t
Value Range | t: The length of time for the timer T304, calculated by second, with the default value of 30sec
Description | Sets the timer T304. UserT304 is applicable to the user side while NetT304 to the network side. See the ISUP Channel State Machine section in Chapter 1 for more information.


3.1.2.28.8.3.21 UserWaitAfterCallProceeding

Configuration Item | UserWaitAfterCallProceeding
Section | [ISDN]
Written Format | UserWaitAfterCallProceeding=n
Value Range | n: The waiting time, with the default value of 10s.
Description | Sets the maximum time that the local end waits for the remote end to send back the acknowledgement message in an outgoing call. If the local end doesn’t receive the acknowledgement message from the remote end before timeout, it will actively disconnect the call.
Note | It is an advanced configuration item only used for user-side outgoing calls.


3.1.2.28.8.3.22 UserTxCallingPartyNum

Configuration Item

UserTxCallingPartyNum

Section

[ISDN]

Written Format

UserTxCallingPartyNum = b

Value Range

b=0: Not to send the 6c unit (i.e. the calling party number) in the ISDN User Setup message for an outgoing call;

b=1: Send the 6c unit (i.e. the calling party number) in the ISDN User Setup message for an outgoing call (default).

Description

Sets whether to send the 6c unit (i.e. the calling party number) in the ISDN User Setup message for an outgoing call.


3.1.2.28.8.3.23 NetTxCallingPartyNum

Configuration Item

NetTxCallingPartyNum

Section

[ISDN]

Written Format

NetTxCallingPartyNum = b

Value Range

b=0: Not to send the 6c unit (i.e. the calling party number) in the ISDN Net Setup message for an outgoing call;

b=1: Send the 6c unit (i.e. the calling party number) in the ISDN Net Setup message for an outgoing call (default).

Description

Sets whether to send the 6c unit (i.e. the calling party number) in the ISDN Net Setup message for an outgoing call.


3.1.2.28.8.3.24 NetWaitAfterCallProceeding

Configuration Item | NetWaitAfterCallProceeding
Section | [ISDN]
Written Format | NetWaitAfterCallProceeding =n
Value Range | n: The waiting time, with the default value of 10s.
Description | Sets the maximum time that the local end waits for the remote end to send back the acknowledgement message in an outgoing call. If the local end doesn’t receive the acknowledgement message from the remote end before timeout, it will actively disconnect the call.
Note | It is an advanced configuration item only used for network-side outgoing calls.


3.1.2.28.8.4 Setting Parameters for Incoming Call


3.1.2.28.8.4.1 UserSideDefaultAckTimer

Refer to NetSideDefaultAck


3.1.2.28.8.4.2 UserSideDefaultAck

Refer to NetSideDefaultAck


3.1.2.28.8.4.3 NetSideDefaultAckTimer

Refer to NetSideDefaultAck


3.1.2.28.8.4.4 NetSideDefaultAck

Configuration Item

UserSideDefaultAckTimer

UserSideDefaultAck

NetSideDefaultAckTimer

NetSideDefaultAck

Section

[ISDN]

Written Format

UserSideDefaultAckTimer=t

UserSideDefaultAck=k

NetSideDefaultAckTimer=t

NetSideDefaultAck=k

Value Range

t: The set value of the timer, calculated by second, t<120, with the default value of 20.

k: The driver’s behavior after the timer overflows. Its values and corresponding meanings are shown in the table below.

K | Meaning | Driver’s Behavior
1 | Called party idle | Send the ALERTING message
2 | Called party busy | Send the DISCONNECT message. Reason=Called party busy
4 | Call refused | Send the DISCONNECT message. Reason=Call refused
5 | No answer | Send the DISCONNECT message. Reason=Called party no answer
Others | Spare |

The default value of k is 1.

Description

After the driver receives the complete number in an incoming call, this configuration item is used to set whether the reply message is automatically sent by the driver. Refer to the ISUP Channel State Machine section in Chapter 1 for more information.

UserSideDefaultAckTimer, UserSideDefaultAck are applicable to the user side while NetSideDefaultAckTimer, NetSideDefaultAck to the network side.

Note

It is an advanced configuration item.


3.1.2.28.8.4.5 UserIsReceivePhoNum

Refer to NetIsReceivePhoNum


3.1.2.28.8.4.6 NetIsReceivePhoNum

Configuration Item | UserIsReceivePhoNum NetIsReceivePhoNum
Section | [ISDN]
Written Format | UserIsReceivePhoNum=b NetIsReceivePhoNum=b
Value Range | b=0: Tandem Exchange Mode; b=1: Terminating Office Mode (default).
Description | ² Sets the driver operating mode during an incoming call. For more information, refer to the section Terminating Office Mode vs. Tandem Exchange Mode in Chapter 1. UserIsReceivePhoNum is applicable to the user side while NetIsReceivePhoNum to the network side.
Note | l Usually this configuration item is set to 0 provided the remote PBX is Alcatel or AVAYA; l The configuration item UserTieStationMode supported by earlier versions of our driver has the same function but is only applicable to the user side. Hence it can be replaced by UserIsReceivePhoNum.


3.1.2.28.8.4.7 UserIsSendChIdentify

Refer to NetIsSendChIdentify


3.1.2.28.8.4.8 NetIsSendChIdentify

Configuration Item | UserIsSendChIdentify NetIsSendChIdentify
Section | [ISDN]
Written Format | UserIsSendChIdentify=b NetIsSendChIdentify=b
Value Range | b=0: No (default); b=1: Yes.
Description | Sets whether the channel identification message is included in the corresponding reply message (such as CALL PROCEEDING, ALERT, etc.) after the local end receives the SETUP message from the remote PBX during an incoming call. UserIsSendChIdentify is applicable to the user side while NetIsSendChIdentify to the network side.
Note | Usually this configuration item is set to 1 if the remote PBX is Siemens.


3.1.2.28.8.4.9 UserT302

Refer to NetT302


3.1.2.28.8.4.10 NetT302

Configuration Item | UserT302 NetT302
Section | [ISDN]
Written Format | UserT302=t NetT302=t
Value Range | t: The length of time for the timer T302, calculated by second, with the default value of 15sec
Description | Sets the timer T302. UserT302 is applicable to the user side while NetT302 to the network side. See the ISUP Channel State Machine section in Chapter 1 for more information.


3.1.2.28.8.4.11 UserT313

Configuration Item | UserT313
Section | [ISDN]
Written Format | UserT313=t
Value Range | t: The length of time for the timer T313, calculated by second, with the default value of 4sec
Description | Sets the timer T313. See the ISUP Channel State Machine section in Chapter 1 for more information.
Note | This configuration item is only applicable to the user side.


3.1.2.28.8.4.12 ProgressExt

Configuration Item | ProgressExt
Section | [ISDN]
Written Format | ProgressExt=n
Value Range | n: Progress indicator, with the default value of 0 that implies no progress indicator is included. The value of n is represented by 8 bits. Each bit means as follows. Bit8=1 Bit7, Bit 6=00----ITU-T coding standard Bit5=0----Spare Bit4~ Bit1= 0000----User (U) 0001----Local private network (LPN) 0010----Local public network (LN) 0011----Transfer network (TN) 0100----Remote public network (RLN) 0101----Remote private network (RPN) 1010----Network formed by points except two connected on the SS7 public network (BI)
Description | In an incoming call, if the ALERT or SETUP message is sent by the local end when the value of ProgressExt is not 0, it will contain the progress indicator.
Note | It is an advanced configuration item, only applicable to incoming calls.


3.1.2.28.8.5 Setting Timers


3.1.2.28.8.5.1 UserT305

Refer to NetT306


3.1.2.28.8.5.2 NetT305

Refer to NetT306


3.1.2.28.8.5.3 NetT306

Configuration Item

UserT305

NetT305

NetT306

Section

[ISDN]

Written Format

UserT305=t

NetT305=t

NetT306=t

Value Range

t: The length of time for the timer, calculated by second, with the default value of 30 sec.

Description

Sets the timers T305 and T306. UserT305 is applicable to the user side while NetT305 and NetT306 to the network side.

² To the user side, the driver will start T305 after the local end sends the DISCONNECT message to the remote PBX, and automatically stop it after the local end receives the RELEASE or DISCONNECT message from the remote PBX.

² To the network side, after the local end sends the DISCONNECT message to the remote PBX, the driver will start T306 if the DISCONNECT message contains the progress indicator field and the value of this field is equal to 8, or start T305 otherwise. After the local end receives the RELEASE or DISCONNECT message from the remote PBX, the driver will automatically stop T305 or T306.

Once T305 or T306 overflows, the driver will send the RELEASE message.


3.1.2.28.8.5.4 UserT308

Refer to NetT308


3.1.2.28.8.5.5 NetT308

Configuration Item | UserT308 NetT308
Section | [ISDN]
Written Format | UserT308=t NetT308=t
Value Range | t: The length of time for the timer, calculated by second, with the default value of 4 sec.
Description | Sets the timer T308. UserT308 is applicable to the user side while NetT308 to the network side. The driver will start T308 after the local end sends the RELEASE message to the remote PBX, and automatically stop it after the local end receives the RELEASE or RELEASE COMPLETE message from the remote PBX. If T308 overflows, the driver will resend the RELEASE message.


3.1.2.28.8.6 Setting Other Parameters


3.1.2.28.8.6.1 WaitHangupTime

Configuration Item | WaitHangupTime
Section | [ISDN]
Written Format | WaitHangupTime=b
Value Range | 20<b<10000, calculated by millisecond (ms), with the default value of 1600.
Description | Sets the ISDN pending time.
Note | It is an advanced configuration item.


3.1.2.28.8.6.2 UserStatusReason

Refer to NetStatusReason


3.1.2.28.8.6.3 NetStatusReason

Configuration Item | UserStatusReason NetStatusReason
Section | [ISDN]
Written Format | UserStatusReason=m NetStatusReason=m
Value Range | m=1: 3-byte Format (default); m=0: 2-byte Format
Description | When the local end receives the STATUS ENQUIRY message (for status query) from the remote PBX, the driver will automatically reply by sending the STATUS message. This configuration item specifies the reason field in the STATUS message to use the 2-byte or 3-byte format. Using which format should be determined according to the parameter setting for the remote PBX. UserStatusReason is applicable to the user side while NetStatusReason to the network side.
Note | l It is an advanced configuration item; l It requires SynCTI Ver. 4.7.1.8 or above.


3.1.2.28.8.6.4 EnAutoAlert02

Refer to EnAutoAlert03


3.1.2.28.8.6.5 EnAutoAlert03

Configuration Item

EnAutoAlert02

EnAutoAlert03

Section

[ISDN]

Written Format

EnAutoAlert02=m

EnAutoAlert03=m

Value Range

m=0: This feature disabled (default);

m=1: This feature enabled.

Description

If EnAutoAlert02=1, it indicates the 02 (CALL PROCEEDING) message is received. In such situation, if the progress indicator turns to be 8 or 1, the system will go into the state of auto alert.

If EnAutoAlert03=1, it indicates the 03 (PROGRESS) message is received. In such situation, if the progress indicator turns to be 8 or 1, the system will go into the state of auto alert.

Note

l It is an advanced configuration item;

l It requires SynCTI Ver. 5.2.0.0 or above.


3.1.2.28.9 Setting Way to Use DSP Chip


3.1.2.28.9.1 LoadFskBin

Configuration Item

LoadFskBin

Section

[BoardId=x]

Written Format

LoadFskBin=m

Value Range

m=0: Enhanced Echo Canceller Mode. In this mode, the voice channel is unable to record voices and receive or send FSK data. The DSP resources standing idle are used to enhance the effect of the echo canceller;

m=1: Normal Running Mode (default);

m=2: TS16 Recording Mode. The driver will directly pass the original signaling data from TS16 to the application by recording. When m=1, each on-board DSP chip processes data from 15 voice time slots. Therefore, two DSP chips are needed to process data from the 30 time slots on each digital trunk, one for TS1~TS15 and the other for TS17~TS31. When m=2, the DSP chip previously used to process data from TS17~TS31 will turn to process those from TS16~TS30, and the voice data from TS31 will be abandoned. Note: In such case, the physical channel number 15 corresponds not to TS17, but to TS16. And the same change also happens to the other channels.

Description

Selects the operating mode for DSP chips on the SHD Series boards.

Note

It is an advanced configuration item, only applicable to the 30/60/120-channel SHD Series A-type boards.


3.1.2.29 Common Configuration Item for SHN Series (CTI Series)


3.1.2.29.1 Advanced General Settings for SHN Series


3.1.2.29.1.1 EnableSIPStun

Refer to HeartInterval


3.1.2.29.1.2 SIPStunServerIP

Refer to HeartInterval


3.1.2.29.1.3 LogLevel

Refer to HeartInterval


3.1.2.29.1.4 LogFile

Refer to HeartInterval


3.1.2.29.1.5 EventThreadNum

Refer to HeartInterval


3.1.2.29.1.6 SipCallCheckInterval

Refer to HeartInterval


3.1.2.29.1.7 SendOptionsOutCallIP

Refer to HeartInterval


3.1.2.29.1.8 SendOptionsOutCallInterval

Refer to HeartInterval


3.1.2.29.1.9 HeartInterval

Note: This configuration item is named UdpHeartTime in versions below SynCTI 5.1.0.0.

Configuration Item

EnableSIPStun

SIPStunServerIP

LogLevel

LogFile

EventThreadNum

SipCallCheckInterval

SendOptionsOutCallIP

SendOptionsOutCallInterval

HeartInterval

Section

[SIP]

Written Format

EnableSIPStun=p

SIPStunServerIP=y

LogLevel=m

LogFile=s

EventThreadNum=j

SipCallCheckInterval=n

SendOptionsOutCallIP=k

SendOptionsOutCallInterval=q

HeartInterval=x

Value Range

p: p=0, disable the Stun feature in SIP; p=1, enable the Stun feature in SIP.

y: The IP address of the Stun server in SIP.

m: Sets the output log level. See below for details.

m=1: SEGMENT, serious error (default);

m=2 : FATAL, error in protocol message;

m=3: ERROR, logic error;

m=4: WARNING, logic warning;

m=5: INFO1, logic information

m=6: INFO2, SIP message information;

m=7: INFO3, RTP message information.

s: Sets the output log file, containing less than 256 characters.

j: Sets the size of the thread pool used to get SIP protocol events. The value range is 0<j<6 and the default value is 3.

n: Sets the interval between checks of the remote end’s abnormal hangup, in second. n=0: Not use this feature.

k: Automatically sends the destination IP address of the signaling message options in case of non registration.

q: Sends the time interval of the signaling message options, in second. q=0: Disable this feature.

x: Sets the heartbeat time for the UDP port. The value range is 0≤x≤1000 (ms) and the default value is x=0 (disable the heartbeat).

Description

Sets other parameters.

Note

This item is valid only when the configuration item ProtocolType is set to 1.


3.1.2.29.1.10 SipTransportProtocol
Configuration Item | SipTransportProtocol
Section | [SIP]
Written Format | SipTransportProtocol =z
Value Range | z=1, SIP is used over TCP; z=0, SIP is used over UDP (default).
Description | Sets whether SIP is used over TCP or UDP


3.1.2.29.1.11 UserName

Refer to SipTotalMultiRegNum


3.1.2.29.1.12 RegPassword

Refer to SipTotalMultiRegNum


3.1.2.29.1.13 Domain

Refer to SipTotalMultiRegNum


3.1.2.29.1.14 RegRealm

Refer to SipTotalMultiRegNum


3.1.2.29.1.15 RegExpires

Refer to SipTotalMultiRegNum


3.1.2.29.1.16 RegStartCh

Refer to SipTotalMultiRegNum


3.1.2.29.1.17 RegEndCh

Refer to SipTotalMultiRegNum


3.1.2.29.1.18 SipTotalMultiRegNum

Configuration Item

UserName

RegPassword

Domain

RegRealm

RegExpires

RegStartCh

RegEndCh

SipTotalMultiRegNum

Section

[SIP]

Written Format

UserName[m]=s

RegPassword[m]=j

Domain[m]=x

RegRealm[m]=r

RegExpires[m]=q

RegStartch[m]=o

RegEndCh[m]=e

SipTotalMultiRegNum=n

Value Range

m: Number for the multi-channel operation. It must start from 0, range of value: 0≤m≤n(n is the set value of the configuration item SipTotalMultiRegNum )

s: Username, a string containing up to 50 characters.

When m≠0, s indicates the registered username; when m=0, s indicates the content of the username field in SIP URI.

j: Registered user password.

It is valid only when m≠0, indicating the registered user password.

x: Registered server.

It is valid only when m≠0, indicating the registered server address in the format of host[:port].

q: Period of registration validity. It indicates how often the board refreshes the registration information to the registered server, with the default value of 3600 and the minimum value of 300.

r: Alias of the SIP server.

o: Starting channel number of the multi-channel operation.

e: Ending channel number of the multi-channel operation. The multi-channel registration is invalid when o=e.

n: Times for performing the multi-channel operation. The upper limit is 20.

Description

Using the configuration items to perform the multi-channel registration for n times is equivalent to invoking the function SsmSipMultiChRegister for n times.

Note

This configuration item is valid only when the set value of the configuration item SipTotalMultiRegNum is greater than 0 and less than 20.

Example

Suppose that there is a SHN-60B-CT/PCI+ board installed in the system, the channels that need to be registered are channels 0~19 (registered to 192.168.1.100:5200 under the username of 1001), channels 20~39 (registered to 192.168.1.101:5200 under the username of 1002) and channels 40~59 (registered to 192.168.1.102:5200 under the username of 1001)

[SIP] // in the SIP field

SipTotalMultiRegNum = 3 //indicates the times for performing the multi-channel operation. The upper limit is 20.

//The following three groups of configuration items are parameters respectively for three multi-channel registrations. For detailed information on each configuration item, you can refer to the configuration item of board registration.

//Configuration items for the first multi-channel registration

Domain[0]=192.168.1.100:5200

RegExpires[0]=3600

UserName[0]=1001

RegPassword[0]=1001

RegRealm[0]=

RegStartCh[0]=0 //The starting channel number of the first multi-channel operation. This channel number is decided over the whole program.

RegEndCh[0]=19 //The ending channel number of the first multi-channel operation. This channel number is decided over the whole program.

//Configuration items for the second multi-channel registration

Domain[1]=192.168.1.101:5200

RegExpires[1]=3600

UserName[1]=1002

RegPassword[1]=1002

RegRealm[1]=

RegStartCh[1]=20

RegEndCh[1]=39

//Configuration items for the third multi-channel registration

Domain[2]=192.168.1.102:5200

RegExpires[2]=3600

UserName[2]=1001

RegPassword[2]=1001

RegRealm[2]=

RegStartCh[2]=40

RegEndCh[2]=59


3.1.2.29.2 SHN A Series


3.1.2.29.2.1 Advanced Setting for SHN A Series


3.1.2.29.2.1.1 Setting RTP Traversal through NAT and SIP Server


3.1.2.29.2.1.1.1 EnableRTPStun

Refer to RegRealm


3.1.2.29.2.1.1.2 StunServerIP

Refer to RegRealm


3.1.2.29.2.1.1.3 Register

Refer to RegRealm


3.1.2.29.2.1.1.4 UserName

Refer to RegRealm


3.1.2.29.2.1.1.5 RegPassword

Refer to RegRealm


3.1.2.29.2.1.1.6 Domain

Refer to RegRealm


3.1.2.29.2.1.1.7 RegExpires

Refer to RegRealm


3.1.2.29.2.1.1.8 RegRealm

Configuration Item

EnableRTPStun

StunServerIP

Register

UserName

RegPassword

Domain

RegExpires

RegRealm

Section

[BoardId=x]

Written Format

EnableRTPStun=y

StunServerIP=p

Register=m

UserName=s

RegPassword=j

Domain=x

RegExpires=q

RegRealm=r

Value Range

y: Sets whether to enable the Stun detection in RTP.

p: The IP address of the Stun server in RTP.

m: Indicates whether to enable registration.

m=0: Disable registration;

m≠0: Enable registration.

s: User name, containing up to 50 characters.

When m≠0, s indicates the registered user name; when m=0, s indicates the content of the ‘username’ field in SIP URI.

j: Registered user password

It is valid only when m≠0.

x: Registered server

It is valid and indicates the registered server address in the format of host[:port] only when m≠0.

q: Period of registration validity, indicating how often the board refreshes the registration information to the registered server.

r: Alias of the SIP server.

Description

Sets the SIP server.

Note

This item is valid only when the configuration item ProtocolType is set to 1.


3.1.2.29.3 SHN B Series


3.1.2.29.3.1 Advanced Setting for SHN B Series


3.1.2.29.3.1.1 Setting RTP Traversal through NAT and SIP Server


3.1.2.29.3.1.1.1 EnableRTPStun

Refer to RegRealm


3.1.2.29.3.1.1.2 StunServerIP

Refer to RegRealm


3.1.2.29.3.1.1.3 Register

Refer to RegRealm


3.1.2.29.3.1.1.4 UserName

Refer to RegRealm


3.1.2.29.3.1.1.5 RegPassword

Refer to RegRealm


3.1.2.29.3.1.1.6 Domain

Refer to RegRealm


3.1.2.29.3.1.1.7 RegExpires

Refer to RegRealm


3.1.2.29.3.1.1.8 RegRealm

Configuration Item

EnableRTPStun

StunServerIP

Register

UserName

RegPassword

Domain

RegExpires

RegRealm

Section

[BoardId=x]

Written Format

EnableRTPStun=y

StunServerIP=p

Register=m

UserName=s

RegPassword=j

Domain=x

RegExpires=q

RegRealm=r

Value Range

y: Sets whether to enable the Stun detection in RTP.

p: The IP address of the Stun server in RTP.

m: Indicates whether to enable registration.

m=0: Disable registration;

m≠0: Enable registration.

s: User name, containing up to 50 characters.

When m≠0, s indicates the registered user name; when m=0, s indicates the content of the ‘username’ field in SIP URI.

j: Registered user password

It is valid only when m≠0.

x: Registered server

It is valid and indicates the registered server address in the format of host[:port] only when m≠0.

q: Period of registration validity, indicating how often the board refreshes the registration information to the registered server.

r: Alias of the SIP server.

Description

Sets the SIP server.

Note

This item is valid only when the configuration item ProtocolType is set to 1.


3.1.2.29.3.1.2 Setting RTP Payload


3.1.2.29.3.1.2.1 SizeG711A

Refer to SizeG729


3.1.2.29.3.1.2.2 SizeG711U

Refer to SizeG729


3.1.2.29.3.1.2.3 SizeG729

Configuration Item | SizeG711A SizeG711U SizeG729
Section | [BoardId=x]
Written Format | SizeG711A=m SizeG711U=n SizeG729=x
Value Range | m=20 or m=30 n=20 or n=30 x=20 or x=30
Description | Sets the RTP payload in millisecond. Meanwhile adjusts the voice processing capability of the board. That is, sets how soon to take an RTP packet and how big it is.
Note | l The value must be 20 or 30. If it is filled in with other number or none, the system will regard it as 30ms by default. l These configuration items are applicable only to SHN-B boards.


3.1.2.30 Common Configuration Items for DST Series (REC Series)


3.1.2.30.1 SupplyBoardClockLine
Configuration Item | SupplyBoardClockLine
Section | [BoardId=x]
Written Format | SupplyBoardClockLine=n
Value Range | n: Board number, numbered from 0
Description | Sets the phone line which offers the reference clock. If this configuration item is not set or set with an illegal value, the board will automatically choose the reference clock.
Note | It is an advanced configuration item which is only applicable to the DST Series boards.


3.1.2.30.2 DEventUpdates
Configuration Item | DEventUpdates
Section | [SystemConfig]
Written Format | DEventUpdates=n
Value Range | n=0: Filtrate events (default); n=1: Not to filtrate events.
Description | Works as a switch to control the event filtration, helping the board to filtrate repeated events once it is enabled.
Note | l This configuration item is only applicable to the DST Series boards.


3.1.2.31 Common Configuration Items for ATP Series (REC Series)


3.1.2.31.1 Setting Input Signal Gain


3.1.2.31.1.1 MicGain
Configuration Item | MicGain
Section | [BoardId=x]
Written Format | Format 1: MicGain=g,g,g,g Format 2: MicGain=g,g,g,g,g,g,g,g Format 3: MicGain=g,g,g,g,g,g,g,g,g,g,g,g,g,g,g,g
Value Range | g=0: Normal volume g=1: Increased volume
Description | Sets the gain of input signals on the analog recording channel. If the voice signal comes from the analog phone line, the gain should be set to 0DB (g=0); if it comes from the moving coil microphone, the gain should be set to 20DB (g=1).
Note | l Format 1 is applicable to the ATP Series USB recording box; l Format 2 is applicable to the 8-channel ATP Series boards; l Format 3 is applicable to the 16-channel ATP Series boards.


3.1.2.31.2 Setting Idle Channel’s Capability of Energy Detection


3.1.2.31.2.1 EnableIdleChTA
Configuration Item | EnableIdleChTA
Section | [BoardId=x]
Written Format | Format 1: EnableIdleChTA =b,b,b,b Format 2: EnableIdleChTA =b,b,b,b,b,b,b,b Format 3: EnableIdleChTA =b,b,b,b,b,b,b,b,b,b,b,b,b,b,b,b
Value Range | b=0: Disable this capability (default); b=1: Enable this capability
Description | Sets whether the analog recording channel can detect the energy and receive DTMF digits when it is in an idle state.
Note | l Format 1 is applicable to the ATP Series USB recording box; l Format 2 is applicable to the 8-channel ATP Series boards; l Format 3 is applicable to the 16-channel ATP Series boards.


3.1.2.31.3 Acquiring More Recording Formats


3.1.2.31.3.1 DspCoder
Configuration Item | DspCoder
Section | [BoardId=x]
Written Format | DspCoder=n
Value Range | N=131: Load G.729A coder; N=49: Load GSM coder; N=85: Load MP3 8kbps coder; N=86: Load MP3 16kbps coder.
Description | Sets the coder loaded by an on-board DSP which gives more formats for recording.
Note | l It is an advanced configuration item which is only applicable to the following boards (in bracket list the corresponding codecs supported): SHD-30B-CT/PCI/FJ （G.729A，GSM） SHD-60B-CT/PCI/FJ （G.729A，GSM） DTP-30C/PCI+ （G.729A，GSM，MP3 8kbps，MP3 16kbps） DTP-60C/PCI+ （G.729A，GSM，MP3 8kbps，MP3 16kbps） DTP-120C/PCI+ （G.729A，GSM，MP3 8kbps，MP3 16kbps） DTP-30C/PCIe+ （G.729A，GSM，MP3 8kbps，MP3 16kbps） DTP-60C/PCIe+ （G.729A，GSM，MP3 8kbps，MP3 16kbps） DTP-120C/PCIe+ （G.729A，GSM，MP3 8kbps，MP3 16kbps） ATP-24A-PCI+ （G.729A，GSM，MP3 8kbps，MP3 16kbps） ATP-24A-PCIe+ （G.729A，GSM，MP3 8kbps，MP3 16kbps） DST-24B/PCI+ （G.729A，GSM，MP3 8kbps，MP3 16kbps） DST-24B/PCI+(SSW) （G.729A，GSM，MP3 8kbps，MP3 16kbps） DST-24B/PCIe+ （G.729A，GSM，MP3 8kbps，MP3 16kbps） l It requires SynCTI Ver. 5.0.2.0 or above.


3.1.2.31.4 Setting Prerecord Feature


3.1.2.31.4.1 PrerecordEnable
Configuration Item | PrerecordEnable
Section | [SystemConfig]
Written Format | PrerecordEnable=b
Value Range | b=0: Disable this feature (default); b=1: Enable this feature
Description | Enables or disables the prerecord feature.
Note | l This configuration item is only applicable to the ATP Series boards. l It requires SynCTI Ver. 2.1 or above.


3.1.2.31.4.2 PrerecordMode

Configuration Item

PrerecordMode

Section

[SystemConfig]

Written Format

PrerecordMode=m

Value Range

m=0: Start to write the recording data into the internal buffer when the Barge-in detector detects voice activities;

m=1: Start to write the recording data into the internal buffer when the analog recording channel detects the pickup behavior on the line.

The default value is 0.

Description

Sets the specific way to do prerecording.

Note

l This configuration item is only applicable to the ATP Series boards;

l It requires SynCTI Ver. 2.1 or above.


3.1.2.31.4.3 PrerecordInsertTime
Configuration Item | PrerecordInsertTime
Section | [SystemConfig]
Written Format | PrerecordInsertTime=t
Value Range | 0<t<n, calculated by millisecond (ms), with the default value of 500. The maximum n is decided by RecordBufSize. n= RecordBufSize/16.
Description | When the application starts the task of file recording after the prerecord feature is enabled, this parameter is used to specify the length of time to write the prerecording data into the file.
Note | l This configuration item is only applicable to the ATP Series boards; l It requires SynCTI Ver. 2.1 or above.


3.1.2.31.4.4 PrerecordCodec
Configuration Item | PrerecordCodec
Section | [SystemConfig]
Written Format | PrerecordCodec=m
Value Range | m=1: PCM8; m=6: A-law (default); m=7: μ-law; m=17: IMA ADPCM (only for boards having a hardware encoder); m=49: GSM 6.10; m=85: MP3.
Description | Sets the prerecording CODEC.
Note | l This configuration item is only applicable to the ATP Series boards; l It requires SynCTI Ver. 2.1 or above.


3.1.2.31.5 Detecting Dial Pulse


3.1.2.31.5.1 EnablePulseKeyDetect
Configuration Item | EnablePulseKeyDetect
Section | [SystemConfig]
Written Format | EnablePulseKeyDetect=b
Value Range | b=0: No (default); b=1: Yes.
Description | Sets whether it is necessary to detect the dial pulse.
Note | This configuration item is only applicable to the analog trunk recording channel.


3.1.2.31.6 Setting Maximum Duration of Flash Signal


3.1.2.31.6.1 MaxRecChFlashFilterTime
Configuration Item | MaxRecChFlashFilterTime
Section | [SystemConfig]
Written Format | MaxRecChFlashFilterTime=t
Value Range | t: time duration, calculated by millisecond (ms), with the default value of 200ms
Description | Sets the filter time for a recording channel to judge flash signals. Refer to the Change in Analog Phone Line Voltage section in Chapter 1 for more information.


3.1.2.31.7 Setting Guard Time for Clearing Ringing Signal Counter


3.1.2.31.7.1 RecChClearRingDelayTime
Configuration Item | RecChClearRingDelayTime
Section | [SystemConfig]
Written Format | RecChClearRingDelayTime=t
Value Range | t≥0, calculated by second, with the default value of 0
Description | Sets the guard time for clearing the ringing signal counter after the recording channel detects ringing signals and picks up the call.


3.1.2.31.8 Setting Soft-switch Feature


3.1.2.31.8.1 BusPlayListen
Configuration Item | BusPlayListen
Section | [SystemConfig]
Written Format | BusPlayListen=b
Value Range | b=0: Disable data exchange via CT-Bus (i.e. enable the soft-switch feature); b=1: Enable data exchange via CT-Bus (default).
Description | Sets whether the driver will enable data exchange via CT-Bus. This item is invalid to boards without CT-bus, such as the ATP series, and in such case, the soft-switch feature will instead be enabled automatically. Refer to the Operation Principle of ATP Series section in Chapter 1 for more information.
Note | l When BusPlayListen=0, GsmCodecEnable=0 will be invalid and the driver will load the record/playback software engine to support the monitoring in compressed format.


3.1.2.31.9 Setting MF detector


3.1.2.31.9.1 MFDualAndAllFreqEnScale
Configuration Item | MFDualAndAllFreqEnScale
Section | [BoardId=x]
Written Format | HighAndLowFreqEnScale=m
Value Range | 0≦m(%)≦100, with the default value of 32
Description | Sets the threshold value in percentage for the rate of MF in-band energy to overall energy
Note | This configuration item is only applicable to the ATP series.


3.1.2.31.9.2 MFFreqOffset
Configuration Item | MFFreqOffset
Section | [BoardId=x]
Written Format | MFFreqOffset=m
Value Range | 0≦m(%)≦30, with the default value of 15
Description | Sets the maximum offset error of the MF signal (offset error = (detected frequency – standard frequency)*1024 / detected frequency).
Note | This configuration item is only applicable to the ATP series.


3.1.2.31.9.3 DTMFFreqOffset
Configuration Item | DTMFFreqOffset
Section | [BoardId=x]
Written Format | DTMFFreqOffset=m
Value Range | 0≦m(%)≦30, with the default value of 15
Description | Sets the maximum offset error of the DTMF signal (offset error = (detected frequency – standard frequency)*1024 / detected frequency).
Note | This configuration item is only applicable to the ATP series.


3.1.2.32 Common Configuration Items for DTP Series (REC Series)


3.1.2.32.1 Saving Monitoring Message to File

Refer to 3.1.3.5 Setting SS1 Monitoring Log, 3.1.3.6 Setting SS7 Monitoring Log, 3.1.3.7 Setting ISDN Monitoring Log, 3.1.3.8 Setting Control Information for Log Creating.


3.1.2.32.2 Setting Signaling Message Output by SS7 State Machine


3.1.2.32.2.1 bOpenSpySS7Msu
Configuration Item | bOpenSpySS7Msu
Section | [SS7Spy]
Written Format | bOpenSpySS7Msu=b
Value Range | b=0: No (default); b=1: Yes.
Description | Sets whether the ISUP/TUP call state machine provided by the SynCTI driver will output original ISUP/TUP messages to the application while processing them. See the section Operation Principle of DTP Series in Chapter 1 for more information.
Note | l This configuration item is only applicable to the DTP Series boards based on SS7 protocol; l It requires SynCTI Ver. 4.7.2.0 or above.


3.1.2.32.3 Supporting CorNet Protocol for ISDN Monitoring


3.1.2.32.3.1 ISDNProtocolType
Configuration Item | ISDNProtocolType
Section | [SpyPcm]
Written Format | ISDNProtocolType=b
Value Range | b=0: No (default); b=1: Yes.
Description | Sets whether to support the CorNet protocol for ISDN monitoring (this protocol is similar to ISDN Q.931).
Note | l This configuration item is only applicable to those DTP Series boards using ISDN signaling; l It requires SynCTI Ver.5.1.0.0 or above.


3.1.3 Advanced Configuration Items


3.1.3.1 Multi-program Support


3.1.3.1.1 MultiCardMultiProcess
Configuration Item | MultiCardMultiProcess
Section | [SystemConfig]
Written Format | MultiCardMultiProcess=b
Value Range | b=0: No (default); b=1: Yes
Description | Sets whether the SynCTI driver supports more than one application program running at the same time.


3.1.3.2 Outputting API Debugging Information


3.1.3.2.1 ApiLogEnable
Configuration Item | ApiLogEnable
Section | [DebugView]
Written Format | ApiLogEnable =b
Value Range | b = 1: Output API function calls information to DebugView; b = 2: Output API function calls information to the LOG file; b = 3: Output events information to the LOG file; b = 4: Output both API function calls and events information to the LOG file; b = 5: Output both API function calls and events information to the DebugView file; b<1 or b>5 (default): Not output information.
Description | Sets whether to output API function calls information or not. If the driver is allowed to output API function calls information, it will output such information as the name, the parameter of each API function invoked by the application as well as the result of the function call, in the form of strings. See the Driver-provided Debugging Feature section in Chapter 1 for more information.
Note | l Since this feature is enabled at the expense of the host CPU cost, usually it is only used in debugging application programs. Disable this feature once the application system is put into formal running.


3.1.3.2.2 ApiLogSetEventRange

Configuration Item

ApiLogSetEventRange

Section

[DebugView]

Written Format

ApiLogSetEventRange =n..m

Value Range

n: The start number of events to be written into LOG. n=-1(default) indicates all events with the number <=m should be output;

m: The end number of events to be written into LOG. m=-1(default) indicates all events with the number >=n should be output.

Description

Sets the event range for logging. Each output event with the number between n and m (including n and m) will be written into the LOG file. If both n and m are equal to -1, it means all output events should be written into the LOG file.

Note

This configuration item becomes effective only when ApiLogEnable is set to output to LOG.


3.1.3.2.3 ApiLogSetChRange

Configuration Item

ApiLogSetChRange

Section

[DebugView]

Written Format

ApiLogSetChRange =n..m

Value Range

n: The start channel number for logging API function calls and output events. n=-1(default) indicates the channel range is <=m.

m: The end channel number for logging API function calls and output events. m=-1(default) indicates the channel range is >=n.

Description

Sets the range of channels where API function calls and output events should be written into the log. All API function calls and output events on the channel whose number is between n and m (including n and m) will be written into the LOG file. If both n and m are equal to -1, it means API function calls and output events on all channels should be written into the LOG file.

Note

This configuration item becomes effective only when ApiLogEnable is set to output to LOG.


3.1.3.2.4 ApiLogCreateMode
Configuration Item | ApiLogCreateMode
Section | [DebugView]
Written Format | ApiLogCreateMode =n
Value Range | n=0: All channel information written into a log file (default) n=1: Each channel has an independent log file.
Description | Sets the way to create logs for API functions and events.
Note | This configuration item becomes effective only when ApiLogEnable is set to output to LOG.


3.1.3.2.5 Mask_SsmGetNoSoundTime

Refer to Mask_SsmGetRecOffset


3.1.3.2.6 Mask_SsmGetChStateKeepTime

Refer to Mask_SsmGetRecOffset


3.1.3.2.7 Mask_SsmGetPlayedTime

Refer to Mask_SsmGetRecOffset


3.1.3.2.8 Mask_SsmGetPlayedPercentage

Refer to Mask_SsmGetRecOffset


3.1.3.2.9 Mask_SsmGetPlayOffset

Refer to Mask_SsmGetRecOffset


3.1.3.2.10 Mask_SsmGetRecTime

Refer to Mask_SsmGetRecOffset


3.1.3.2.11 Mask_SsmGetRecOffset
Configuration Item | Mask_SsmGetNoSoundTime Mask_SsmGetChStateKeepTime Mask_SsmGetPlayedTime Mask_SsmGetPlayedPercentage Mask_SsmGetPlayOffset Mask_SsmGetRecTime Mask_SsmGetRecOffset
Section | [DebugView]
Written Format | Mask_SsmGetNoSoundTime=b Mask_SsmGetChStateKeepTime=b Mask_SsmGetPlayedTime=b Mask_SsmGetPlayedPercebtage=b Mask_SsmGetPlayOffset=b Mask_SsmGetRecTime=b Mask_SsmGetRecOffset=b
Value Range | b=0: Not output (default); b=1: Output
Description | Sets whether the driver will output debugging information of some query API functions or not. In the name of this configuration item, the string following ‘Mask_’ is just the function name. See the Driver-provided Debugging Feature section in Chapter 1 for more information.
Note | This configuration item becomes effective only when the ‘Debugging Information Output’ feature is enabled via the configuration item EnableDebugAPI.


3.1.3.3 Setting ISDN Connection Log


3.1.3.3.1 IsdnLogEnable
Configuration Item | IsdnLogEnable
Section | [DebugView]
Written Format | IsdnLogEnable =n
Value Range | =0: Not output (default); =1: Output to the LOG file; =2: Output to DebugView.
Description | Sets whether to record a frame of messages on the data link layer of ISDN protocol.


3.1.3.3.2 DecodeIsdnMsg
Configuration Item | DecodeIsdnMsg
Section | [DebugView]
Written Format | DecodeIsdnMsg=b
Value Range | b=0: No (default); b=1: Yes.
Description | Sets whether to decode ISDN messages before outputting ISDN debugging messages. The original ISDN messages use binary system, not easy to read. The decoded ISDN messages are in text format, easy to read, applicable to both network and user sides.


3.1.3.3.3 IsdnDebugLog
Configuration Item | IsdnDebugLog
Section | [ISDN]
Written Format | IsdnDebugLog=b
Value Range | b=0: No (default); b=1: Yes.
Description | Sets whether to output ISDN debugging information on condition that IsdnLogEnable is enabled so that developers can monitor the running results. If IsdnLogEnable is disabled, no information will be output.


3.1.3.4 Setting SS1 Connection Log


3.1.3.4.1 Ss1LogEnable
Configuration Item | Ss1LogEnable
Section | [DebugView]
Written Format | Ss1LogEnable=n
Value Range | =0: Not output (default); =1: Output to the LOG file; =2: Output to DebugView.
Description | Sets whether to output received and sent ABCD codes and R2 to the log file.


3.1.3.4.2 Ss1LogCreateMode
Configuration Item | Ss1LogCreateMode
Section | [DebugView]
Written Format | Ss1LogCreateMode=b
Value Range | b=0: All channel information written into a log file (default); b=1: Each channel has an independent log file.
Description | Sets the way to create logs for SS1 connection.
Note | This configuration item becomes effective only when Ss1LogEnable is set to output to LOG.


3.1.3.5 Setting SS1 Monitoring Log


3.1.3.5.1 SpySs1LogEnable
Configuration Item | SpySs1LogEnable
Section | [DebugView]
Written Format | SpySs1LogEnable=n
Value Range | =0: Not output (default); =1: Output to the LOG file; =2: Output to DebugView.
Description | Sets whether to output information about SS1 CAS and R2 that the driver receives to the log file.


3.1.3.5.2 SpySs1CreateMode
Configuration Item | SpySs1CreateMode
Section | [DebugView]
Written Format | SpySs1CreateMode=b
Value Range | b=0: All channel information written into a log file (default); b=1: Each channel has an independent log file.
Description | Sets the way to create logs for SS1 monitoring.
Note | This configuration item becomes effective only when SypSs1LogEnable is set to output to LOG.


3.1.3.6 Setting SS7 Monitoring Log


3.1.3.6.1 SpySs7LogEnable
Configuration Item | SpySs7LogEnable
Section | [DebugView]
Written Format | SpySs7LogEnable=n
Value Range | =0: Not output (default); =1: Output to the LOG file; =2: Output to DebugView.
Description | Sets whether to output the SS7-related information that the driver receives to the LOG file.


3.1.3.7 Setting ISDN Monitoring Log


3.1.3.7.1 SpyIsdnLogEnable
Configuration Item | SpyIsdnLogEnable
Section | [DebugView]
Written Format | SpyIsdnLogEnable=n
Value Range | =0: Not output (default); =1: Output to the LOG file; =2: Output to DebugView.
Description | Sets whether to output the ISDN-related information that the driver receives to the LOG file.


3.1.3.8 Setting PCM Link Information Monitoring Log


3.1.3.8.1 PcmLinkInfoLogEnable
Configuration Item | PcmLinkInfoLogEnable
Section | [DebugView]
Written Format | PcmLinkInfoLogEnable =n
Value Range | =0: Not output (default); =1: Output to the LOG file; =2: Output to DebugView.
Description | Sets whether to record the information about the link sync, the local-end impedance, E1/T1 and CRC-4.


3.1.3.9 Setting Control Information for Log Creating


3.1.3.9.1 LogCreatePeriod

Configuration Item

LogCreatePeriod

Section

[DebugView]

Written Format

LogCreatePeriod=n

Value Range

n>0, calculated by hour, with the default value of 24 hours.

Description

Sets the period to create a log.

Note

This configuration item is valid only to the following logs.

Log Type | Definition
ShCtiApiLog | Records information about API function calls and events thrown out by the driver.
ShCtiSs1Log | Records received and sent ABCD codes and R2
ShCtiIsdnLog | Records a frame of messages on the data link layer of ISDN protocol
ShCtiSpySs7Log | Records a frame of messages that the driver receives
ShCtiSpySs1Log | Records information about SS1 CAS and R2 that the driver receives
ShCtiSpyIsdnLog | Records a frame of messages that the driver receives


3.1.3.9.2 LogMaxKeep

Configuration Item

LogMaxKeep

Section

[DebugView]

Written Format

LogMaxKeep=n

Value Range

n>0 or n=-1. The default setting is n=7.

Description

When the number of generated log files is greater than the set value of this parameter, the first generated files will be deleted automatically. If n=-1, it means there is no limit on the number to save log files and no log files will be deleted.

Note

This configuration item is valid only to the following logs.

Log Type | Definition
ShCtiApiLog | Records information about API function calls and events thrown out by the driver.
ShCtiSs1Log | Records received and sent ABCD codes and R2
ShCtiIsdnLog | Records a frame of messages on the data link layer of ISDN protocol
ShCtiSpySs7Log | Records a frame of messages that the driver receives
ShCtiSpySs1Log | Records information about SS1 CAS and R2 that the driver receives
ShCtiSpyIsdnLog | Records a frame of messages that the driver receives


3.1.3.9.3 LogMaxPeriod

Configuration Item

LogMaxPeriod

Section

[DebugView]

Written Format

LogMaxPeriod=n

Value Range

n>0 or n=-1. The default setting is n=30.

Description

When the number of log generating periods reaches the set value of this parameter, the log output will be stopped automatically. If n= -1, it means there is no limit on the number to generate log files.

Note

This configuration item is valid only to the following logs.

Log Type | Definition
ShCtiApiLog | Records information about API function calls and events thrown out by the driver.
ShCtiSs1Log | Records received and sent ABCD codes and R2
ShCtiIsdnLog | Records a frame of messages on the data link layer of ISDN protocol
ShCtiSpySs7Log | Records a frame of messages that the driver receives
ShCtiSpySs1Log | Records information about SS1 CAS and R2 that the driver receives
ShCtiSpyIsdnLog | Records a frame of messages that the driver receives


3.1.3.9.4 LogFilePath

Configuration Item

LogFilePath

Section

[DebugView]

Written Format

LogFilePath=S

Value Range

S is the path to save the log file. The default setting is the working directory of the current application.

Description

The path to save logs. Note that it must be a path already existing, such as ‘D:\’, or the function call will fail. If it is set to null, the log will be saved to the current working path; if it is set to a name, a folder with such name will be created under the current working path to save the log.

Note

This configuration item is valid only to the following logs.

Log Type | Definition
ShCtiApiLog | Records information about API function calls and events thrown out by the driver.
ShCtiSs1Log | Records received and sent ABCD codes and R2
ShCtiIsdnLog | Records a frame of messages on the data link layer of ISDN protocol
ShCtiSpySs7Log | Records a frame of messages that the driver receives
ShCtiSpySs1Log | Records information about SS1 CAS and R2 that the driver receives
ShCtiSpyIsdnLog | Records a frame of messages that the driver receives


3.1.3.9.5 LogOverWrite

Configuration Item

LogOverWrite

Section

[DebugView]

Written Format

LogOverWrite=n

Value Range

n=0: The old content of the log will not be overridden but be appended with new content upon application restart;

n=1: The old content of the log will be overridden upon application restart (default).

Description

Sets whether to override the old content of the log upon application restart.

Note

This configuration item is valid only to the following logs.

Log Type | Definition
ShCtiApiLog | Records information about API function calls and events thrown out by the driver.
ShCtiSs1Log | Records received and sent ABCD codes and R2
ShCtiIsdnLog | Records a frame of messages on the data link layer of ISDN protocol
ShCtiSpySs7Log | Records a frame of messages that the driver receives
ShCtiSpySs1Log | Records information about SS1 CAS and R2 that the driver receives
ShCtiSpyIsdnLog | Records a frame of messages that the driver receives


3.1.3.9.6 CreateDumpWhenCrash

Configuration Item

CreateDumpWhenCrash

Section

[SystemConfig]

Written Format

CreateDumpWhenCrash=n

Value Range

n=0: Not to create a dump file when the driver crashes;

n=1: Create a dump file when the driver crashes (default).

Description

Sets whether to enable the feature of creating a dump file when the driver crashes.

If the driver crashed in Windows, a dump file named ‘Crash-yyyymmdd(date)-hhmmss(time).dmp’ would be generated under the current directory of the application. At the VC platform, the dump file would be output when either the application or the driver runs illegal; at other platforms in Windows, the dump file would be output only when the driver runs illegal. This feature is unsupported in Windows 2000 and below.

If the driver crashed in Linux, a file named ‘core.PID’ (PID: Process Identifier) would be generated under the current directory of the application.


3.2 Preload Voice Configuration File ShIndex.ini (CTI Series)


3.2.1 [System] Section


3.2.1.1 MaxIndexSeg

Configuration Item | MaxIndexSeg
Section | [System]
Written Format | MaxIndexSeg=n
Value Range | 0≤n≤65535, with the default value of 0. (Note: The value of ‘n×the total number of channels×306’ must be less than the physical memory, otherwise the initialization would fail.)
Description | Sets the total number of preload voice segments on a single channel.
Note | MaxIndexSeg determines the number of [SegNo=x] sections.


3.2.2 [SegNo=x] Section

It is used to set the file information of each voice segment used for memory playback by index. x is the segment number. More than one [SegNo=x] section should be configured if there are many voice segments available.


3.2.2.1 FileName

Configuration Item

FileName

Section

[SegNo=x]

Written Format

FileName=s

Value Range

s is the name of the file which contains voice segments, being either the standard wav file or the non-header file. If it is the standard wav file, the format specified by the configuration item CodecFormat will be ignored; otherwise, it is regarded as the non-header file, using the CODEC designated by the configuration item CodecFormat.

If the full path is not specified, the driver will search for this file under the current directory of the application.

Description

Sets the voice file name.

Example

FileName=d0.wav


3.2.2.2 Alias

Configuration Item | Alias
Section | [SegNo=x]
Written Format | Alias=s
Value Range | s is an alias with the length not exceeding 20 characters. It does not accept the digits ‘0’ ~ ‘9’ as the initial character. The value being null indicates no alias is specified. The default value is null.
Description | Allocates aliases to voice segments.
Example | Alias=D0


3.2.2.3 CodecFormat

Configuration Item | CodecFormat
Section | [SegNo=x]
Written Format | CodecFormat=n
Value Range | n=6: A-Law (default)； n=7: µ-Law； n=17: IMA ADPCM。
Description | Sets the voice CODEC.
Note | All preload voice segments should have the same CODEC.


3.2.2.4 StartOffset

Configuration Item | StartOffset
Section | [SegNo=x]
Written Format | StartOffset=n
Value Range | n: The start position offset of the voice segment in the file, calculated by byte, with the default value of 0. While using ADPCM format, it should be set to the multiple of 256.
Description | Sets the position among voice data in the file where the voice segment is counted from. In the standard wav file, the value being 0, the segment is counted from the first data byte following the file header; in the non-header file, the segment is counted from the top of the file.


3.2.2.5 Length

Configuration Item

Length

Section

[SegNo=x]

Written Format

Length=n

Value Range

n: The length of the voice segment, calculated by byte, with the default value of -1.

Description

Sets the data length of this voice segment. The conversion ratio between the data length and the time length varies on the CODEC. See the SynCTI Supported CODECs section in Chapter 1 for details.

Note

l If this parameter is set greater than the length of data from the configuration item StartOffset to the end of the file, the length of the voice segment actually loaded is just the value of StartOffset;

l Length being set to -1 indicates the loaded voice segment fills the space from lStartPos to the end of the file.


4 SS7 (CTI Series)


4.1 Basic Concepts


4.1.1 OPC & DPC

Signaling Point (SP) is a node in a signaling network that either originates and receives signaling messages, or transfers signaling messages from one signaling link to another, or both. The signaling point that originates messages is called Originating Point Code (OPC), set in the configuration item OPC; the signaling point that receives messages is called Destination Point Code (DPC). Both OPC and DPC are configured in the file Ss7Server.ini for the SS7 server.

There exist two encoding formats for signaling points: International Signaling Point Code (ISPC) Format and National Signaling Point Code (NSPC) Format in China. As to the international signaling point code, CCITT suggests using the14-bit format. See below for the grouping of the ISPC bits.

3bit | 8bit | 3bit
ZONE | AREA | POINT

The national signaling point code in China uses the 24-bit format, grouped as follows.

8bit | 8bit | 8bit
MAIN AREA | SUBAREA | POINT

The Synway SHD Series boards support both International Signaling Point Code (ISPC) Format and National Signaling Point Code (NSPC) Format in China, configurable via the configuration item SpCodeLen.


4.1.2 Associated Mode & Quasi-associated Mode

Directly connecting the signaling links between two signaling points to transmit the inbetween signaling messages is called Associated Mode.

Connecting two or more than two signaling links serially via one or more than one signaling transport points to transmit signaling messages, provided the path of signaling messages through the signaling network is predetermined and fixed within a certain period of time, is called Quasi-associated Mode.

These two concepts are vividly illustrated below.

The SynCTI driver supports both the associated mode and the quasi-associated mode, which can be set via the configuration items MaxDPC/DPC and MaxUP_DPC/UP_DPC. See the SS7 Server Configuration section in this chapter for more information.


4.1.3 Signaling Link & Signaling Link Set

The link used to transmit signaling messages between two signaling points is called Signaling Link; a group of links used to connect two signaling points directly constitute a signaling link set.

The SynCTI driver supports up to 48 signaling link sets, configurable via the configuration items MaxLinkSet and LinkSet. Each signaling link set supports up to 16 64kbps signaling links, which can be set via the configuration items MaxSs7Pcm and Ss7PcmLink. While 16 signaling links are included in a signaling link set, they will work in a load sharing mode.

The SS7 server is allowed to connect with up to 48 signaling points or signaling transport points.


4.2 SS7 Application System Based on Synway Board

The SynCTI driver assigns the SS7 service to the application by the SS7 server. The application program serves as the Client program, without limitation on the quantity and physical environment. It is acceptable that one or more application programs run in one or more computers, or run with the SS7 server in a same computer.

The SS7 server supports the connectivity of the local signaling point with other signaling points, providing the signaling service for the digital trunks which are compliant with China SS7 protocol. The relationship among the signaling link, the signaling link set, DPC/OPC and the signaling route is shown in the figure below.

Features of this SS7 server:

Ø A digital trunk can transmit both signaling messages and voice information simultanously. Usually TS16 is used to transport signaling messages while other 30 time slots (TS 1~15 and TS 17~31) to transmit voice information.

Ø Each signaling link set contains up to 16 64kbps signaling links which work in the load sharing mode. The load management is automatically performed by the server itself.

Ø The local signaling point is allowed to connect with up to 48 SP or STP. In direction connection, however, only 1 signaling link set (i.e. 1 signaling route) can be used between the local point and the other signaling points.

Ø Uses the C/S setup which is available via the distributed signaling link/client connectivity supported by the TCP/IP protocol. Network cards are not necessary for a single computer system (the server and the on-board signaling links are involved in a same computer).

Ø If the SS7 server has physical signaling links in it, it will automatically load the SynCTI driver for the SHD Series boards upon the start. Note: In such case, the voice time slots on the digital trunk cannot be used as voice paths.

The SS7 server includes the following files.

Ss7Server.ini | Configuration file for the SS7 server
Ss7Monitor.exe | Main program of the SS7 server
Ss7Server.dll | The scheduling component for SS7 signaling
Mtp3.dll | The MTP3 component in the SS7 server
TcpServer.dll | SS7 Server-to-Client Communication Component 1
MmfServer.dll | SS7 Server-to-Client Communication Component 2


4.3 SS7 Server Configuration

The executive program of the SS7 server is Ss7Monitor.exe, and the configuration file it uses is Ss7server.ini.

Run Ss7Monitor.exe and the following interface appears:

There are seven status bars and a button selection area in the interface.

1. ①②: Receive/transmit message list

This program displays the received and sent messages respectively in the above windows ① and ②. However, what kind of messages shall be displayed are determined by which options are selected in the button selection area ⑧:

l Display sent message: Display the message sent to the remote end only if ticked.

l Display received message: Display the message received from the remote end only if ticked.

l Display SNT message: Display the SNT message when ticked

l Display SNM message: Display the SNM message when ticked

l Auto translate: Automatically translate the received/sent message when ticked; otherwise display the received/sent data originally in the hexadecimal format.

l Write-to-file: Output the displayed message to the file with the name ‘msu_rcv + number’ or ‘msu_send + number’ only if ticked.

l Display DPC and OPC: Display DPC and OPC only if ticked

When “Auto translate” is ticked, all receive/transmit messages are usually in the following format:

Time Total number Signaling link number# SIO Content

For the TUP message, SIO is just ‘TUP’ (0x84), followed by the message content. It is usually in the following format:

Title code CIC=PCM:TS Message body

2. ③: Linkset/signaling link information

This window shows the information about signaling links and link sets.

l Linkset: Linkset number, from Section [LinkSetInfo] in the configuration file Ss7Server.ini.

l Linkset state: Working state of linkset, including ‘Service On’ and ‘Service Interrupt’. A signaling linkset will go into the state ‘Service On’ as long as a link in it is at the state of ‘Service On’.

l Link@physical position: Signaling link number and its physical position. For example, ‘0 @ IP[0]:PCM[0]’ means the physical position of Link 0 in this gateway is the E1 with the local PCM numbered 0 on Client 0. This example comes from the configuration file Ss7Server.ini, Section [Ss7PcmLinkInfo].

l Network: Whether the signaling link is registered to the program, including two states ‘Connected’ and ‘Disconnected’ (or no display). The signaling link can be used normally only in the state of ‘Connected’.

l Sync: Basic frame Synchronization (Timeslot 0), including two states ‘Synchronous’ and ‘Asynchronous’. The signaling link can be used only in the state of ‘Synchronous’.

l State time: A time period since the last time the signaling link enters into the state of ‘Service On’.

l Position: How many times of positioning that occurs on the signaling link after the program starts.

l Send MSU: Total number of messages sent on the signaling link after the program starts.

l Receive MSU: Total number of messages received on the signaling link after the program starts.

l Switchover MSU: Total number of messages switched over on the signaling link after the program starts.

3. ④: Client Information

This window displays the client IP address and the connection state which are from the configuration file Ss7Server.ini, Section [Ss7ClientInfo].

l Client: Client number

l IP address: IP address of the client

l Network: Whether the client has been successfully connected to the program

4. ⑤: DPC Information

This window displays the DPC information configured by the program which is from the configuration file Ss7Server.ini, Section [DPCInfo].

l DPC#: DPC number which starts from 0

l DPC code: Destination point code, allocated by the central office

l DPC state: Indicates whether the route to this signaling point is available, involving two states ‘Service On’ and ‘Service Interrupt’. The message can be sent to the DPC only when the route to the signaling point is at the state of ‘Service On’. The DPC will turn into the state of ‘Service On’ as long as one of the linksets reaching the DPC is at the state of ‘Service On’.

l DPC route table: Route to the DPC, i.e. linkset number.

5. ⑥: Link information

This status bar displays the detailed information on the state of all signaling links, usually used for searching the cause for service interrupt on a signaling link.

Link# | STA | L2 | POC | LSC | FSN | ERR | CHO
Link Number | Link States 0-6 | Link Failure Causes (interrupt) | Processor Failures 0-3 | Live Communication Server Service 0-1 | Forward Sequence Number | spare | spare
 | 0: uploaded but not started | 0: normal | 0: normal | 0: service is unavailable |  |  |
 | 1: service interrupt | 1: BSNR illegal | 1: the local end processor failure | 1: service is available |  |  |
 | 2: initial positioning | 2: FIBR illegal | 2: the remote end processor failure |  |  |  |
 | 3: positioned/ ready | 3: T2 timeout | 3: both ends processor failure |  |  |  |
 | 4: positioned/ not ready | 4: T6 timeout, the remote end busy |  |  |  |  |
 | 5: service on | 5: L3 sends a command to stop |  |  |  |  |
 | 6: processor failure | 6: signaling error rate too high |  |  |  |  |
 |  | 7: during the course of initial positioning, fail to enter a normal position |  |  |  |  |
 |  | 8: Timer 1 timeout |  |  |  |  |
 |  | 9: positioned and ready, receive the interrupt signal of the remote end |  |  |  |  |
 |  | 10: positioned but not ready, receive the interrupt signal of the remote end |  |  |  |  |
 |  | 11: in the state of Service On, receive the interrupt signal of the remote end |  |  |  |  |
 |  | 12: in a processor failure, receive the interrupt signal of the remote end |  |  |  |  |

6. ⑦: Run log

This log records all MTP3 commands and all error information that pops up during the operation.

This status bar displays the log records generated after the program starts.


4.3.1 Setting Signaling Point Code


4.3.1.1 OPC

Configuration Item | OPC
Section | [Ss7SystemConfig]
Written Format | OPC=a.b.c
Value Range | A: Main area code, represented by decimal digits; B: Subarea code, represented by decimal digits; C: Point code, represented by decimal digits.
Description | Sets the signaling point code for the SS7 server which is usually allocated by the central office.
Note | It is an essentially configured item
Example | OPC=1.2.13


4.3.1.2 SpCodeLen

Configuration Item | SpCodeLen
Section | [Ss7SystemConfig]
Written Format | SpCodeLen=n
Value Range | n: Signaling point code format n=24 (default): Uses National Signaling Point Code Format in China n=14: Uses International Signaling Point Code Format
Description | Sets the signaling point code format.
Note | Users in China don't need to configure this item.


4.3.2 Setting IP Address


4.3.2.1 ServerIP

Refer to SecondServerIP


4.3.2.2 SecondServerIP

Configuration Item | ServerIP SecondServerIP
Section | [Ss7SystemConfig]
Written Format | ServerIP=a.b.c.d SecondServerIP=a.b.c.d。
Value Range | a.b.c.d: IP address. The default value of ServerIP is 127.0.0.1.
Description | Sets the IP address of the SS7 server: ServerIP is used to set the IP address for the SS7 server itself while SecondServerIP is used to set the IP address for the back-up server.
Note | There is no need to set SecondServerIP if only one server is used. In case SecondServerIP is configured, the SS7 server must be started in the warm back-up mode.


4.3.2.3 Port

Configuration Item | Port
Section | [Ss7SystemConfig]
Written Format | Port=n
Value Range | n: Port number, with the default value of 5150.
Description | Sets the monitoring port number of the SS7 sever.
Note | There is no need to configure this item if only one server is used.


4.3.3 Setting Operating Mode and Parameters for MTP3 Layer


4.3.3.1 ConfigMtp3AsSTP

Configuration Item | ConfigMtp3AsSTP
Section | [Ss7SystemConfig]
Written Format | ConfigMtp3AsSTP=m
Value Range | m=0: Signaling point (default). The driver will check whether the DPC of a signaling link set conforms to its OPC at the MTP3 layer. m=1: Signaling transport point. The driver will not examine the DPC at the MTP3 layer.
Description | Sets the operating mode of MTP3 in the SS7 server.


4.3.3.2 SendSNT

Configuration Item | SendSNT
Section | [Ss7SystemConfig]
Written Format | SendSNT=n
Value Range | n=0: not send (default) n=1: send
Description | Sets parameters for MTP3: whether to regularly send Signaling Link Test Message (SLTM) to the remote PBX.


4.3.3.3 SubServicefield

Configuration Item | SubServicefield
Section | [Ss7SystemConfig]
Written Format | SubServicefield=0xn
Value Range | n: The subservice code, represented by hexadecimal digits, the 4 lower bits being valid (Bit3~Bit0 are respectively marked as DCBA): DC: Network Indicator 00: International Network 01:Spare International Network 10: National Network 11: Spare National Network BA: Spare. The default value of n is 8.
Description | sets the SS7 subservice code.
Example | SubServicefield=0x8


4.3.4 Setting Client Information


4.3.4.1 MaxSs7Client

Refer to IP


4.3.4.2 IP

Configuration Item | MaxSs7Client IP
Section | [Ss7ClientInfo]
Written Format | MaxSs7Client=M IP[m]=a.b.c.d
Value Range | M: The total number of client computers that use SS7 servers, with the default value of 0. If M＞0, the configuration item IP must be displayed for M times. M: The logical client number, numbered from 0, 0≤m<M. a.b.c.d: The IP address of Client m.
Description | MaxSs7Client is used to set the total number of client computers that use SS7 signaling, while IP is used to set the IP address of each client computer point by point. This configuration item can be set to 1 in a single computer system.
Example | If the SS7 server is running with the client in a same computer: [Ss7ClientInfo] MaxSs7Client=1 IP[0]=127.0.0.1 If 2 client computers are connected to the SS7 server: [Ss7ClientInfo] MaxSs7Client=2 IP[0]=203.203.203.200 IP[1]= 203.203.203.201


4.3.5 Setting Physical Position of Signaling Link


4.3.5.1 MaxSs7Pcm

Refer to Ss7PcmLink


4.3.5.2 Ss7PcmLink

Configuration Item

MaxSs7Pcm

Ss7PcmLink

Section

[Ss7PcmLinkInfo]

Written Format

MaxSs7Pcm=M

Ss7PcmLink[m]=IP[n],LocalPCM[k]

Value Range

M: The total number of signaling links. The SS7 server supports up to 48 signaling link sets, each of which supports up to 16 signaling links. Therefore, the range of M is 0<M≤768;

m: The logical signaling link number in the server (numbered from 0), 0≤m<M;

n: The logical number for the client computer which is connected to Signaling Link m. This logical number is defined in the configuration item IP;

k: The logical number on the client computer for Signaling Link m in the SS7 server. k can be set via the configuration items TotalPcm and Pcm in the file ShConfig.ini.

Description

MaxSs7Pcm is used to set the total number of 64kbps signaling links, while Ss7PcmLink is to set the physical position on the client computer of a signaling link in the SS7 server.

Example

On the assumption that the application system contains one SS7 server, two client computers and two signaling links in total, if the 1st link is physically located at the 1st client computer, with the local number of 0, the 2nd link is at the 2nd client computer, with the local number of 3, relative configuration items are set as follows.

[Ss7ClientInfo]

MaxSs7Client=2

IP[0]=203.203.203.200

IP[1]= 203.203.203.201

[Ss7PcmLinkInfo]

MaxSs7Pcm=2

Ss7PcmLink[0]=IP[0],LocalPCM[0]

Ss7PcmLink[1]=IP[1],LocalPCM[3]

If both the two signaling links are at the 1st client computer and their local numbers are respectively 0 and 1, the set values of MaxSs7Pcm and Ss7PcmLink shall be:

Ss7PcmLink[0]=IP[0],LocalPCM[0]

Ss7PcmLink[1]=IP[0],LocalPCM[1]


4.3.6 Setting Signaling Link Set


4.3.6.1 MaxLinkSet

Refer to LinkSet


4.3.6.2 LinkSet

Configuration Item

MaxLinkSet

LinkSet

Section

[LinkSetInfo]

Written Format

MaxLinkSet=N

Format 1: LinkSet[n]=Ss7PcmLink[i] (only one signaling link involved in the link set)

Format 2: LinkSet[n]=Ss7PcmLink[i]+ … +Ss7PcmLink[j] (two or more than two signaling links involved in the link set)

Format 3: LinkSet[n]=Ss7PcmLink[i],a.b.c (only one signaling link involved in the link set)

Format 4: LinkSet[n]=Ss7PcmLink[i]+ … +Ss7PcmLink[j],a.b.c (two or more than two signaling links involved in the link set)

Value Range

N: The total number of signaling link sets in the server, 1≤N≤48. N determines how many LinkSet the driver will read;

n: The logical serial number of the signaling link set, numbered from 0, 0≤n<N;

i, ,j: The logical number in the sever for those signaling links involved in Signaling Link Set n, specified in the configuration item Ss7PcmLink . Each link set includes up to 16 signaling links;

a.b.c: The OPC allocated to Signaling Link Set n.

Description

MaxLinkSet is used to set the total number of signaling link sets connected to the local server; LinkSet is to configure which signaling links compose the link set.

Note

l Format 1 and Format 3 are used for the situation when only one signaling link is involved in the link set; Format 2 and Format 4 are used for the situation when there are two or more than two signaling links in the link set;

l Format 3 and Format 4 are applicable to the situation that involves different OPCs;

l The OPC of the signaling link set is preferentially specified by the configuration item LinkSet[n] . If not designated in LinkSet, it is set by the configuration item OPC .

Example

MaxLinkSet=2

LinkSet[0]=Ss7PcmLink[1],1.1.1

LinkSet[1]=Ss7PcmLink[2]+ Ss7PcmLink[0],1.1.2


4.3.7 Setting DPC


4.3.7.1 MaxDPC

Refer to DPC


4.3.7.2 DPC

Configuration Item

MaxDPC

DPC

Section

[DPCInfo]

Written Format

MaxDPC=N

DPC[n]=x.y.z,LinkSet[k]

Value Range

N: The total number of DPC, 0≤N≤48;

n: The logical DPC number, numbered from 0, 0≤n<N;

x.y.z: The signaling point code for DPC n (represented by decimal digits): x - Main Area, y - Subarea. z is the signaling point code allocated by the central office.

k: The logical number of the signaling link set which connects the SS7 server with DPC n. This number is specified in the configuration items MaxLinkSet and LinkSet.

Description

MaxDPC is used to set the total number of DPC (SP or STP) connected to the SS7 server; DPC is to set the signaling point code and the route information for the DPC.

Note

l If N≥1, DPC must be configured for N times, numbered from n=0.

l This configuration item is only applicable to the associated mode which you can set via the configuration items MaxUP_DPC and UP_DPC.

Example

MaxDPC=2

DPC[0]=1.1.8,LinkSet[0]

DPC[1]=1.1.9,LinkSet[1]


4.3.8 Setting DPC for User Layer Messages


4.3.8.1 MaxUP_DPC

Refer to UP_DPC


4.3.8.2 UP_DPC

Configuration Item

MaxUP_DPC

UP_DPC

Section

[UP_DPCInfo]

Written Format

MaxUP_DPC=N

Format 1: UP_DPC[n]=x.y.z,LinkSet[i]

Format 2: UP_DPC[n]= x.y.z,LinkSet[i]+LinkSet[j]

Format 3: UP_DPC[n]= x.y.z,LinkSet[i]+LinkSet[j],m

Value Range

N: The number of UP_DPC, 0≤N≤48;

n: The logical UP_DPC number, numbered from 0, 0≤n<N;

x.y.z: The signaling point code for UP_DPC n (represented by decimal digits): x - Main Area, y - Subarea. z is the signaling point code allocated by the central office.

i,j: The logical number of the signaling link set which connects the SS7 server with UP_DPC n. This number is specified in the configuration items MaxLinkSet and LinkSet.

m: In case there are 2 signaling link sets between the SS7 server and UP_DPC n, m is to specify the way how the server uses Link Set i and Link Set j.

m=0: The load sharing mode (default, and in such case, Format 2 and Format 3 makes no difference for your use)

m=1: Signaling Link Set i serves as the normal route while Signaling Link Set j works as the alternate route.

Description

MaxUP_DPC is used to set the total number of SP which connect to the SS7 server via STP. Its value determines how many UP_DPC[n] the driver will read. UP_DPC is used to set the signaling point code and the route information for SP n.

Note

l If N≥1, UP_DPC must be configured for N times, numbered from n=0.

l This configuration item is applicable to the associated mode, the quasi-associated mode, and the hybrid use of these two modes.

l If this item is used in the associated mode, it should comply to the parameters of configuration items MaxDPC and DPC. That is, UP_DPC and its corresponding DPC should point to a same SP.

l The format used to set UP_DPC is determined by the total number of signaling link sets between the SS7 server and UP_DPC n.

² Only 1 link set: use Format 1

² 2 link sets available: use Format 2 or Format 3

Example

MaxUP_DPC=2

UP_DPC[0]=1.2.8,LinkSet[0]

UP_DPC[1]=1.2.9,LinkSet[1]


4.3.9 Setting Route to Distribute TUP/ISUP Messages


4.3.9.1 UP_DPC

Refer to DPC


4.3.9.2 CIC_PCM

Refer to DPC


4.3.9.3 DPC

Configuration Item

UP_DPC

CIC_PCM

DPC

Section

[TUPRouter] / [ISUPRouter]

Written Format

Format 1: UP_DPC[i],CIC_PCM[p]=IP[j],LocalPCM[k] //used for TUP/ISUP protocol

Format 2: DPC[i],CIC_PCM[p]=IP[j],LocalPCM[k] // used for TUP/ISUP protocol

Value Range

i: The logical DPC/UP_DPC number. Format 1 specifies the use of UP_DPC, in which case the value of the configuration item MaxUP_DPC must be set greater than 0. It is used in the associated mode or quasi-associated mode. Format 2 specifies the use of DPC, in which case the configuration item MaxUP_DPC may either be set to 0 or not be set. It is only applicable to the associated mode.

p: The digital trunk number in the CIC field, and the value is obtained by dividing the initial CIC number from the central office by 32, not necessarily numbered from 0.

j: The logical number for the client computer’s IP address. See description on configuration items MaxSs7Client and IP for more information.

k: The logical digital trunk number on the client computer. See description on configuration items TotalPcm and Pcm for more information.

Description

UP_DPC, CIC_PCM are used to set the route to distribute TUP/ISUP messages.

How the SS7 server distributes TUP/ISUP Messages is described as follows.

² Every time when the SS7 server receives a TUP/ISUP message from UP_DPC / DPC i, it will acquire the digital trunk number p from the CIC field. If the matched route can be found for this TUP/ISUP message according to the route set by the configuration items UP_DPC, CIC_PCM, the server will change the digital trunk number p to k in the CIC field and forward this TUP message to Client j; otherwise, this TUP/ISUP message will be discarded.

² Every time when the SS7 server receives a TUP/ISUP message from Client j, it will acquire the digital trunk number k from the CIC field. If the matched route can be found for this TUP/ISUP message according to the route set by the configuration items UP_DPC, CIC_PCM, the server will change the digital trunk number k to p in the CIC field and forward this TUP message to UP_DPC / DPC i; otherwise, the server will discard the TUP/ISUP message.

Note

l The TUP protocol uses the [TUPRouter] section while the ISUP protocol uses the [ISUPRouter] section;

l If the [UP_DPCInfo] section is not set or MaxUP_DPC=0, what shall be used is DPC, CIC_PCM: DPC[i],CIC_PCM[p]=IP[j],LocalPCM[k];

l If the client uses the TUP/ISUP protocol provided by the driver, this configuration item must be set;

l This configuration item shall be used to set all digital trunks allocated by the central office one by one.

Example

[ISUPRouter]

DPC[0]:CIC_PCM[0]=IP[0],LocalPCM[0]

DPC[1]:CIC_PCM[1]=IP[0],LocalPCM[1]


4.3.10 Setting Way to Start SS7 Server


4.3.10.1 ConfigAsGateway

Configuration Item

ConfigAsGateway

Section

[Monitor]

Written Format

ConfigAsGateway=n

Value Range

n=0: no (default)

n=1: yes

Description

Determines whether to load the SynCTI driver at the start of the SS7 server. If no Synway boards are installed in the server, this configuration item shall be set to 0; if the SHD Series boards are installed for signaling links, this item must be set to 1, and in such case the SS7 server will automatically load the SynCTI driver when it is started.

When loading the SynCTI driver, the SS7 server uses two configuration files named ShConfig.ini and ShIndex.ini. The server will search both files under the current directory, and then under the SynCTI driver installation directory. If they are not found, the server will fail to start and return error information. Refer to Chapter 4 for the configuration of ShConfig.ini and ShIndex.ini.

Note

If this configuration item is set to 1, other application programs (if available) running in the server are not allowed to load the SynCTI driver.


4.3.11 Setting Display Ability of SS7 Server


4.3.11.1 RcvMsuListMaxItem

Refer to TxMsuListMaxItem


4.3.11.2 TxMsuListMaxItem

Configuration Item

RcvMsuListMaxItem

TxMsuListMaxItem

Section

[Monitor]

Written Format

RcvMsuListMaxItem=n //used for messages from the client to the server

TxMsuListMaxItem=m //used for messages from the SP/STP to the server

Value Range

n,m: The maximum number of the messages allowed to be displayed, with the default value of 50.

Description

The SS7 server can display the messages from the SP/STP or the client on the screen. The configuration item is used to set the maximum number of the messages allowed to be displayed.

TxMsuListMaxItem is used to set the maximum number for the messages from the client to the server while RcvMsuListMaxItem is to set the maximum number for the messages from the SP/STP to the server.


4.3.12 Special Configuration Item for Linux SS7 Server


4.3.12.1 ShowMSU

Configuration Item | ShowMSU
Section | [Monitor]
Written Format | ShowMSU=n
Value Range | n=0: disable (default) n=1: enable
Description | Records the MSU messages to /var/log/ss7log/msu.0.log,msu.1.log


4.3.12.2 ShowStatus

Configuration Item | ShowStatus
Section | [Monitor]
Written Format | ShowStatus=n
Value Range | n=0: disable (default) n=1: enable
Description | Records the Link messages to /var/log/ss7log/Ss7RunInfo.0.ini


4.3.12.3 ShowSNT

Configuration Item | ShowSNT
Section | [Monitor]
Written Format | ShowSNT=n
Value Range | n=0: disable (default) n=1: enable
Description | Enables the SNT recording feature


4.3.12.4 ShowSNM

Configuration Item | ShowMSU
Section | [Monitor]
Written Format | ShowSNM=n
Value Range | n=0: disable (default) n=1: enable
Description | Enables the SNM recording feature


4.3.12.5 AutoTranslate

Configuration Item | AutoTranslate
Section | [Monitor]
Written Format | AutoTranslate=n
Value Range | n=0: disable n=1: enable (default)
Description | Enables the MSU translation feature


4.3.13 One Ss7Monitor Supporting Multiple Clients

For a digital board using SS7(TUP/ISUP), both the Test program (client application) and the Ss7Monitor program should be started. Ss7Monitor.exe is responsible for data transmission at MTP1-3 the bottom layer of SS7. At present, a signal machine supports only one Ss7Monitor program but more than one Test program (client application) to be started. Using the configuration item MultiCardMultiProcess, you can set to determine whether the SynCTI driver supports multiprocessing with multi boards or not. If you set MultiCardMultiProcess to 1, more than one Test program (client application) is allowed to run in the machine.

See the specific example below for details:

Suppose there were two SHD-120D-CT/PCI boards inserted in a machine and the configuration item MultiCardMultiProcess was set to 1. Then three files would be generated, including two independent shconfig.ini files and one ss7server.ini file. First configure the self-loop ISUP call as usual. Then modify some configuration files as follows:

ss7server.ini before modification:

[Ss7ClientInfo]

MaxSs7Client=2
IP[0] = 127.0.0.1
IP[1] = 127.0.0.1

……

ss7server.ini after modification:

[Ss7ClientInfo]

MaxSs7Client=2
IP[0] = 127.0.0.1-0
IP[1] = 127.0.0.1-1

……

One shconfig.ini before modification:

[SS7]
Ss7ServerIP = 127.0.0.1
LocalIP = 127.0.0.1

After modification:

[SS7]
Ss7ServerIP = 127.0.0.1
LocalIP = 127.0.0.1-0

The other shconfig.ini before modification:

[SS7]
Ss7ServerIP = 127.0.0.1
LocalIP = 127.0.0.1

After modification:

[SS7]
Ss7ServerIP = 127.0.0.1
LocalIP = 127.0.0.1-1

Modify and save the above configurations. Then start ss7monitor.exe and two Test programs.


4.4 Application and Configuration Instance for SS7 Server


4.4.1 Single OPC/Single DPC


4.4.1.1 Single-PC-Single-Board System

The figure below shows the smallest system composed of a computer and one SHD Series board installed on it.

Take the TUP protocol for example. Provided the board used is SHD-60A-CT/SS7/PCI, if as shown above, on the 1st digital trunk, TS16 serves as the signaling link while other 30 time slots work as voice paths, on the 2nd digital trunk, all unused times slots except TS 16 serve as voice paths, the system is configured as follows:

Ss7Server.ini | ShConfig.ini
[Ss7SystemConfig] OPC=1.2.3 ServerIP=127.0.0.1 [Ss7ClientInfo] MaxSs7Client=1 IP[0]=127.0.0.1 [Ss7PcmLinkInfo] MaxSs7Pcm=1 Ss7PcmLink[0]=IP[0],LocalPCM[0] [LinkSetInfo] MaxLinkSet=1 LinkSet[0]=Ss7PcmLink[0] [DPCInfo] MaxDPC=1 DPC[0]=4.5.6,LinkSet[0] [TUPRouter] DPC[0]:CIC_PCM[0]=IP[0],LocalPCM[0] DPC[0]:CIC_PCM[1]=IP[0],LocalPCM[1] | …… [SS7] Ss7ServerIP=127.0.0.1 //the IP address of the SS7 server LocalIP=127.0.0.1 //the IP address of the local PC [PcmInfo] TotalPcm=2 Pcm[0]=0,0 Pcm[1]=0,1 [BoardId=0] …… PcmNumber=2 PcmSSx[0]=7 //SS7 PcmClockMode[0]=0 //master clock, line synchronization Ss7SignalingTS[0]=16 //TS16 used as the signaling time slot UseTS16AsCircuit[0]=0 PcmSSx[1]=7 //SS7 PcmClockMode[1]=2 //slave clock Ss7SignalingTS[1]=16 //TS16 used as the signaling time slot UseTS16AsCircuit[1]=1


4.4.1.2 Single-PC-Multi-Board System

Take the TUP protocol for example. Assuming that the system contains 4 E1/T1 links (established via 2 boards) and 1 16-channel station board: as to both the 1st and the 2nd boards, the 1st PCM is the link to transport both signaling and voices while the 2nd PCM serves as the pure voice path, it is configured as follows.

Ss7Server.ini | ShConfig.ini
[Ss7SystemConfig] OPC=1.2.3 ServerIP=127.0.0.1 [Ss7ClientInfo] MaxSs7Client=1 IP[0]=127.0.0.1 [Ss7PcmLinkInfo] MaxSs7Pcm=2 Ss7PcmLink[0]=IP[0],LocalPCM[0] Ss7PcmLink[1]=IP[0],LocalPCM[2] [LinkSetInfo] MaxLinkSet=1 LinkSet[0]=Ss7PcmLink[0]+Ss7PcmLink[1] [DPCInfo] MaxDPC=1 DPC[0]=4.5.6,LinkSet[0] [TUPRouter] DPC[0]:CIC_PCM[0]=IP[0],LocalPCM[0] DPC[0]:CIC_PCM[1]=IP[0],LocalPCM[1] DPC[0]:CIC_PCM[2]=IP[0],LocalPCM[2] DPC[0]:CIC_PCM[3]=IP[0],LocalPCM[3] | …… [SS7] Ss7ServerIP=127.0.0.1 LocalIP=127.0.0.1 [PcmInfo] TotalPcm=4 Pcm[0]=0,0 Pcm[1]=0,1 Pcm[2]=1,0 Pcm[3]=1,1 [BoardId=0] …… PcmNumber=2 PcmSSx[0]=7 PcmClockMode[0]=0 //master clock, line synchronization PcmSSx[1]=7 PcmClockMode[1]=2 //slave clock [BoardId=1] …… PcmNumber=2 PcmSSx[0]=7 PcmClockMode[0]=2 //slave clock PcmSSx[1]=7 PcmClockMode[1]=2 //slave clock [BoardId=2] //configure SHT-16B-CT/PCI ……


4.4.1.3 Multi-PC System

Assume that the system contains 2 devices: the SS7 sever and the application program running at one time in Device 1; Device 2 serving as the Client of Device 1. Device 1 covers 2 digital trunks: on the 1st digital trunk, TS16 serves as the signaling link while other 30 time slots work as voice paths; on the 2nd digital trunk, all unused times slots except TS16 serve as voice paths. Device 2 also contains 2 digital trunks, with all of the 30×2 time slots serving as voice paths. Taking the TUP protocol for example, such a system is configured as follows.

Ø Device 1: Configuration Files for SS7 Sever and Application Program

Ss7Server.ini | ShConfig.ini
[Ss7SystemConfig] OPC=1.2.3 ServerIP=201.123.123.1 [Ss7ClientInfo] MaxSs7Client=2 IP[0]= 201.123.123.1 IP[1]= 201.123.123.2 [Ss7PcmLinkInfo] MaxSs7Pcm=1 Ss7PcmLink[0]=IP[0],LocalPCM[0] [LinkSetInfo] MaxLinkSet=1 LinkSet[0]=Ss7PcmLink[0] [DPCInfo] MaxDPC=1 DPC[0]=4.5.6,LinkSet[0] [TUPRouter] DPC[0]:CIC_PCM[0]=IP[0],LocalPCM[0] DPC[0]:CIC_PCM[1]=IP[0],LocalPCM[1] DPC[0]:CIC_PCM[2]=IP[1],LocalPCM[0] DPC[0]:CIC_PCM[3]=IP[1],LocalPCM[1] | …… [SS7] Ss7ServerIP=201.123.123.1 //the IP address of the SS7 server LocalIP=201.123.123.1 //the IP address of the local PC ……

Ø Device 2: Configuration File for Application Program (ShConfig.ini)

……

[SS7]

Ss7ServerIP=201.123.123.1 //the IP address of the SS7 server

LocalIP=201.123.123.2 //the IP address of the local PC

……


4.4.1.4 Multi-PC System with Separate SS7 Server

For high system reliability, we suggest the use of a computer as the separate SS7 server and the run of application programs on other one or more computers as shown below.

In the figure above, Device 1 only processes signaling, which requires not only the SS7 server but also the SynCTI driver loaded for the board only supporting signaling links, while the application system serves as the client. Assuming that the separate SS7 server has 2 digital trunks, with only TS16 being in use, and Device 2 covers 4 digital trunks, consecutively numbered as 5, 6, 7, 8 by the central office in the TUP protocol, the system is configured as follows.

Ø SS7 Server Configuration Files

Ss7Server.ini | ShConfig.ini
[Ss7SystemConfig] OPC=1.2.3 ServerIP=201.123.123.1 //the IP address of the SS7 server [Ss7ClientInfo] MaxSs7Client=2 IP[0]= 201.123.123.1 IP[1]= 201.123.123.2 [Ss7PcmLinkInfo] MaxSs7Pcm=2 Ss7PcmLink[0]=IP[0],LocalPCM[0] Ss7PcmLink[1]=IP[0],LocalPCM[1] [LinkSetInfo] MaxLinkSet=1 LinkSet[0]=Ss7PcmLink[0]+ Ss7PcmLink[1] [DPCInfo] MaxDPC=1 DPC[0]=4.5.6,LinkSet[0] [TUPRouter] DPC[0]:CIC_PCM[5]=IP[1],LocalPCM[0] DPC[0]:CIC_PCM[6]=IP[1],LocalPCM[1] DPC[0]:CIC_PCM[7]=IP[1],LocalPCM[2] DPC[0]:CIC_PCM[8]=IP[1],LocalPCM[3] [Monitor] ConfigAsGateway=1 //need to load the SynCTI driver | …… [SS7] Ss7ServerIP=201.123.123.1 //the IP address of the SS7 server LocalIP=201.123.123.1 //the IP address of the client ……

Ø Configuration File for Application System (ShConfig.ini)

……

[SS7]

Ss7ServerIP=201.123.123.1 //the IP address of the SS7 server

LocalIP=201.123.123.2 //the IP address of the local PC

……


4.4.2 Single OPC/Multiple DPC

Assume that the application system involves two SHD-60A-CT/PCI/SS7 boards, each of which has the time slots TS 1~15,17~31 on its 2 digital trunks serving as voice paths, TS16 on the 1st digital trunk being the signaling link, and TS16 on the 2nd digital trunk being unused. These 2 boards are respectively connected to 2 PBXes with different DPC. Taking the TUP protocol for example, such a system is configured as follows.

Ss7Server.ini | ShConfig.ini
[Ss7SystemConfig] OPC=1.2.3 ServerIP=127.0.0.1 [Ss7ClientInfo] MaxSs7Client=1 IP[0]= 127.0.0.1 //the IP address of the client [Ss7PcmLinkInfo] MaxSs7Pcm=2 Ss7PcmLink[0]=IP[0],LocalPCM[0] Ss7PcmLink[1]=IP[0],LocalPCM[2] [LinkSetInfo] MaxLinkSet=2 LinkSet[0]=Ss7PcmLink[0] LinkSet[1]=Ss7PcmLink[1] [DPCInfo] MaxDPC=2 DPC[0]=4.5.6,LinkSet[0] DPC[1]=7.8.9,LinkSet[1] [TUPRouter] DPC[0]:CIC_PCM[0]=IP[0],LocalPCM[0] DPC[0]:CIC_PCM[1]=IP[0],LocalPCM[1] DPC[1]:CIC_PCM[0]=IP[0],LocalPCM[2] DPC[1]:CIC_PCM[1]=IP[0],LocalPCM[3] | …… [PcmInfo] TotalPcm=4 Pcm[0]=0,0 Pcm[1]=0,1 Pcm[2]=1,0 Pcm[3]=1,1 [BoardId=0] …… PcmNumber=2 PcmSSx[0]=7 PcmSSx[1]=7 PcmClockMode[0]=0 //master clock, line synchronization PcmClockMode[1]=2 //slave clock [BoardId=1] …… PcmNumber=2 PcmSSx[0]=7 PcmSSx[1]=7 PcmClockMode[0]=2 //slave clock PcmClockMode[1]=2 //slave clock


4.4.3 SS7 Application System with Multiple OPC

Assume that the application system involves two SHD-60A-CT/PCI/SS7 boards. The 1st PCM serves as the link for both signaling and voices (TS16 is the signaling time slot) while the 2nd PCM works as the pure voice path. These two PCM correspond to a same OPC. Likewise, the 3rd PCM serves as the link for both signaling and voices (TS16 is the signaling time slot) while the 4th PCM works as the pure voice path. These two PCMs correspond to another OPC. Taking the TUP protocol for example, such a system is configured as follows.

Ss7Server.ini | ShConfig.ini
[Ss7SystemConfig] OPC=1.2.3 ServerIP=127.0.0.1 [Ss7ClientInfo] MaxSs7Client=1 IP[0]=127.0.0.1 [Ss7PcmLinkInfo] MaxSs7Pcm=2 Ss7PcmLink[0]=IP[0],LocalPCM[0] Ss7PcmLink[1]=IP[0],LocalPCM[2] [LinkSetInfo] MaxLinkSet=2 LinkSet[0]=Ss7PcmLink[0],1.2.3 LinkSet[1]=Ss7PcmLink[1],4.5.6 [DPCInfo] MaxDPC=2 DPC[0]=7.8.9,LinkSet[0] DPC[1]=7.8.9,LinkSet[1] [TUPRouter] DPC[0]:CIC_PCM[0]=IP[0],LocalPCM[0] DPC[0]:CIC_PCM[1]=IP[0],LocalPCM[1] DPC[1]:CIC_PCM[0]=IP[0],LocalPCM[2] DPC[1]:CIC_PCM[1]=IP[0],LocalPCM[3] | …… [PcmInfo] TotalPcm=4 Pcm[0]=0,0 Pcm[1]=0,1 Pcm[2]=1,0 Pcm[3]=1,1 [BoardId=0] …… PcmNumber=2 PcmSSx[0]=7 PcmSSx[1]=7 PcmClockMode[0]=0 //master clock, line synchronization PcmClockMode[1]=2 //slave clock [BoardId=1] …… PcmNumber=2 PcmSSx[0]=7 PcmSSx[1]=7 PcmClockMode[0]=2 //slave clock PcmClockMode[1]=2 //slave clock


4.4.4 High-reliability Application System

The SS7 server developed by Synway supports the warm back-up mode, bringing the carrier-class reliability to the application system. The figure below illustrates a typical high-reliability application system.

As shown in the figure above, two SS7 servers, each of which has an SHD board installed in it and only uses the signaling time slot on the digital trunk (i.e. does not process voice data), run at one time and share the same point code (OPC=1.2.3), providing signaling services to the voice processing system. One serves as the Master server while the other as the Slave server. Once something wrong happens to the master server, the slave server will automatically take over all signaling services from it.

The rules below shall be followed to run the master and slave servers.

1. Use the first-started SS7 server as the master server and the other as the slave server.

2. While both servers are running well, the slave server will automatically become the master server if the master server fails, and will be the slave server again once the original master server recovers into a normal use.

3. It is allowed to switch manually between the master and slave servers while both servers are running.

The voice processing system consist of one or more computers and the SHD boards installed on them, and acquires signaling services from the server via the local area network (LAN). Therefore, it does not rely on the client computer to run the SS7 server.

Ø Master SS7 server (referred to as S1 for short) Configuration Files (including Ss7Server.ini and ShConfig.ini)

Ss7Server.ini | ShConfig.ini
[Ss7SystemConfig] OPC=1.2.3 ServerIP=201.123.123. 1 //the IP address of S1 SecondServerIP=201.123.123.2 //the IP address of S2 …… [Ss7ClientInfo] MaxSs7Client=3 IP[0]=201.123.123.1 //signaling link processing program IP[1]=201.123.123.2 //signaling link processing program IP[2]=201.123.123.3 //the IP address of the client [Ss7PcmLinkInfo] MaxSs7Pcm=2 Ss7PcmLink[0]=IP[0],LocalPCM[0] Ss7PcmLink[1]=IP[1],LocalPCM[0] [LinkSetInfo] MaxLinkSet=1 LinkSet[0]=Ss7PcmLink[0]+ Ss7PcmLink[1] [DPCInfo] MaxDPC=1 DPC[0]=4.5.6,LinkSet[0] [TUPRouter] //not to be configured in no use of the TUP protocol DPC[0]:CIC_PCM[0]=IP[2],LocalPCM[0] DPC[0]:CIC_PCM[1]=IP[2],LocalPCM[1] [ISUPRouter] //not to be configured in no use of the ISUP protocol DPC[0]:CIC_PCM[0]=IP[2],LocalPCM[0] DPC[0]:CIC_PCM[1]=IP[2],LocalPCM[1] [Monitor] ConfigAsGateway=1 //need to load the SynCTI driver …… | …… [PcmInfo] TotalPcm=1 Pcm[0]=0,0 [BoardId=0] …… PcmNumber=1 PcmSSx[0]=7 PcmClockMode[0]=0 //master clock, line synchronization [SS7] Ss7ServerIP=201.123.123.1 //the IP address of S1 SecondServerIP=201.123.123.2 ///the IP address of S2 LocalIP= 201.123.123.1 //the IP address of the local PC ……

Ø Slave SS7 Server (referred to as S2 for short) Configuration Files (including Ss7Server.ini and ShConfig.ini)

Ss7Server.ini | ShConfig.ini
[Ss7SystemConfig] OPC=1.2.3 ServerIP=201.123.123.2 //the IP address of S2 SecondServerIP=201.123.123.1 //the IP address of S1 …… [Ss7ClientInfo] MaxSs7Client=3 IP[0]= 201.123.123.1 //signaling link processing program IP[1]= 201.123.123.2 //signaling link processing program IP[2]= 201.123.123.3 //the IP address of the client [Ss7PcmLinkInfo] MaxSs7Pcm=2 Ss7PcmLink[0]=IP[1],LocalPCM[0] Ss7PcmLink[1]=IP[0],LocalPCM[0] [LinkSetInfo] MaxLinkSet=1 LinkSet[0]=Ss7PcmLink[0]+ Ss7PcmLink[1] [DPCInfo] MaxDPC=1 DPC[0]=4.5.6,LinkSet[0] [TUPRouter] //not to be configured in no use of the TUP protocol DPC[0]:CIC_PCM[0]=IP[2],LocalPCM[0] DPC[0]:CIC_PCM[1]=IP[2],LocalPCM[1] [ISUPRouter] //not to be configured in no use of the ISUP protocol DPC[0]:CIC_PCM[0]=IP[2],LocalPCM[0] DPC[0]:CIC_PCM[1]=IP[2],LocalPCM[1] [Monitor] ConfigAsGateway=1 //need to load the SynCTI driver …… | …… [PcmInfo] TotalPcm=1 Pcm[0]=0,0 [BoardId=0] …… PcmNumber=1 PcmSSx[0]=7 PcmClockMode[0]=0 //master clock, line synchronization [SS7] Ss7ServerIP=201.123.123.1 //the IP address of S1 SecondServerIP=201.123.123.2 //the IP address of S2 LocalIP= 201.123.123.2 //the IP address of the local PC ……

Ø Client Configuration File (ShConfig.ini)

……

[PcmInfo]

TotalPcm=1

Pcm[0]=0,0

[BoardId=0]

……

PcmNumber=2

PcmSSx[0]=7

PcmSSx[1]=7

PcmClockMode[0]=0 //master clock, line synchronization

PcmClockMode[1]=2 //slave clock

[SS7]

Ss7ServerIP=201.123.123.1 //the IP address of S1

SecondServerIP=201.123.123.2 //the IP address of S2

LocalIP=201.123.123.3 //the IP address of the local PC

……


4.4.5 Supplying SS7 Service for Third-party Board

In the figure above, the SS7 server uses a Synway board to process signaling and the service processing system controls the third-party board. In this way, the signaling messages are acquired from the SS7 server via the TCP/IP protocol. Assuming that the digital trunks connected to the SS7 server have voice time slots, the data on those time slots can be exchanged to another digital trunk interface so as to reach the application system with the help of the Synway board’s TDM capability which is enabled via the configuration item LoadShp_a3AsSIU, as illustrated above by dotted lines. Taking the TUP protocol for example, such a system is configured as follows.

Ø SS7 Server Configuration Files (Ss7Server.ini and ShConfig.ini)

Ss7Server.ini | ShConfig.ini
[Ss7SystemConfig] OPC=1.2.3 ServerIP=201.123.123.1 [Ss7ClientInfo] MaxSs7Client=2 IP[0]= 201.123.123.1 IP[1]= 201.123.123.2 [Ss7PcmLinkInfo] MaxSs7Pcm=1 Ss7PcmLink[0]=IP[0],LocalPCM[0] [LinkSetInfo] MaxLinkSet=1 LinkSet[0]=Ss7PcmLink[0] [DPCInfo] MaxDPC=1 DPC[0]=4.5.6,LinkSet[0] [TUPRouter] DPC[0]:CIC_PCM[0]=IP[1],LocalPCM[0] [Monitor] ConfigAsGateway=1 //need to load the SynCTI driver | …… [SystemConfig] LoadShp_a3AsSIU=1 //specify the time slot to output voice data …… [PcmInfo] TotalPcm=1 Pcm[0]=0,0 [BoardId=0] PcmNumber=1 PcmSSx[0]=7 PcmClockMode[0]=0 //master clock, line synchronization

Ø UserNo7.ini (the configuration file for the application program based on the third-party board which is using the client of the SS7 server SDK)

[SystemConfig]

TotalPcm=2

DefaultPcmLinkStatus=0x0000

……

[AppChToPcmTsTable]

TotalAppCh=60

AppCh[0]=0,1..15

AppCh[15]=0,17..31

AppCh[30]=1,1..15

AppCh[45]=1,17..31

[SS7]

Ss7ServerIP=201.123.123.1 //the IP address of the SS7 server

LocalIP=201.123.123.2 //the IP address of the local PC

……


4.4.6 Application System in Quasi-associated Mode

As shown in the figure above, assume that the application system is composed of two SHD-120A/SS7 boards, with the 1st one only processing the signaling on the 4 digital trunks (the logical PCM numbers are respectively 0, 1, 2, 3, and TS16 on each trunk is the signaling time slot) and the 2nd one processing the voice data on the 4 digital trunks. Taking the TUP protocol for example, such a system is configured as follows.

Ss7Server.ini | ShConfig.ini
[Ss7SystemConfig] OPC=7.8.9 ServerIP=127.0.0.1 [Ss7ClientInfo] MaxSs7Client=1 IP[0]=127.0.0.1 [Ss7PcmLinkInfo] MaxSs7Pcm=4 Ss7PcmLink[0]=IP[0],LocalPCM[0] Ss7PcmLink[1]=IP[0],LocalPCM[1] Ss7PcmLink[2]=IP[0],LocalPCM[2] Ss7PcmLink[3]=IP[0],LocalPCM[3] [LinkSetInfo] MaxLinkSet=2 LinkSet[0]=Ss7PcmLink[0]+ Ss7PcmLink[1] LinkSet[1]=Ss7PcmLink[2]+ Ss7PcmLink[3] [DPCInfo] MaxDPC=2 DPC[0]=1.2.3,LinkSet[0] DPC[1]=1.3.3,LinkSet[1] [UP_DPCInfo] MaxUP_DPC=2 UP_DPC[0]=4.5.6,LinkSet[0]+LinkSet[1] //load sharing UP_DPC[1]=4.6.6,LinkSet[1]+LinkSet[0],1 //Signaling Link Set 1 serves as the normal route while Signaling Link Set 0 as the alternate route. [TUPRouter] UP_DPC[0]:CIC_PCM[1]=IP[0],LocalPCM[4] UP_DPC[0]:CIC_PCM[2]=IP[0],LocalPCM[5] UP_DPC[1]:CIC_PCM[1]=IP[0],LocalPCM[6] UP_DPC[1]:CIC_PCM[2]=IP[0],LocalPCM[7] …… | …… [PcmInfo] TotalPcm=8 Pcm[0]=0,0 Pcm[1]=0,1 Pcm[2]=0,2 Pcm[3]=0,3 Pcm[4]=1,0 Pcm[5]=1,1 Pcm[6]=1,2 Pcm[7]=1,3 [BoardId=0] PcmNumber=4 PcmSSx[0]=7 PcmSSx[1]=7 PcmSSx[2]=7 PcmSSx[3]=7 PcmClockMode[0]=0 //master clock, line synchronization PcmClockMode[1]=2 //slave clock PcmClockMode[2]=2 //slave clock PcmClockMode[3]=2 //slave clock Ss7SignalingTS[0]=16 //TS16 used as the signaling time slot UseTS16AsCircuit[0]=0 Ss7SignalingTS[1]=16 //TS16 used as the signaling time slot UseTS16AsCircuit[1]=0 Ss7SignalingTS[2]=16 //TS16 used as the signaling time slot UseTS16AsCircuit[2]=0 Ss7SignalingTS[3]=16 //TS16 used as the signaling time slot UseTS16AsCircuit[3]=0 …… [BoardId=1] PcmNumber=4 PcmSSx[0]=7 PcmSSx[1]=7 PcmSSx[2]=7 PcmSSx[3]=7 PcmClockMode[0]=2 //slave clock PcmClockMode[1]=2 //slave clock PcmClockMode[2]=2 //slave clock PcmClockMode[3]=2 //slave clock ……


Appendix 1 ISDN Release Cause Information Element

Return Value | Cause | Application
1 | Unallocated (unassigned) number | DSS1, ISUP
2 | No route to specified transit network | DSS1, ISUP
3 | No route to destination | DSS1, ISUP
4 | Send special information tone | ISUP
5 | Misdialled trunk prefix | ISUP
6 | Channel unacceptable | DSS1, ISUP
7 | Call awarded and being delivered in an established channel | DSS1, ISUP
8 | Preemption | DSS1, ISUP
9 | Preemption-circuit reserved for reuse | ISUP
16 | Normal call clearing | DSS1, ISUP
17 | User busy | DSS1, ISUP
18 | No user responding | DSS1, ISUP
19 | No answer from user (user alerted) | DSS1, ISUP
20 | Subscriber absent | DSS1, ISUP
21 | Call rejected | DSS1, ISUP
22 | Number changed | DSS1, ISUP
26 | Non-selected user clearing | DSS1, ISUP
27 | Destination out of order | DSS1, ISUP
28 | Invalid number format (address incomplete) | DSS1, ISUP
29 | Facility rejected | DSS1, ISUP
30 | Response to STATUS ENQUIRY | DSS1
31 | Normal, unspecified | DSS1, ISUP
34 | No circuit/channel available | DSS1, ISUP
38 | Network out of order | DSS1, ISUP
39 | Permanent frame mode connection out of service | DSS1
40 | Permanent frame mode connection operational | DSS1
41 | Temporary failure | DSS1, ISUP
42 | Switching equipment congestion | DSS1, ISUP
43 | Access information discarded | DSS1, ISUP
44 | Requested circuit/channel not available | DSS1, ISUP
46 | Precedence call blocked | DSS1, ISUP
47 | Resource unavailable, unspecified | DSS1, ISUP
49 | Quality of service unavailable | DSS1
50 | Requested facility not subscribed | DSS1, ISUP
53 | Outgoing calls barred within CUG | DSS1, ISUP
55 | Incoming calls barred within CUG | DSS1, ISUP
57 | Bearer capability not authorized | DSS1, ISUP
58 | Bearer capability not presently available | DSS1, ISUP
62 | Inconsistency in designated outgoing access information and subscriber class | DSS1, ISUP
63 | Service or option not available, unspecified | DSS1, ISUP
65 | Bearer capability not implemented | DSS1, ISUP
66 | Channel type not implemented | DSS1
69 | Requested facility not implemented | DSS1, ISUP
70 | Only restricted digital information bearer capability is available | DSS1, ISUP
79 | Service or option not implemented, unspecified | DSS1, ISUP
81 | Invalid call reference value | DSS1
82 | Identified channel does not exist | DSS1
83 | A suspended call exists, but this call identity does not | DSS1
84 | Call identity in use | DSS1
85 | No call suspended | DSS1
86 | Call having the requested call identity has been cleared | DSS1
87 | User not member of CUG | DSS1, ISUP
88 | Incompatible destination | DSS1, ISUP
90 | Non-existent CUG | DSS1, ISUP
91 | Invalid transit network selection | DSS1, ISUP
95 | Invalid message, unspecified | DSS1, ISUP
96 | Mandatory information element is missing | DSS1
97 | Message type non-existent or not implemented | DSS1, ISUP
98 | Message not compatible with call state or message type non-existent or not implemented | DSS1
99 | Information element/parameter non-existent or not implemented | DSS1, ISUP
100 | Invalid information element contents | DSS1
101 | Message not compatible with call state | DSS1
102 | Recovery on timer expiry | DSS1, ISUP
103 | Parameter non-existent or not implemented, passed | ISUP
110 | Message with unrecognized parameter, discarded | ISUP
111 | Protocol error, unspecified | DSS1, ISUP
127 | Interworking, unspecified | DSS1, ISUP
128 | T303 time out | Synway Define
129 | T304 time out | Synway Define
130 | T310 time out | Synway Define
131 | T308 time out again | Synway Define
132 | Network busy | Synway Define
133 | Circuit restarted | Synway Define
134 | Temporary fault | Synway Define
135 | Data link failure | Synway Define
136 | Connection after pickup failed | Synway Define
137 | Pickup time out | Synway Define


Appendix 2 ISUP Parameters

1. Called party number:

The first byte: HGFEDCBA

1) H represents Odd/Even Indicator.

0: Even number of address signals

1: Odd number of address signals

2) GFEDCBA represents Nature of Address Indicator

0000001: Subscriber number

0000011: National number

0000100: International number

Others are spare.

The second byte: HGFEDCBA

1) H represents Internal Network Number Indicator.

0: Routing to internal network number allowed

1: Routing to internal network number not allowed

2) GFE represents Numbering Plan Indicator.

001: ISDN (Telephony) numbering plan (Recommendations E.164, E.163)

011: Data numbering plan (Recommendation X.164)

100: Telex numbering plan (Recommendation F.164)

Others are spare.

3) DCBA is spare

From the third byte begins the called party number.

2. Calling party number：

The first byte: HGFEDCBA

1) H represents Odd/Even Indicator.

0: Even number of address signals

1: Odd number of address signals

2) GFEDCBA represents Nature of Address Indicator

0000001: Subscriber number

0000011: National number

0000100: International number

Others are spare.

The second byte: HGFEDCBA

1) H represents Number Incomplete Indicator.

0: Complete

1: Incomplete

2) GFE represents Numbering Plan Indicator.

001: ISDN (Telephony) numbering plan (Recommendations E.164, E.163)

011: Data numbering plan (Recommendation X.164)

100: Telex numbering plan (Recommendation F.164)

Others are spare.

3) DC represents Address Presentation Restricted Indicator.

00: Presentation allowed

01: Presentation restricted

10: Address not available

Others are spare.

4) BA represents Screening Indicator.

00: User provided, not verified (national use)

01: User reserved, verified and passed

10: User provided, verified and not passed (national use)

11: Network provided

From the third byte begins the calling party number.

3. Calling party category (CAT)

Only one byte: HGFEDCBA

00001001: National operator (for domestic use)

00001010: Ordinary subscriber, used for toll to toll or toll to local office calls

00001011: Calling subscriber with priority

00001100: Data call (voice with data)

00001101: Test call

00001111: Pay phone

11111000: Ordinary calling subscriber, used for local office to local office calls

Others are spare.

4. Backward Call Indicator (BCI)

The first byte: HGFEDCBA

1) BA represents Charge Indicator.

00: No indication

01: No charge

10: Charge

11: Spare

2) DC represents Called Party’s Status Indicator.

00: No indication

01: Subscriber free

10: Connect when free

11: Spare

3) FE represents Called Party’s Category Indicator.

00: No indication

01: Ordinary subscriber

10: payphone

11: Spare

4) HG represents End-to-end Method Indicator.

00: No end-to-end method available

01: Pass-along method available

10: SCCP method available

11: Pass-along and SCCP methods available

The second byte: HGFEDCBA

1) A represents Interworking Indicator.

0: No interworking encountered

1: Interworking encountered

2) B represents End-to-end Information Indicator.

0: No end-to-end information available

1: End-to-end information available

3) C represents ISUP Indicator.

0: ISUP not used all the way

1: ISUP used all the way

4) D represents Holding Indicator.(national use)

0: Holding not requested

1: Holding requested

5) E represents ISDN Access Indicator.

0: Terminating access non-ISDN

1: Terminating access ISDN

6) F represents Echo Control Device Indicator.

0: Incoming half-echo control device not included

1: Incoming half-echo control device included

7) HG represents SCCP Method Indicator.

00: No indication

01: Connectionless method available

10: Connection oriented method available

11: Connectionless and connection oriented methods available

5. Forward Call Indicator (FCI)

The first byte: HGFEDCBA

1) A represents National/International Call Indicator.

0: National call

1: International call

This bit can be any value in the origin country. But in the destination country, it is set to 1 for a call from the international network

2) CB represents End-to-end Method indicator.

00: No end-to-end method available

01: Pass-along method available

10: SCCP method available

11: Pass-along and SCCP methods available

3) D represents Interworking Indicator.

0: No interworking encountered

1: Interworking encountered

4) E represents End-to-end Information Indicator.

0: No end-to-end information available

1: End-to-end information available

5) F represents ISUP Indicator.

0: ISUP not used all the way

1: ISUP used all the way

6) HG represents ISDN User Part Preference Indicator

00: ISDN user part preferred

01: ISUP not required all the way

10: ISUP required all the way

11: Spare

The second byte: HGFEDCBA

1) A represents ISDN Access Indicator.

0: Terminating access non-ISDN

1: Terminating access ISDN

2) CB represents SCCP Method Indicator.

00: No indication

01: Connectionless method available

10: Connection oriented method available

11: Connectionless and connection oriented methods available

Others are spare.

6. Transmission Medium Requirement (TMR)

Only one byte: HGFEDCBA

0000000: Speech

0000001: Spare

0000010: 64kbps unrestricted

0000011: 3.1kHz audio

0000100: Alternate speech (service 2) / 64kbps unrestricted (service 1)

0000101: Alternate 64kbps unrestricted (service 1) / speech (service 2)

7. Nature of Connection Indicator

Only one byte: HGFEDCBA

1) AB represents Satellite Indicator.

00: No satellite circuit in the connection

01: One satellite circuit in the connection

10: Two satellite circuits in the connection

11: Spare

2) DC represents Continuity Check Indicator.

00: Continuity check not required

01: Continuity check required on this circuit

10: Continuity check performed on a previous circuit

11: Spare

3) E represents Echo Control Device Indicator.

0: Outgoing half echo control device not included

1: Outgoing half echo control device included

8. Cause Value (incomplete)

0x81: Unallocated number

0x82: No route to specified transit network

0x83: No route to destination

0x84: Send special information tone

0x85: Misdialed trunk prefix

0x90: Normal call clearing

0x91: User busy

0x92: No user responding

0x93: No answer from user

0x95: Call rejected

0x96: Number changed

0x9b: Destination out of order

0x9c: Address Incomplete

0x9d: Facility rejected

0x9f: Normal

0xa2: No circuit available

0xa6: Network failure

0xa9: Temporary failure

0xaa: Switching equipment congestion

0xac: Requested channel not available

0xaf: Resource unavailable

oxd8: Incompatible destination

Below are two typical scenarios of ISUP signaling connection

1. The called party is idle when you are calling.

2. The called party is busy when you are calling.