Intel 05-2409-003 About This Publication

Global Call API for HMP on Windows Programming Guide — August 2006 13

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® architecture without the need for specialized hardware. When installed on a

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® Digital Network Interface

boards provide physical E1 and T1 interfaces for applications that require E1/T1 network

connectivity.

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)

Contents

Main Global Call API for HMP on Windows Programming Guide August 2006 Contents Page Page Page Figures Page Tab le s Page Revision History This revision history summarizes the changes made in each published version of this document. Page About This Publication Purpose Applicability Intended Audience How to Use This Publication Related Information Page Page 1.1 Global Call Software Overview 1.2 Global Call Feature Categories 1.2.1 Call Control Features 1.2.2 Operation, Administration and Maintenance Features 1.3 Global Call Architecture 1.3.1 Overview 20 Global Call API for HMP on Windows Programming Guide August 2006 Product Description Figure 1. Global Call Architecture for IP Technology 1.3.2 Global Call API 1.4 Call Control Libraries 1.4.1 Starting Call Control Libraries 1.4.2 Call Control Library States 1.5 Global Call Object Identifiers 1.5.1 Line Device Identifier 1.5.2 Call Reference Number 1.5.3 Object Identifiers and Resource Sharing Across Processes 1.5.4 Target Objects Page Target Object Availability Retrieving Target IDs Page 2.1 Programming Models Overview 2.2 Asynchronous Mode Programming 2.2.1 Asynchronous Model Overview 2.2.2 Asynchronous Model with Event Handlers 2.2.3 Asynchronous with Windows Callback Model 2.2.4 Asynchronous with Win32 Synchronization Model 2.2.5 Extended Asynchronous Programming Model Page 3.1 Call State Model Overview 3.2 Basic Call Model 3.2.1 Basic Call States at the Inbound Interface 3.2.2 Basic Call States at the Outbound Interface 3.2.3 Basic Call States for Call Termination 3.3 Basic Call Model Configuration Options 3.3.1 Call State Configuration 3.3.2 Call State Event Configuration 3.3.3 Call Acknowledgement Configuration 3.3.4 Call Proceeding Configuration 3.4 Basic Call Control in Asynchronous Mode 3.4.1 Inbound Calls in Asynchronous Mode 3.4.1.1 Inbound Calls in Asynchronous Mode Overview Figure 4. Basic Asynchronous Inbound Call State Diagram gc_CallAck(MORE_INFO) GCEV_MOREINFO Table6. Asynchronous Inbound Call State Transitions State Description Previous/Next State Applies to E1, T1 and ISDN technology only. Valid Call State Trans iti on Functions Call Transition Events 3.4.1.2 Channel Initialization 3.4.1.3 Call Detection 3.4.1.4 Call Offered 3.4.1.5 Call Routing 3.4.1.6 Call Acceptance 3.4.1.7 Call Establishment 3.4.1.8 Overlap Receiving Scenario 1 Scenario 2 Scenario 3 Scenario 4 3.4.1.9 Call Failure 3.4.1.10 Abandoned Calls 3.4.1.11 Inbound Call Scenarios in Asynchronous Mode Page Page Page Page 3.4.2 Outbound Calls in Asynchronous Mode 3.4.2.1 Outbound Calls in Asynchronous Mode Overview Figure 11. Basic Asynchronous Outbound Call State Diagram GCEV_PROCEEDING Table7. Asynchronous Outbound Call State Transitions State Previous/Next State Applies to E1, T1 and ISDN technologies only. Valid Call State Transition Functions Call Transition Events 3.4.2.2 Channel Initialization 3.4.2.3 Call Dialing 3.4.2.4 Call Proceeding 3.4.2.5 Call Alerting 3.4.2.6 Call Connected 3.4.2.7 Overlap Sending 3.4.2.8 Call Failure 3.4.2.9 Outbound Call Scenarios in Asynchronous Mode Page 3.4.3 Call Termination in Asynchronous Mode 3.4.3.1 Call Termination in Asynchronous Mode Overview 3.4.3.2 User Initiated Termination 3.4.3.3 Network Initiated Termination 3.4.3.4 Call Release 3.4.3.5 Call Termination Call Control Scenarios in Asynchronous Mode Figure 17. Network Initiated Asynchronous Call Termination Scenario 3.4.4 Handling Unsolicited Events 3.5 Advanced Call Control with Call Hold and Transfer 3.5.1 Advanced Call State Model Overview 3.5.2 Advanced Call States for Hold and Transfer 3.5.3 Call Hold 3.5.4 Call Transfer 3.5.4.1 Call Transfer Overview 3.5.4.2 Supervised Transfers Figure 19. Call State Model for Supervised and Unsupervised Transfers 3.5.4.3 Unsupervised Transfers Page 4.1 Overview of Event Handling 4.2 Event Categories 4.3 Blocked and Unblocked Event Handling 4.4 Event Retrieval 4.5 Events Indicating Errors 4.6 Masking Events 4.7 Event Handlers Page Page Guidelines 5.1 General Programming Tips 5.2 Tips for Programming Drop and Insert Applications 5.3 Using Global Call with Digital Network Interface Boards 5.3.1 Routing Overview 5.3.2 Working with Flexible Routing Configurations 5.3.2.1 Determining Channel Capabilities (Flexible Routing) 5.3.2.2 Using Device Handles (Flexible Routing) 5.3.2.3 Multi-Threading and Multi-Processing (Flexible Routing) 5.3.2.4 Initializing an Application (Flexible Routing) 5.3.2.5 Initializing Global Call (Flexible Routing) Page 5.3.2.6 Device Initialization Hint (Flexible Routing) 5.3.2.7 Using Protocols (Flexible Routing) 5.3.3 Handling Multiple Call Objects Per Channel in a Glare Condition Page 6.1 Error Handling Overview Page 7.1 Call Progress Analysis when Using IP Technology 7.2 Call Progress Analysis when Using Digital Network Interface Boards 7.2.1 Call Progress Analysis Definition 7.2.2 Configuring Default Call Progress Analysis Parameters 7.2.3 Configuring Call Progress Analysis on a Per Call Basis Page 7.2.4 Setting Call Analysis Attributes on a Per Call Basis 7.2.5 Configuring Call Progress Analysis on a Per Channel Basis 7.2.6 Setting Call Analysis Attributes on a Per Channel Basis 7.2.7 Customizing Call Progress Tones on a Per Board Basis 7.3 Resource Routing 7.4 Feature Transparency and Extension 7.4.1 Feature Transparency and Extension Overview 7.4.2 Technology-Specific Feature Access 7.4.3 Technology-Specific User Information Page 8.1 Alarm Handling Overview 8.1.1 Alarm Management System Components Page 8.2 Operation and Configuration of GCAMS 8.2.1 Generation of Events for Blocking Alarms 8.2.2 Generation of Alarm Events 8.2.3 Configuration of Alarm Properties and Characteristics 8.2.3.1 Configuring Alarm Notification 8.2.3.2 Configuring Alarm Flow 8.2.3.3 Configuring Blocking and Non-Blocking Alarm Classification 8.2.3.4 Configuring Alarm Parameters 8.2.3.5 Alarm Configuration Tips 8.2.4 Starting and Stopping Alarm Transmission 8.2.5 Retrieving Alarm Data 8.2.5.1 Alarm Numbers and Names 8.2.5.2 Alarm Source Object IDs and Names 8.3 Sample Alarm Scenarios 8.3.1 Scenario 1: Application Notified of First and Last Blocking Alarm Page 8.3.2 Scenario 2: Default Behavior for Alarm Notification 8.3.3 Scenario 3: Alarm Transmission Management 9.1 Real Time Configuration Manager Overview 9.2 RTCM Components 9.2.1 Customer Application Using Global Call RTCM 9.2.2 Global Call RTCM 9.2.3 RTCM Parameters 9.3 Using RTCM Parameters 9.3.1 Parameter Dependencies 9.3.2 Parameter Definitions 9.4 Getting and Setting Parameter Information 9.4.1 GC_PARM_BLK Data Structure 9.4.2 Control Parameters 9.4.2.1 Programming Mode 9.4.2.2 Timeout Option 9.4.2.3 Update Condition 9.5 Handling RTCM Errors 9.6 Configuration Procedure Real Time Configuration Management Figure 26. Run Time Configuration Procedure 9.7 Sample Scenarios Using the RTCM API Functions 9.7.1 Getting or Setting GCLib Configuration in Synchronous Mode 9.7.2 Getting or Setting CCLib Configuration in Synchronous Mode 9.7.3 Getting or Setting Line Device Configuration in Synchronous Mode Page 9.7.4 Setting Line Device Configuration in Asynchronous Mode 9.7.5 Setting Board Device Configuration in Asynchronous Mode (IP Technology) Page Page 10.1 Service Request Overview 10.2 10.3 Service Request Data 10.4 General Service Request Scenario Handling Service Requests Figure 33. Generic Service Request Operation Call Transfer 11.1 Introduction to Call Transfer 11.1.1 Blind Call Transfer Figure 34. Blind Call Transfer (Unsupervised Transfer) 11.1.2 Supervised Call Transfer 11.2 Call Transfer State Machine Table14. New Global Call Transfer Call States Figure 36. Call State Model for Blind Call Transfer at Party A Transferring Party (Party A) Figure 37. Call State Model for Blind Transfer at Party B Transferred Party (Party B) Transferring Party (Party A) Call 1 Call 2 Figure 39. Call State Model for Supervised Transfer at Party B Call 1 Transferred Party (Party B) Call 3 Figure 40. Call State Model for Supervised Transfer at Party C Call 2 Call 3 Transferred-To Party (Party C) 12.1 Compiling and Linking 12.1.1 Include Files 12.1.2 Required Libraries 12.1.3 Variables for Compiling and Linking Commands 12.1.4 Dynamically Loaded Libraries Page Page Glossary Page Page Page Page Page Page Page Index A B C D F G I L M P R S T U