Intel 05-2409-003 manual

Global Call API f or Host Media Pr ocessing on Windo ws Pr ogramming Guide A ugust 2006 05-2409-00 3[...]

Global Call API for HMP on Windows Programming Guide – August 2006 INFORMA TION IN THIS DO CUMENT IS PRO VIDED IN CONNECTION WITH INTEL® PRODUCTS. NO LICENSE , EXPRESS OR IMPLIED , BY EST OPPEL OR OTHER WISE, T O ANY INTELLECTUAL PR OPERTY RIGHTS IS GRANTED BY THIS DOCUMENT . EXCEPT AS PR OVID ED IN INTEL'S TERMS AND CONDITIONS OF SALE FOR [...]

Global Call API for HMP on Windows Programming Guide – August 2006 3 Contents Revision H istory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 About This Publication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . [...]

4 Global Call API for HMP on Windows Programming Guide – August 2006 Contents 3.4 Basic Call Contr ol in Asynchrono us Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 3.4.1 Inbound Calls in Asynchronous Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 3.4.2 Outbound Calls in Asynchronou[...]

Global Call API for HMP on Windows Programming Guide – August 2006 5 Contents 8.2.1 Generation of Events fo r Blocking Alarm s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 8.2.2 Generation of Alarm Eve nts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 00 8.2.3 Configuratio n of Alarm Pro perti[...]

6 Global Call API for HMP on Windows Programming Guide – August 2006 Contents Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .[...]

Global Call API for HMP on Windows Programming Guide – August 2006 7 Contents Figures 1 Global Call Ar chitecture for IP Technolo gy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 2 Global Call Ar chitecture for E1/T1 and ISDN Technologies . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 3 Call Control [...]

8 Global Call API for HMP on Windows Programming Guide – August 2006 Contents[...]

Global Call API for HMP on Windows Programming Guide – August 2006 9 Contents Ta b l e s 1 Call Control Library States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 2 Supported Target Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .[...]

10 Global Call API for HMP on Windows Programming Guide – August 2006 Contents[...]

Global Call API fo r HMP on Windows Programming Guide — August 2006 11 Re vision Histor y This re vision history summarizes the changes made in each published ve rsion of this document. Document No. Publication Date Description of Revisions 05-2409-003 August 2006 Call Control Libraries section : Updated the librar y descriptions to identify the [...]

12 Global Call API for HMP on Win dows Programming Gu ide — August 2006 Revisi on Histor y[...]

Global Call API fo r HMP on Windows Programming Guide — August 2006 13 About This Pub lication The following topics provide information about this publicati on: • Purpose • Intended Audience • How to Use This Publication • Related Information Purpose This publication provides guidelines fo r using the Global Call API to build computer tel[...]

14 Global Call API for HMP on Win dows Programming Gu ide — August 2006 About This Public ation • Original Equipment Manufacturers (OEMs) How to Use This Pub lication Refer to this publication after you hav e installed the hard ware and the system software, which includes the Global Call software. This publication assumes that you are familiar [...]

Global Call API fo r HMP on Windows Programming Guide — August 2006 15 About This Public ation • Global Call IP T echnology Guide • Standar d Runt ime Library API Pr ogr amm ing Guide . • Standar d Runtime Li brary API Libr ary Reference . • The Release Update for your HMP software, which may include updates to this manual, av ailable on [...]

16 Global Call API for HMP on Win dows Programming Gu ide — August 2006 About This Public ation[...]

Global Call API fo r HMP on Windows Programming Guide — August 2006 17 1 1 . Pr oduct Description This chapter describes the Global Call software. T opics include: • Global Call Software Ov erview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 • Global Call Feature Cate gories . . . . . . . . . . . . [...]

18 Global Call API for HMP on Win dows Programming Gu ide — August 2006 Produc t Description 1.2 Global Call Feature Categories The Global Call dev elo pment software provides many features allo wing for the dev elop ment of flexible and rob ust applications. The featur es fall into one of two main categories: • Call Control Features • Operat[...]

Global Call API fo r HMP on Windows Programming Guide — August 2006 19 Pr oduct Description Event Handling Functionality Provides the ability to handle and process e vents, in cluding the abilit y to disable and enable e vents and to retrieve e vent information. See Chapter 4, “Event Handling” for more information. Global Call Alarm Managemen[...]

20 Global Call API for HMP on Win dows Programming Gu ide — August 2006 Produc t Description Figure 1. Global Call Arc hitecture for IP T echnolog y GlobalCall Host Application IP Media Resource Signaling IP Network Media IP Network RTP/R TCP Call Control Media Routing IP Media Call Control Library (IPM CCLib) H.323 or SIP Call Control Library (I[...]

Global Call API fo r HMP on Windows Programming Guide — August 2006 21 Pr oduct Description Figure 2. Global Call Ar chitecture for E1/T1 and ISDN T echnologies 1.3.2 Global Call API The Global Call API is a call control API. Similar to other Intel Dialogic APIs (such as the V oice API), the Global Call API uses th e Standard Run time Library (SR[...]

22 Global Call API for HMP on Win dows Programming Gu ide — August 2006 Produc t Description 1.4 Call Contr ol Libraries Each supported network technolog y requires a cal l control library to provide the interface between the network and the Global Call library . The cal l contr ol libraries currently suppo rted by the Global Call API for HMP are[...]

Global Call API fo r HMP on Windows Programming Guide — August 2006 23 Pr oduct Description Figure 3. Call Contr ol Librar y States T able 1 describes the diff erent states of a call control library . Each conf igured call contro l library is assigned an ID num ber by Global Call. Each library also has a name in an ASCII string format. Library fu[...]

24 Global Call API for HMP on Win dows Programming Gu ide — August 2006 Produc t Description group of resources using a single de vice identifier . Certain features , such as Feature T ransparency and Extension (FTE), Real T ime Configuration Management (R TCM), and Global Call Service Request (GCSR) operate on a basi c entity called a Global Cal[...]

Global Call API fo r HMP on Windows Programming Guide — August 2006 25 Pr oduct Description one call may exist on a given line). A line device can ha ve a maximum of 20 CRNs associated with it. At any given instant, each CRN is a unique numb er within a process. Af ter a call is terminated and the gc_ReleaseCallEx ( ) function is called to releas[...]

26 Global Call API for HMP on Win dows Programming Gu ide — August 2006 Produc t Description • Firmwar e The possible entities include: System NIC for IP technology; all physical boards for E1, T1 and ISDN technologies Network Interf ace logical board or virtual board Channel time slot CRN call reference number A target type ( target_type ) nam[...]

Global Call API fo r HMP on Windows Programming Guide — August 2006 27 Pr oduct Description T arget Object A vailability Except for the GCTGT_GCLIB_SYSTEM target object, all target IDs are generated or assigned b y the Global Call API when the target object is created (for physical targets) or loaded (for software targets). T able 4 shows when a [...]

28 Global Call API for HMP on Win dows Programming Gu ide — August 2006 Produc t Description Global Call CRN After a call target object is created , its target object ID (that is, the Global Ca ll CRN) will be an output of the gc_MakeCall( ) function or provided by the metaev ent associated with the GCEV_OF FERED ev ent. † F or E1, T1 and ISDN [...]

Global Call API fo r HMP on Windows Programming Guide — August 2006 29 2 2 . Pr ogramming Models This chapter describes the programming models supported by Global Call. T opics include: • Programming Models Overvie w . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 • Asynchronous Mode Programming . . . . [...]

30 Global Call API for HMP on Win dows Programming Gu ide — August 2006 Progra mm ing Models and gc_GetMetaEvent( ) functions. When these functions retur n with an event, the e vent information i s stored in the MET AEVENT data structure. The event information retrieved determines the exact e vent that occurred and is v alid until the sr_waitevt([...]

Global Call API fo r HMP on Windows Programming Guide — August 2006 31 Programming Mode ls Indi vidual handlers can be written to handle ev en ts for each channel. The SRL handler thread can be used when porting applications developed for other operating systems. 2.2.3 Asynchr onous with Windo ws Callback Model The asynchronous with W indows call[...]

32 Global Call API for HMP on Win dows Programming Gu ide — August 2006 Progra mm ing Models Whereas default asynchronous programming uses the sr_waitevt( ) funct ion to wait for ev ents specific to one de vice, extended asynchronous programm ing uses the sr_waitevtEx( ) function to wait for e vents specif ic to a num ber of de vices (chan nels).[...]

Global Call API fo r HMP on Windows Programming Guide — August 2006 33 3 3 . Call State Models This chapter describes the call stat e models provided by Global Call. T opics in clude the following: • Call State Model Ov erview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 • Basic Call Model . .[...]

34 Global Call API for HMP on Win dows Programming Gu ide — August 2006 Call State Models 3.2.1 Basic Call States at the Inbound Interface The basic inbound call states are as follo ws: Null state (GCST_NULL) This state indicates that no call is assigned to th e channel (time slot or line). This is the initial state of a channel when it is fi rst[...]

Global Call API fo r HMP on Windows Programming Guide — August 2006 35 Call State Models 3.2.2 Basic Call States at the Outbound Interface The basic outbound call st ates are as follo ws: Null state (GCST_NULL) This state indicates that no call is assigned to the channel (tim e slot or line). This is the initial state of a channel when it is f ir[...]

36 Global Call API for HMP on Win dows Programming Gu ide — August 2006 Call State Models Call Idle (GCST_I DLE) This state indicates that the local user has dropped t he call. This may be a ter mination initiated by the local user or a response to the remote side disco nnecting the call. While the call no longer ex ists, internal system re sourc[...]

Global Call API fo r HMP on Windows Programming Guide — August 2006 37 Call State Models The GCA CT_A DDMSK, GCA CT_SU BMSK and G CA CT_SET MSK parameter I Ds can be assigned one of the following v alues (of ty pe GC_V ALUE_LONG), or an ORed combination of the values: • GCMSK_ALER TING_ST A TE • GCMSK_CALLR OUTING_ST A TE (for E1 , T1, and IS[...]

38 Global Call API for HMP on Win dows Programming Gu ide — August 2006 Call State Models See the Global Call API Library Refer ence for more information on the gc_SetConfigD ata( ) function. 3.3.3 Call Ackno wledg ement Configuration Note: This functionality app lies to E1, T1 and ISDN technologies only . When an incoming call is recei ved, an a[...]

Global Call API fo r HMP on Windows Programming Guide — August 2006 39 Call State Models 3.4 Basic Call Contr ol in Asynchr onous Mode This section describes and illustrates the ba sic call model and state transitions for call control in asynchronous mode. This section also describes th e process for call establishment for both inb ound and outbo[...]

40 Global Call API for HMP on Win dows Programming Gu ide — August 2006 Call State Models Figure 4. Basic Asynchr onous Inbound Call State Diagra m Note: In Figure 4, the GetMoreInfo state and all transitions to/from that st ate apply to E1, T1, and ISDN technologies only . GCEV_DETECTED (maskable) gc_AcceptCall() GCEV_ACCEPT gc_AcceptCall() GCEV[...]

Global Call API fo r HMP on Windows Programming Guide — August 2006 41 Call State Models T able 6. Async hronous Inbound Call Stat e T ransitions State Description Previous/Next State V alid Call State Tr a n s i t i o n Functions Call T ransition Events Accepted (GCST_A CCEPTED) Maskable Previous : Offered, GetMoreInf o †, CallRouting Nex t : [...]

42 Global Call API for HMP on Win dows Programming Gu ide — August 2006 Call State Models The following sections describe th e asynchronous inbound call processes. 3.4.1.2 Channel Initialization T o establish calls, the f ollowing conditions must be met: • The condition of the line device must be unblocked. When a channel is initially opened, t[...]

Global Call API fo r HMP on Windows Programming Guide — August 2006 43 Call State Models is opened using the gc_OpenEx( ) function. Howev er , if th e gc_ResetLineDev( ) function was issued, gc_WaitC all( ) must be reissued. In asynchronous mode, it is not necessary to issue gc_WaitCall( ) again after a call is released. Note: After gc_WaitCall( [...]

44 Global Call API for HMP on Win dows Programming Gu ide — August 2006 Call State Models 3.4.1.5 Call Routing After the call has been of fered, a call proceeding indication can be sent to the remote party to indicate that all the info rmation has been recei ved and the call is no w proceeding. This indication can be sent by the technology call c[...]

Global Call API fo r HMP on Windows Programming Guide — August 2006 45 Call State Models then the call is of fered to the application rega rdless of the amount of information available. The application can then request and co llect more information as required. The follo wing sections describe v arious configurations op erating in ov erlap receiv[...]

46 Global Call API for HMP on Win dows Programming Gu ide — August 2006 Call State Models address (caller ID) b y issuing the gc_GetCallInfo( ) function. If more info rmation is required, the application may also request more address information using the gc_CallAck(GCACK_ SERVICE_INFO) function. Since an acknowl edgement w as already sent out, n[...]

Global Call API fo r HMP on Windows Programming Guide — August 2006 47 Call State Models the gc_ResetLineDev( ) function to reset the li ne de vice to th e Null state. For more information, see the gc_DropCall( ) , gc_R eleaseCallEx( ) and gc_ResetLineDev( ) function descriptions in the Global Call API Library Refer ence . 3.4.1.10 Abandoned Call[...]

48 Global Call API for HMP on Win dows Programming Gu ide — August 2006 Call State Models Figure 6 shows an asynchronous call scenario for an inco ming call with call proceeding. Figure 6. Incoming Call Scenario with Call Pr oceeding Application GlobalCall Library/ T echnology Network GCEV_CALLPROC GCEV_OFFERED GCEV_ACCEPTED Incoming Call (All In[...]

Global Call API fo r HMP on Windows Programming Guide — August 2006 49 Call State Models Figure 7 shows an asynchronous call scenario for an incoming call with call ackno wledgement and call proceeding controlled b y the application. This scenario applies to E1, T1 and ISDN technologies only . Figure 7. Call Ackno wledgement and Call Proceeding D[...]

50 Global Call API for HMP on Win dows Programming Gu ide — August 2006 Call State Models Figure 8 sh o ws an asynchronous call scenario for an incoming call with call proceeding controlled by the application with the minimum informati on configuration. This scenario applies to E1, T1 and ISDN technologies only . Figure 8. Call Pr oceeding Done b[...]

Global Call API fo r HMP on Windows Programming Guide — August 2006 51 Call State Models Figure 9 shows an asynchronous call scenario for an incoming call with call ackno wledgement and call proceeding controlled b y the call control layer . Figure 9. Call Ackno wledgement and Call Proceeding Done at T echnology Ca ll Control Lay er Note: In Figu[...]

52 Global Call API for HMP on Win dows Programming Gu ide — August 2006 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 Ac knowledgement Done by the T echnolog y Call Control La yer[...]

Global Call API fo r HMP on Windows Programming Guide — August 2006 53 Call State Models • Call Dialing • Call Proceeding • Call Alerting • Call Connected • Overlap Sending (for E1, T1, and ISDN technologies only) • Call Failure • Outbound Call Scen arios in Asynchronous Mo de 3.4.2.1 Outbound Calls in A synchr onous Mode Over view [...]

54 Global Call API for HMP on Win dows Programming Gu ide — August 2006 Call State Models Figure 11. Basic Asynchr onous Outbound Call State Dia gram Note: In Figure 11, the SendMoreInfo state and all trans iti ons to/from that state apply to E1, T1, and ISDN technologies on ly . GCEV_ALERTING GCEV_ALERTING GCEV_ALERTING GCEV_CONNECTED Required O[...]

Global Call API fo r HMP on Windows Programming Guide — August 2006 55 Call State Models T able 7. Async hronous Outbound Ca ll State T ransitions State Previous/Next State V alid Call State T ransition Function s Call T ran sition Events Alerting (GCST_ALERTING) Maskable Previous : Proceeding, Dialing, SendMoreInf o † Next : GCEV_CONNECTED -&g[...]

56 Global Call API for HMP on Win dows Programming Gu ide — August 2006 Call State Models The following sections describe the asynch ronous outbound call processes, as sho wn in Figure 1 1, “Basic Asynchronous Outbound Call State Diagram ” , on page 54. 3.4.2.2 Channel Initialization T o establish calls, the f ollowing conditions must be met:[...]

Global Call API fo r HMP on Windows Programming Guide — August 2006 57 Call State Models established. This event changes the call to the Conn ected state. In the Conn ected state, the call is connected to the called part y and ca ll charges begin. When the call is answered (the remote end makes the connection), a GCEV_CONNEC TED ev ent changes th[...]

58 Global Call API for HMP on Win dows Programming Gu ide — August 2006 Call State Models 3.4.2.9 Outbound Call Scen arios in Asynchr onous Mode This section shows v arious asynchro nous outbound call scenarios. For call scenarios used for a specific s ignaling protocol, check the Global Call T echnology Guide for that technology . Figure 12 show[...]

Global Call API fo r HMP on Windows Programming Guide — August 2006 59 Call State Models Figure 13 shows an asynchronous call scenario for outgoing calls with call acknowledgement. Figure 13. Asynchr onous Outbound Call Scenario With Call Ac knowledgement Application GlobalCall Library/ T echnology Network GCEV_PROCEEDING Outbound Call Aler ting [...]

60 Global Call API for HMP on Win dows Programming Gu ide — August 2006 Call State Models Figure 14 shows an asynchronous call scenario for outgoing calls with overlap send ing. Note: This scenario applies to E1, T1 and ISDN technolo gies only . Figure 14. Async hronous Outbound Call Sc enario With Overlap Sending 3.4.3 Call T ermination in Async[...]

Global Call API fo r HMP on Windows Programming Guide — August 2006 61 Call State Models 3.4.3.1 Call T ermination in Asynchr onous Mode Over view Figure 15 illustrates the call stat es associated with call termin ation or call teardo wn in the asynchronous mode initiated by either a call disc onnection or failure. See T able 8 for a sum mary of [...]

62 Global Call API for HMP on Win dows Programming Gu ide — August 2006 Call State Models gc_ReleaseCallE x( ) 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_ReleaseCallE x( ) function to free[...]

Global Call API fo r HMP on Windows Programming Guide — August 2006 63 Call State Models Figure 17. Netw ork Initiated Asynchr onous Call T ermination Scenario Application GlobalCall Library/ T echnology Network Call Disconnected GCEV_DROPCALL GCEV_RELEASECALL GCEV_DISCONNECTED Disconnected gc_DropCall() gc_ReleaseCallEx ()[...]

64 Global Call API for HMP on Win dows Programming Gu ide — August 2006 Call State Models 3.4.4 Handling Unsolicited Events The application must handl e unsolic ited ev ents in the synchronous mode, unless these e vents are masked or disabled. The gc_SetConfigData( ) function specif ies the even ts that are enabled or disabled for a specified lin[...]

Global Call API fo r HMP on Windows Programming Guide — August 2006 65 Call State Models describes the call state transitions that occur when the functions are used. This section also provides f igures that illustrate the call state transitions for advanced call model functions. Note: The hold, retrie ve, and transfer fun ctions are supported by [...]

66 Global Call API for HMP on Win dows Programming Gu ide — August 2006 Call State Models The gc_HoldCall( ) function places an activ e call in the On-hold (GCST_ONHOLD) state. The gc_RetrieveCall( ) function retriev es the call from the GC ST_ONHOLD state and returns it to the Connected (GCST_CONNECTED) state. Figure 18 i llustrates the transiti[...]

Global Call API fo r HMP on Windows Programming Guide — August 2006 67 Call State Models Supervised transfers use the follow ing Global Call API functions: gc_SetupTransfer( ) initiates a supervised t ransfer gc_CompleteTransfer( ) completes a supervised transfer gc_SwapHold( ) switches between the consultation call and the call pending transfer [...]

68 Global Call API for HMP on Win dows Programming Gu ide — August 2006 Call State Models Figure 19. Call State Model for Supervised and Unsupervised T ransfer s If the network or application te rminates a call during a transfer , the call s t ate tran sitions are as shown in Figure 20. gc_SwapHold() GCEV_SW APHOLD Idle (Call 1) Idle (Call 2)* Co[...]

Global Call API fo r HMP on Windows Programming Guide — August 2006 69 Call State Models Figure 20. Call T ermination by the Ne twork or Application During a T ransfer Note: In Figure 20, when gc_DropCall( ) is issued, an unsolicited GCEV_CONNECTED event is recei ved for call 1 transitionin g it back to the Connected state. 3.5.4.3 Unsupervised T[...]

70 Global Call API for HMP on Win dows Programming Gu ide — August 2006 Call State Models Figure 19 illustrat es the call state transitions that occur in an unsuperv ised transfer , which basically includes only: • The transition of Call 1 fro m the Connected to the Idle state (in voked by the gc_BlindTransfer( ) function) • The transition of[...]

Global Call API fo r HMP on Windows Programming Guide — August 2006 71 4 4 . Event Handling This chapter describes how Global Call handles e vents generated in the call state model. T opi cs include: • Overvie w of Event Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 • Event Categories . [...]

72 Global Call API for HMP on Win dows Programming Gu ide — August 2006 Event Handling 4.3 Blocked and Unbl ocked Event Handling Global Call uses the concept of blocked and unblocked conditions for line de vices. By default, when the gc_OpenEx( ) function is used to open a line devi ce, the line device is in a blocked condition meaning that th e [...]

Global Call API fo r HMP on Windows Programming Guide — August 2006 73 Event Handling critical ev en ts. In addition, if the GCEV_BLOCKED ev ent is di sabled, some functio ns will fail with a reason of EGC_INV ALIDST A TE, which may cause confusio n. For more information on blocking alarms and the GCEV_BLOCKED and GCEV_UNBLOCK ED e vents, see Sec[...]

74 Global Call API for HMP on Win dows Programming Gu ide — August 2006 Event Handling 4.5 Events Indicating Error s Events that explicitly pro vide error indications are as follows: GCEV_T ASKF AIL Recei ved when an API function call fails When this e vents is recei ved, the application should call gc_ResultInfo( ) immediately after the ev ent a[...]

Global Call API fo r HMP on Windows Programming Guide — August 2006 75 Event Handling • disabled when using an application-handler t hr ead wherein a separate ev ent handler thread is created within the application that calls the sr_waitevt( ) and gc_GetMetaEvent( ) funct ions. For an application-handler model, use the asynchronous with SRL cal[...]

76 Global Call API for HMP on Win dows Programming Gu ide — August 2006 Event Handling[...]

Global Call API fo r HMP on Windows Programming Guide — August 2006 77 5 5 . Application De velopment Guidelines This chapter provides some tips when developing programs using Gl obal Call. T opics include: • General Programming T ips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 • T ips for Pr[...]

78 Global Call API for HMP on Win dows Programming Gu ide — August 2006 Application Development Gu idelines threads. Asynchronous programming uses system resources more ef fi ciently because it handles multiple channels in a sin gle thread. Asynchronous models let you program complex applications easily , and achiev e a high lev el of resource ma[...]

Global Call API fo r HMP on Windows Programming Guide — August 2006 79 Application Development Gui delines connected so as to pro vide the calling party wi th immediate outbound li ne status and voice cut- through. For a drop and insert application in which a call cannot be completed, the applicat ion can simulate and return a busy tone or a fast[...]

80 Global Call API for HMP on Win dows Programming Gu ide — August 2006 Application Development Gu idelines 5.3.2 W orking with Flexib le Routing Configurations The following topics provide more information about using Global Call with Dig ital Network Interface boards that us e the fl exible routing configuration: • Determining Channel Capabi [...]

Global Call API fo r HMP on Windows Programming Guide — August 2006 81 Application Development Gui delines 5.3.2.2 Using Device Handl es (Fle xible Routing) When using Digital Network Interface boards, application perfor mance may be a consideration when opening and closing devices using Global Call. If an application must use Global Call to dyna[...]

82 Global Call API for HMP on Win dows Programming Gu ide — August 2006 Application Development Gu idelines with the voice de vice (they are attached and rout ed on the TDM b us). If you do not specify the voice de vice name when you open the Global Call line device, you can separately open a voice device, and then attach and route it to the netw[...]

Global Call API fo r HMP on Windows Programming Guide — August 2006 83 Application Development Gui delines 5.3.2.6 Device Initialization Hint (Flexible Routing) In some applications, when xx_open( ) functions (Global Call, V oice, Fax) are issued asynchronously , it may cause slow de vice-initialization perfo rmance. Fortunately , you can av oi d[...]

84 Global Call API for HMP on Win dows Programming Gu ide — August 2006 Application Development Gu idelines Alternativ ely , the application can just respond t o e vents using their associated CRN, simply performing a gc_R eleaseCallEx( ) upon reception of any GCEV_D R OPCALL ev ent whether the CRN is the activ e on e or not. Using this procedure[...]

Global Call API fo r HMP on Windows Programming Guide — August 2006 85 6 6 . Err or Handling The chapter describes the error ha ndling capabilities provided by Global Call. T opics in clude the following: • Error Handling Ov erview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 6.1 Err or Handli[...]

86 Global Call API for HMP on Win dows Programming Gu ide — August 2006 Error Handling[...]

Global Call API fo r HMP on Windows Programming Guide — August 2006 87 7 7 . Call Contr ol This chapter describes Global Call capabilities relating to call control. T opics include: • Call Progress Analysis when Using IP T echno logy . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 • Call Progress Analysis when Using Digital Networ k [...]

88 Global Call API for HMP on Win dows Programming Gu ide — August 2006 Call Control 7.2.2 Configuring Default Call Progress Anal ysis P arameters Call Progress Analysis (CP A) is char acterized by parameters such as CaSignalT imeout (t he maximum tim e to wait to detect a call progress tone ), CaAnswerTimeout (the maximum time that call analysis[...]

Global Call API fo r HMP on Windows Programming Guide — August 2006 89 Call Contr ol GC_CA_PREONL Y_SIT Busy , Ringing and SIT enabled GC_CA_POSTONL Y_PVD Fax and PVD enabled GC_CA_POSTONL Y_PVD_P AMD Fax, PVD and P AMD enabled GC_CA_EN ABLE_PVD Busy , Ringing, and SIT enabled; fax and PVD enab led GC_CA_EN ABLE_ALL Busy , Ringing, and SIT enable[...]

90 Global Call API for HMP on Win dows Programming Gu ide — August 2006 Call Control See the Global Call API Library Refer ence for more informat ion about the gc_ResultInfo( ) function. When an option that enables call analysis is selected, a GCEV_MEDIADETECTED e vent can be recei ved. The gc_GetCallInfo( ) function can be used to determin e the[...]

Global Call API fo r HMP on Windows Programming Guide — August 2006 91 Call Contr ol CCP ARM_CA_P AMD_QTEMP P AMD Qualification T empl ate. Specifies w hich P AMD tem plate to use. Possible v alues are: • P AMD_QUAL1TMP – First predefined qualification template. This is th e default value. • -1 – No qualification template Setting CCP ARM_[...]

92 Global Call API for HMP on Win dows Programming Gu ide — August 2006 Call Control GCPR_CALLPR OGRESS and GCPR_MEDIADETECT parameters. S ee the Global Call E1/T1 CAS/R2 T echnology User’ s Guide for more infor m ation. T able 12 shows ho w the CCP ARM_CA_MODE values correspond to the GCPR_CALLPR OGRESS and GCPR_MEDIADETECT parameters. T h is [...]

Global Call API fo r HMP on Windows Programming Guide — August 2006 93 Call Contr ol 7.3 Resour ce Routing The Global Call routing func tions use the de vi ce ha ndles of resources such as a v oice channel, a media resource, or a network time slot. The gc_GetResourceH( ) function can be used to obtain the network, media and voice de vice handles,[...]

94 Global Call API for HMP on Win dows Programming Gu ide — August 2006 Call Control The Global Call API functi ons pro vided for FTE are: gc_Extension( ) provides a generic interface e xtensible for technology-sp ecifi c features gc_GetUserInfo( ) (for E1, T1 and ISDN technologies only) retriev es technology-sp ecific user information for the sp[...]

Global Call API fo r HMP on Windows Programming Guide — August 2006 95 Call Contr ol The gc_Extension( ) function can also be used to transmit information to the remote end point. In this case, while the application at the loca l end point recei ves a GCEV_EXTENSIONCMPL T , the application at the remote end point will receive an unsolicited GCEV_[...]

96 Global Call API for HMP on Win dows Programming Gu ide — August 2006 Call Control[...]

Global Call API fo r HMP on Windows Programming Guide — August 2006 97 8 8 . Alarm Handling This chapter describes the Global Call Alarm Ma nagement System (GCAMS). T opics include the follo wing: • Alarm Handling Ove rview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 • Operation and Conf igu[...]

98 Global Call API for HMP on Win dows Programming Gu ide — August 2006 Alarm Handling a call control library . Figure 21 illustr ates the relationship between the alarm management system components. Figure 21. Arc hitectural Diagram of Alarm Management Compone nts The customer application is resp onsible for configuring the behavior of GCAMS, in[...]

Global Call API fo r HMP on Windows Programming Guide — August 2006 99 Alarm Handling responsible for starting and stopping the transm issi on of alarms and sett ing and getting alarm parameters, such as timing param eters. 8.2 Operation and Configuration of GCAMS The primary functions of G CAMS are as follows: • Generation of Events for Blocki[...]

100 Global Call API for HMP on Win dows Programming Gu ide — August 2006 Alarm Handling The GCEV_BLOCKED and GCEV_DISCONNECTED ev ents may arriv e in any order . When the blocking condition(s) clears, an unsolicited GCEV_ UNBLOCKED e vent is sent to the application indicating complete recov ery fr om the blocking con dition. When a blocking condi[...]

Global Call API fo r HMP on Windows Programming Guide — August 2006 101 Alarm Handling In addition, the alarm so urce object must meet the alarm flow conf iguration requirem ents, which are set using the gc_SetA larmFlow( ) function or the gc_NotifyA ll( ) function. (See Section 8.2.3, “Configuration of Alarm Prop erties and C haracteristics”[...]

102 Global Call API for HMP on Win dows Programming Gu ide — August 2006 Alarm Handling network ASO ID. This define is useful in man y co ntexts. F or example, notif ication of all alarms on a line device can be conf igured using the call: gc_SetAl armNotifyAll(. .., ALARM_SOUR CE_ID_NETWORK_ ID, ...) The ALARM_SOURCE_ID_NETWORK_ID is a value th [...]

Global Call API fo r HMP on Windows Programming Guide — August 2006 103 Alarm Handling synchronization must be present befo re the ASO declares a loss of sync alarm or alarm ha ndling mode. Use of the gc_SetAlarm Parm( ) function, as well as the gc_GetAlarmParm ( ) fu nction, is highly alarm source object dependen t and requires detail ed knowled[...]

104 Global Call API for HMP on Win dows Programming Gu ide — August 2006 Alarm Handling 8.2.4 Star ting and Stopping Alarm T ransmission Note: This section applies to E1, T1 and ISDN technologies only . GCAMS is automatically started wh en Global Call is starte d. Ho wever , to begin the transmission of alarms to the remote side, the gc_TransmitA[...]

Global Call API fo r HMP on Windows Programming Guide — August 2006 105 Alarm Handling The following functions ar e used to retrieve ASO names and IDs and to con vert them from one to the other: gc_AlarmSourceObjectID( ) retriev es the alarm source object ID, for a giv en e vent gc_AlarmSourceObjectIDToName( ) con verts an alarm source object ID [...]

106 Global Call API for HMP on Win dows Programming Gu ide — August 2006 Alarm Handling The steps are: 1. Configure all known call control libraries – set a ll alarms to not ify and set flow control to first and last bloc king. 2. Open a line device. The line de vice’ s configuration will be “inherited” from its network ASO, which has alr[...]

Global Call API fo r HMP on Windows Programming Guide — August 2006 107 Alarm Handling 8.3.2 Scenario 2: Default Beha vior f or Alarm Notification The default behavior is that the application is not notified of alarm e vents. See Figure 23. Figure 23. Default Beha vior for Alarm No tification Application GlobalCall Alarm Source Object (ASO) gc_Op[...]

108 Global Call API for HMP on Win dows Programming Gu ide — August 2006 Alarm Handling 8.3.3 Scenario 3: Alarm T ransmission Note: This scenario applies to E1, T1 and ISDN technolo gies only . Figure 24 show s a scenario that de monstrates the sequence of func tion calls and the actions that they cause in the transmission of alarms. Figure 24. A[...]

Global Call API fo r HMP on Windows Programming Guide — August 2006 109 9 9 . Real Time Configuration Mana g ement This chapter describes the G lobal Call Real T ime C onfiguration Manager (R TCM). T opics i nclude the following: • Real T ime Configuration Manager Overvie w . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 •[...]

110 Global Call API for HMP on Win dows Programming Gu ide — August 2006 Real Time Configuration Mana g ement • T roubleshoot ing software and hardware • Performance tuning • Dynamic alterat ion of a target obj ect’ s beha vior based upon past beha vior • Generation of status repo rts • Dynamic configuration of Global Call call module[...]

Global Call API fo r HMP on Windows Programming Guide — August 2006 111 Real Time Configuration Management 9.2.1 Customer Application Using Global Call R TCM The customer application interf aces with the Global Call R TCM Manager via Global Call R TCM API functions. The primary function of an app lication with regards to R TCM is the maintenan ce[...]

112 Global Call API for HMP on Win dows Programming Gu ide — August 2006 Real Time Configuration Mana g ement the target object is located. The customer appli cation must ensure that the target object and requested parameters match. 9.2.3 R TC M P arameters The third component of the R TCM feature are th e R TCM Parameters. The parameters are def[...]

Global Call API fo r HMP on Windows Programming Guide — August 2006 113 Real Time Configuration Management parameter IDs are only guaranteed to be uni que within a gi ven set ID. Note that some configurable parameters are def ined only fo r a specific software module, while others may be used across dif feren t software modules. T ypically , a so[...]

114 Global Call API for HMP on Win dows Programming Gu ide — August 2006 Real Time Configuration Mana g ement 9.4 G etting and Setting P arameter Inf ormation The Global Call R TCM feature supports the retr iev al (E1, T1 and ISDN techn ologies only) or updating (all technologies) of m ultiple parameters of the same target object in a single Glo [...]

Global Call API fo r HMP on Windows Programming Guide — August 2006 115 Real Time Configuration Management • the update condition; that is, whether th e update should occur either at the Null call state or immediately when updating the param eters of a target object with an acti ve call. (This parameter does not appl y to the gc_GetConfigData( [...]

116 Global Call API for HMP on Win dows Programming Gu ide — August 2006 Real Time Configuration Mana g ement gc_SetConf igData( ) (all technologies) Asynchr onous Mode: The Global Call application r ecei ves the GCEV_SETCONFIGD A T A ev ent if all the requested par ameters in a gi v en target object are successfully updated. Otherwise, the Globa[...]

Global Call API fo r HMP on Windows Programming Guide — August 2006 117 Real Time Configuration Management The gc_ResetLineDev( ) function is used to speed the up date of the parameters that are waiting for the arriv al of the Null state. For exampl e, the customer application can call the gc_SetConfigData( ) fu nction multiple times to request t[...]

118 Global Call API for HMP on Win dows Programming Gu ide — August 2006 Real Time Configuration Mana g ement Figure 26. Run Time Configuratio n Pr ocedure Note: In Figure 26, for IP technology , only the gc_SetConfigData( ) function is supported for changing the parameter values of a board device. See Section 9.7.3, “Getting or Setting Line De[...]

Global Call API fo r HMP on Windows Programming Guide — August 2006 119 Real Time Configuration Management • Getting or Setting Line Device Conf iguration in Synchronous Mode • Setting Line Device Configuration in Asynchronous Mode • Setting Board Device Conf igurat ion in Asynchronous Mode (IP T echnolo gy) 9.7.1 Getting or Setting GCLib C[...]

120 Global Call API for HMP on Win dows Programming Gu ide — August 2006 Real Time Configuration Mana g ement 4. If the gc_GetConfigData( ) function returns successfully , then obtain the indi vidual parameter data by calling the gc_util_get_next_parm( ) function. If an er ror occurs, call the gc_ErrorInfo( ) function to f ind the error and corre[...]

Global Call API fo r HMP on Windows Programming Guide — August 2006 121 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_GetConf igData( ) function returns successfully , t hen obtain the individu[...]

122 Global Call API for HMP on Win dows Programming Gu ide — August 2006 Real Time Configuration Mana g ement Figure 29. Getting or Setting Line De vice Configuration in Sy nchronous Mode The following describes the procedure for getting or setting the configurat ion of a Line De vice: 1. Open the line de vice (by calling the gc_OpenEx( ) functio[...]

Global Call API fo r HMP on Windows Programming Guide — August 2006 123 Real Time Configuration Management 9.7.4 Setting Line Device Conf iguration in Async hronous Mode Note: This section applies to E1, T1 and ISDN technologies only . The Global Call R TCM allows th e customer application to retr ie ve or change the default configuration of a li[...]

124 Global Call API for HMP on Win dows Programming Gu ide — August 2006 Real Time Configuration Mana g ement GCTGT_FIRMW ARE_ CHAN target_id = Global Call line de vice ID time_out = 0 mode = EV_ASYNC update condition = GC UP A TE_ A TNULL 3. Call the gc_ResetLineDev( ) function to enforce the line to the NULL state. 4. If the gc_ResetLineDev( ) [...]

Global Call API fo r HMP on Windows Programming Guide — August 2006 125 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 acti ve call. Create the ta r get obj ect data (that is, a GC_P ARM_BLK data structure) with the approp[...]

126 Global Call API for HMP on Win dows Programming Gu ide — August 2006 Real Time Configuration Mana g ement[...]

Global Call API fo r HMP on Windows Programming Guide — August 2006 127 10 1 0 . Handling Ser vice Requests This chapter describes the Global Call Service Request (GCSR) feature. T opics include the follo wing: • Service Request Overvie w . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 • Servi[...]

128 Global Call API for HMP on Win dows Programming Gu ide — August 2006 Handling Service Requests Figure 32. Service Request Arc hitecture 10.2 Service Request Components Using the Global Call Service Request (GCSR ) f eature in volves the following API components: gc_ReqService( ) function to make a request gc_RespService( ) function to respond[...]

Global Call API fo r HMP on Windows Programming Guide — August 2006 129 Handling Service Re quests 10.3 Service Request Data All information transmitted and recei ved using the Service Reques t feature is done using the generic GC_P ARM_BLK data structure. Three parameter IDs, und er the GCSET_SER VREQ set ID, are used for all requests and respon[...]

130 Global Call API for HMP on Win dows Programming Gu ide — August 2006 Handling Service Requests Figure 33. Generic Service Request O peration Requesting Application Requesting Device Responding Application gc_ReqService () Responding Device GCEV_SER VICEREQ* Generate Request Notification of Request Process Request gc_RespService () Generate Re[...]

Global Call API fo r HMP on Windows Programming Guide — August 2006 131 11 1 1 . Using Global Call to Implement Call T ransf er The information in this chap ter is technology independent, howe ver it describes a method of call transfer that is supported by IP technology only . For more specif ic information about implementing call transfer on IP [...]

132 Global Call API for HMP on Win dows Programming Gu ide — August 2006 Using Global Call to I mplement Call T ransfer Figure 34. Blind Call T ransfer (Unsupervised T ransfer) 11.1.2 Supervised Call T ransfer In a supervised call transfer scen ario, party A transfers the call between A and B (Call 1) to a call between party B and C after establi[...]

Global Call API fo r HMP on Windows Programming Guide — August 2006 133 Using Global Call to Implement Call T ransfer Note: The state diagrams in Figure 36 and Figure 37 a pply to the case where party B initiates the transferred call to party C (see Figure 34), and not to the case where Party A places the primary call with party B on hold and the[...]

134 Global Call API for HMP on Win dows Programming Gu ide — August 2006 Using Global Call to I mplement Call T ransfer Figure 36. Call State Model for Blind Call T ransfer at P arty A GCST_NULL GCST_IDLE GCST_INV OKE_XFER GCEV_DISCONNECTED (XFER CMPL T) GCEV_RELEASECALL T ransf err ing P ar ty (P ar ty A) GCEV_INV OKE_ XFER_F AIL GCST_INV OKE_ X[...]

Global Call API fo r HMP on Windows Programming Guide — August 2006 135 Using Global Call to Implement Call T ransfer Figure 37. Call State Model f or Blind T ransfer at P ar ty B GCST_CONNECTED or GCST_HELD GCST_NULL GCST_IDLE GCST_REQ_XFER GCEV_REQ_XFER GCEV_DROPCALL GCEV_RELEASECALL T ransferred P ar ty (P ar ty B) GCEV_REJ_XFER GCEV_ACCEPT_XF[...]

136 Global Call API for HMP on Win dows Programming Gu ide — August 2006 Using Global Call to I mplement Call T ransfer Note: The state diagrams in Figure 38, Figure 39 and Fi gure 40 apply to the supervised transfer case represented in Figure 35. Figure 38. Call State Model for Supervised T ransfer at P arty A GCEV_INV OKE_ XFER_F AIL GCST_INV O[...]

Global Call API fo r HMP on Windows Programming Guide — August 2006 137 Using Global Call to Implement Call T ransfer Figure 39. Call Sta te Model for Supervi sed T ransfer at P arty B GCST_XFER_CMPL T GCST_ACCEPT_XFER GCST_CONNECTED or GCST_HELD GCEV_REQ_XFER GCEV_XFER_CMPL T Call 1 GCEV_XFER_F AIL GCST_DISCONNECTED GCEV_DISCONNECTED GCST_NULL G[...]

138 Global Call API for HMP on Win dows Programming Gu ide — August 2006 Using Global Call to I mplement Call T ransfer Figure 40. Call State Model for Supervised T ransfer at P arty C GCST_CONNECTED or GCST_HELD GCST_REQ_INIT_XFER GCEV_REQ_INIT_XFER GCEV_ACCEPT_INIT_XFER or GCEV_REJ_INIT_XFER or GCEV_REJ_INIT_XFER_F AIL or GCEV_ACCEPT_INIT_XFER_[...]

Global Call API fo r HMP on Windows Programming Guide — August 2006 139 12 1 2 . Building Applications This chapter provides gen eral information for buil d applications that use the Global Call software. For additional technology-specif ic information, refer t o the appropriate Global Call T echnology Guide. T opics included in this chapter are:[...]

140 Global Call API for HMP on Win dows Programming Gu ide — August 2006 Building Applications 12.1.3 V ariables f or Compi ling and Linking Commands The follo w ing v ariables provide a standardized wa y of referencing the directories t hat contain header file s and shared objects: INTEL_DIAL OGIC_INC V ariable that points to the direct ory wher[...]

Global Call API fo r HMP on Windows Programming Guide — August 2006 141 13 1 3 . Deb ugging This chapter provides re ferences to other d ocuments that provide detailed information for debugging applications that use Global Call. For general Global Call debugging information, s ee the “Runtime T race Facility (R TF) Reference” chapter in the I[...]

142 Global Call API for HMP on Win dows Programming Gu ide — August 2006 Debug ging[...]

Global Call API fo r HMP on Windows Programming Guide — August 2006 143 Glossar y ASO: Alarm Source Object. The source of an alarm, for e xample, either a ph ysical alarm or a logical alarm. ANI-on-Demand: A feature of A T&T ISDN service whereb y the us er can automatically request caller ID from the network e ven when cal ler ID does not exi[...]

144 Global Call API for HMP on Win dows Programming Gu ide — August 2006 call cont rol library: A collection of routines that in teract directly with a netw or k interface. Thes e libraries are used by the Global Call functions to implemen t network specif ic comman ds and communications. call progress: When using Int el NetStructure ® D igital [...]

Global Call API fo r HMP on Windows Programming Guide — August 2006 145 DDI string: A string of Direct Dialing In digits that identifies a called number . DLL (Dynamically Linked Libra r y): In W indows en vironments, a sequen ce of instructions, dynamically linked at runtime and loaded into memo ry when they are needed. These librarie s can be s[...]

146 Global Call API for HMP on Win dows Programming Gu ide — August 2006 glare: When an inbound call arri ves while an outbound call is in the process of being set up, a glare condition occurs. Unless the protocol specif i es otherwise, the inco ming call takes precedence o ver the outbound call. Global Call: A unif ied, high-l e vel API that shi[...]

Global Call API fo r HMP on Windows Programming Guide — August 2006 147 device. Once the NCAS connect ion is established, the application can transmit user-to-user messages using the CRN associated with the NCAS call. Networ k Facility As sociated Signal: See NFAS . NF AS: Network Facility Associated Signaling; Allows multiple spans to be control[...]

148 Global Call API for HMP on Win dows Programming Gu ide — August 2006 Public Switche d T elephone Network (P STN): Refers to the worldwide telephone network accessible to all those with either a telephone or access pri vileges. QSIG: QSIG) is a protocol for Integrated Services Digita l Network (ISDN) communicat ions based on the Q.931 standard[...]

Global Call API fo r HMP on Windows Programming Guide — August 2006 149 synchr onous mode: Programming characterized by functions that run uninterrupted to completion. Synchronous functions block an applicati on or process unt il the required task is successfully comple ted or a failed/error message is returned. T1: A digital lin e transmitting a[...]

150 Global Call API for HMP on Win dows Programming Gu ide — August 2006 condition. The application re ceives a GCEV_UN BLOCKED ev ent to indicat e that the line device has mo ved to an unblocked condition from a previously blocked condition. See also blocked . unsupervised trans fer: A transfer in which the call is transferred without any consul[...]

Global Call API fo r HMP on Windows Programming Guide — August 2006 151 Inde x 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 async[...]

152 Global Call API for HMP on Window s Programming Guide — August 2006 exiting an applicat ion programming tips 77 extended asynchronous programming model, Windows 30 , 31 F Features call control 18 operation, administrati on and maintenance 18 firmware 112 firmware module 112 G gc_BlindTransfer(_) 67 gc_Close(_) LDID becomes invalid 24 programm[...]

Global Call API for HM P on Windows Programming Guide — August 2006 153 non-blocking alarms 99 Null state call terminat ion 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_[...]

154 Global Call API for HMP on Window s Programming Guide — August 2006[...]