Intel 05-2409-003 User Manual
Global Call API for Host Media Processing on Windows
Programming Guide
August 2006
05-2409-003
INFORMATION IN THIS DOCUMENT IS PROVIDED IN CONNECTION WITH INTEL® PRODUCTS. NO LICENSE, EXPRESS OR IMPLIED, BY
ESTOPPEL OR OTHERWISE, TO ANY INTELLECTUAL PROPERTY RIGHTS IS GRANTED BY THIS DOCUMENT. EXCEPT AS PROVIDED IN
INTEL'S TERMS AND CONDITIONS OF SALE FOR SUCH PRODUCTS, INTEL ASSUMES NO LIABILITY WHATSOEVER, AND INTEL DISCLAIMS
ANY EXPRESS OR IMPLIED WARRANTY, RELATING TO SALE AND/OR USE OF INTEL PRODUCTS INCLUDING LIABILITY OR WARRANTIES
RELATING TO FITNESS FOR A PARTICULAR PURPOSE, MERCHANTABILITY, OR INFRINGEMENT OF ANY PATENT, COPYRIGHT OR OTHER
INTELLECTUAL PROPERTY RIGHT. Intel products are not intended for use in medical, life saving, life sustaining, critical control or safety systems, or
nuclear facility applications.
Intel may make changes to specifications and product descriptions at any time, without notice.
This Global Call API for Host Media Processing on Windows Programming Guide as well as the software described in it is furnished under license and
may only be used or copied in accordance with the terms of the license. The information in this manual is furnished for informational use only, is
subject to change without notice, and should not be construed as a commitment by Intel Corporation. Intel Corporation assumes no responsibility or
liability for any errors or inaccuracies that may appear in this document or any software that may be provided in association with this document.
Except as permitted by such license, no part of this document may be reproduced, stored in a retrieval system, or transmitted in any form or by any
means without the express written consent of Intel Corporation.
Copyright © 1996-2005, Intel Corporation
Dialogic, Intel, Intel logo, and Intel NetStructure are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States
and other countries.
* Other names and brands may be claimed as the property of others.
Publication Date: August 2006
Document Number: 05-2409-003
Intel
1515 Route 10
Parsippany, NJ 07054
For Technical Support, visit the Intel Telecom Support Resources website at:
http://developer.intel.com/design/telecom/support
For Products and Services Information, visit the Intel Telecom and Compute Products website at:
http://www.intel.com/design/network/products/telecom
For Sales Offices and other contact information, visit the Buy Telecom Products page at:
http://www.intel.com/buy/networking/telecom.htm
Global Call API for HMP on Windows Programming Guide – August 2006
Contents
Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
About This Publication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Applicability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
How to Use This Publication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Related Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
1 Product Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
1.1 Global Call Software Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
1.2 Global Call Feature Categories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
1.2.1 Call Control Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
1.2.2 Operation, Administration and Maintenance Features . . . . . . . . . . . . . . . . . . . . . 18
1.3 Global Call Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
1.3.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
1.3.2 Global Call API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
1.4 Call Control Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
1.4.1 Starting Call Control Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
1.4.2 Call Control Library States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
1.5 Global Call Object Identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
1.5.1 Line Device Identifier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
1.5.2 Call Reference Number . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
1.5.3 Object Identifiers and Resource Sharing Across Processes . . . . . . . . . . . . . . . . 25
1.5.4 Target Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
2 Programming Models. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
2.1 Programming Models Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
2.2 Asynchronous Mode Programming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
2.2.1 Asynchronous Model Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
2.2.2 Asynchronous Model with Event Handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
2.2.3 Asynchronous with Windows Callback Model. . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
2.2.4 Asynchronous with Win32 Synchronization Model . . . . . . . . . . . . . . . . . . . . . . . . 31
2.2.5 Extended Asynchronous Programming Model . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
3 Call State Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
3.1 Call State Model Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
3.2 Basic Call Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
3.2.1 Basic Call States at the Inbound Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
3.2.2 Basic Call States at the Outbound Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
3.2.3 Basic Call States for Call Termination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
3.3 Basic Call Model Configuration Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
3.3.1 Call State Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
3.3.2 Call State Event Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
3.3.3 Call Acknowledgement Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
3.3.4 Call Proceeding Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Global Call API for HMP on Windows Programming Guide – August 2006 3
Contents
3.4 Basic Call Control in Asynchronous Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
3.4.1 Inbound Calls in Asynchronous Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
3.4.2 Outbound Calls in Asynchronous Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
3.4.3 Call Termination in Asynchronous Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
3.4.4 Handling Unsolicited Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
3.5 Advanced Call Control with Call Hold and Transfer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
3.5.1 Advanced Call State Model Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
3.5.2 Advanced Call States for Hold and Transfer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
3.5.3 Call Hold . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
3.5.4 Call Transfer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
4 Event Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
4.1 Overview of Event Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
4.2 Event Categories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
4.3 Blocked and Unblocked Event Handling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
4.4 Event Retrieval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
4.5 Events Indicating Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .74
4.6 Masking Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
4.7 Event Handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
5 Application Development Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
5.1 General Programming Tips. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
5.2 Tips for Programming Drop and Insert Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
5.3 Using Global Call with Digital Network Interface Boards . . . . . . . . . . . . . . . . . . . . . . . . . . 79
5.3.1 Routing Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
5.3.2 Working with Flexible Routing Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
5.3.3 Handling Multiple Call Objects Per Channel in a Glare Condition . . . . . . . . . . . . . 83
6 Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
6.1 Error Handling Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
7Call Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
7.1 Call Progress Analysis when Using IP Technology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
7.2 Call Progress Analysis when Using Digital Network Interface Boards . . . . . . . . . . . . . . . . 87
7.2.1 Call Progress Analysis Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
7.2.2 Configuring Default Call Progress Analysis Parameters . . . . . . . . . . . . . . . . . . . . 88
7.2.3 Configuring Call Progress Analysis on a Per Call Basis . . . . . . . . . . . . . . . . . . . . 88
7.2.4 Setting Call Analysis Attributes on a Per Call Basis . . . . . . . . . . . . . . . . . . . . . . . 90
7.2.5 Configuring Call Progress Analysis on a Per Channel Basis. . . . . . . . . . . . . . . . .91
7.2.6 Setting Call Analysis Attributes on a Per Channel Basis . . . . . . . . . . . . . . . . . . . . 92
7.2.7 Customizing Call Progress Tones on a Per Board Basis . . . . . . . . . . . . . . . . . . . 92
7.3 Resource Routing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
7.4 Feature Transparency and Extension. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
7.4.1 Feature Transparency and Extension Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 93
7.4.2 Technology-Specific Feature Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
7.4.3 Technology-Specific User Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
8 Alarm Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
8.1 Alarm Handling Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
8.1.1 Alarm Management System Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
8.2 Operation and Configuration of GCAMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
4 Global Call API for HMP on Windows Programming Guide – August 2006
Contents
8.2.1 Generation of Events for Blocking Alarms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
8.2.2 Generation of Alarm Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
8.2.3 Configuration of Alarm Properties and Characteristics . . . . . . . . . . . . . . . . . . . . 101
8.2.4 Starting and Stopping Alarm Transmission. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
8.2.5 Retrieving Alarm Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
8.3 Sample Alarm Scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
8.3.1 Scenario 1: Application Notified of First and Last Blocking Alarm . . . . . . . . . . . 105
8.3.2 Scenario 2: Default Behavior for Alarm Notification . . . . . . . . . . . . . . . . . . . . . . 107
8.3.3 Scenario 3: Alarm Transmission . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
9 Real Time Configuration Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
9.1 Real Time Configuration Manager Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
9.2 RTCM Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
9.2.1 Customer Application Using Global Call RTCM . . . . . . . . . . . . . . . . . . . . . . . . . 111
9.2.2 Global Call RTCM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
9.2.3 RTCM Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
9.3 Using RTCM Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
9.3.1 Parameter Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
9.3.2 Parameter Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
9.4 Getting and Setting Parameter Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
9.4.1 GC_PARM_BLK Data Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
9.4.2 Control Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
9.5 Handling RTCM Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
9.6 Configuration Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
9.7 Sample Scenarios Using the RTCM API Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
9.7.1 Getting or Setting GCLib Configuration in Synchronous Mode. . . . . . . . . . . . . . 119
9.7.2 Getting or Setting CCLib Configuration in Synchronous Mode. . . . . . . . . . . . . . 120
9.7.3 Getting or Setting Line Device Configuration in Synchronous Mode . . . . . . . . . 121
9.7.4 Setting Line Device Configuration in Asynchronous Mode . . . . . . . . . . . . . . . . . 123
9.7.5 Setting Board Device Configuration in Asynchronous Mode (IP Technology) . . 124
10 Handling Service Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
10.1 Service Request Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
10.2 Service Request Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
10.3 Service Request Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
10.4 General Service Request Scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
11 Using Global Call to Implement Call Transfer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
11.1 Introduction to Call Transfer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
11.1.1 Blind Call Transfer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
11.1.2 Supervised Call Transfer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
11.2 Call Transfer State Machine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
12 Building Applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
12.1 Compiling and Linking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
12.1.1 Include Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
12.1.2 Required Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
12.1.3 Variables for Compiling and Linking Commands . . . . . . . . . . . . . . . . . . . . . . . . 140
12.1.4 Dynamically Loaded Libraries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
13 Debugging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
Global Call API for HMP on Windows Programming Guide – August 2006 5
Contents
Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
6 Global Call API for HMP on Windows Programming Guide – August 2006
Contents
Figures
1 Global Call Architecture for IP Technology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
2 Global Call Architecture for E1/T1 and ISDN Technologies . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
3 Call Control Library States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
4 Basic Asynchronous Inbound Call State Diagram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
5 Basic Asynchronous Inbound Call Scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
6 Incoming Call Scenario with Call Proceeding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
7 Call Acknowledgement and Call Proceeding Done at the Application Layer. . . . . . . . . . . . . . . 49
8 Call Proceeding Done by the Application Layer with Minimum Information Configured . . . . . . 50
9 Call Acknowledgement and Call Proceeding Done at Technology Call Control Layer . . . . . . . 51
10 Call Acknowledgement Done by the Technology Call Control Layer and Call Proceeding Done by
the Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
11 Basic Asynchronous Outbound Call State Diagram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
12 Asynchronous Outbound Call Scenario. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
13 Asynchronous Outbound Call Scenario With Call Acknowledgement . . . . . . . . . . . . . . . . . . . . 59
14 Asynchronous Outbound Call Scenario With Overlap Sending . . . . . . . . . . . . . . . . . . . . . . . . . 60
15 Asynchronous Call Tear-Down State Diagram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
16 User Initiated Asynchronous Call Termination Scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
17 Network Initiated Asynchronous Call Termination Scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
18 Call State Transitions for Hold and Retrieve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
19 Call State Model for Supervised and Unsupervised Transfers . . . . . . . . . . . . . . . . . . . . . . . . . 68
20 Call Termination by the Network or Application During a Transfer . . . . . . . . . . . . . . . . . . . . . . 69
21 Architectural Diagram of Alarm Management Components . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
22 Notification of First and Last Blocking Alarm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
23 Default Behavior for Alarm Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
24 Alarm Transmission . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
25 Relationship of Customer Application, Global Call RTCM, and RTCM Parameters . . . . . . . . 110
26 Run Time Configuration Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
27 Getting or Setting GCLib Configuration in Synchronous Mode . . . . . . . . . . . . . . . . . . . . . . . . 119
28 Getting or Setting CCLib Configuration in Synchronous Mode . . . . . . . . . . . . . . . . . . . . . . . . 120
29 Getting or Setting Line Device Configuration in Synchronous Mode. . . . . . . . . . . . . . . . . . . . 122
30 Setting Line Device Configuration in Asynchronous Mode (E1, T1 and ISDN Technology) . . 123
31 Setting Board Device Configuration in Asynchronous Mode (IP Technology). . . . . . . . . . . . . 124
32 Service Request Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
33 Generic Service Request Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
34 Blind Call Transfer (Unsupervised Transfer) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
35 Supervised Call Transfer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
36 Call State Model for Blind Call Transfer at Party A . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
37 Call State Model for Blind Transfer at Party B . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
38 Call State Model for Supervised Transfer at Party A . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
39 Call State Model for Supervised Transfer at Party B . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
40 Call State Model for Supervised Transfer at Party C. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Global Call API for HMP on Windows Programming Guide – August 2006 7
Contents
8 Global Call API for HMP on Windows Programming Guide – August 2006
Contents
Tables
1 Call Control Library States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
2 Supported Target Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
3 Target Types and Target IDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
4 Target Object Availability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
5 Obtaining Target IDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
6 Asynchronous Inbound Call State Transitions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
7 Asynchronous Outbound Call State Transitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
8 Asynchronous Call Termination Call State Transitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
9 Unsolicited Events Requiring Signal Handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
10 Handling Glare. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
11 Call Progress Analysis Settings and Possible Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
12 Comparison with Call Progress Analysis Using gc_SetParm( ). . . . . . . . . . . . . . . . . . . . . . . . . 92
13 Update Condition Flag and Global Call Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
14 New Global Call Transfer Call States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Global Call API for HMP on Windows Programming Guide – August 2006 9
Contents
10 Global Call API for HMP on Windows Programming Guide – August 2006
Revision History
This revision history summarizes the changes made in each published version of this document.
Document No. Publication Date Description of Revisions
05-2409-003 August 2006 Call Control Libraries section: Updated the library descriptions to identify the
technologies/protocols that each library supports.
Using Protocols (Flexible Routing) section: Removed incorrect reference to using the
DM3 PDK Manager.
Setting Call Analysis Attributes on a Per Call Basis section: Updated to indicate that
PAMD_QUAL2TMP is not supported and to provide a pointer to a related Tech
Note.
Debugging chapter : Added reference to the “Runtime Trace Facility (RTF) Reference”
chapter in the Intel Dialogic System Diagnostics Guide.
05-2409-002 October 2005 Global change: Added support for protocols that can be run on the E1 or T1
interfaces provided by Intel NetStructure
Global change: Updates to recognize the Intel NetStructure
Starting Call Control Libraries section : Added note about loading only the required
call control libraries to keep the required memory footprint small.
Overlap Sending section : Explicitly mentioned ISDN in the list of technologies that do
not have messages to request more information.
Configuring Default Call Progress Analysis Parameters section: Added a note that
pre-connect call progress is enabled by default, regardless of the CPA setting in
the CONFIG file
Real Time Configuration Management chapter : Fixed several references to
gc_util_insert_val( ) and gc_util_insert_ref( ) which should be
gc_util_insert_parm_val( ) and gc_util_insert_parm_ref( ).
Supervised Transfers section: Updated the call termination figure and added note to
describe the unsolicited GCEV_CONNECTED event that is generated for a call
when the new call being set up is terminated.
05-2409-001 April 2005 Initial version of document. Much of the information contained in this document was
previously published in the Global Call API for Windows Operating Systems
Programming Guide, document number 05-1867-002.
®
Digital Network Interface boards.
®
brand.
Global Call API for HMP on Windows Programming Guide — August 2006 11
Revision History
12 Global Call API for HMP on Windows Programming Guide — August 2006
About This Publication
The following topics provide information about this publication:
• Purpose
• Intended Audience
• How to Use This Publication
• Related Information
Purpose
This publication provides guidelines for using the Global Call API to build computer telephony
applications that require call control functionality. Such applications include, but are not limited to,
Call Routing, Enhanced Services, Unified Messaging, Voice Messaging, LAN Telephony Services,
Computer Telephony Services, Switching, PBX, Interactive Voice Response, Help Desk and Work
Flow applications. This publication is a companion guide to the Global Call API Library Reference
that provides details on the functions and parameters in the Global Call API library and the Global
Call Technology Guides that provide IP-, E1/T1- and ISDN-specific information.
Host Media Processing (HMP) software performs media processing tasks on general-purpose
servers based on Intel
system, HMP performs like a virtual DM3 board to the customer application, but all media
processing takes place on the host processor. In this document, the term “board” represents the
virtual DM3 board, unless explictly noted otherwise. Intel NetStructure
boards provide physical E1 and T1 interfaces for applications that require E1/T1 network
connectivity.
®
architecture without the need for specialized hardware. When installed on a
®
Digital Network Interface
Applicability
This document is published for Intel NetStructure® Host Media Processing Software.
Intended Audience
This publication is written for the following audience:
• Distributors
• System Integrators
• Toolkit Developers
• Independent Software Vendors (ISVs)
• Value Added Resellers (VARs)
Global Call API for HMP on Windows Programming Guide — August 2006 13
About This Publication
• Original Equipment Manufacturers (OEMs)
How to Use This Publication
Refer to this publication after you have installed the hardware and the system software, which
includes the Global Call software.
This publication assumes that you are familiar with the Windows operating system and the C
programming language.
The information in this guide is organized as follows:
• Chapter 1, “Product Description” provides an overview of the Global Call development
software.
• Chapter 2, “Programming Models” describes the supported programming models in the
Windows environment.
• Chapter 3, “Call State Models” describes the call state models used by Global Call.
• Chapter 4, “Event Handling” describes how to handle Global Call events.
• Chapter 6, “Error Handling” describes the error handling facilities provided by Global Call.
• Chapter 5, “Application Development Guidelines” provides guidelines when developing
applications that use Global Call.
• Chapter 7, “Call Control” describes basic call control capabilities, resource routing and feature
extensions provided by Global Call.
• Chapter 8, “Alarm Handling” describes how Global Call can be used to handle alarms.
• Chapter 9, “Real Time Configuration Management” describes how Global Call can be used for
real time configuration of parameters associated with the interface.
• Chapter 10, “Handling Service Requests” describes the generic service request facility
provided by Global Call.
• Chapter 11, “Using Global Call to Implement Call Transfer” provides general information on
the implementation of unsupervised (blind) and supervised call transfer.
• Chapter 12, “Building Applications” provides guidelines for building applications that use the
Global Call software.
• Chapter 13, “Debugging” provides pointers to where technology-specific debugging
information can be obtained.
• The Glossary provides a definition of terms used in this guide.
Related Information
Refer to the following sources for more information:
• Global Call API Library Reference
• Global Call E1/T1 CAS/R2 Technology Guide
• Global Call ISDN Technology Guide
14 Global Call API for HMP on Windows Programming Guide — August 2006
About This Publication
• Global Call IP Technology Guide
• Standard Runtime Library API Programming Guide.
• Standard Runtime Library API Library Reference.
• The Release Update for your HMP software, which may include updates to this manual,
available on the Telecom Support Resources website at:
http://www.intel.com/design/network/products/telecom/software/index.htm
• http://developer.intel.com/design/telecom/support/ (for technical support)
• http://www.intel.com/design/network/products/telecom (for product information)
Global Call API for HMP on Windows Programming Guide — August 2006 15
About This Publication
16 Global Call API for HMP on Windows Programming Guide — August 2006
1.Product Description
This chapter describes the Global Call software. Topics include:
• Global Call Software Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
• Global Call Feature Categories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
• Global Call Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
• Call Control Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
• Global Call Object Identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
1.1 Global Call Software Overview
Global Call development software provides a common signaling interface for network-enabled
applications, regardless of the signaling protocol needed to connect to the local telephone network.
The signaling interface provided by Global Call software facilitates the exchange of call control
messages between the telephone network and virtually any network-enabled application. Global
Call software enables developers to create applications that can work with signaling systems
worldwide, regardless of the network to which the applications are connected. The Global Call
software is ideal for high-density, network-enabled solutions, such as voice, data, and video
applications, where the supported hardware and signaling technology can vary widely from country
to country.
1
As an example, the signal acknowledgement or information flow required to establish a call may
vary from country to country. Rather than requiring the application to handle low-level details,
Global Call software offers a consistent, high-level interface to the user and handles each country's
unique protocol requirements transparently to the application.
The Global Call software comprises three major components:
Global Call Application Programming Interface (API)
A common, extensible API providing network interfaces to higher levels of software.
Application developers use API function calls in their computer telephony applications. The
Global Call API is the preferred call control interface.
Call Control Libraries
A set of libraries that provide the interface between the Global Call API and the various
network signaling protocols.
Global Call Protocols
Network signaling protocols, such as T1 Robbed Bit, E1 CAS, ISDN, QSIG, IP H.323 and SIP
can be invoked by the Global Call API to facilitate call control.
Global Call API for HMP on Windows Programming Guide — August 2006 17
Product Description
1.2 Global Call Feature Categories
The Global Call development software provides many features allowing for the development of
flexible and robust applications. The features fall into one of two main categories:
• Call Control Features
• Operation, Administration and Maintenance Features
1.2.1 Call Control Features
The Global Call development software provides the following call control features:
Basic Call Control
Includes basic call control features such as, the ability to make a call, detect a call, answer a
call, release a call, etc. The implementation of these capabilities is based on the basic call state
model, which is a common model for all network technologies. See Section 3.2, “Basic Call
Model” for more information on the basic call model.
Advanced Call Model
Defines the behavior for advanced features, such as hold and transfer. These capabilities are
provided to support technologies and protocols that support such features, for example,
Supervised Transfer. The implementation of these capabilities is based on a more advanced
call state model. See Section 3.5, “Advanced Call Control with Call Hold and Transfer” for
more information. The advanced call model applies only to E1/T1 and ISDN technologies, not
IP technology, which uses a different scheme for features such as call transfer. See the Global
Call IP Technology Guide.
Call Progress and Call Analysis
Provides the capabilities for handling pre-connect (Call Progress) information that reports the
status of the call connection, such as, busy, no dial tone or no ringback, and post connect (Call
Analysis) information that reports the destination party’s media type, for example, voice,
answering machine, or fax modem. This information is determined by the detection of tones
defined specifically for this purpose. See Section 7.2, “Call Progress Analysis when Using
Digital Network Interface Boards” for more information. The call progress and call analysis
feature applies only to E1/T1 and ISDN technologies, not IP technology.
Feature Transparency and Extension (FTE)
Provides the ability to extend the capabilities of Global Call to handle features that are specific
to a particular technology so that those features are accessible via the Global Call interface.
For example, for ISDN applications, Global Call supports supplementary services such as
Overlap Send, Overlap Receive, Any Message, Any IE, and User-to-User messaging. See
Section 7.4, “Feature Transparency and Extension” for more information.
1.2.2 Operation, Administration and Maintenance Features
The Global Call development software provides the following features that facilitate the operation,
administration and maintenance of Global Call applications:
Error Handling Functionality
When an error occurs, Global Call provides functions that enable an application to retrieve
more information about the error. See Chapter 6, “Error Handling” for more information.
18 Global Call API for HMP on Windows Programming Guide — August 2006
Product Description
Event Handling Functionality
Provides the ability to handle and process events, including the ability to disable and enable
events and to retrieve event information. See Chapter 4, “Event Handling” for more
information.
Global Call Alarm Management System (GCAMS)
Provides the ability to manage alarms. GCAMS provides Global Call applications with the
ability to receive extensive alarm information that can be used to troubleshoot line problems.
See Chapter 8, “Alarm Handling” for more information.
Real Time Configuration Management (RTCM)
Allows the modification of call control and protocol elements in real time, providing a single
common user interface for configuration management. See Chapter 9, “Real Time
Configuration Management” for more information.
Global Call Service Request (GCSR)
Enables an application to send a request for a service to a remote device. Examples of the types
of services that this feature supports are device registration, channel setup, call setup,
information requests, or other kinds of requests that need to be made between two devices
across the network. See Chapter 10, “Handling Service Requests” for more information.
Library Information Functions
Enables an application to get information about the call control libraries being used. See the
Global Call API Library Reference for more information about these functions.
Debugging Facilities
Global Call provides powerful debugging capabilities for troubleshooting protocol-related
problems, including the ability to generate a detailed log file. See the appropriate Global Call
Technology Guide for information on the debugging facilities available when using Global
Call with each technology.
1.3 Global Call Architecture
The Global Call development software architecture is based on the Intel® Dialogic® architecture
that supports Host Media Processing (HMP) software and DM3 hardware. The architecture is
described in the following topics:
• Overview
• Global Call API
1.3.1 Overview
Figure 1 shows a system-level view of the Global Call architecture for IP technology and Figure 2
shows the Global Call architecture for E1/T1 and ISDN technologies on DM3 hardware.
Global Call API for HMP on Windows Programming Guide — August 2006 19
Product Description
Figure 1. Global Call Architecture for IP Technology
Host Application
GlobalCall
Signaling
IP Network
Call Control
Host
NIC
Media
IP Network
H.323 or SIP
Call Control
Library
(IPT CCLib)
RTP/RTCP
Media
Control
Media
Routing
IP Media
Call Control
Library
(IPM CCLib)
IP Media
Resource
20 Global Call API for HMP on Windows Programming Guide — August 2006
Figure 2. Global Call Architecture for E1/T1 and ISDN Technologies
User Application
GlobalCall API
Product Description
Other
Dialogic
Libraries
1.3.2 Global Call API
Call Control Library
Device Driver Operating Systems
Firmware
Network Interface
DM3CC
Firmware
Network Interface
PSTN
The Global Call API is a call control API. Similar to other Intel Dialogic APIs (such as the Voice
API), the Global Call API uses the Standard Runtime Library (SRL) API to deliver response events
to its API commands. The Global Call API and other Intel Dialogic APIs form a family of APIs
that use the underlying services provided by the SRL API.
The Global Call API provides a collection of functions supporting call control operations as well as
functions to support operation, administration and maintenance tasks. See the Global Call API
Library Reference for detailed information about each function.
Global Call API for HMP on Windows Programming Guide — August 2006 21
Product Description
1.4 Call Control Libraries
Each supported network technology requires a call control library to provide the interface between
the network and the Global Call library. The call control libraries currently supported by the
Global Call API for HMP are as follows:
GC_CUSTOM1_LIB
The first of two call control library place holders for custom call control libraries. Any thirdparty Global Call compatible call control library can be used as a custom library. The Global
Call library supports up to two custom libraries.
GC_CUSTOM2_LIB
The second of two call control library place holders for custom call control libraries. Any
third-party Global Call compatible call control library can be used as a custom library. The
Global Call library supports up to two custom libraries.
GC_DM3CC_LIB
The call control library that controls access to network interfaces on Digital Network Interface
boards. This library is used for call control using ISDN and CAS/R2MF (PDK protocols)
signaling on Digital Network Interface boards.
GC_H3R_LIB
The call control library that controls access to IP network interfaces. This call control library
supports IP H.323 and SIP protocols and is used in conjunction with GC_IPM_LIB.
GC_IPM_LIB
The call control library that provides access to IP media resources. This library is used for
H323/SIP call control signaling and is used in conjunction with GC_H3R_LIB.
1.4.1 Starting Call Control Libraries
Call control libraries must be started before they can be used by the Global Call functions. The call
control libraries are started when a gc_Start( ) function is issued. The gc_Start( ) function allows
the selective starting of call control libraries where the application can specify if all the call control
libraries are to be started or only specified libraries are to be started. The application can also start
a custom call control library that is not supported by Global Call. See the Global Call API Library
Reference for more information about the gc_Start( ) function.
Note: Invoking gc_Start(NULL) loads all call control libraries and consequently the memory footprint
includes memory that is allocated for all call control libraries. To reduce the memory footprint,
selective loading of call control libraries is recommended. For more information and an example,
see the gc_Start( ) function in the Global Call API Library Reference.
1.4.2 Call Control Library States
The initial state of all the call control libraries is the Configured state. When a call control library is
successfully started, the library will be in the Available state. If the call control library fails to start,
the library will be in the Failed state as shown in the diagram below. If the call control library is not
started, it remains in the Configured state.
22 Global Call API for HMP on Windows Programming Guide — August 2006
Figure 3. Call Control Library States
CONFIGURED
gc_Start()
Product Description
Start
Successful
AVAILABLE FAILED
Start
Failed
Table 1 describes the different states of a call control library.
Table 1. Call Control Library States
State Description
Configured A library that is supported by Global Call is considered a configured library.
Available A library that has been successfully started is considered to be available for use by a
Global Call application.
Failed A library that has failed to start is considered to be unavailable for use by a Global Call
application.
Each configured call control library is assigned an ID number by Global Call. Each library also has
a name in an ASCII string format. Library functions perform tasks such as converting a call control
library ID to an ASCII name and vice-versa, determining the configured libraries, determining the
available libraries, determining the libraries started and the libraries that failed to start, and other
library functions.
The following functions are the call control library information functions. All the library functions
are synchronous, thus they return without a termination event.
• gc_CCLibIDToName( )
• gc_CCLibNameToID( )
• gc_CCLibStatusEx( )
• gc_GetVer( )
See the Global Call API Library Reference for detailed information about these functions.
1.5 Global Call Object Identifiers
The Global Call API is call-oriented, that is, each call initiated by the application or network is
assigned a Call Reference Number (CRN) for call control and tracking purposes. Call handling is
independent of the line device over which the call is routed. Each line device or device group is
assigned a Line Device Identifier (LDID) that enables the application to address any resource or
Global Call API for HMP on Windows Programming Guide — August 2006 23
Product Description
group of resources using a single device identifier. Certain features, such as Feature Transparency
and Extension (FTE), Real Time Configuration Management (RTCM), and Global Call Service
Request (GCSR) operate on a basic entity called a Global Call target object. Target objects are
identified by a target type and a target ID.
The following topics provide more detailed information:
• Line Device Identifier
• Call Reference Number
• Object Identifiers and Resource Sharing Across Processes
• Target Objects
1.5.1 Line Device Identifier
A Line Device Identifier (LDID) is a unique logical number assigned to a specific resource (for
example, a time slot) or a group of resources within a process by the Global Call library. Minimally,
the LDID number will represent a network resource. For example, both a network resource and a
voice resource are needed to process an R2 MFC dialing function. Using Global Call, a single
LDID number is used by the application (or thread) to represent this combination of resources for
call control.
An LDID number is assigned to represent a physical device(s) or logical device(s) that will handle
a call, such as a network interface resource, when the gc_OpenEx( ) function is called. This
identification number assignment remains valid until the gc_Close( ) function is called to close the
line device.
When an event arrives, the application (or thread) can retrieve the LDID number associated with
the event by using the linedev field of the associated METAEVENT structure. The LDID is
retrieved using the gc_GetMetaEvent( ) or the gc_GetMetaEventEx( ) function.
1.5.2 Call Reference Number
A Call Reference Number (CRN) is a means of identifying a call on a specific line device. A CRN
is created by the Global Call library when a call is requested by the application, thread or network.
With the CRN approach, the application (or thread) can access and control the call without any
reference to a specific physical port or line device. CRNs are assigned to both inbound and
outbound calls:
Inbound calls
The CRN is assigned via the gc_WaitCall( ) function. For more information on
gc_WaitCall( ), see the Global Call API Library Reference.
Outbound calls
The CRN is assigned via the gc_MakeCall( ) function. For more information on this function,
see the Global Call API Library Reference.
This CRN has a single LDID associated with it, for example, the line device on which the call was
made. However, a single line device may have multiple CRNs associated with it (that is, more than
24 Global Call API for HMP on Windows Programming Guide — August 2006
Product Description
one call may exist on a given line). A line device can have a maximum of 20 CRNs associated with
it. At any given instant, each CRN is a unique number within a process. After a call is terminated
and the gc_ReleaseCallEx( ) function is called to release the resources used for the call, the CRN
is no longer valid.
1.5.3 Object Identifiers and Resource Sharing Across Processes
The CRNs and LDIDs assigned by the Global Call API library can not be shared among multiple
processes. These assigned CRNs and LDIDs remain valid only within the process invoked. That is,
for call control purposes, you should not open the same physical device from more than one
process, nor from multiple threads in a Windows environment. Unpredictable results may occur if
this advice is not followed.
1.5.4 Target Objects
A target object provides a way of identifying a particular entity that is maintained by a specific
software module. In API function calls, the target object is specified by a pair of parameters, the
target_type and target_ID:
target_type
Identifies the kind of software module and the entity that it maintains. For example, the target
type GCTGT_GCLIB_CHAN represents the Global Call Library and a channel entity that it
maintains.
target_ID
Identifies the specific target object, such as a line device ID (LDID), which is generated by
Global Call at runtime.
Table 2 shows the combinations of physical or logical entities and software module entities that can
make up a target type (target_type).
Table 2. Supported Target Types
Software Module
GCLib SSSS
CCLib S S S S
Protocol SV SV SV
Firmware SV SV
S = Supported
SV = Supported with Variances, see the appropriate Global Call Technology Guide for more information.
The possible software modules include:
• GCLib
• CCLib
• Protocol
Entity
System Network Interface Channel CRN
Global Call API for HMP on Windows Programming Guide — August 2006 25
Product Description
• Firmware
The possible entities include:
System
NIC for IP technology; all physical boards for E1, T1 and ISDN technologies
Network Interface
logical board or virtual board
Channel
time slot
CRN
call reference number
A target type (target_type) name is composed of the prefix, GCTGT, which stands for Global Call
Target, a software module name, such as GCLIB, and an entity name, such as NETIF. For example,
the target type GCTGT_GCLIB_NETIF, indicates that the desired target type is a network interface
maintained by the Global Call library.
A target ID (target_ID) identifies the specific object that is located within the category defined by
the target type (target_type). A target ID can be any of the following:
• line device ID (LDID)
• call reference number (CRN)
• Global Call library ID (GCGV_LIB)
• call control library ID (CCLib ID)
• protocol ID
The types and IDs for target objects are defined at the Global Call level. Table 3 shows the target
types, as described in Table 2, with various target IDs to represent valid target objects.
Table 3. Target Types and Target IDs
Target Type Target ID Description
GCTGT_GCLIB_SYSTEM
GCTGT_CCLIB_SYSTEM †
GCTGT_GCLIB_NETIF Global Call Line device ID Network interface target object in Global
GCTGT_CCLIB_NETIF Global Call Line device ID Network interface target object in call
GCTGT_GCLIB_CHAN Global Call Line device ID Channel target object in Global Call library
GCTGT_CCLIB_CHAN Global Call Line device ID Channel target object in call control library
† For E1, T1 and ISDN technologies only.
‡ Target types that can only be used by functions issued in synchronous mode. If a function uses one of these target types in
asynchronous mode, an error will be generated. The functions that can use these target types are gc_GetConfigData( ) (E1, T1
and ISDN technologies only), gc_SetConfigData( ), gc_ReqService( ), and gc_RespService( ).
‡ GCGV_LIB Global Call library module target object.
‡ CCLib ID Call control library module target object.
Call Library module.
control library module.
module.
module.
26 Global Call API for HMP on Windows Programming Guide — August 2006
Table 3. Target Types and Target IDs (Continued)
Target Type Target ID Description
GCTGT_GCLIB_CRN Global Call CRN CRN target object in Global Call library
GCTGT_CCLIB_CRN Global Call CRN CRN target object in call control library
† For E1, T1 and ISDN technologies only.
‡ Target types that can only be used by functions issued in synchronous mode. If a function uses one of these target types in
asynchronous mode, an error will be generated. The functions that can use these target types are gc_GetConfigData( ) (E1, T1
and ISDN technologies only), gc_SetConfigData( ), gc_ReqService( ), and gc_RespService( ).
Target Object Availability
Except for the GCTGT_GCLIB_SYSTEM target object, all target IDs are generated or assigned by
the Global Call API when the target object is created (for physical targets) or loaded (for software
targets). Table 4 shows when a target object becomes available and when it becomes unavailable,
depending on the target type.
Table 4. Target Object Availability
Product Description
module.
module.
Target Type Target Object Available Target Object Unavailable
GCTGT_GCLIB_SYSTEM
GCTGT_CCLIB_SYSTEM †
GCTGT_GCLIB_CRN
GCTGT_CCLIB_CRN
GCTGT_GCLIB_NETIF
GCTGT_CCLIB_NETIF
GCTGT_GCLIB_CHAN
GCTGT_CCLIB_CHAN
† For E1, T1 and ISDN technologies only.
Retrieving Target IDs
Before the Global Call application can retrieve, update, or query the configuration data of a target
object, it should obtain the target ID as shown in Table 5.
Table 5. Obtaining Target IDs
Target ID Procedure for Obtaining Target ID
GCGV_LIB After the call control library has been successfully started (that is, after the
Global Call Line Device ID † After a line device is opened, the CCLib ID and protocol ID (if applicable)
After gc_Start( ) After gc_Stop( )
After a call is created
(gc_MakeCall( ) returns or
GCEV_OFFERED is received)
After gc_OpenEx( ) After gc_Close( )
gc_Start( ) function is called), the target object’s CCLib ID can be obtained by
calling the gc_CCLibNameToID( ) function.
associated with this line device can be obtained by the gc_GetConfigData( )
function with the set ID and parameter ID as (GCSET_CCLIB_INFO,
GCPARM_CCLIB_ID) and (GCSET_PROTOCOL,
GCPARM_PROTOCOL_ID).
After gc_ReleaseCallEx( )
Global Call API for HMP on Windows Programming Guide — August 2006 27
Product Description
Table 5. Obtaining Target IDs
Target ID Procedure for Obtaining Target ID
Global Call CRN After a call target object is created, its target object ID (that is, the Global Call
† For E1, T1 and ISDN technologies only.
CRN) will be an output of the gc_MakeCall( ) function or provided by the
metaevent associated with the GCEV_OFFERED event.
28 Global Call API for HMP on Windows Programming Guide — August 2006
2.Programming Models
This chapter describes the programming models supported by Global Call. Topics include:
• Programming Models Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
• Asynchronous Mode Programming. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
2.1 Programming Models Overview
The Global Call development software supports application development using asynchronous
programming models. By usage, the asynchronous models are often said to use asynchronous
mode. Asynchronous mode programming is introduced briefly in this chapter and described in
more detail in the Standard Runtime Library API Programming Guide.
2.2 Asynchronous Mode Programming
Programming in asynchronous mode in Windows is described in the following topics:
• Asynchronous Model Overview
• Asynchronous Model with Event Handlers
• Asynchronous with Windows Callback Model
• Asynchronous with Win32 Synchronization Model
• Extended Asynchronous Programming Model
2
2.2.1 Asynchronous Model Overview
Asynchronous mode programming is characterized by the calling thread performing other
processing while a function executes. At completion, the application receives event notification
from the SRL and then the thread continues processing the call on a particular channel.
A function called in the asynchronous mode returns control immediately after the request is passed
to the device driver and allows thread processing to continue. A termination event is returned when
the requested operation completes, thus allowing the Intel Dialogic operation (state machine
processing) to continue.
Caution: In general, when a function is called in asynchronous mode, and an associated termination event
exists, the gc_Close( ) function should not be called until the termination event has been received.
In order to disable gc_WaitCall( ), gc_ResetLineDev( ) should be called. If this is not done, there
are potential race conditions under which the application may crash with a segmentation fault.
Functions may be initiated asynchronously from a single thread and/or the completion
(termination) event can be picked up by the same or a different thread that calls the sr_waitevt( )
Global Call API for HMP on Windows Programming Guide — August 2006 29
Programming Models
and gc_GetMetaEvent( ) functions. When these functions return with an event, the event
information is stored in the METAEVENT data structure. The event information retrieved
determines the exact event that occurred and is valid until the sr_waitevt( ) and
gc_GetMetaEvent( ) functions are called again.
For Windows environments, the asynchronous models provided for application development also
include:
• asynchronous model with event handlers
• asynchronous with Windows callback
• asynchronous with Win32 synchronization
• extended asynchronous programming
The asynchronous programming models are recommended for more complex applications that
require coordinating multiple tasks. Asynchronous model applications typically run faster than
synchronous models and require lower levels of system resources. Asynchronous models reduce
processor loading because of the reduced number of threads inherent in asynchronous models and
the elimination of scheduling overhead. Asynchronous models use processor resources more
efficiently because multiple channels are handled in a single thread or in a few threads. See
Section 5.1, “General Programming Tips”, on page 77 for details. Of the asynchronous models, the
asynchronous with SRL callback model and the asynchronous with Windows callback model
provide the tightest integration with the Windows message/event mechanism. Asynchronous model
applications are typically more complex than corresponding synchronous model applications due
to a higher level of resource management (that is, the number of channels managed by a thread and
the tracking of completion events) and the development of a state machine.
After the application issues an asynchronous function, the application uses the sr_waitevt( )
function to wait for events on Intel Dialogic devices. All event coding can be accomplished using
switch statements in the main thread. When an event is available, event information may be
retrieved using the gc_GetMetaEvent( ) function. Retrieved event information is valid until the
sr_waitevt( ) function is called again. The asynchronous model does not use event handlers to
process events.
In this model, the SRL handler thread must be initiated by the application by setting the
SR_MODELTYPE value to SR_STASYNC.
2.2.2 Asynchronous Model with Event Handlers
The asynchronous with event handlers model uses the sr_enbhdlr( ) function to automatically
create the SRL handler thread. The application does not need to call the sr_waitevt( ) function
since the thread created by the sr_enbhdlr( ) already calls the sr_waitevt( ) function to get events.
Each call to the sr_enbhdlr( ) function allows the Intel Dialogic events to be serviced when the
operating system schedules the SRL handler thread for execution.
Note: The SR_MODELTYPE value must not be set to SR_STASYNC because the SRL handler thread
must be created by the sr_enbhdlr( ) call. The event handler must not call the sr_waitevt( )
function or any synchronous Intel Dialogic function.
30 Global Call API for HMP on Windows Programming Guide — August 2006
Loading...