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.
Contents Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 About This Publication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Applicability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents 3.4 3.5 4 Event Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 4.1 4.2 4.3 4.4 4.5 4.6 4.7 5 7.3 7.4 Call Progress Analysis when Using IP Technology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 Call Progress Analysis when Using Digital Network Interface Boards . . . . . . . . . . . . . . . . 87 7.2.1 Call Progress Analysis Definition. . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents 8.3 9 Real Time Configuration Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 9.1 9.2 9.3 9.4 9.5 9.6 9.7 10 11.2 Service Request Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Service Request Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Service Request Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents Figures 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 Global Call Architecture for IP Technology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 Global Call Architecture for E1/T1 and ISDN Technologies . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 Call Control Library States. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents 8 Global Call API for HMP on Windows Programming Guide – August 2006
Contents Tables 1 2 3 4 5 6 7 8 9 10 11 12 13 14 Call Control Library States. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 Supported Target Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 Target Types and Target IDs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 Target Object Availability . . . . . . . . . . . . . . . .
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.
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.
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.
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.
About This Publication 16 Global Call API for HMP on Windows Programming Guide — August 2006
Product Description 1. 1 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 . . . . . . . . . . . . .
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.
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.
Product Description Figure 1. Global Call Architecture for IP Technology Host Application GlobalCall Media Routing Call Control Signaling IP Network Host NIC H.
Product Description Figure 2. Global Call Architecture for E1/T1 and ISDN Technologies User Application GlobalCall API Call Control Library Other Dialogic Libraries DM3CC Device Driver Operating Systems Firmware Firmware Network Interface Network Interface PSTN 1.3.2 Global Call API The Global Call API is a call control API.
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.
Product Description Figure 3. Call Control Library States CONFIGURED gc_Start() Start Successful Start Failed AVAILABLE 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.
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.
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.
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.
Product Description 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 module. GCTGT_CCLIB_CRN Global Call CRN CRN target object in call control library module. † 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.
Product Description Table 5. Obtaining Target IDs Target ID Global Call CRN Procedure for Obtaining Target ID After a call target object is created, its target object ID (that is, the Global Call CRN) will be an output of the gc_MakeCall( ) function or provided by the metaevent associated with the GCEV_OFFERED event. † For E1, T1 and ISDN technologies only.
Programming Models 2. 2 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.
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.
Programming Models Individual handlers can be written to handle events for each channel. The SRL handler thread can be used when porting applications developed for other operating systems. 2.2.3 Asynchronous with Windows Callback Model The asynchronous with Windows callback model allows an asynchronous application to receive SRL event notification through the standard Windows message handling scheme. This model is used to achieve the tightest possible integration with the Windows messaging scheme.
Programming Models Whereas default asynchronous programming uses the sr_waitevt( ) function to wait for events specific to one device, extended asynchronous programming uses the sr_waitevtEx( ) function to wait for events specific to a number of devices (channels). Note: Do not use the sr_waitevtEx( ) function in combination with either the sr_waitevt( ) function or event handlers. This model can run an entire application using only a few threads.
Call State Models 3. 3 This chapter describes the call state models provided by Global Call. Topics include the following: • Call State Model Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 • Basic Call Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 • Basic Call Model Configuration Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Call State Models 3.2.1 Basic Call States at the Inbound Interface The basic inbound call states are as follows: Null state (GCST_NULL) This state indicates that no call is assigned to the channel (time slot or line). This is the initial state of a channel when it is first opened. This state is also reached when a call is released or after the channel is reset. A channel in this state is available for inbound calls after being initialized to receive incoming calls.
Call State Models 3.2.2 Basic Call States at the Outbound Interface The basic outbound call states are as follows: Null state (GCST_NULL) This state indicates that no call is assigned to the channel (time slot or line). This is the initial state of a channel when it is first opened. This state is also reached when a call is released or after the channel is reset. The channel in this state is available for making outbound calls.
Call State Models Call Idle (GCST_IDLE) This state indicates that the local user has dropped the call. This may be a termination initiated by the local user or a response to the remote side disconnecting the call. While the call no longer exists, internal system resources committed to servicing the call are still present. The user must release these resources, as they are no longer required. 3.
Call State Models The GCACT_ADDMSK, GCACT_SUBMSK and GCACT_SETMSK parameter IDs can be assigned one of the following values (of type GC_VALUE_LONG), or an ORed combination of the values: • GCMSK_ALERTING_STATE • GCMSK_CALLROUTING_STATE (for E1, T1, and ISDN technologies only) • GCMSK_DETECTED_STATE • GCMSK_GETMOREINFO_STATE (for E1, T1, and ISDN technologies only) • GCMSK_PROCEEDING_STATE • GCMSK_SENDMOREINFO_STATE (for E1, T1, and ISDN technologies only) See the Global Call API Library Reference for more
Call State Models See the Global Call API Library Reference for more information on the gc_SetConfigData( ) function. 3.3.3 Call Acknowledgement Configuration Note: This functionality applies to E1, T1 and ISDN technologies only. When an incoming call is received, an acknowledgement is typically sent to the remote side to indicate that the call was received.
Call State Models 3.4 Basic Call Control in Asynchronous Mode This section describes and illustrates the basic call model and state transitions for call control in asynchronous mode. This section also describes the process for call establishment for both inbound and outbound calls and call termination in the asynchronous mode.
Call State Models Figure 4.
Call State Models Table 6.
Call State Models Table 6.
Call State Models is opened using the gc_OpenEx( ) function. However, if the gc_ResetLineDev( ) function was issued, gc_WaitCall( ) must be reissued. In asynchronous mode, it is not necessary to issue gc_WaitCall( ) again after a call is released. Note: 3.4.1.3 After gc_WaitCall( ) is issued to wait for incoming calls on a line device, it is possible to use gc_makeCall( ) to make an outbound calls on that line device.
Call State Models 3.4.1.5 Call Routing After the call has been offered, a call proceeding indication can be sent to the remote party to indicate that all the information has been received and the call is now proceeding. This indication can be sent by the technology call control layer or by the application by issuing the gc_CallAck(GCACK_SERVICE_PROC) function. This stage typically involves routing the call to the destination exchange or party.
Call State Models then the call is offered to the application regardless of the amount of information available. The application can then request and collect more information as required. The following sections describe various configurations operating in overlap receiving mode. Scenario 1 In this scenario, the application is configured to acknowledge the incoming call and send a call proceeding indication after sufficient information has been received.
Call State Models address (caller ID) by issuing the gc_GetCallInfo( ) function. If more information is required, the application may also request more address information using the gc_CallAck(GCACK_SERVICE_INFO) function. Since an acknowledgement was already sent out, no acknowledgement is sent to the remote side at this time. When the additional information is received, the GCEV_MOREINFO event is generated.
Call State Models the gc_ResetLineDev( ) function to reset the line device to the Null state. For more information, see the gc_DropCall( ), gc_ReleaseCallEx( ) and gc_ResetLineDev( ) function descriptions in the Global Call API Library Reference. 3.4.1.10 Abandoned Calls During call establishment, the remote side may choose to hang up before call setup has been completed. The application must be capable of handling error conditions and the lack of complete information when requesting call information.
Call State Models Figure 6 shows an asynchronous call scenario for an incoming call with call proceeding. Figure 6.
Call State Models Figure 7 shows an asynchronous call scenario for an incoming call with call acknowledgement and call proceeding controlled by the application. This scenario applies to E1, T1 and ISDN technologies only. Figure 7.
Call State Models Figure 8 shows an asynchronous call scenario for an incoming call with call proceeding controlled by the application with the minimum information configuration. This scenario applies to E1, T1 and ISDN technologies only. Figure 8.
Call State Models Figure 9 shows an asynchronous call scenario for an incoming call with call acknowledgement and call proceeding controlled by the call control layer. Figure 9.
Call State Models Figure 10 shows an asynchronous call scenario for an incoming call with call acknowledgement controlled by the call control layer and call proceeding controlled by the application. Figure 10.
Call State Models • Call Dialing • Call Proceeding • Call Alerting • Call Connected • Overlap Sending (for E1, T1, and ISDN technologies only) • Call Failure • Outbound Call Scenarios in Asynchronous Mode 3.4.2.1 Outbound Calls in Asynchronous Mode Overview Figure 11 illustrates a basic Outbound Call Model, which shows the call states associated with establishing a call in the asynchronous mode. All calls start from a Null state. The call establishment process for outbound calls is shown.
Call State Models Figure 11.
Call State Models Table 7.
Call State Models The following sections describe the asynchronous outbound call processes, as shown in Figure 11, “Basic Asynchronous Outbound Call State Diagram”, on page 54. 3.4.2.2 Channel Initialization To establish calls, the following conditions must be met: • The condition of the line device must be unblocked. When a channel is initially opened, the initial condition of a line device is blocked.
Call State Models established. This event changes the call to the Connected state. In the Connected state, the call is connected to the called party and call charges begin. When the call is answered (the remote end makes the connection), a GCEV_CONNECTED event changes the call to the Connected state. In the Connected state, the call is connected to the called party and call charges begin. The GCEV_CONNECTED event indicates successful completion of the gc_MakeCall( ) function. 3.4.2.
Call State Models 3.4.2.9 Outbound Call Scenarios in Asynchronous Mode This section shows various asynchronous outbound call scenarios. For call scenarios used for a specific signaling protocol, check the Global Call Technology Guide for that technology. Figure 12 shows a basic asynchronous call scenario for outgoing calls. Figure 12.
Call State Models Figure 13 shows an asynchronous call scenario for outgoing calls with call acknowledgement. Figure 13.
Call State Models Figure 14 shows an asynchronous call scenario for outgoing calls with overlap sending. Note: This scenario applies to E1, T1 and ISDN technologies only. Figure 14.
Call State Models 3.4.3.1 Call Termination in Asynchronous Mode Overview Figure 15 illustrates the call states associated with call termination or call teardown in the asynchronous mode initiated by either a call disconnection or failure. See Table 8 for a summary of the call state transitions. A call can be terminated by the application or by the detection of a call disconnect from the network.
Call State Models gc_ReleaseCallEx( ) function must be issued to release all internal resources committed to servicing the call. 3.4.3.4 Call Release Once in the Idle state, the call has been disconnected and the application must issue a gc_ReleaseCallEx( ) function to free the line device for another call. The gc_ReleaseCallEx( ) function releases all internal system resources committed to servicing the call. A GCEV_RELEASECALL event is generated and the call state transitions to the Null state. 3.4.3.
Call State Models Figure 17.
Call State Models 3.4.4 Handling Unsolicited Events The application must handle unsolicited events in the synchronous mode, unless these events are masked or disabled. The gc_SetConfigData( ) function specifies the events that are enabled or disabled for a specified line device. This function sets the event mask associated with the specified line device. If an event bit in the mask is cleared, the event is disabled and not sent to the application.
Call State Models describes the call state transitions that occur when the functions are used. This section also provides figures that illustrate the call state transitions for advanced call model functions. Note: 3.5.2 The hold, retrieve, and transfer functions are supported by particular protocols for the ISDN, E1 (PDKRT only) and T1 (PDKRT only) technologies. For more information, see the function descriptions in the Global Call API Library Reference and the appropriate Global Call Technology Guide.
Call State Models The gc_HoldCall( ) function places an active call in the On-hold (GCST_ONHOLD) state. The gc_RetrieveCall( ) function retrieves the call from the GCST_ONHOLD state and returns it to the Connected (GCST_CONNECTED) state. Figure 18 illustrates the transition between call states when a call is put on hold and then retrieved. Figure 18.
Call State Models Supervised transfers use the following Global Call API functions: gc_SetupTransfer( ) initiates a supervised transfer gc_CompleteTransfer( ) completes a supervised transfer gc_SwapHold( ) switches between the consultation call and the call pending transfer Unsupervised transfers use the following Global Call API function: gc_BlindTransfer( ) initiates and completes an unsupervised (one-step) transfer 3.5.4.
Call State Models Figure 19.
Call State Models Figure 20.
Call State Models Figure 19 illustrates the call state transitions that occur in an unsupervised transfer, which basically includes only: • The transition of Call 1 from the Connected to the Idle state (invoked by the gc_BlindTransfer( ) function) • The transition of Call 1 from the Idle to the Null state (invoked by the gc_ReleaseCallEx( ) function).
Event Handling 4. 4 This chapter describes how Global Call handles events generated in the call state model. Topics include: • Overview of Event Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 • Event Categories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 • Blocked and Unblocked Event Handling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 • Event Retrieval.
Event Handling 4.3 Blocked and Unblocked Event Handling Global Call uses the concept of blocked and unblocked conditions for line devices. By default, when the gc_OpenEx( ) function is used to open a line device, the line device is in a blocked condition meaning that the application can not perform call related functions on the line device, such as waiting for a call or making a call. The application must wait for the GCEV_UNBLOCKED event before waiting for a call or making a call.
Event Handling critical events. In addition, if the GCEV_BLOCKED event is disabled, some functions will fail with a reason of EGC_INVALIDSTATE, which may cause confusion. For more information on blocking alarms and the GCEV_BLOCKED and GCEV_UNBLOCKED events, see Section 8.2.1, “Generation of Events for Blocking Alarms”, on page 99. Note: 4.4 A GCEV_UNBLOCKED event will be generated when opening a virtual board device.
Event Handling 4.5 Events Indicating Errors Events that explicitly provide error indications are as follows: GCEV_TASKFAIL Received when an API function call fails When this events is received, the application should call gc_ResultInfo( ) immediately after the event arrives to determine the reason for the event. The data structure associated with gc_ResultInfo( ) can contain reason information provided by Global Call and additional reason information provided by the underlying call control library.
Event Handling • disabled when using an application-handler thread wherein a separate event handler thread is created within the application that calls the sr_waitevt( ) and gc_GetMetaEvent( ) functions. For an application-handler model, use the asynchronous with SRL callback model but set the SR_MODELTYPE value to SR_STASYNC to disable the creation of the internal SRL event handler thread. Note: An application-handler thread must not call any synchronous functions.
Event Handling 76 Global Call API for HMP on Windows Programming Guide — August 2006
Application Development Guidelines 5. 5 This chapter provides some tips when developing programs using Global Call. Topics include: • General Programming Tips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 • Tips for Programming Drop and Insert Applications . . . . . . . . . . . . . . . . . . . . . . . . . . 78 • Using Global Call with Digital Network Interface Boards . . . . . . . . . . . . . . . . . . . . . . 79 5.
Application Development Guidelines threads. Asynchronous programming uses system resources more efficiently because it handles multiple channels in a single thread. Asynchronous models let you program complex applications easily, and achieve a high level of resource management in your application by combining multiple voice channels in a single thread. This streamlined code reduces the system overhead required for inter process communication and simplifies the coordination of events from many devices.
Application Development Guidelines connected so as to provide the calling party with immediate outbound line status and voice cutthrough. For a drop and insert application in which a call cannot be completed, the application can simulate and return a busy tone or a fast busy (redial) tone to the calling party.
Application Development Guidelines 5.3.
Application Development Guidelines 5.3.2.2 Using Device Handles (Flexible Routing) When using Digital Network Interface boards, application performance may be a consideration when opening and closing devices using Global Call. If an application must use Global Call to dynamically open and close devices as needed, it can impact the application’s performance.
Application Development Guidelines with the voice device (they are attached and routed on the TDM bus). If you do not specify the voice device name when you open the Global Call line device, you can separately open a voice device, and then attach and route it to the network interface device. For boards that use the DM3 architecture in a flexible routing configuration, only the network device name is required.
Application Development Guidelines 5.3.2.6 Device Initialization Hint (Flexible Routing) In some applications, when xx_open( ) functions (Global Call, Voice, Fax) are issued asynchronously, it may cause slow device-initialization performance. Fortunately, you can avoid this particular problem quite simply by reorganizing the way the application opens and then configures devices. The recommendation is to do all xx_open( ) functions for all channels before proceeding with the next function.
Application Development Guidelines Table 10. Handling Glare Application Global Call Library <-- GCEV_OFFERED(CRN2) gc_AcceptCall(CRN2) --> <-- GCEV_DROPCALL(CRN1) gc_ReleaseCallEx(CRN1) --> Alternatively, the application can just respond to events using their associated CRN, simply performing a gc_ReleaseCallEx( ) upon reception of any GCEV_DROPCALL event whether the CRN is the active one or not. Using this procedure, the application only needs to store one CRN per line device.
Error Handling 6. 6 The chapter describes the error handling capabilities provided by Global Call. Topics include the following: • Error Handling Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 6.
Error Handling 86 Global Call API for HMP on Windows Programming Guide — August 2006
Call Control 7. 7 This chapter describes Global Call capabilities relating to call control. Topics include: • Call Progress Analysis when Using IP Technology . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 • Call Progress Analysis when Using Digital Network Interface Boards . . . . . . . . . . . . 87 • Resource Routing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 • Feature Transparency and Extension . . . . . . . . . . . . . . . . .
Call Control 7.2.2 Configuring Default Call Progress Analysis Parameters Call Progress Analysis (CPA) is characterized by parameters such as CaSignalTimeout (the maximum time to wait to detect a call progress tone), CaAnswerTimeout (the maximum time that call analysis will wait for ringback to stop), and others that define CPA behavior. Depending on the technology you are using, the default values of CPA parameters may be configurable in the CONFIG file corresponding to the board.
Call Control GC_CA_PREONLY_SIT Busy, Ringing and SIT enabled GC_CA_POSTONLY_PVD Fax and PVD enabled GC_CA_POSTONLY_PVD_PAMD Fax, PVD and PAMD enabled GC_CA_ENABLE_PVD Busy, Ringing, and SIT enabled; fax and PVD enabled GC_CA_ENABLE_ALL Busy, Ringing, and SIT enabled; fax, PVD and PAMD enabled These options correspond closely to call progress and call analysis options available when using the Voice API as indicated in Table 11. See the “Call Progress Analysis” chapter in the Voice API Programming Guide.
Call Control See the Global Call API Library Reference for more information about the gc_ResultInfo( ) function. When an option that enables call analysis is selected, a GCEV_MEDIADETECTED event can be received. The gc_GetCallInfo( ) function can be used to determine the type of detection (by setting the info_id function parameter to CONNECT_TYPE). The valuep function parameter indicates the connect type when the function completes.
Call Control CCPARM_CA_PAMD_QTEMP PAMD Qualification Template. Specifies which PAMD template to use. Possible values are: • PAMD_QUAL1TMP – First predefined qualification template. This is the default value. • -1 – No qualification template Setting CCPARM_CA_PAMD_QTEMP to a value of PAMD_QUAL2TMP is not supported. Note: The CCPARM_CA_PAMD_QTEMP parameter can also be set to a qualification template ID that is defined in the CONFIG file. CCPARM_CA_PVD_QTEMP PVD Qualification Template.
Call Control GCPR_CALLPROGRESS and GCPR_MEDIADETECT parameters. See the Global Call E1/T1 CAS/R2 Technology User’s Guide for more information. Table 12 shows how the CCPARM_CA_MODE values correspond to the GCPR_CALLPROGRESS and GCPR_MEDIADETECT parameters. This table is provided as a convenience for users that have previously used the gc_SetParm( ) method and now wish to use the greater flexibility provided by gc_MakeCall( ) with the CCPARM_CA_MODE parameter. Table 12.
Call Control 7.3 Resource Routing The Global Call routing functions use the device handles of resources such as a voice channel, a media resource, or a network time slot. The gc_GetResourceH( ) function can be used to obtain the network, media and voice device handles, associated with the specified line device. The gc_GetResourceH( ) function, with a resourcetype of GC_MEDIADEVICE returns the media device handle for the specified line device.
Call Control The Global Call API functions provided for FTE are: gc_Extension( ) provides a generic interface extensible for technology-specific features gc_GetUserInfo( ) (for E1, T1 and ISDN technologies only) retrieves technology-specific user information for the specified line device gc_SetUserInfo( ) permits technology-specific user information to be defined for the specified line device or call Note: 7.4.2 The gc_SetUserInfo( ) function is not supported for a board device.
Call Control The gc_Extension( ) function can also be used to transmit information to the remote endpoint. In this case, while the application at the local end point receives a GCEV_EXTENSIONCMPLT, the application at the remote end point will receive an unsolicited GCEV_EXTENSION notification event from the network with the transmitted information.
Call Control 96 Global Call API for HMP on Windows Programming Guide — August 2006
Alarm Handling 8. 8 This chapter describes the Global Call Alarm Management System (GCAMS). Topics include the following: • Alarm Handling Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 • Operation and Configuration of GCAMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 • Sample Alarm Scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105 8.
Alarm Handling a call control library. Figure 21 illustrates the relationship between the alarm management system components. Figure 21.
Alarm Handling responsible for starting and stopping the transmission of alarms and setting and getting alarm parameters, such as timing parameters. 8.2 Operation and Configuration of GCAMS The primary functions of GCAMS are as follows: • Generation of Events for Blocking Alarms • Generation of Alarm Events • Configuration of Alarm Properties and Characteristics • Starting and Stopping Alarm Transmission (E1, T1 and ISDN technologies only) • Retrieving Alarm Data 8.2.
Alarm Handling The GCEV_BLOCKED and GCEV_DISCONNECTED events may arrive in any order. When the blocking condition(s) clears, an unsolicited GCEV_UNBLOCKED event is sent to the application indicating complete recovery from the blocking condition. When a blocking condition occurs while a line device is in the Null, Disconnected, or Idle state, only the GCEV_BLOCKED event is sent since there is no call to disconnect.
Alarm Handling In addition, the alarm source object must meet the alarm flow configuration requirements, which are set using the gc_SetAlarmFlow( ) function or the gc_NotifyAll( ) function. (See Section 8.2.3, “Configuration of Alarm Properties and Characteristics”, on page 101 for more information.) When the application returns a GCEV_ALARM event, indicating that an alarm has been received, information about the alarm can be retrieved using the gc_AlarmName( ) function.
Alarm Handling network ASO ID. This define is useful in many contexts. For example, notification of all alarms on a line device can be configured using the call: gc_SetAlarmNotifyAll(..., ALARM_SOURCE_ID_NETWORK_ID, ...) The ALARM_SOURCE_ID_NETWORK_ID is a value that can be used to represent, for a given line device, whatever the network ASO ID happens to be. 8.2.3.
Alarm Handling synchronization must be present before the ASO declares a loss of sync alarm or alarm handling mode. Use of the gc_SetAlarmParm( ) function, as well as the gc_GetAlarmParm( ) function, is highly alarm source object dependent and requires detailed knowledge of the underlying ASO technology by the application writer. For a description of ASOs that are common across multiple technologies, see the Global Call API Library Reference. 8.2.3.
Alarm Handling 8.2.4 Starting and Stopping Alarm Transmission Note: This section applies to E1, T1 and ISDN technologies only. GCAMS is automatically started when Global Call is started. However, to begin the transmission of alarms to the remote side, the gc_TransmitAlarms( ) function must be called. The gc_TransmitAlarms( ) function sends all alarms as specified in the ALARM_LIST data structure for a given alarm source object.
Alarm Handling The following functions are used to retrieve ASO names and IDs and to convert them from one to the other: gc_AlarmSourceObjectID( ) retrieves the alarm source object ID, for a given event gc_AlarmSourceObjectIDToName( ) converts an alarm source object ID gc_AlarmSourceObjectName( ) retrieves the alarm source object name, for a given event gc_AlarmSourceObjectNameToID( ) converts the alarm source object name to the alarm source object ID Note: GCAMS uses predefined IDs for the ASOs it has im
Alarm Handling The steps are: 1. Configure all known call control libraries – set all alarms to notify and set flow control to first and last blocking. 2. Open a line device. The line device’s configuration will be “inherited” from its network ASO, which has already been initialized. Figure 22.
Alarm Handling 8.3.2 Scenario 2: Default Behavior for Alarm Notification The default behavior is that the application is not notified of alarm events. See Figure 23. Figure 23.
Alarm Handling 8.3.3 Scenario 3: Alarm Transmission Note: This scenario applies to E1, T1 and ISDN technologies only. Figure 24 shows a scenario that demonstrates the sequence of function calls and the actions that they cause in the transmission of alarms. Figure 24.
Real Time Configuration Management 9. 9 This chapter describes the Global Call Real Time Configuration Manager (RTCM). Topics include the following: • Real Time Configuration Manager Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 • RTCM Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110 • Using RTCM Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Real Time Configuration Management • Troubleshooting software and hardware • Performance tuning • Dynamic alteration of a target object’s behavior based upon past behavior • Generation of status reports • Dynamic configuration of Global Call call modules or call events 9.2 RTCM Components The RTCM comprises three major components: the customer application using RTCM, the Global Call RTCM, which consists of the Global Call RTCM APIs and the Global Call RTCM Manager, and the RTCM parameters.
Real Time Configuration Management 9.2.1 Customer Application Using Global Call RTCM The customer application interfaces with the Global Call RTCM Manager via Global Call RTCM API functions. The primary function of an application with regards to RTCM is the maintenance of parameter data. It is the application developer’s responsibility to understand the impact on system operation before changing a parameter value.
Real Time Configuration Management the target object is located. The customer application must ensure that the target object and requested parameters match. 9.2.3 RTCM Parameters The third component of the RTCM feature are the RTCM Parameters. The parameters are defined and maintained in four categories of software modules: Global Call Library (GCLib), Call Control Library (CCLib), Protocol and Firmware. Each software module supports different target objects as well as the target objects’ parameters. 9.
Real Time Configuration Management parameter IDs are only guaranteed to be unique within a given set ID. Note that some configurable parameters are defined only for a specific software module, while others may be used across different software modules. Typically, a software module that supports RTCM contains multiple parameter sets as well as target objects. Note: The set ID and parm ID pairs are used by other Global Call features in addition to RTCM. 9.3.
Real Time Configuration Management 9.4 Getting and Setting Parameter Information The Global Call RTCM feature supports the retrieval (E1, T1 and ISDN technologies only) or updating (all technologies) of multiple parameters of the same target object in a single Global Call API function call.
Real Time Configuration Management • the update condition; that is, whether the update should occur either at the Null call state or immediately when updating the parameters of a target object with an active call. (This parameter does not apply to the gc_GetConfigData( ) function.) 9.4.2.1 Programming Mode The customer application can specify whether to access configurations in the asynchronous mode or synchronous mode.
Real Time Configuration Management gc_SetConfigData( ) (all technologies) Asynchronous Mode: The Global Call application receives the GCEV_SETCONFIGDATA event if all the requested parameters in a given target object are successfully updated. Otherwise, the Global Call application receives the GCEV_SETCONFIGDATA_FAIL event, which indicates that at least one requested parameter in the target object failed to update due to an error.
Real Time Configuration Management Table 13.
Real Time Configuration Management Figure 26.
Real Time Configuration Management • Getting or Setting Line Device Configuration in Synchronous Mode • Setting Line Device Configuration in Asynchronous Mode • Setting Board Device Configuration in Asynchronous Mode (IP Technology) 9.7.1 Getting or Setting GCLib Configuration in Synchronous Mode Note: This section applies to E1, T1 and ISDN technologies only.
Real Time Configuration Management 4. If the gc_GetConfigData( ) function returns successfully, then obtain the individual parameter data by calling the gc_util_get_next_parm( ) function. If an error occurs, call the gc_ErrorInfo( ) function to find the error and correct it. 9.7.2 Getting or Setting CCLib Configuration in Synchronous Mode Note: This section applies to E1, T1 and ISDN technologies only.
Real Time Configuration Management 4. Call the gc_GetConfigData( ) or gc_SetConfigData( ) function with: target_type = GCTGT_CCLIB_SYSTEM target_id = CCLib ID time_out = 0 mode = EV_SYNC 5. If the gc_GetConfigData( ) function returns successfully, then obtain the individual parameter data by calling the gc_util_get_next_parm( ) function. If an error occurs, call the gc_ErrorInfo( ) function to find the error and correct it. 9.7.
Real Time Configuration Management Figure 29.
Real Time Configuration Management 9.7.4 Setting Line Device Configuration in Asynchronous Mode Note: This section applies to E1, T1 and ISDN technologies only. The Global Call RTCM allows the customer application to retrieve or change the default configuration of a line device in asynchronous mode.
Real Time Configuration Management GCTGT_FIRMWARE_CHAN target_id = Global Call line device ID time_out = 0 mode = EV_ASYNC update condition = GCUPATE_ATNULL 3. Call the gc_ResetLineDev( ) function to enforce the line to the NULL state. 4. If the gc_ResetLineDev( ) function is successful, a GCEV_RESETLINE event is received. If the gc_SetConfigData( ) function is successful, a GCEV_SETCONFIGDATA event is received.
Real Time Configuration Management The procedure for setting the configuration of a board device in asynchronous mode for IP technology is as follows: 1. The channel has an active call. Create the target object data (that is, a GC_PARM_BLK data structure) with the appropriate set ID, parm ID, value size, and value buffer by calling the Global Call utility functions. See the Global Call API Library Reference for more information. 2.
Real Time Configuration Management 126 Global Call API for HMP on Windows Programming Guide — August 2006
Handling Service Requests 10. 10 This chapter describes the Global Call Service Request (GCSR) feature. Topics include the following: • Service Request Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 • Service Request Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128 • Service Request Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Handling Service Requests Figure 32. Service Request Architecture CUSTOMER APPLICATION Operation and Configuration Subsystem GlobalCall Operation and Configuration Subsystem GCSR CALL CONTROL LIBRARY Network Interface Remote Device 10.
Handling Service Requests 10.3 Service Request Data All information transmitted and received using the Service Request feature is done using the generic GC_PARM_BLK data structure. Three parameter IDs, under the GCSET_SERVREQ set ID, are used for all requests and responses: PARM_SERVICEID (unsigned long) the service identification number.
Handling Service Requests Figure 33.
Using Global Call to Implement Call Transfer 11. 11 The information in this chapter is technology independent, however it describes a method of call transfer that is supported by IP technology only. For more specific information about implementing call transfer on IP technology, see the Global Call IP for Host Media Processing Technology Guide. For more specific information about implementing call transfer on E1, T1 and ISDN technologies, see Section 3.
Using Global Call to Implement Call Transfer Figure 34. Blind Call Transfer (Unsupervised Transfer) Transferring Party (A) Transferred Party (B) Transferring Party (A) Call 1 Transferring Party (A) Transferred Party (B) Call 1 Transferred_ To_Party (C) Before Blind Transfer 11.1.
Using Global Call to Implement Call Transfer Table 14. New Global Call Transfer Call States New Call State Note: Description Trigger Event GCST_INVOKE_XFER_ ACCEPTED The transfer request has been accepted by the remote party GCEV_INVOKE_XFER_ACCEPTED (unsolicited event) GCST_INVOKE_XFER The invoke transfer is successful (i.e.
Using Global Call to Implement Call Transfer Figure 36.
Using Global Call to Implement Call Transfer Figure 37.
Using Global Call to Implement Call Transfer Note: The state diagrams in Figure 38, Figure 39 and Figure 40 apply to the supervised transfer case represented in Figure 35. Figure 38.
Using Global Call to Implement Call Transfer Figure 39.
Using Global Call to Implement Call Transfer Figure 40.
Building Applications 12. 12 This chapter provides general information for build applications that use the Global Call software. For additional technology-specific information, refer to the appropriate Global Call Technology Guide. Topics included in this chapter are: • Compiling and Linking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 12.
Building Applications 12.1.3 Variables for Compiling and Linking Commands The following variables provide a standardized way of referencing the directories that contain header files and shared objects: INTEL_DIALOGIC_INC Variable that points to the directory where header files are stored. INTEL_DIALOGIC_LIB Variable that points to the directory where shared library files are stored. These variables are automatically set at login and should be used in compiling and linking commands.
Debugging 13. 13 This chapter provides references to other documents that provide detailed information for debugging applications that use Global Call. For general Global Call debugging information, see the “Runtime Trace Facility (RTF) Reference” chapter in the Intel Dialogic System Software Diagnostics Guide.
Debugging 142 Global Call API for HMP on Windows Programming Guide — August 2006
Glossary ASO: Alarm Source Object. The source of an alarm, for example, either a physical alarm or a logical alarm. ANI-on-Demand: A feature of AT&T ISDN service whereby the user can automatically request caller ID from the network even when caller ID does not exist. ANI: Automatic Number Identification. A service that identifies the phone number of the calling party. ASCII: American Standard Code for Information Interchange.
call control library: A collection of routines that interact directly with a network interface. These libraries are used by the Global Call functions to implement network specific commands and communications. call progress: When using Intel NetStructure® Digital Network Interface boards, a term that describes the activity that occurs before a call is connected (pre-connect), such as busy or ringback. Compare to call analysis.
DDI string: A string of Direct Dialing In digits that identifies a called number. DLL (Dynamically Linked Library): In Windows environments, a sequence of instructions, dynamically linked at runtime and loaded into memory when they are needed. These libraries can be shared by several processes. device: Any computer peripheral or component that is controlled through a software device driver. device channel: An Intel® Dialogic® data path that processes one incoming or outgoing call at a time.
glare: When an inbound call arrives while an outbound call is in the process of being setup, a glare condition occurs. Unless the protocol specifies otherwise, the incoming call takes precedence over the outbound call. Global Call: A unified, high-level API that shields developers from the low-level signaling protocol details that differ in countries around the world.
device. Once the NCAS connection is established, the application can transmit user-to-user messages using the CRN associated with the NCAS call. Network Facility Associated Signal: See NFAS. NFAS: Network Facility Associated Signaling; Allows multiple spans to be controlled by a single D channel subaddressing. Non-Call Associated Signal: See NCAS. NSI: Network Specific Information message. NT1: Network Terminator.
Public Switched Telephone Network (PSTN): Refers to the worldwide telephone network accessible to all those with either a telephone or access privileges. QSIG: QSIG) is a protocol for Integrated Services Digital Network (ISDN) communications based on the Q.931 standard. It is used for signaling between digital private branch exchanges (PBXs). QSIG is employed in voice over IP (VoIP) networks, virtual private networks (VPNs), and high-speed, multi-application networks.
synchronous mode: Programming characterized by functions that run uninterrupted to completion. Synchronous functions block an application or process until the required task is successfully completed or a failed/error message is returned. T1: A digital line transmitting at 1.544 Mbps over 2 pairs of twisted wires. Designed to handle a minimum of 24 voice conversations or channels, each conversation digitized at 64 Kbps. T1 is a digital transmission standard in North America.
condition. The application receives a GCEV_UNBLOCKED event to indicate that the line device has moved to an unblocked condition from a previously blocked condition. See also blocked. unsupervised transfer: A transfer in which the call is transferred without any consultation or announcement by the person transferring the call. UUI: User-to-User Information. Proprietary messages sent to remote system during call establishment.
Index A abandoned calls 47 alarm flow 102 alarm handling 97 alarm source objects 97 ALARM_SOURCE_ID_NETWORK_ID usage 101 alarms 97 blocking 99 GCEV_UNBLOCKED event 99 non-blocking 99 recovery 99 application-handler thread, Windows 75 ASO 97 asynchronous mode Windows 29 asynchronous models Windows 30 asynchronous programming model Windows 30 asynchronous with SRL callback 74, 75 asynchronous with SRL callback model Windows 30 asynchronous with Win32 synchronization Windows 30 asynchronous with Win32 synchron
exiting an application programming tips 77 extended asynchronous programming model, Windows 30, 31 F Features call control 18 operation, administration and maintenance 18 firmware 112 firmware module 112 G gc_BlindTransfer(_) 67 gc_Close(_) LDID becomes invalid 24 programming tips 77 gc_CompleteTransfer(_) 67 gc_DropCall(_) 61 programming tips 77 gc_GetMetaEvent(_) 30, 31, 73, 75 gc_GetMetaEventEx(_) 32, 73 caution re.
non-blocking alarms 99 Null state call termination 62 P programming tips choosing a programming model in Windows 78 drop and insert applications 78 general 77 protocol handler 71 protocol operation errors 85 R resource sharing 25 S setting up a call 53 signal handlers 64 sr_enbhdlr(_) 30, 74 SR_MODELTYPE 30, 31, 32, 75 SR_MODELTYPE value 74 sr_NotifyEvt(_) 31 sr_setparm(_) 74 SR_STASYNC 75 sr_waitevt(_) 29, 30, 31, 32, 75 sr_waitevtEx(_) 32 SRL event handler thread 31, 32 SRL events 29 SRL handler thread
Global Call API for HMP on Windows Programming Guide — August 2006
